ultra-builder-pro-cli 0.23.0 → 0.24.1

package/.ultra-template/docs/research/README.md

@@ -49,7 +49,7 @@ copying memory, code-graph payloads, or large source material into Ultra.
 
 ## Completion
 
-Update the affected baseline specification, record the report through `workflow.step`,
-include it in `baseline.record` evidence when material, and record unresolved work in
-the authoritative gap ledger. The final synthesis also binds the three specifications
-and research distillate. Do not create a condensed duplicate of the baseline.
+Update the affected baseline specification, register the report through typed
+`ultra.record`, reference it from the Research Stage Checkpoint, and record unresolved
+work in the authoritative gap ledger. The final synthesis also binds the baseline
+specifications and research distillate. Do not create a condensed duplicate.

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

@@ -1,13 +1,15 @@
 {
   "kind": "ultra-team-task-ledger",
-  "schema_version": "1.0",
+  "schema_version": "2.0",
   "generation": 0,
   "parent_digest": null,
   "ancestors": [],
-  "state_digest": "5bf27fb3627b711c97abf72f0aad150ba693d35bcebdd57c2d80e325f495de6d",
+  "state_digest": "88098433d797125bb0f87068a01205cf378494169ca93ee2a9dcf15c1c83dd63",
   "published_at": null,
   "reason": "scaffold",
   "baseline": null,
   "changes": [],
+  "decisions": [],
+  "checkpoints": [],
   "tasks": []
 }

package/CHANGELOG.md

@@ -7,6 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.1] — 2026-07-31
+
+### Changed
+
+- Kept semantic completeness, route selection, baseline sufficiency, and delivery
+  acceptance in Skills and the host model. The MCP kernel now records those conclusions
+  as advisory diagnostics while retaining hard failures only for structural authority,
+  current bytes, digests, scope ownership, concurrency, permissions, and recovery.
+- Made local delivery follow the evidence required by the actual Change route. Explicit
+  omissions and their rationale are preserved without imposing a fixed
+  Plan/Dev/Test/Review sequence on every archive.
+- Made completed Tasks explicitly reopenable without erasing their prior completion
+  commit or accepted history.
+
+### Fixed
+
+- Fixed nonexistent or mismatched Task/Change checkpoint scopes creating ghost
+  checkpoint authority; invalid scopes now fail before any Context or checkpoint write.
+- Fixed shallow or contradictory evidence declarations being accepted without checking
+  current managed artifact authority and stable file bytes.
+- Fixed baseline semantic gaps, missing optional research, and `not_run` verification
+  being misrepresented as mechanical authority failures.
+- Fixed installed Change revision paths depending on source-only semantic supervisor
+  modules excluded from the npm package.
+- Fixed Hooks, Skills, templates, and packaged documentation disagreeing about advisory
+  diagnostics, adaptive delivery, and the persistence/safety-kernel boundary.
+
+## [0.24.0] — 2026-07-30
+
+### Added
+
+- Added normalized Decision Records, reversible Stage Checkpoints, bounded Context
+  Envelopes, and immutable Worker Packets as the shared evidence and handoff model
+  across Skills, Hooks, agents, SQLite, and tracked `.ultra` artifacts.
+- Added a native Grok Build plugin so Claude Code, Codex, OpenCode, Kimi Code, and
+  Grok Build share the same eleven explicit workflows and seven-tool MCP kernel.
+- Added schema 22 backup-first migration and real-history compatibility for v4.4,
+  v4.5, v0.22, and v0.23 state and team-ledger formats.
+- Added packaged `better-sqlite3` provenance, platform and Node ABI verification,
+  and durable Doctor and archive workers for every supported host.
+
+### Changed
+
+- Completed the MCP boundary reduction: Skills own adaptive semantic procedure;
+  MCP owns persistence, identity, transactions, leases, paths, recovery, and
+  irreversible safety; Hooks only observe or inject bounded context; agents consume
+  immutable Worker Packets without writing SQLite authority.
+- Folded Plan artifact publication into the accepted Plan checkpoint so a later
+  export cannot invalidate its own authority.
+- Replaced semantic supervisor failures with mutable diagnostics and repairable
+  drafts. Only corruption, unsafe paths, concurrency conflicts, permission failures,
+  and irreversible external effects remain hard blockers.
+- Made `ultra.context`, `ultra.sync`, and `ultra.doctor` own their inspection and
+  repair preflight so an older valid ledger cannot block the tools required to
+  migrate it.
+- Reduced packaged and documented MCP contracts to the exact seven public tools;
+  removed the retired fine-grained schemas, fixtures, and command bypasses.
+
+### Fixed
+
+- Fixed accepted or stale workflow runs becoming permanently self-locked after an
+  artifact changed, and made reversible stages reopenable without rewriting
+  immutable accepted history.
+- Fixed v0.23 team ledgers using `research_run_id` being rejected under the newer
+  `research_checkpoint_id` digest contract.
+- Fixed native SQLite drivers and Doctor workers being absent or unresolved in
+  installed plugins.
+- Fixed session acquisition, archive recovery, Context identity, and Worker Packet
+  cleanup paths leaving partial authority after failure.
+- Fixed installed interaction guidance failing to render each host's native question
+  surface while keeping canonical Skills host-neutral.
+
 ## [0.23.0] — 2026-07-30
 
 ### Added

package/README.md

@@ -2,8 +2,8 @@
 
 **An adaptive delivery harness for AI coding agents.**
 
-Ultra Builder Pro helps Claude Code, Codex, OpenCode, and Kimi Code carry a
-software project from an unclear request to a verified, recoverable delivery.
+Ultra Builder Pro helps Claude Code, Codex, OpenCode, Kimi Code, and Grok Build
+carry a software project from an unclear request to a verified, recoverable delivery.
 It keeps the user and the agent aligned, preserves project authority across
 sessions, and prevents specifications from quietly drifting away from the code.
 
@@ -44,12 +44,14 @@ Ultra Builder Pro addresses those gaps with four ideas:
    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 checkout-local
-   lifecycle, decisions, workflows, evidence digests, sessions, incidents, and
+   lifecycle facts, decisions, checkpoints, 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.
+4. **Adaptive delivery.** The host model evaluates the evidence produced by the
+   actual Change route, explicitly records any omitted capability and its rationale,
+   and asks the owner to accept the local handoff. MCP validates current managed
+   authority and archive integrity rather than requiring a fixed stage sequence.
 
 For example, if the user asks an agent to add organization SSO to an existing
 application, Ultra helps the agent inspect the real authentication path, capture
@@ -65,13 +67,13 @@ 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"]
+        UI["Host-native interaction<br/>Claude Code / Codex / OpenCode / Kimi Code / Grok Build"]
         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"]
+    MCP["Ultra MCP safety kernel<br/>exactly 7 public tools"]
     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,14 +105,14 @@ 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 checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery |
+| **Ultra MCP** | Structure/current-byte validation, caller-declared checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery; never semantic completeness or route selection |
 | **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 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 MCP does not replace the model's judgment, judge completion, or pre-authorize a
+semantic route. It reports diagnostics and safely commits the model's explicit
+checkpoint/archive handoff. 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
 
@@ -120,16 +122,15 @@ The public model-facing surface is intentionally small:
 |---|---|
 | `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.checkpoint` | Commit one caller-declared stage checkpoint after structural, byte, digest, and publication validation |
 | `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.archive` | Persist one explicit local delivery handoff 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.
+Retired fine-grained operation names are neither discoverable nor callable. 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:
 
@@ -165,8 +166,9 @@ and effects—not chain-of-thought, raw prompts, transcripts, or UI receipts.
 
 ## What you get
 
-- Native plugins for **Claude Code**, **OpenCode**, **Codex**, and **Kimi Code**.
-- One workflow vocabulary across all four hosts.
+- Native plugins for **Claude Code**, **OpenCode**, **Codex**, **Kimi Code**, and
+  **Grok Build**.
+- One workflow vocabulary across all five hosts.
 - Deterministic initialization for new, existing, monorepo, and older Ultra
   projects.
 - Evidence-backed greenfield research and brownfield adoption.
@@ -218,6 +220,7 @@ npx --yes ultra-builder-pro-cli@latest --claude --global
 npx --yes ultra-builder-pro-cli@latest --opencode --global
 npx --yes ultra-builder-pro-cli@latest --codex --global
 npx --yes ultra-builder-pro-cli@latest --kimi --global
+npx --yes ultra-builder-pro-cli@latest --grok --global
 ```
 
 Use `--local` instead of `--global` to install into the current project's host
@@ -282,7 +285,7 @@ resolves observable facts itself and asks for material product decisions as
 needed. Once the evidence and specifications are accurate, the user approves
 the baseline.
 
-The common path after baseline approval is:
+One common full-depth path after baseline approval is:
 
 ```text
 ultra-change
@@ -294,11 +297,14 @@ ultra-change
   -> ultra-deliver
 ```
 
-Each public workflow is explicitly invoked rather than auto-chained. Thinking and
-research coverage are adaptive, and verification depth is risk-selected, but every
-Change reaches a current plan, DB-backed task contract, and role-scoped context before
-development. “Direct Build” skips Research only; it does not bypass Plan, Task, or
-Context authority.
+Each public workflow is explicitly invoked rather than auto-chained. The example is a
+recommended route for a normal implementation Change, not an archive state machine.
+Thinking and research coverage are adaptive, verification depth is risk-selected, and
+the host may omit or repeat a capability when the actual Change makes that appropriate,
+provided the delivery handoff names the omission and its rationale. Any implementation
+task still requires a current plan, DB-backed task contract, and role-scoped context.
+“Direct Build” skips Research only; it does not bypass Plan, Task, or Context authority
+when development is performed.
 
 ### 2. Adopt an existing project
 
@@ -364,9 +370,12 @@ must be reconciled against the current Change authority.
 
 ### 4. Deliver and continue
 
-`ultra-deliver` verifies that implementation, acceptance evidence, testing,
-review findings, specification learning, and baseline reconciliation agree. It
-then archives the local Ultra change authority.
+`ultra-deliver` asks the host model to assess the current managed evidence for the
+route the Change actually took. The handoff explicitly records any omitted capability
+and its evidence-based rationale; the owner decides whether that semantic packet is
+sufficient. MCP then validates paths, digests, reconciliation structure, idempotency,
+and recoverability before archiving the local Ultra change authority. It does not
+require every Change to pass through a fixed Research/Plan/Dev/Test/Review sequence.
 
 Delivery does **not** grant permission to commit, push, publish, tag, deploy, or
 perform another external effect. Those actions remain separate and require the
@@ -429,11 +438,16 @@ flowchart TD
     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"]
+    TASKS -->|"No"| ASSESS{"What evidence does this Change still need?"}
+    ROUTE -->|"Accepted handoff already has sufficient evidence"| DELIVER["ultra-deliver"]
+    ASSESS -->|"Risk-selected verification"| TEST["ultra-test<br/>risk-selected formal verification"]
+    ASSESS -->|"Independent review"| REVIEW["ultra-review<br/>specification fidelity and engineering quality"]
+    ASSESS -->|"Caller accepts current evidence and explicit omissions"| DELIVER
     TEST -->|"Failed or incomplete"| DEV
-    TEST -->|"Passing"| REVIEW["ultra-review<br/>specification fidelity and engineering quality"]
+    TEST -->|"Review is warranted"| REVIEW
+    TEST -->|"Caller accepts current evidence and explicit omissions"| DELIVER
     REVIEW -->|"Changes required"| DEV
-    REVIEW -->|"Approved"| DELIVER["ultra-deliver"]
+    REVIEW -->|"Approved"| DELIVER
     DELIVER --> ARCHIVE["Reconcile specifications<br/>apply the Change overlay and archive evidence"]
     ARCHIVE --> NEXT{"Continue"}
     NEXT -->|"Next outcome"| CHANGE
@@ -454,7 +468,7 @@ health without selecting product intent.
 ```text
 .ultra/
   .runtime/                # local mutable state; ignored by Git
-    state.db               # lifecycle, index, transition, and freshness authority
+    state.db               # facts, indexes, checkpoints, leases, CAS, and recovery
     checkpoint.json        # advisory recovery projection
     projections/           # generated local task and task-context views
     backups/               # verified migration and recovery snapshots
@@ -463,17 +477,18 @@ health without selecting product intent.
     worktrees/             # registered local Git worktrees
     telemetry/             # local operational telemetry
   specs/                   # digest-bound product and architecture baseline
+  decisions/baseline/      # normalized accepted baseline decisions
   changes/
     active/<id>/           # all current Change semantics and evidence
       intent.md            # accepted Change Contract
-      findings.md          # durable Change findings
+      decisions/           # normalized accepted Change decisions
       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
+      contexts/            # immutable canonical Context Envelopes
       test/                # Change-scoped test reports
       review/              # Change-scoped review workers and summary
       delivery/            # Change-scoped delivery evidence
@@ -584,9 +599,10 @@ host's existing model session.
   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.
+- **A draft checkpoint reports warnings:** the model keeps them visible and decides
+  whether to investigate, revise, defer with rationale, or accept. If a checkpoint is
+  rejected for a structural, digest, path, publication, or concurrency conflict, fix
+  the same mutable draft and retry; no hidden workflow state must be cancelled first.
 - **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`.
@@ -616,7 +632,7 @@ and `test:rest`.
 |---|---|
 | [Architecture](./docs/ARCHITECTURE.md) | Components, authority boundaries, and live integration paths |
 | [Workflow Lifecycle](./docs/WORKFLOW-LIFECYCLE.md) | Command ownership, transitions, invalidation, recovery, and convergence |
-| [Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) | Claude Code, OpenCode, Codex, and Kimi presentation details |
+| [Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) | Claude Code, OpenCode, Codex, Kimi Code, and Grok Build presentation details |
 | [Legacy CLI Crosswalk](./docs/LEGACY-CLI-CROSSWALK.md) | What was preserved, strengthened, or replaced from the original Ultra Builder Pro |
 | [Agent Context](./docs/AGENT-CONTEXT.md) | Context Manifest and host-agent execution contract |
 | [Plugin Isolation Contract](./docs/PLUGIN-ISOLATION-CONTRACT.md) | Plugin ownership, explicit activation, idle behavior, and user-instruction isolation |