ultra-builder-pro-cli 0.23.0 → 0.24.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.23.0",
-  "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, and Kimi Code, with project-local MCP authority and lifecycle recovery.",
+  "version": "0.24.0",
+  "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build, with a project-local MCP persistence and safety kernel.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
     "ubp": "bin/install.js",
@@ -61,13 +61,19 @@
     "!**/*.pyo",
     "!**/*.test.cjs",
     "!**/tests/**",
-    "!mcp-server/test-support/**"
+    "!mcp-server/test-support/**",
+    "!mcp-server/lib/workflow-state.cjs",
+    "!mcp-server/lib/decision-dialogue.cjs",
+    "!mcp-server/lib/context-spine.cjs",
+    "!mcp-server/lib/project-breadcrumb.cjs",
+    "!mcp-server/lib/spec-learning.cjs"
   ],
   "keywords": [
     "claude-code",
     "opencode",
     "codex",
     "kimi-code",
+    "grok-build",
     "agent",
     "cli",
     "multi-runtime",
@@ -101,6 +107,7 @@
     "prepublishOnly": "npm run verify:release",
     "install:claude": "node bin/install.js --claude --local",
     "install:kimi": "node bin/install.js --kimi --local",
+    "install:grok": "node bin/install.js --grok --local",
     "install:all": "node bin/install.js --all --local"
   },
   "dependencies": {

package/skills/ultra-change/SKILL.md

@@ -22,24 +22,25 @@ checkpoint accepts the downstream authority.
    a choice changes accepted product intent, compatibility, security, material cost,
    external effects, or recovery.
 
-Read `../ultra-think/references/decision-dialogue.md` before asking. MCP may report
+Read `../ultra-think/references/interaction-boundary.md` before asking. MCP may report
 contradictory risk fields, but the model and owner choose the semantic correction.
 
 ## Record the contract
 
-Use one `ultra.record` batch for `change.create` or `change.update`, relevant
-`decision.*`, and `change.delta` when the delta is already known. Every entry carries
-a stable idempotency key. Read the result through `ultra.context`.
+Use one `ultra.record` batch with `change_contract / open` or
+`change_contract / revise`, relevant `decision / accept`, and `artifact / bind` for
+an already-known typed delta. Every entry carries a stable idempotency key. Read the
+result through `ultra.context`.
 
 Keep every Change-owned semantic artifact below
 `.ultra/changes/active/<change-id>/`. Standard and major Changes require a typed delta
 before planning. A true no-semantic-change case records an explicit reason instead of
 manufacturing a mutation.
 
-Changing accepted intent reopens the draft and makes only genuinely dependent evidence
-stale. `ready` is not an absorbing state. A semantic rejection returns diagnostics;
-repair and retry the same draft. Use `workflow.abandon` only to preserve and cancel an
-attempt intentionally.
+Changing accepted intent creates a new accepted checkpoint revision and makes only
+genuinely dependent evidence stale. Readiness is derived, not a stored absorbing
+state. A semantic rejection returns diagnostics; repair and retry the same draft.
+Use `change_contract / cancel` only when the owner intentionally abandons the Change.
 
 Publish the durable Change contract with `ultra.sync { action: publish }` when it is a
 useful team handoff. Recommend bounded `ultra-research` for a real evidence gap or

package/skills/ultra-deliver/SKILL.md

@@ -21,8 +21,8 @@ publication, deployment, or another external effect.
    worktree/context digests, local checks, rollback guidance, and timestamp; it contains
    no release decision.
 
-Use one `ultra.record` batch for the reconciliation, report artifact, learning
-resolutions, and other durable facts.
+Use one typed `ultra.record` batch for `artifact / bind`, any normalized
+`decision / accept`, and bounded `event / append` facts.
 
 ## Archive once
 
@@ -35,7 +35,7 @@ internally:
 - derives convergence from current dev, test, review, delta, docs, and checkout;
 - applies the overlay and archive through the recoverable filesystem/DB transaction;
 - rebinds registered artifacts into a self-contained archive;
-- completes the durable delivery checkpoint;
+- accepts one immutable delivery checkpoint revision;
 - publishes the updated team checkpoint.
 
 A semantic rejection returns mutable blockers. Repair the same packet and retry. A

package/skills/ultra-dev/SKILL.md

@@ -5,17 +5,21 @@ description: Implement one authoritative Ultra task through a fresh-context, tes
 
 # Implement one task
 
-The model owns code reasoning and edits. Ultra owns the durable task contract, current
-Context Manifest, execution lease, evidence references, and checkpoint.
+The model owns code reasoning and edits. Ultra owns the durable task contract,
+canonical Context Envelope, execution lease, immutable Worker Packet, evidence
+references, and checkpoint.
 
 ## Bind execution
 
 1. Call `ultra.context { stage: dev, scope: { change_id, task_id }, detail: full }`.
 2. Import a newer team checkpoint with `ultra.sync`; stop on a real same-record or
    active-session conflict.
-3. Reuse a valid lease or call `ultra.session { action: admission }`, then
-   `ultra.session { action: acquire }`. Work only in the returned worktree.
-4. Confirm purpose, acceptance, dependencies, public seam, verification command,
+3. Reuse a valid lease or call `ultra.session { action: acquire }`. Acquire atomically
+   performs admission, compiles or reuses the implementation Context Envelope, mints
+   the lease/worktree, and returns the immutable Worker Packet. A separate
+   `action: admission` is an optional read-only preview, not a prerequisite.
+4. Verify the returned packet digest, purpose, acceptance, dependencies, public seam,
+   exact output path/schema, verification command,
    non-goals, recovery, and required context refs. Update the task contract before
    implementation when accepted intent changed.
 
@@ -26,10 +30,13 @@ before changing logic. Implement the smallest complete vertical slice. Ask the o
 only when new evidence changes product intent, compatibility, security, material cost,
 external effects, or recovery.
 
-Use `ultra.record` batches for task status, bounded events, artifacts, decisions, and
-documentation candidates. Live ownership, `in_progress`, session ids, leases,
-worktrees, telemetry, and completion hashes remain local runtime state; durable task
-outcome and evidence may enter the team checkpoint.
+Use typed `ultra.record` entries for `task_outcome / start|block|complete`,
+`event / append`, `artifact / bind`, `decision / accept`, and corrected
+`task_contract / revise`. Every worker output must repeat the exact `packet_digest`;
+the parent registers it only after packet, output path, schema, and digest validation.
+Live ownership, `in_progress`, session ids, leases, worktrees, telemetry, and
+completion hashes remain local runtime state; durable task outcome and evidence may
+enter the team checkpoint.
 
 Run focused and adjacent risk-justified checks, then a task-scoped independent review.
 Fix blocking findings and refresh affected evidence.
@@ -37,8 +44,8 @@ Fix blocking findings and refresh affected evidence.
 ## Commit one semantic checkpoint
 
 Call `ultra.checkpoint` once with `stage: dev`, the exact Change/Task scope, evidence,
-and stable idempotency key. It compiles or reuses the implementation Context Manifest
-and validates the durable outcome. A rejection leaves the draft mutable.
+and stable idempotency key. It binds the exact Context Envelope and Worker Packet and
+reports outcome diagnostics. A rejection leaves the draft mutable.
 
 After acceptance, mark the task durably completed, publish with `ultra.sync`, and
 create at most one authorized local task commit containing code and semantic

package/skills/ultra-doctor/SKILL.md

@@ -30,8 +30,8 @@ journals, reconcile orphan sessions, and repair installed mechanical assets.
 
 It may not manufacture semantic evidence, import or publish a team checkpoint, replace
 a healthy baseline, resolve decisions, edit application code, or force a draft to
-accepted. Use `ultra.sync` for reviewed checkpoint import/publish and
-`workflow.abandon` through `ultra.record` for intentional draft cancellation.
+accepted. Use `ultra.sync` for reviewed checkpoint import/publish. Doctor never changes
+semantic checkpoint acceptance or Change intent.
 
 Preserve corrupt DB/WAL/SHM and dirty worktrees. Never patch plugin cache files by
 hand; reinstall through `ubp` and verify the installed manifest and hook targets.

package/skills/ultra-init/SKILL.md

@@ -23,17 +23,18 @@ capability.
 4. Ask the owner only when scope, healthy-authority replacement, destructive recovery,
    or another material choice cannot be derived. Reuse explicit intent.
 
-Read `../ultra-think/references/decision-dialogue.md` before asking a material
+Read `../ultra-think/references/interaction-boundary.md` before asking a material
 question.
 
 ## Initialize once
 
-Call `ultra.record` with one entry:
+Call `ultra.record` with one typed entry:
 
 ```text
-operation: task.init_project
-data: target_dir, project_name, mode=auto, git_mode=auto, optional scope
-idempotency_key: stable init attempt id
+kind: baseline
+action: initialize
+data: { target_dir, project_name, mode=auto, git_mode=auto, optional scope }
+idempotency_key: <stable init attempt id>
 ```
 
 This stateless bootstrap is the only `ultra.record` operation allowed before

package/skills/ultra-init/references/brownfield-adoption.md

@@ -66,7 +66,8 @@ ledger into hundreds of application tasks.
 
 ## Record authority
 
-Call `baseline.record` with full replacement arrays for:
+Use `ultra.record` with `kind: baseline`, `action: observe`, and full replacement
+arrays for:
 
 - scope and repository revision;
 - repository classification;
@@ -82,12 +83,14 @@ Use the server-returned revision, branch, worktree digest, and specification dig
 ## Obtain approval and converge
 
 Present scope, observed behavior, drift, known-red verification, unknowns, gaps, dirty
-worktree state, and material decisions to the owner. Call `baseline.converge` only after
-explicit approval. Set `accept_known_red` and `accept_dirty_worktree` only for the exact
-items the owner accepted.
+worktree state, and material decisions to the owner. Use `ultra.record` with
+`kind: baseline`, `action: accept` only after explicit approval. Set
+`accept_known_red` and `accept_dirty_worktree` only for the exact items the owner
+accepted.
 
 Resolve returned blockers through evidence or an owner decision, record the replacement
-snapshot, and retry. Adoption is complete only when `baseline.get` is `ready` and
-current, the gap ledger has no open blocker, and project doctor has no authority
-failure. Route all selected work through `ultra-change`, including work described by a
-legacy plan. Import its accepted intent into a current Change Contract before planning.
+snapshot, and retry. Adoption is complete only when `ultra.context` reports a current
+accepted baseline, the gap ledger has no open blocker, and project doctor has no
+authority failure. Route all selected work through `ultra-change`, including work
+described by a legacy plan. Import its accepted intent into a current Change Contract
+before planning.

package/skills/ultra-plan/SKILL.md

@@ -28,13 +28,14 @@ Large sources stay lazy. Use digest freshness for accepted inputs that must rema
 byte-current, existence for expected implementation targets, and advisory only when
 drift must be visible without blocking.
 
-Read `../ultra-think/references/decision-dialogue.md` before asking a material
+Read `../ultra-think/references/interaction-boundary.md` before asking a material
 question.
 
 ## Record and checkpoint
 
-Use one `ultra.record` batch for all `task.create` and necessary `task.update`
-operations. Read back the draft with `ultra.context`.
+Use one `ultra.record` batch with `task_contract / define` for new tasks and
+`task_contract / revise` for corrected contracts. Read back the draft with
+`ultra.context`.
 Never read or write `.ultra/tasks/tasks.json`; use `ultra.sync` for the Git team
 checkpoint, and never edit the local runtime projection directly.
 
@@ -47,13 +48,14 @@ payload: planning posture, optional approval already obtained, context budget/re
 idempotency_key: stable semantic Plan checkpoint id
 ```
 
-The checkpoint compiles or reuses the content-addressed Context Manifest, validates
-task coverage and dependencies, exports `plan.json` and `plan.md` once, completes the
-durable Plan, and publishes the team checkpoint. Do not export again after validation.
+The checkpoint compiles or reuses the content-addressed Context Envelope, derives
+coverage diagnostics, exports `plan.json` and `plan.md` inside the same recoverable
+publication, accepts one Plan revision, and publishes the team checkpoint. Do not
+export separately.
 
 If rejected, the same Plan draft stays mutable. Fix task contracts or evidence and
-retry. To discard it, record `workflow.abandon`; never edit SQLite or open a parallel
-run to escape a blocker.
+retry. To replace an accepted Plan, submit a new checkpoint revision; never edit
+SQLite or open a parallel run to escape a diagnostic.
 
 Return topology, executable slices, public seams, exact checks, checkpoint result, and
 the model's recommended execution order. Do not invoke `ultra-dev` automatically.

package/skills/ultra-research/SKILL.md

@@ -21,7 +21,7 @@ not a questionnaire or a step-by-step supervisor.
 5. Use the host-native question surface only for a material unresolved route. Reuse an
    explicit owner choice without asking again.
 
-Read `../ultra-think/references/decision-dialogue.md` before asking. Load only the
+Read `../ultra-think/references/interaction-boundary.md` before asking. Load only the
 reference files for research areas that actually apply.
 
 ## Investigate
@@ -34,10 +34,15 @@ For each selected area:
 - never store transcripts, hidden reasoning, raw provider payloads, or copied prompts;
 - record evidence, specification updates, decisions, deferrals, and consequences.
 
-Use one `ultra.record` batch for durable facts such as `artifact.record`,
-`decision.*`, `baseline.*`, `change.update`, or `change.delta`. Every entry needs a
-stable idempotency key. A rejected entry is a mutable diagnostic: fix the draft and
-retry; use `workflow.abandon` only when intentionally discarding that attempt.
+Use one `ultra.record` batch for typed durable facts:
+
+- `artifact / bind` for a managed research or specification artifact;
+- `decision / accept` for normalized owner intent;
+- `baseline / observe` or `baseline / accept` for baseline authority;
+- `change_contract / revise` for Change-bound findings.
+
+Every entry needs a stable idempotency key. A semantic rejection is a mutable
+diagnostic: correct the same draft and retry.
 
 ## Commit one research checkpoint
 
@@ -46,8 +51,8 @@ and their report outputs in `payload.steps`; include only work actually performe
 verified, reused, deferred with owner authority, or proved not applicable. Synthesis
 must always be present.
 
-For baseline research, record and converge the accepted baseline through
-`ultra.record`, then publish the team checkpoint with `ultra.sync { action: publish }`.
+For baseline research, update and accept the baseline through typed `ultra.record`
+entries, then publish the team checkpoint with `ultra.sync { action: publish }`.
 For Change-bound research, keep all findings and delta artifacts below the Change
 root and never edit accepted baseline specs directly.
 

package/skills/ultra-review/SKILL.md

@@ -21,12 +21,15 @@ Keep two independent verdict axes:
 5. Always run `review-spec`. Select the smallest engineering worker set that covers
    actual risk; record selected and excluded roles with rationale.
 
-Workers are read-only and use the host-native bounded-worker mechanism. Validate their
-artifacts with `scripts/review_wait.py` and
-`references/unified-schema.md`. Preserve every finding unchanged in `SUMMARY.json`;
-group duplicates only in the human summary.
-
-Register specialist and summary artifacts through one `ultra.record` batch.
+Use the current host's native bounded-worker mechanism. Workers are read-only and
+receive one immutable Worker Packet containing the exact Context Envelope, HEAD/diff,
+decisions, acceptance, output path/schema, and `packet_digest`. Validate their artifacts with `scripts/review_wait.py` and
+`references/unified-schema.md`; reject any output that does not echo the exact packet
+digest. Preserve every finding unchanged in `SUMMARY.json`; group duplicates only in
+the human summary.
+
+Register specialist and summary artifacts through one `ultra.record` batch using
+`artifact / bind`.
 
 ## Checkpoint
 

package/skills/ultra-review/references/unified-schema.md

@@ -10,6 +10,7 @@ return only a one-line acknowledgement to the parent.
   "$schema": "ultra-review-findings-v2",
   "agent": "review-code",
   "axis": "engineering_standards",
+  "packet_digest": "<sha256-of-exact-worker-packet>",
   "session": "<session-id>",
   "timestamp": "<ISO-8601>",
   "scope": {
@@ -74,6 +75,7 @@ preference as a defect. Preserve the source specialist's severity during coordin
   "head": "<full-git-head>",
   "worktree_digest": "<sha256-of-current-worktree>",
   "context_digest": "<sha256-of-recorded-review-context>",
+  "packet_digest": "<sha256-of-coordinator-worker-packet>",
   "status": "complete",
   "verdict": "REQUEST_CHANGES",
   "axes": {

package/skills/ultra-review/scripts/review_wait.py

@@ -66,6 +66,10 @@ def nonempty_string(value) -> bool:
     return isinstance(value, str) and bool(value.strip())
 
 
+def digest_string(value) -> bool:
+    return isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value) is not None
+
+
 def validate_finding(finding, artifact_axis: str, seen_ids):
     if not isinstance(finding, dict):
         return "finding must be an object"
@@ -97,6 +101,8 @@ def validate_specialist(data):
         return f"$schema must be {FINDINGS_SCHEMA}"
     if not nonempty_string(data.get("agent")):
         return "agent must be a non-empty string"
+    if not digest_string(data.get("packet_digest")):
+        return "packet_digest must be a lowercase SHA-256 digest"
     axis = data.get("axis")
     if axis not in AXES:
         return "axis must be spec_fidelity or engineering_standards"
@@ -197,6 +203,8 @@ def validate_summary(data):
     for field in ["session", "change_id", "head", "context_digest"]:
         if not nonempty_string(data.get(field)):
             return f"{field} must be a non-empty string"
+    if not digest_string(data.get("packet_digest")):
+        return "packet_digest must be a lowercase SHA-256 digest"
     if data.get("worktree_digest") is not None and not nonempty_string(data.get("worktree_digest")):
         return "worktree_digest must be null or a non-empty string"
     task_ids = data.get("task_ids")

package/skills/ultra-status/SKILL.md

@@ -20,14 +20,14 @@ Report:
 ```text
 Ultra: <healthy|degraded> · <branch>@<head|unborn|non-git>
 Baseline: <mode>/<status> · gaps=<open>/<blocking>
-Workflow drafts: <active|blocked|ready> · accepted checkpoints=<current|stale>
+Stage checkpoints: drafts=<count> · accepted=<current|stale|none>
 Change: <id/status|none> · delta/docs=<state>
 Task: <id/status|none> · Sessions: <active>
 Evidence: plan=<state> · test=<state> · review=<axes> · delivery=<state>
 Team checkpoint: <current|drifted|revalidation_required|missing|invalid>
 Blockers: <hard mechanical blockers or none>
 Warnings: <advisory semantic diagnostics or none>
-Host recommendation: <capability and concise rationale>
+Model recommendation: <capability and concise rationale>
 ```
 
 Treat warnings and failed draft checks as information, not mechanical orders. Only

package/skills/ultra-test/SKILL.md

@@ -20,10 +20,12 @@ generated projections are not evidence.
 5. Run repository-native commands and real boundaries. A bug or incident needs one
    deterministic red-to-green regression signal.
 
-Write an `ultra-test-report-v1` report below the owning Change. Bind exact acceptance
+When delegated, use the immutable Worker Packet supplied by the parent and echo its
+`packet_digest` in the report. Write an `ultra-test-report-v1` report below the owning
+Change. Bind exact acceptance
 ids, task ids, HEAD, worktree/context digests, commands, seams, failures, recovery,
 profile, timestamp, blockers, and evidence-derived verdict. Register it with
-`ultra.record` using `artifact.record`.
+`ultra.record` using `artifact / bind`.
 
 ## Checkpoint
 

package/skills/ultra-think/SKILL.md

@@ -18,20 +18,20 @@ project-bound decision that must survive interruption or control later work.
    implementation judgment, and unresolved owner choice.
 5. Stress-test the leading answer with its strongest failure path and recovery.
 
-Read `references/decision-dialogue.md`. Reuse a clear decision already present in the
+Read `references/interaction-boundary.md`. Reuse a clear decision already present in the
 request. Decide reversible delegated implementation details yourself. When owner
 authority is necessary, ask one dependent decision through the host-native question
 surface with a recommendation, decisive evidence, and the effect of the answer.
 
 ## Persist only the normalized result
 
-Use one `ultra.record` batch for `decision.thread_start`, `decision.open`, the
-appropriate resolve/delegate/defer/supersede operation, the owning artifact mutation,
-and `decision.complete` when they are all known. Store normalized decisions and
-artifact references, never transcripts or internal reasoning.
+Use one `ultra.record` batch with `decision / accept` and, when required,
+`artifact / bind` for the owning semantic document. A revised answer carries
+`supersedes_id`; accepted records remain immutable history. Store normalized decisions
+and artifact references, never transcripts or internal reasoning.
 
-A semantic rejection remains a mutable diagnostic. Correct the record or intentionally
-abandon the draft; do not invent a new decision merely to satisfy a state machine.
+A semantic rejection remains a mutable diagnostic. Correct the record; do not invent a
+new decision merely to satisfy a state machine.
 
 Return the conclusion, decisive evidence, uncertainty, affected authority, and the
 model's recommended next explicit capability. Thinking never performs unrelated

package/skills/ultra-think/references/interaction-boundary.md

@@ -0,0 +1,56 @@
+# Owner interaction boundary
+
+Use this reference only when a material choice remains after inspecting current
+authority and observable facts. Ultra does not require a ceremonial question before
+every write.
+
+## Responsibility split
+
+- The owner controls product intent, acceptance, non-goals, material tradeoffs, risk
+  acceptance, irreversible actions, external effects, and real-money commitments.
+- The host model investigates facts, recommends a direction, makes reversible
+  implementation judgments, and explains uncertainty.
+- Use the host-native question surface declared by the installed interaction contract;
+  prefer its structured form when the host exposes one.
+- `ultra.record` persists only the normalized result and its provenance.
+- MCP validates structure, identity, digests, CAS, leases, paths, and recovery. It does
+  not decide whether a product answer is good.
+
+## Interaction sequence
+
+1. Read `ultra.context` for the relevant scope.
+2. Inspect source, runtime, tests, accepted artifacts, and primary documentation.
+3. Reuse an explicit choice already present in the current request or an accepted
+   Decision Record.
+4. Decide a reversible delegated detail without asking.
+5. When owner authority is still required, ask one unresolved owner choice at a time
+   with:
+   - the recommendation;
+   - the discriminating evidence;
+   - the meaningful cost or failure mode;
+   - what changes when the answer changes.
+6. Normalize the answer into a deterministic Decision Record and persist it with
+   `ultra.record` using `kind: decision`, `action: accept`.
+7. Read `ultra.context` back and verify that the accepted decision is visible before
+   relying on it.
+
+## Decision Record
+
+Persist only:
+
+- normalized question;
+- recommendation and selected answer;
+- effects and non-goals;
+- owner, source, and bounded provenance;
+- applied artifact references;
+- supersession link when revising an earlier answer.
+
+Never persist raw transcripts, hidden reasoning, full prompts, UI receipts, or copied
+memory-provider payloads.
+
+## Revisions and interruptions
+
+Accepted decisions are immutable history. A changed answer creates a new Decision
+Record that supersedes the prior record. A cancelled question writes nothing. If a
+decision cannot be obtained, preserve the unresolved issue as a diagnostic or bounded
+event; do not invent an answer or block unrelated work.