feat(mcp): reduce Ultra to a seven-tool kernel

Cause: the 0.22 MCP exposed 60 fine-grained operations and encoded semantic workflow sequencing as hard state-machine gates, creating high prompt cost, repeated model round trips, and unrecoverable draft self-locks.

Scope: add the seven-tool public facade, keep legacy operations hidden for one compatibility release, make drafts reversible, collapse semantic checkpoint bookkeeping, make context compilation idempotent, update four host adapters and all public Skills, and release package metadata as 0.23.0.

Verification: npm run verify:release; 18 Skill Creator validations; Codex plugin validator; npm pack --dry-run --json; git diff --check.

Residual risk: hidden 0.22 compatibility operations remain callable for one release and should be removed only after downstream migration evidence. Rollback: reinstall 0.22.0 and revert this commit; accepted SQLite revisions remain backward-readable by the retained compatibility layer.

Author: rocky2431

AGENTS.md

@@ -7,8 +7,10 @@ not create or rewrite that file.
 ## Product boundary
 
 Ultra Builder Pro is a host-adapted workflow plugin for Claude Code, Codex, OpenCode,
-and Kimi Code. It owns workflow authority, evidence, recovery, host adapters, and the
-minimal prompts required to operate them.
+and Kimi Code. It owns durable project checkpoints, evidence, recovery, host adapters,
+and the minimal prompts required to operate them. The host model owns semantic
+reasoning and route selection; MCP is a persistence and safety kernel, not a
+fine-grained workflow supervisor.
 
 It owns project-local cross-session workflow memory under `.ultra/`: normalized intent,
 progress, tasks, bounded context, specifications, evidence, provenance, and recovery.
@@ -20,8 +22,11 @@ Keep those capabilities in separately installed owner packages.
 
 - `adapters/_shared/runtime-assets.cjs`: packaged Skill, hook, and collaboration allowlists.
 - `docs/PLUGIN-ISOLATION-CONTRACT.md`: installation, activation, idle, and ownership boundaries.
-- `mcp-server/lib/workflow-state.cjs`: workflow state transitions and durable gates.
-- `spec/mcp-tools.yaml`: public MCP contract.
+- `mcp-server/lib/ultra-facade.cjs`: seven-tool model-facing MCP kernel.
+- `mcp-server/lib/workflow-state.cjs`: hidden compatibility bookkeeping and durable
+  checkpoint validation.
+- `spec/mcp-tools.yaml`: seven public contracts plus one-release hidden compatibility
+  contracts.
 - `skills/*/SKILL.md`: reusable workflow prompts.
 - Codex plugin Skills: native `$ultra-builder-pro:<skill>` entry points.
 - `.ultra/.runtime/state.db`: lifecycle, index, transition, freshness, and coordination authority
@@ -52,8 +57,10 @@ one workflow may recommend but must not launch another.
 4. Run the narrow test first, then the relevant package suite.
 5. Inspect the final diff and packaged artifact.
 
-Do not weaken gates merely to make tests pass. Context-size guidance is advisory;
-authority, security, irreversible effects, and evidence integrity may block.
+Do not turn semantic advice, incomplete exploration, or an editable draft into a hard
+MCP failure. Failed checkpoints report mutable diagnostics. Corruption, unsafe paths,
+true concurrency conflicts, permissions, irreversible effects, and accepted evidence
+integrity remain fail-closed. Context-size guidance is advisory.
 
 ## Verification
 

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

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`.

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');
   }

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',
+      ],
     },
   };
 }

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,

adapters/_shared/tests/interaction-contract.test.cjs

@@ -22,7 +22,7 @@ test('every supported host receives the same authority split with a native quest
   };
   for (const runtime of ['claude', 'codex', 'opencode', 'kimi']) {
     const contract = interactionContract(runtime);
-    assert.equal(contract.schema_version, '1.2');
+    assert.equal(contract.schema_version, '1.3');
     assert.equal(contract.runtime, runtime);
     assert.equal(contract.interaction.question_surface.primary, expectedSurfaces[runtime]);
     assert.equal(contract.interaction.question_surface.primary, SURFACES[runtime].primary);
@@ -51,7 +51,9 @@ test('every supported host receives the same authority split with a native quest
     assert.ok(!contract.authority.host_model.includes('semantic_route_selection'));
     assert.equal(contract.routing.semantic_recommendation_owner, 'host_model');
     assert.equal(contract.routing.durable_recommendation_authority, false);
-    assert.equal(contract.routing.hard_invariant_field, 'required_transition');
+    assert.equal(contract.routing.current_context_tool, 'ultra.context');
+    assert.deepEqual(contract.routing.checkpoint_diagnostic_fields, ['warnings', 'blockers']);
+    assert.ok(contract.routing.hard_blocker_boundary.includes('concurrency_conflict'));
   }
 });
 

adapters/_shared/tests/runtime-assets.test.cjs

@@ -103,7 +103,7 @@ test('the public capability graph is exact and every handoff remains explicit',
     assert.deepEqual(PUBLIC_CAPABILITY_GRAPH[name], {
       mode: GRAPH_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,

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',
           );
         }

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/`',
     );
   }