ultra-builder-pro-cli 0.25.1 → 0.26.1

package/README.md

@@ -1,655 +1,293 @@
 # Ultra Builder Pro
 
-**An adaptive delivery harness for AI coding agents.**
+Ultra Builder Pro is a file-first engineering workflow for Claude Code, Codex,
+OpenCode, Kimi Code, and Grok Build. It keeps product intent, specifications, task
+contracts, evidence, decisions, and recovery notes in the repository, so a different
+session or host can continue by reading files and Git.
 
-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.
-
-It is not another model and it is not a rigid step-by-step autopilot. The active
-host agent still investigates, reasons, recommends, and implements. Ultra adds
-the durable workflow state, evidence gates, recovery paths, and host-native
-tools needed to make that work dependable over time.
-
-<div align="center">
-
-[![npm](https://img.shields.io/npm/v/ultra-builder-pro-cli?label=npm)](https://www.npmjs.com/package/ultra-builder-pro-cli)
-[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#development-and-verification)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
-
-</div>
+The host model remains the engineer. Ultra supplies reusable methods and checkable
+artifacts; it does not replace reasoning with a workflow engine.
 
 ## Why it exists
 
-AI coding works well inside one conversation. Real projects last much longer.
-After several sessions, teams commonly find that:
-
-- the agent no longer knows which decisions are authoritative;
-- implementation changed but product and architecture documents did not;
-- a new session repeats research or asks the same questions again;
-- an existing codebase is treated like a blank new product;
-- a rigid workflow blocks reasonable work, while an unstructured workflow loses
-  traceability;
-- “tests passed” or “work completed” cannot be tied back to the exact change,
-  task, commit, and acceptance criteria.
-
-Ultra Builder Pro addresses those gaps with four ideas:
-
-1. **Adaptive workflow, not a fixed pipeline.** MCP exposes valid capabilities
-   and hard recovery requirements. The host model recommends the next semantic
-   action from the user's goal and current evidence.
-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 checkout-local
-   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. **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
-the intended compatibility and recovery contract, ask only the unresolved
-product decision, plan and implement against current evidence, update affected
-specifications, and preserve the exact verification and review result. A later
-session resumes from that authority instead of reconstructing it from chat.
-
-## The mental model
-
-```mermaid
-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 / 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/>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"]
-    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
-```
+Long agentic changes tend to fail in four repeatable ways:
 
-The responsibility split is deliberate:
+- intent is paraphrased until the delivered product no longer matches the owner;
+- a locally green layer is mistaken for a working end-to-end path;
+- context loss turns an interrupted task into archaeology;
+- safety mechanisms start deciding product meaning and trap the primary workflow.
 
-| Owner | Responsibility |
-|---|---|
-| **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** | 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 |
+Ultra addresses those failures with short owner-readable files, progressive Skills,
+real verification evidence, and Git recovery. There is no database, MCP server,
+semantic state machine, generated prompt projection, or background daemon.
 
-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.
+## Product surface
 
-### The seven-tool MCP kernel
+The package installs exactly fourteen Skills in three roles.
 
-The public model-facing surface is intentionally small:
+### Owner-invoked workflows
 
-| Tool | Responsibility |
+| Skill | Outcome |
 |---|---|
-| `ultra.context` | Read the complete current spine without side effects |
-| `ultra.record` | Batch typed draft facts and events with idempotency |
-| `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` | Persist one explicit local delivery handoff through the recoverable filesystem/DB boundary |
-| `ultra.doctor` | Inspect or repair mechanical health, backup first |
-
-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.
+| `ultra-init` | Establish the project skeleton and one-line north star |
+| `ultra-research` | Verify external claims and refresh specifications |
+| `ultra-change` | Reconcile a requested change against current product truth |
+| `ultra-plan` | Write tracer-bullet tasks, contexts, dependencies, and seams |
+| `ultra-dev` | Implement one task through red/green development and six evidence dimensions |
+| `ultra-test` | Audit whole-system wiring, E2E behavior, performance, and security |
+| `ultra-deliver` | Reconcile, review, document, and archive a completed Change |
+| `ultra-delegate` | Run a bounded instruction through another supported CLI |
+
+### Model-invoked disciplines
+
+| Skill | Reused method |
+|---|---|
+| `ultra-grilling` | Draw out incomplete owner intent one material question at a time |
+| `ultra-domain-modeling` | Maintain precise ubiquitous language in `CONTEXT.md` |
+| `ultra-tdd` | Prove one confirmed seam red, then green |
+| `ultra-review` | Run six independent review lenses and synthesize findings |
+| `ultra-think` | Stress-test consequential decisions and record durable results |
+
+`ultra-status` is the single router. It infers the current route from project files,
+Git, and installation health without mutating the workflow.
+
+Public workflows are explicitly selected by the owner. One public workflow can
+recommend the next one, but does not launch it. Model-invoked disciplines remain
+available to the host model and are not separate user routes. The model selects one
+when the active task presents its trigger: incomplete intent uses grilling, competing
+terms use domain modeling, an accepted seam uses TDD, review-ready evidence uses
+review, and a consequential unresolved decision uses think. A host with native bounded
+subagents may parallelize review lenses; another host runs the same lens assets
+sequentially.
+
+### What happened to the original Agents
+
+v0.26 does not install a custom `agents/` projection. The old review workers became the
+six focused files under `ultra-review/references/`; review coordination and synthesis
+belong to the parent `ultra-review` Skill. The old debugger procedure lives under
+`ultra-dev/references/debugging.md`, and test execution lives under
+`ultra-tdd/references/test-execution.md`. These are assets of their Skills and therefore
+travel to all five hosts. They preserve a bounded role without pretending that every
+host exposes the same custom-agent API.
+
+## Project authority
+
+A new project uses this shape:
 
-Rejected semantic attempts remain visible as bounded `ultra_kernel_attempt` audit
-diagnostics in the next `ultra.context`; they do not create rejected authority.
-`_ultra.projection_commit` describes only generated-view processing, never semantic
-acceptance. The production Change API has no legacy/current mode switch.
+```text
+CONTEXT.md
+.ultra/
+├── .gitignore                  # ignores only derived Ultra paths
+├── north-star.md
+├── tasks.json
+├── test-report.json
+├── specs/
+│   ├── product.md
+│   ├── architecture.md
+│   ├── discovery.md
+│   └── research-distillate.md
+├── changes/
+│   ├── active/<change-id>/{intent.md,delivery.md}
+│   └── archive/<change-id>/intent.md
+├── contexts/<task-id>.md
+├── decisions/<decision-id>.md
+├── evidence/<task-id>/...
+└── research/<run-id>/...
+```
 
-The enforcement gradient is:
+Canonical semantic facts live in those files. Git provides history, comparison,
+rollback, and archive moves. The following are derived and can be deleted or rebuilt:
 
 ```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
+.ultra/.runtime/
+.ultra/progress/
+.ultra/reviews/
 ```
 
-### 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"]
-```
+See [Artifact Authority](docs/ARTIFACT-AUTHORITY.md) for writer, reader, promotion,
+staleness, and recovery rules.
 
-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
-
-- 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.
-- A durable Change Contract for every ongoing feature, fix, refactor, or
-  incident.
-- Context compilation that detects stale plans, tasks, references, and
-  specifications.
-- Risk-selected testing and independent specification/engineering review.
-- Crash-safe sessions, worktree recovery, circuit breakers, and backup-first
-  state migration.
-- Read-only installation and project diagnostics.
-- Optional dependency-wave worker orchestration for already-approved plans.
-
-## When to use it
-
-Ultra Builder Pro is useful when:
-
-- a project will span multiple agent sessions;
-- more than one supported host may work on the same repository;
-- product or architecture specifications must stay synchronized with delivery;
-- an existing codebase needs a trustworthy baseline before new changes;
-- failures must be diagnosable and recoverable;
-- user decisions, agent reasoning, and mechanical enforcement need clear
-  boundaries.
-
-It is probably unnecessary for a disposable one-file experiment or a change
-that does not need durable project context.
+### Which route writes which document
 
-## Install
+| Route | Canonical write | Who consumes it next |
+|---|---|---|
+| `ultra-init` | north star and four specification skeletons; empty task and test ledgers | every later workflow and context Hook |
+| `ultra-research` | selected cited reports plus reconciled specifications and distillate | change, plan, and delivery |
+| `ultra-change` | one active `intent.md` with exact acceptance, seams, reconciliation, and recovery | plan, dev, test, review, status, delivery |
+| `ultra-plan` | `tasks.json`, one context per task, and Planning Posture in the active intent | dev and every resume path |
+| `ultra-dev` | source/tests, task evidence, synchronized task/context status, Completion and Resume Note | review, test, status, delivery |
+| `ultra-test` | the one current `test-report.json` bound to HEAD and worktree digest | status and delivery |
+| `ultra-deliver` | one `delivery.md`, reconciled specs/docs, then the archived Change directory | owner and future Change history |
+| `ultra-status` | none | recommends the smallest explicit route from current files |
+| `ultra-delegate` | derived runtime receipt plus an isolated worktree diff | primary host inspection and optional integration |
 
-Requirements:
+`ultra-domain-modeling` is the sole focused writer of `CONTEXT.md`; `ultra-think` writes
+a durable decision only after owner acceptance. Review packets, Hook progress, compact
+snapshots, and delegation receipts are derived evidence, not extra semantic documents.
 
-- Node.js 22 or newer;
-- Git for the normal project workflow;
-- Python 3 on a POSIX platform with `dir_fd` filesystem operations for
-  inode-pinned archive finalization and recovery;
-- one or more supported coding-agent hosts.
+## Install
 
-Install globally into all detected host configuration directories:
+Node.js 22 or newer is required.
 
 ```bash
-npx --yes ultra-builder-pro-cli@latest --all --global
-```
+# Current project, one host
+npx ultra-builder-pro-cli --claude --local
+npx ultra-builder-pro-cli --codex --local
 
-Or install only one host:
+# Global installation
+npx ultra-builder-pro-cli --opencode --global
+npx ultra-builder-pro-cli --kimi --global
+npx ultra-builder-pro-cli --grok --global
 
-```bash
-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
+# All supported hosts
+npx ultra-builder-pro-cli --all --global
 ```
 
-Use `--local` instead of `--global` to install into the current project's host
-configuration:
+Use the host's native Skill picker or invocation syntax to select an owner workflow.
+Codex exposes namespaced entries such as `$ultra-builder-pro:ultra-init`. The installed
+frontmatter and metadata keep user routes explicit and model disciplines implicit.
 
-```bash
-npx --yes ultra-builder-pro-cli@latest --all --local
-```
+### Diagnose, update, and uninstall
 
-Verify the installation without changing it:
+Installation is managed, atomic, and provenance-checked.
 
 ```bash
-npx --yes ultra-builder-pro-cli@latest --all --global --doctor
-npx --yes ultra-builder-pro-cli@latest --all --global --doctor --json
-```
+# Re-running install updates the managed artifact
+npx ultra-builder-pro-cli --codex --global
 
-After installing or upgrading, start a new Claude Code, OpenCode, or Codex
-session. In Kimi Code, run `/reload` or start a new session.
+# Read-only diagnosis
+npx ultra-builder-pro-cli --all --global --doctor --json
 
-Plugin installation, update, doctor, and uninstall never mutate durable user
-instructions such as `CLAUDE.md` or `AGENTS.md`. Ultra policy stays in the plugin
-and becomes active only after an explicit workflow invocation. Existing legacy
-Ultra marker blocks in a user handbook are left untouched for the owner to review;
-the plugin neither claims nor silently deletes user-authored content.
+# Remove only managed Ultra assets
+npx ultra-builder-pro-cli --all --global --uninstall
+```
 
-### Host invocation
+`--config-dir <path>` isolates both the primary config and host-owned sidecars. It is
+the safe choice for tests and does not fall through to the real home directory. When
+more than one host is selected, each host receives `<path>/<runtime>` so their native
+layouts cannot overwrite one another.
 
-| Host | Example |
-|---|---|
-| Claude Code | `/ultra-builder-pro:ultra-init` |
-| OpenCode | `/ultra-init` |
-| Codex | `$ultra-builder-pro:ultra-init` |
-| Kimi Code | `/ultra-builder-pro:ultra-init` |
+Uninstall removes the managed plugin and prunes only empty config shells that were
+absent before the first install. Pre-existing registries, directories, symlinks, and
+any path containing owner data are preserved.
 
-The same naming applies to `ultra-research`, `ultra-change`, `ultra-plan`,
-`ultra-dev`, `ultra-test`, `ultra-review`, `ultra-deliver`, `ultra-status`,
-`ultra-think`, and `ultra-doctor`.
+Kimi Code and Grok Build currently expose user-scoped plugins only, so `--local`
+rejects them before mutation. Claude Code, Codex, and OpenCode support project-local
+installation; all five support managed global installation and isolated
+`--config-dir` verification.
 
-See the
-[Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) for exact
-host-specific presentation and lifecycle differences.
+## Typical workflow
 
-## How to use it
+1. Select `ultra-init` once. It writes the skeleton, records the owner's one-line goal,
+   initializes Git when needed, and recommends the next route.
+2. Select `ultra-research` when a product or architecture claim needs evidence.
+3. Select `ultra-change` for the requested outcome and reconcile it against current
+   specifications before planning.
+4. Select `ultra-plan` to confirm public seams and produce resumable tracer-bullet tasks.
+5. Select `ultra-dev` for one task at a time. Each task leaves a Completion entry,
+   evidence, and a closing Resume Note.
+6. Select `ultra-test` once the ledger is complete. Local green tests do not substitute
+   for wiring and E2E proof.
+7. Select `ultra-deliver` to run aggregate review, reconcile documentation, and archive
+   the Change. Commit, push, tag, publication, and deployment remain separately
+   authorized effects.
 
-### 1. Start a new project
+At any point, `ultra-status` can reconstruct the current position. A fresh session or
+different host resumes by reading `.ultra/tasks.json`, the selected `context_file`, its
+`## Resume Note`, `CONTEXT.md`, relevant decisions, the active Change, and Git.
 
-From the project root, invoke `ultra-init`.
+## Three independent integration defences
 
-Initialization:
+The workflow does not treat “tests pass” as an end-to-end verdict.
 
-- identifies the repository root and scope;
-- classifies the repository as greenfield, brownfield, or migrated;
-- initializes Git when needed;
-- creates `.ultra/` and schema 20 project authority;
-- verifies that the scaffold and database can be read back;
-- completes without silently starting research, creating a commit, adding a
-  remote, or pushing anything.
+- `ultra-plan` rejects horizontal feature slicing and confirms observable seams.
+- `ultra-dev` records tests, persistence, feature flags, vertical execution, and spec
+  trace as six separate observations.
+- `ultra-test` searches changed exports for real non-test consumers and runs the
+  smallest primary flow through its boundary.
 
-Then explicitly invoke `ultra-research`. For a new product, the agent evaluates
-the complete research catalog but executes only the areas that matter. It
-resolves observable facts itself and asks for material product decisions as
-needed. Once the evidence and specifications are accurate, the user approves
-the baseline.
+Each defence can report a defect independently. The reports are sensors, not semantic
+gates; the model and owner decide the response without erasing evidence.
 
-One common full-depth path after baseline approval is:
+## Hooks
 
-```text
-ultra-change
-  -> optional ultra-think or bounded ultra-research
-  -> ultra-plan
-  -> ultra-dev
-  -> risk-selected ultra-test
-  -> ultra-review
-  -> ultra-deliver
-```
+Five optional hooks accelerate file reading and protect a narrow effect boundary:
 
-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
-
-Run the same `ultra-init` entry point. Ultra detects delivered-system evidence
-such as application source, APIs, persistence, tests, or deployment
-configuration and classifies the repository as brownfield.
-
-Brownfield adoption does not ask the agent to invent a new MVP or rewrite the
-product story. It builds a current-system baseline from:
-
-- observable code and runtime behavior;
-- existing product and architecture documents;
-- build, lint, type-check, and test results;
-- APIs, data, permissions, integrations, deployment, and recovery seams;
-- known failures, documentation drift, technical debt, and unresolved unknowns.
-
-During `ultra-research`, the host model inspects current evidence and recommends
-the smallest sufficient route. The owner selects, modifies, delegates, or
-defers it through the host-native question surface unless the current request
-already resolves the route. The normalized accepted coverage is then stored in
-`.ultra/.runtime/state.db`. Every included area receives one explicit disposition:
-
-- `execute` — produce fresh evidence;
-- `verify_existing` — validate an existing artifact;
-- `reuse` — reuse evidence that is still current;
-- `not_applicable` — exclude it with evidence and rationale;
-- `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 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
-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
-
-After the baseline is ready, start features, fixes, refactors, and incidents
-with `ultra-change`.
-
-`ultra-change` records the accepted outcome, scope, acceptance criteria,
-compatibility boundary, recovery strategy, documentation impact, risk profile,
-and research disposition. Capturing intent does not automatically start every
-downstream workflow.
-
-The host then recommends one valid capability:
-
-- `ultra-think` for a material unresolved decision or diagnosis;
-- bounded `ultra-research` for a real evidence gap;
-- `ultra-plan` for the required task decomposition and dependency planning boundary;
-- `ultra-dev` after the current plan has produced an executable task contract;
-- `ultra-status` when the user needs the current authority and available routes;
-- `ultra-doctor` when state or installation health is degraded.
-
-Semantic changes invalidate dependent tasks and compiled context. A stale task
-cannot be revived by flipping a status flag; its complete execution contract
-must be reconciled against the current Change authority.
-
-### 4. Deliver and continue
-
-`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
-user's explicit request.
-
-The next piece of daily work starts with a new `ultra-change`.
-
-## Core workflows
-
-| Workflow | Purpose |
+| Hook | Behavior |
 |---|---|
-| `ultra-init` | Classify the repository and create or recover project authority |
-| `ultra-research` | Build or refresh an evidence-backed baseline with adaptive coverage |
-| `ultra-think` | Resolve one material decision or perform bounded diagnosis |
-| `ultra-change` | Capture the durable contract for one feature, fix, refactor, or incident |
-| `ultra-plan` | Create current task contracts, dependencies, acceptance coverage, and execution context |
-| `ultra-dev` | Implement one owned vertical slice and record exact evidence |
-| `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 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. 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.
-
-Review and debug agents are evidence-only workers. They may inspect the assigned
-checkout and write their declared report, but they never edit source or commit
-authority. The primary host evaluates the evidence, applies any repair, and records
-the verified outcome.
-
-### 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"| 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 -->|"Review is warranted"| REVIEW
-    TEST -->|"Caller accepts current evidence and explicit omissions"| DELIVER
-    REVIEW -->|"Changes required"| DEV
-    REVIEW -->|"Approved"| 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"]
-```
+| `session_context.py` | Inject north star and current acceptance at session start |
+| `mid_workflow_recall.py` | Restate acceptance before relevant source operations |
+| `compact_context.py` | Save and restore a disposable Git/file snapshot |
+| `post_edit_guard.py` | Record mechanical evidence observations after edits |
+| `block_dangerous_commands.py` | Advise on additive protected-branch publication; deny history rewrites and named destructive shell effects until the exact command is authorized |
 
-“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.
+All five exit silently when `.ultra/` is absent. Details are in
+[Plugin Isolation](docs/PLUGIN-ISOLATION-CONTRACT.md).
 
-## What lives in `.ultra/`
+## Delegation
 
-```text
-.ultra/
-  .runtime/                # local mutable state; ignored by Git
-    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
-    collab/                # local collaboration scratch
-    sessions/              # local leases and session runtime
-    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
-      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 canonical Context Envelopes
-      test/                # Change-scoped test reports
-      review/              # Change-scoped review workers and summary
-      delivery/            # Change-scoped delivery evidence
-    archive/               # immutable delivered Change artifacts
-  docs/research/           # baseline-only research evidence
-  reports/templates/       # blank report schemas; never delivery evidence
-  tasks/
-    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
-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
-graph systems remain separate providers; Ultra may store bounded metadata
-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.
-
-## Optional orchestration
-
-The normal workflow can be driven interactively by the host agent. For an
-already-approved plan, `ubp-orchestrator` can dispatch dependency-ready tasks
-into isolated Git worktrees:
+Delegation writes an immutable instruction and permission envelope, then starts the
+selected CLI in the background. Empty writable roots select native read-only mode;
+declared roots select bounded write mode. The model returns one schema-constrained final
+response; the launcher extracts it from native structured output, validates the actual
+Git diff, and atomically publishes a terminal `finished`, `blocked`, or `failed` result
+beside the instruction.
 
 ```bash
-ubp-orchestrator execute-plan
+ubp delegate run --to codex \
+  --instruction .ultra/.runtime/delegations/D-01/instruction.md \
+  --permission .ultra/.runtime/delegations/D-01/permission.json \
+  --worktree .ultra/.runtime/worktrees/D-01
 ```
 
-The orchestrator is intentionally not a replacement for Ultra gates. A worker
-process exiting successfully does not complete a task. Task evidence, current
-dev state, testing, review, integration, and baseline reconciliation still have
-to converge. Worktrees with uncommitted or unintegrated work are preserved for
-recovery.
+Use `skills/ultra-delegate/scripts/delegate_wait.py` to wait for `result.json` without
+loading intermediate worker output into the parent context. Delegation grants no new
+authority; writable roots remain inside the worktree, and its permission file must
+declare zero external effects without widening the host sandbox.
 
-See [Architecture](./docs/ARCHITECTURE.md) and
-[Workflow Lifecycle](./docs/WORKFLOW-LIFECYCLE.md) before enabling automated
-worker execution or verified auto-merge.
+## Host support
 
-## CLI utilities
+| Host | Skills | Hooks | Managed lifecycle |
+|---|---:|---:|---|
+| Claude Code | 14 | 5 direct | install / doctor / update / uninstall |
+| Codex | 14 + native metadata | 5 through wire adapter | plugin + personal marketplace |
+| OpenCode | 14 | 5 through native JS plugin | bundle + skill directories |
+| Kimi Code | 14 | 5 through wire adapter | managed plugin registry |
+| Grok Build | 14 | 5 through wire adapter | native plugin registration when available |
 
-| Binary | Purpose |
-|---|---|
-| `ultra-builder-pro-cli` / `ubp` | Install, update, uninstall, and diagnose host plugins |
-| `ultra-tools` | Inspect and maintain project tasks, sessions, state, migration, and recovery |
-| `ubp-orchestrator` | Execute current dependency waves or supervise configured workers |
+See [Runtime Compatibility](docs/RUNTIME-COMPAT-MATRIX.md) for exact paths and host
+limitations.
 
-Useful read-only checks:
+## Development
 
 ```bash
-ultra-tools status
-ultra-tools status --cost --since 24h
-ultra-tools session list --json
-ultra-tools system doctor
-```
+# Node contracts, package smoke, host adapters, delegation, and Skills
+npm run test:node
 
-Ultra MCP does not require `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or another
-model-provider key. It validates and persists structures derived by the active
-host's existing model session.
-
-## Troubleshooting
-
-- **Installed workflows are missing:** start a new host session. Kimi users can
-  run `/reload`.
-- **An installed Hook or MCP path is stale:** run
-  `npx --yes ultra-builder-pro-cli@latest --all --global --doctor --json`, then
-  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.
-- **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 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`.
-
-For exact recovery commands and invariants, see
-[Workflow Lifecycle](./docs/WORKFLOW-LIFECYCLE.md) and
-[State DB Access Policy](./docs/STATE-DB-ACCESS-POLICY.md).
-
-## Development and verification
-
-```bash
-npm install
-npm run test:all
+# File-first hook behavior and wire wrappers
 npm run test:hooks
-npm audit --omit=dev --audit-level=high
 
 # Complete release gate
 npm run verify:release
+
+# Inspect the exact publish artifact
+npm pack --dry-run --json
 ```
 
-Individual Node suites are available as `test:state`, `test:orch`, `test:spec`,
-and `test:rest`.
+Every changed Skill is also validated with the Codex Skill Creator validator. A changed
+Codex manifest is validated against the Plugin Creator schema. No release effect is
+implied by a green verification run.
 
 ## Documentation
 
-| Document | Purpose |
-|---|---|
-| [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, 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 |
-| [State DB Access Policy](./docs/STATE-DB-ACCESS-POLICY.md) | Multi-process authority and write rules |
-| [Roadmap](./docs/ROADMAP.md) | Current and historical delivery scope |
-| [Changelog](./CHANGELOG.md) | Release history |
+- [Philosophy](docs/PHILOSOPHY.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Artifact Authority](docs/ARTIFACT-AUTHORITY.md)
+- [Workflow Lifecycle](docs/WORKFLOW-LIFECYCLE.md)
+- [Skill Authoring](docs/SKILL-AUTHORING.md)
+- [Plugin Isolation](docs/PLUGIN-ISOLATION-CONTRACT.md)
+- [Runtime Compatibility](docs/RUNTIME-COMPAT-MATRIX.md)
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+[MIT](LICENSE)