ultra-builder-pro-cli 0.21.1 → 0.23.0

package/.ultra-template/tasks/tasks.json

@@ -1,6 +1,13 @@
 {
-  "schema_version": "4.5",
-  "generated_at": "1970-01-01T00:00:00.000Z",
-  "source": ".ultra/.runtime/state.db",
+  "kind": "ultra-team-task-ledger",
+  "schema_version": "1.0",
+  "generation": 0,
+  "parent_digest": null,
+  "ancestors": [],
+  "state_digest": "5bf27fb3627b711c97abf72f0aad150ba693d35bcebdd57c2d80e325f495de6d",
+  "published_at": null,
+  "reason": "scaffold",
+  "baseline": null,
+  "changes": [],
   "tasks": []
 }

package/.ultra-template/templates/task-context.md

@@ -0,0 +1,19 @@
+<!-- Runtime task views are generated under .ultra/.runtime/projections/contexts/. -->
+
+# Task Context Reference
+
+Use this file only as a structure reference. Runtime task context views are generated
+from SQLite authority and must not be edited by hand. Stable specification learning
+must follow the Change workflow.
+
+## Implementation Notes
+
+- [Evidence-backed note with a source reference]
+
+## Open Questions
+
+- [Question, consequence, owner, and next evidence]
+
+## Recovery Notes
+
+- [Current safe resume point and any external prerequisite]

package/CHANGELOG.md

@@ -7,6 +7,84 @@ 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
+
+- Added a versioned, digest-chained Git team checkpoint at
+  `.ultra/tasks/tasks.json` for portable baseline, Change, task-contract,
+  dependency, and durable task-status handoff.
+- Added `task.ledger_get`, `task.ledger_publish`, and `task.ledger_import` with
+  per-record revisions, bounded ancestry, transactional fast-forward imports,
+  and typed baseline, Change, task, deletion, and active-session conflicts.
+- Added exact-byte backup and deterministic upgrade of matching legacy v4.4
+  and v4.5 task projections during project resume.
+
+### Changed
+
+- Moved generated task and context views under
+  `.ultra/.runtime/projections/`; SQLite remains checkout-local operational
+  authority while the Git checkpoint is the narrow team handoff.
+- Updated all public workflow Skills, project templates, hooks, adapters, and
+  documentation to inspect and synchronize the team checkpoint without
+  turning hooks or host adapters into semantic authorities.
+- Made imported ready baselines require checkout-local revalidation before
+  they may publish a descendant checkpoint.
+
+### Fixed
+
+- Fixed tracked task projections creating a self-referential
+  `BASELINE_HEAD_STALE` treadmill after every Ultra operation or metadata-only
+  commit. Baseline freshness now uses scoped source content plus Git ancestry
+  while continuing to detect specification and source drift.
+- Fixed task completion requiring a second bookkeeping commit. The completion
+  SHA is now backfilled only into local SQLite and generated views after the
+  single real completion commit.
+- Fixed resume, doctor, status, and four-host install paths disagreeing about
+  legacy task projections, team checkpoints, generated views, and protected
+  files.
+- Replaced the daemon's machine-speed-dependent 500ms release assertion with a
+  bounded observable-session wait while preserving the immediate-poll
+  behavior requirement.
+
 ## [0.21.1] — 2026-07-29
 
 ### Fixed

package/README.md

@@ -43,9 +43,11 @@ Ultra Builder Pro addresses those gaps with four ideas:
 2. **Low-load user alignment.** The agent investigates observable facts itself
    and asks the user only for material intent, scope, risk, or authorization
    decisions—normally one dependent decision at a time.
-3. **Durable project authority.** `.ultra/.runtime/state.db` records baselines, changes,
-   decisions, workflows, tasks, evidence digests, sessions, incidents, and
-   recovery state across hosts and sessions.
+3. **Durable project authority.** `.ultra/.runtime/state.db` records checkout-local
+   lifecycle, decisions, workflows, evidence digests, sessions, incidents, and
+   recovery state across host sessions. Tracked semantic artifacts plus the
+   MCP-published `.ultra/tasks/tasks.json` checkpoint carry reviewed project intent
+   across Git checkouts without committing SQLite, leases, or telemetry.
 4. **Convergent delivery.** Research, plans, implementation, tests, review, and
    specification updates must agree before a change is archived.
 
@@ -59,14 +61,40 @@ session resumes from that authority instead of reconstructing it from chat.
 ## The mental model
 
 ```mermaid
-flowchart LR
-    U["User<br/>intent and material decisions"] <--> H["Host agent<br/>reasoning and implementation"]
-    H <--> S["Ultra skills<br/>task-specific workflows"]
-    S <--> M["Ultra MCP<br/>state, evidence, freshness, recovery"]
-    M <--> D[(".ultra/.runtime/state.db")]
-    H --> A["Code, specifications,<br/>tests and review artifacts"]
-    A --> M
-    K["Lifecycle hooks<br/>breadcrumb and projection protection"] --> M
+flowchart TB
+    U["User<br/>goals, acceptance, trade-offs, risk, and external authorization"]
+
+    subgraph HOST["Supported coding host"]
+        UI["Host-native interaction<br/>Claude Code / Codex / OpenCode / Kimi Code"]
+        MODEL["Host agent<br/>inspect, recommend, implement, test, and review"]
+        ADAPTER["Host adapter<br/>native questions, commands, tools, and lifecycle wiring"]
+    end
+
+    SKILLS["Eleven explicit Ultra Skills<br/>init / research / think / change / plan / dev<br/>test / review / deliver / status / doctor"]
+    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"]
+    FILES["Digest-bound .ultra artifacts<br/>specification / research / change / plan / context<br/>test / review / delivery"]
+    HOOKS["Lifecycle hooks<br/>health, breadcrumbs, recovery hints, and managed-file protection"]
+    OPS["Operational tools<br/>ubp / ultra-tools / optional orchestrator"]
+    EXTERNAL["External memory and graph providers"]
+
+    U <-->|"intent, recommendation, and owner choice"| UI
+    UI <--> MODEL
+    ADAPTER --> UI
+    ADAPTER -.->|"discovers and presents"| SKILLS
+    MODEL -->|"explicit invocation"| SKILLS
+    SKILLS -->|"typed operations"| MCP
+    MCP <--> DB
+    MCP -->|"publish / validate / import"| LEDGER
+    MCP -->|"regenerate"| VIEWS
+    MODEL -->|"writes semantic and evidence bodies"| FILES
+    MCP <-->|"registers owner, digest, provenance, and freshness"| FILES
+    HOOKS -->|"observes and records lifecycle events"| MCP
+    OPS -->|"installation"| ADAPTER
+    OPS -->|"diagnosis, recovery, and approved dispatch"| MCP
+    EXTERNAL -.->|"bounded provider references only"| DB
 ```
 
 The responsibility split is deliberate:
@@ -75,13 +103,65 @@ 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** | Durable state, evidence references, digests, freshness, locks, valid transitions and hard recovery |
+| **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 generated projections |
+| **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
+
+```mermaid
+flowchart TD
+    CURRENT["Current Ultra workflow"] --> INSPECT["Host model inspects code, documents, and current authority"]
+    INSPECT --> SUGGEST["Model recommends a route and explains its consequences"]
+    SUGGEST --> CLEAR{"Is current owner intent already explicit?"}
+    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 --> 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"]
+```
+
+The interaction before the write establishes owner intent. Once the host model
+normalizes and persists that intent, MCP treats the stored result as current
+authority; it does not try to prove that the owner clicked a particular UI
+control. Ultra stores the accepted result and its scope, evidence, provenance,
+and effects—not chain-of-thought, raw prompts, transcripts, or UI receipts.
 
 ## What you get
 
@@ -248,13 +328,16 @@ 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. Use `ultra-doctor` when initialization
-reports migration or authority damage; do not overwrite old state manually.
+backup-first migration or rebaseline. The first supported checkpoint publication
+replaces a v4.4/v4.5 task projection only when its ids and durable fields match
+SQLite, after copying its exact bytes to `.ultra/.runtime/backups/task-ledger/`.
+Use `ultra-doctor` when initialization reports migration, mismatch, or authority
+damage; do not overwrite old state manually.
 
 ### 3. Make daily changes
 
@@ -304,12 +387,67 @@ 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 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
+    START["Project entry"] --> INIT["ultra-init"]
+    INIT --> CLASSIFY{"Repository classification"}
+
+    CLASSIFY -->|"Greenfield"| GREEN["Create scaffold<br/>verify Git and project authority"]
+    CLASSIFY -->|"Brownfield"| BROWN["Preserve the delivered system<br/>bootstrap adoption authority"]
+    CLASSIFY -->|"Legacy or damaged authority"| REPAIR["ultra-doctor<br/>migrate, recover, or rebaseline"]
+    REPAIR --> BROWN
+
+    GREEN --> RESEARCH["Explicit ultra-research"]
+    BROWN --> RESEARCH
+    RESEARCH --> BASELINE{"Has the baseline converged?"}
+    BASELINE -->|"Material decision gap"| THINK_BASE["ultra-think"]
+    THINK_BASE --> RESEARCH
+    BASELINE -->|"Evidence gap"| RESEARCH
+    BASELINE -->|"Approved and current"| CHANGE["Explicit ultra-change"]
+
+    CHANGE --> ROUTE{"Model recommends a route<br/>owner selects or modifies it"}
+    ROUTE -->|"Material intent remains unresolved"| THINK_CHANGE["ultra-think"]
+    THINK_CHANGE --> ROUTE
+    ROUTE -->|"Real evidence gap"| CHANGE_RESEARCH["Bounded ultra-research<br/>owned by the active Change"]
+    CHANGE_RESEARCH --> PLAN["ultra-plan"]
+    ROUTE -->|"Evidence is sufficient: Direct Build"| PLAN
+
+    PLAN --> DEV["ultra-dev<br/>one dependency-ready vertical task"]
+    DEV --> TASKS{"More executable tasks?"}
+    TASKS -->|"Yes"| DEV
+    TASKS -->|"No"| TEST["ultra-test<br/>risk-selected formal verification"]
+    TEST -->|"Failed or incomplete"| DEV
+    TEST -->|"Passing"| REVIEW["ultra-review<br/>specification fidelity and engineering quality"]
+    REVIEW -->|"Changes required"| DEV
+    REVIEW -->|"Approved"| DELIVER["ultra-deliver"]
+    DELIVER --> ARCHIVE["Reconcile specifications<br/>apply the Change overlay and archive evidence"]
+    ARCHIVE --> NEXT{"Continue"}
+    NEXT -->|"Next outcome"| CHANGE
+    NEXT -->|"Inspect current authority"| STATUS["ultra-status"]
+
+    ANY["Any active stage"] -.->|"read-only routing"| STATUS
+    ANY -.->|"mechanical health fault"| DOCTOR["ultra-doctor"]
+```
+
+“Direct Build” skips additional Research only. It still requires
+`ultra-plan`, current DB-backed task contracts, dependency ownership, and an
+immutable role-scoped Context Manifest before `ultra-dev`. `ultra-status` is a
+read-only side route, while `ultra-doctor` diagnoses and repairs mechanical
+health without selecting product intent.
 
 ## What lives in `.ultra/`
 
@@ -318,6 +456,7 @@ capability starts only after an explicit user command or skill invocation.
   .runtime/                # local mutable state; ignored by Git
     state.db               # lifecycle, index, transition, and freshness authority
     checkpoint.json        # advisory recovery projection
+    projections/           # generated local task and task-context views
     backups/               # verified migration and recovery snapshots
     collab/                # local collaboration scratch
     sessions/              # local leases and session runtime
@@ -326,9 +465,14 @@ capability starts only after an explicit user command or skill invocation.
   specs/                   # digest-bound product and architecture baseline
   changes/
     active/<id>/           # all current Change semantics and evidence
+      intent.md            # accepted Change Contract
+      findings.md          # durable Change findings
+      progress.md          # generated human-readable projection
       research/            # Change-only findings and research reports
       delta/               # typed baseline overlay and semantic payloads
       documentation/       # documentation overlay and reconciliation evidence
+      plan.json            # machine-readable task topology
+      plan.md              # deterministic human plan projection
       contexts/            # immutable role/task context snapshots
       test/                # Change-scoped test reports
       review/              # Change-scoped review workers and summary
@@ -337,17 +481,20 @@ capability starts only after an explicit user command or skill invocation.
   docs/research/           # baseline-only research evidence
   reports/templates/       # blank report schemas; never delivery evidence
   tasks/
-    tasks.json             # generated projection, never the authority
-    contexts/              # bounded role/task context artifacts
+    tasks.json             # MCP-published Git team checkpoint; never hand-edited
+  templates/
+    task-context.md        # authored template, not a generated task context
 ```
 
 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
-lifecycle and index authority; registered digest-bound files carry the semantic
-or evidence bodies that the DB references. Generated projections and working
-scratch are not authority.
+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
+not a second live session authority. Generated projections and working scratch are
+not authority.
 
 Ultra does not store chain-of-thought, raw prompts, transcripts, general
 conversational or episodic memory, or code-graph payloads. External memory and
@@ -356,6 +503,29 @@ references to them as workflow context. Only `.ultra/.runtime/` is ignored by
 Git: semantic and evidence artifacts can travel with the repository, while
 SQLite, leases, telemetry, and recovery scratch remain checkout-local.
 
+### Team checkpoint protocol
+
+MCP publishes `.ultra/tasks/tasks.json` at durable boundaries: baseline convergence,
+Change creation or revision, accepted plan export, durable task-contract or status
+changes, task expansion or deletion, and Change convergence or archive. The file
+contains per-record revisions and digests plus checkpoint ancestry. It excludes
+`in_progress` ownership, session ids, leases, worktrees, telemetry, and
+`completion_commit`.
+
+After a pull or on a fresh checkout, MCP validates and imports the checkpoint. Clean
+records fast-forward independently. A baseline imported as `ready` is downgraded to
+checkout-local revalidation until its scope, files, verification, and HEAD are proven
+again. Concurrent edits to the same baseline, Change, or task, a non-descendant
+checkpoint, or remote modification of an active local task fail with a typed conflict;
+Ultra never silently picks a side. Re-importing the same checkpoint is read-only, and
+an imported ready baseline cannot publish another checkpoint until local revalidation
+converges.
+
+Baseline freshness does not use the checkpoint commit as a self-referential marker.
+It combines Git ancestry with a scoped content digest that excludes `.ultra/`.
+Consequently, a commit containing only Ultra metadata does not make the baseline stale,
+while a descendant commit that changes scoped application content does.
+
 See [Artifact authority](./docs/ARTIFACT-AUTHORITY.md) for the promotion and
 evidence rules.
 
@@ -409,10 +579,14 @@ host's existing model session.
   reinstall only the degraded host.
 - **Project state is unhealthy:** invoke `ultra-doctor` or run
   `ultra-tools system doctor`. Repairs and schema migrations are backup-first.
-- **A projection disagrees with MCP:** trust `.ultra/.runtime/state.db`; do not repair
-  `tasks.json` or generated context Markdown by hand.
-- **A workflow appears blocked:** use `ultra-status` to read the exact current
-  workflow, blocker, owner decision, and mechanically valid transitions.
+- **The team checkpoint disagrees with local state:** run `ultra-status`, inspect the
+  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 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',
     );
   }
@@ -337,7 +337,8 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-const TASKS_PROJECTION = ".ultra/tasks/tasks.json";
+const TEAM_TASK_LEDGER = ".ultra/tasks/tasks.json";
+const LIVE_TASK_PROJECTION = ".ultra/.runtime/projections/tasks.json";
 const NODE_BINARY = ${JSON.stringify(process.execPath)};
 const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url));
 const BREADCRUMB_CLI = path.resolve(
@@ -382,20 +383,28 @@ function targetPaths(tool, args) {
   return [...new Set(paths)];
 }
 
-function projectionRootForTarget(baseRoot, candidate) {
+function managedTaskRootForTarget(baseRoot, candidate) {
   const target = path.isAbsolute(candidate)
     ? path.resolve(candidate)
     : path.resolve(baseRoot, candidate);
-  if (path.basename(target) !== "tasks.json"
-      || path.basename(path.dirname(target)) !== "tasks"
-      || path.basename(path.dirname(path.dirname(target))) !== ".ultra") {
-    return null;
+  if (target === path.resolve(baseRoot, TEAM_TASK_LEDGER)
+      || target === path.resolve(baseRoot, LIVE_TASK_PROJECTION)) return baseRoot;
+  if (path.basename(target) !== "tasks.json") return null;
+  const parent = path.dirname(target);
+  if (path.basename(parent) === "tasks"
+      && path.basename(path.dirname(parent)) === ".ultra") {
+    return path.dirname(path.dirname(parent));
+  }
+  if (path.basename(parent) === "projections"
+      && path.basename(path.dirname(parent)) === ".runtime"
+      && path.basename(path.dirname(path.dirname(parent))) === ".ultra") {
+    return path.dirname(path.dirname(path.dirname(parent)));
   }
-  return path.dirname(path.dirname(path.dirname(target)));
+  return null;
 }
 
-function protectsTasksProjection(baseRoot, candidate) {
-  const targetRoot = projectionRootForTarget(baseRoot, candidate);
+function protectsManagedTaskFile(baseRoot, candidate) {
+  const targetRoot = managedTaskRootForTarget(baseRoot, candidate);
   if (!targetRoot) return false;
   return Boolean(readUltraContext(targetRoot));
 }
@@ -421,11 +430,13 @@ export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
       const tool = String(input?.tool ?? "").toLowerCase();
       if (!["write", "edit", "apply_patch"].includes(tool)) return;
       if (targetPaths(tool, output?.args).some(
-        (candidate) => protectsTasksProjection(root, candidate),
+        (candidate) => protectsManagedTaskFile(root, candidate),
       )) {
         throw new Error(
-          "Ultra Builder Pro refused a direct write to .ultra/tasks/tasks.json. " +
-          ".ultra/.runtime/state.db is authoritative; use MCP task tools and run ultra-doctor when state or projection health is degraded."
+          "Ultra Builder Pro refused a direct write to an MCP-managed task file. " +
+          ".ultra/tasks/tasks.json is the MCP-published team checkpoint and " +
+          ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. " +
+          "Use the Ultra MCP task or task.ledger tools."
         );
       }
     },