ultra-builder-pro-cli 0.25.1 → 0.26.0

package/docs/PHILOSOPHY.md

@@ -0,0 +1,177 @@
+# Ultra Builder PHILOSOPHY (v0.26)
+
+**Authority**: This document defines the harness design philosophy. Every hook, Skill, template,
+and CLI behavior must be justifiable by these principles. Conflicts → cite the principle, not the
+rule.
+
+**Provenance**: Goals 1–4 and Commandments C1–C5 are carried forward unchanged in substance from
+Ultra Builder Pro v7.0, where they were derived from a 2026-04-30 system audit of real failures.
+Do not weaken any of them without a reproduced failure case.
+
+**Why exactly four goals and five commandments** — the counts are not sacred, the derivation
+rules are:
+
+- A **goal** is a class of systemic failure that has actually recurred, stated positively.
+  A fifth goal requires naming a fifth recurring failure class that none of these four covers.
+- A **commandment** is a rule the model must cite to resolve a semantic conflict. If the model
+  will never face a moment where it needs to invoke the rule, the rule is not a commandment —
+  it is either a code invariant (enforce and test it) or dead weight (delete it).
+
+By that second rule, "stay silent in repositories that never opted in" is **not** a commandment:
+it is `if not exists('.ultra'): exit(0)`, a mechanical invariant the model never reasons about.
+It lives in `docs/PLUGIN-ISOLATION-CONTRACT.md` and is verified by test, not by citation.
+
+---
+
+## 4 Core Goals
+
+The harness exists to serve these — every constraint derives its legitimacy from contributing to
+one or more.
+
+1. **Intent Fidelity** — what the user said they wanted is what gets built. No silent
+   reinterpretation, no scope creep, no convenient shortcuts that drift from the original ask.
+2. **Long-term Evolvability** — iteration #5 is as easy as iteration #1. Cognitive debt cannot
+   accumulate; spec / task / code / doc must stay coherent.
+3. **Production-Ready** — real persistence, real tests, real integration. No in-memory facades,
+   no `default off` to dodge integration, no `it.skip` to dodge failures.
+4. **Cognitive Coherence** — agent and user share the same picture of "what is currently true."
+   Spec changes propagate. Doc rot is detected. Orphan code surfaces.
+
+---
+
+## 5 Commandments
+
+### C1 — Goal-Always-Present
+
+The agent never stops seeing the north-star. Every hook trigger that costs context budget injects:
+the project one-liner plus the current task's acceptance criteria. The cost of repetition is
+always less than the cost of drift.
+
+> **Test**: pick a random in-progress task, ask the agent "what's the acceptance criteria?" — if
+> it cannot answer in one sentence, this commandment is broken.
+
+### C2 — Enabling > Defensive
+
+Every prohibition ships with a runnable alternative. Prohibitions without an enabling path force
+agents to find loopholes (rename `mock` to `stub`, etc.). The cheaper path must be the right path.
+
+> **Test**: scan every prohibition in every Skill; each must reference a template that exists
+> under that Skill's `references/templates/` and can be copied as-is. The templates are rules,
+> so they ship with the package rather than being copied into each project.
+
+### C3 — Sensors not Blockers
+
+Hooks emit signal; agents and users decide. Block only the **truly irreversible**:
+
+- `git push` to protected branches
+- Funds transfer / on-chain transactions
+- DB migrations / `DROP` / `TRUNCATE`
+- Hardcoded secret commit
+- Arbitrary code execution driven by user input
+
+Everything else is advisory on stderr — the work stands, the signal is delivered, the agent
+proceeds.
+
+> **Why this is absolute**: hard final gates and hard pre-commit gates each produced the same
+> over-correction loop in v7 — the agent weakened tests to escape the gate and drifted from the
+> spec. A gate that can be escaped by damaging the work is worse than no gate.
+
+> **Test**: count blocking outputs across all hooks; they must map 1:1 to the irreversible list.
+
+### C4 — Incremental Validation
+
+The agent always knows "how far from done." Each edit updates `.ultra/progress/<task-id>.json`
+with evidence completeness across six dimensions. Final-gate audits are forbidden — if a gap
+matters at the end, it matters mid-flight.
+
+> **Scoped exception**: whole-system wiring audit (`ultra-test`) is necessarily terminal, because
+> "this export has no non-test importer" cannot be evaluated while later tasks are still pending.
+> It is a terminal **sensor**, never a gate: it reports and hands the trade-off to the owner.
+> This is the only permitted end-of-flow audit.
+
+> **Test**: at any point in a task, reading `.ultra/progress/<task-id>.json` answers "what's left."
+
+### C5 — Bounded Autonomy
+
+Autonomy is defined by goals, not rules. Inside the boundary the agent picks freely; crossing the
+boundary surfaces to the user.
+
+- **Inside**: choosing libraries, naming, file layout, internal abstractions, decomposition
+  strategy, evidence interpretation, prioritization, final expression
+- **Crossing**: weakening test assertions, modifying spec to match implementation, default-off
+  feature flags, in-memory replacing real persistence, scope reduction, external or irreversible
+  effects
+
+**Operational test for spec changes.** When implementation and spec disagree, classify the change
+before touching the spec. Do not classify by intent — classify by asking one question that can be
+checked against the file:
+
+> **Does every commitment the spec already made still hold after this change?**
+
+| Answer | Classification | Action |
+|---|---|---|
+| Yes, and it now commits to more | EXPANSION | write it, log it |
+| Yes, the commitment is unchanged but stated correctly | CORRECTION | write it, log it |
+| **No — at least one prior commitment no longer holds** | **REDUCTION** | **stop and ask the owner** |
+
+The classification follows from the outcome, never from the reason. A well-argued rationale does
+not convert a REDUCTION into a CORRECTION; the rationale goes into the question put to the owner.
+This is the mechanism by which specs shrink silently, so it is the one place the model must not
+be allowed to self-certify.
+
+> **Test**: any boundary-crossing action must trigger an owner question, an active task
+> `## Change Log` entry, or an accepted `.ultra/decisions/<id>.md`.
+
+---
+
+## When commandments conflict
+
+Goals override commandments. Commandments override rules. Cite the higher level:
+
+- `C2 overrides rule "no mock" → use the testcontainer template`
+- `goal Intent-Fidelity overrides C5 → ask the owner before reducing scope`
+
+---
+
+## Modifying this file
+
+Changes to PHILOSOPHY require:
+
+1. A concrete failure case the change addresses, linked in the active Change or evidence
+2. An impact assessment on every dependent hook and Skill
+3. Migration of any dependent constraint
+
+PHILOSOPHY is the only file whose changes propagate to every prohibition, template reference, and
+Skill instruction. Do not touch it casually.
+
+---
+
+## Contract Table
+
+> Each row is a hardcoded contract between two parts of the system. Changing one side **without**
+> the other was the v7 audit's #1 cause of silently broken Goal-Always-Present injection. Update
+> this table BEFORE editing either side.
+
+| Consumer | Reads | Source of truth | Failure mode if drifted |
+|---|---|---|---|
+| `session_context` | headings `## One-line`, `## Hard Constraints` | `.ultra-template/north-star.md` | SessionStart shows no goal; C1 dies |
+| `session_context` | active `in_progress` task → its context | `tasks.json[].context_file` | acceptance criteria never surfaced |
+| `mid_workflow_recall` | heading `## Acceptance Criteria` | `.ultra-template/contexts/TEMPLATE.md` | hook injects nothing; C1 dies silently |
+| `ultra-tdd` | path `references/templates/*` | `skills/ultra-tdd/references/templates/` | guidance points at a missing runnable alternative; C2 dies |
+| `post_edit_guard` | writes `.ultra/progress/<task-id>.json` | `tasks.json[].id`, created on demand | mechanical observations disappear; C4 weakens |
+| `ultra-dev` and `post_edit_guard` | 6 keys: `tests_written`, `tests_passed`, `persistence_real`, `feature_flags_audit`, `vertical_slice`, `spec_trace` | the six-dimension table in `skills/ultra-dev/SKILL.md` | sensor and workflow report different evidence |
+| planning and status | marker `[NEEDS CLARIFICATION]` | `.ultra-template/specs/*.md` | unresolved product truth is hidden |
+| `ultra-plan` / `ultra-dev` / hooks | `trace_to` form `.ultra/specs/file.md#anchor` | `tasks.json[].trace_to` + GFM heading slugify | traces appear resolved when their heading is absent |
+| `ultra-deliver` / `ultra-status` | field `git_commit` | `.ultra/test-report.json` | stale test results pass as current |
+| `compact_context` | `.ultra/.runtime/compact-snapshot.md` | derived from canonical files and Git | compact recovery loses acceleration, not authority |
+| every hook | existence of `.ultra/` | the project directory | Ultra taxes projects that never opted in (see `docs/PLUGIN-ISOLATION-CONTRACT.md`) |
+| `ultra-init` | the project data skeleton | `.ultra-template/` and the exact file list in its Skill | later Skills read missing authority paths; C1 dies |
+
+### Maintenance protocol
+
+Before editing any row's source of truth:
+
+1. Find every consumer in this table
+2. Update consumer and source together in one change
+3. Re-run the end-to-end injection check
+4. Update this table if the contract surface changed

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -1,59 +1,82 @@
-# Plugin Isolation Contract
+# Plugin isolation contract
 
-Ultra Builder Pro is an explicitly invoked, removable workflow plugin. Installation
-must not change a user's durable engineering policy or initialize any repository.
+Ultra Builder Pro owns a narrow install surface and becomes active only in a project
+that contains `.ultra/` or when the owner explicitly invokes an Ultra Skill.
 
 ## Owned surfaces
 
-An adapter may write only:
+Per host, Ultra may install:
 
-- the host's plugin-owned command, skill, worker, hook, and runtime directories;
-- the host registry or manifest entries required to load those assets;
-- the plugin's own provenance and managed-file markers.
+- exactly fourteen managed Skills;
+- exactly five hook scripts plus `_common.py` and any required wire adapter;
+- one native plugin manifest or entrypoint;
+- provenance and managed-ownership markers;
+- the host's native registry entry where required.
 
-The first command allowed to create project authority is `ultra-init`. Once invoked,
-Ultra owns only the repository-local `.ultra/` workflow-memory envelope and its
-MCP-published checkpoint plus generated local projections.
+The package also owns `ubp delegate run`, its worker, and rule-side Skill references.
 
 ## Surfaces Ultra does not own
 
-Install, update, doctor, and uninstall must not create, rewrite, trim, merge, or delete:
+Ultra must not create or rewrite:
 
-- user-level `CLAUDE.md`, `AGENTS.md`, or equivalent instruction files;
-- repository-level instruction files;
-- project source, Git history, remotes, or `.ultra/` data;
-- general memory or code-graph provider data.
+- global user instruction files such as `~/.codex/AGENTS.md` or
+  `~/.claude/CLAUDE.md`;
+- general memory, code-graph, browser, deployment, framework, or productivity assets;
+- user-defined commands, agents, plugins, hooks, or registry entries;
+- repository files outside `.ultra/` and `CONTEXT.md` unless the selected engineering
+  task itself authorizes them;
+- an Ultra database, server registration, semantic runtime, or daemon.
 
-Existing Ultra marker blocks in a user handbook are legacy user content after this
-contract takes effect. They are not silently removed because the plugin cannot prove
-ownership or preserve unrelated edits. The owner may review and remove them separately.
+## Installation lifecycle
 
-## Activation
+Install builds a complete staging tree, marks it managed, writes provenance, then
+atomically publishes it. An existing unmanaged target is never overwritten. Reinstall
+replaces only the managed tree. Doctor is read-only. Uninstall removes only assets
+whose ownership can be proven.
+
+Host-owned sidecars must resolve from the same isolation root as `--config-dir`. For
+Codex this includes both `plugins/ultra-builder-pro` and
+`.agents/plugins/marketplace.json`; sandbox installation must not touch the real home
+directory. Codex native registration runs with both `HOME` and `CODEX_HOME` set to that
+root. If registration fails, install restores the previous managed tree and marketplace,
+or removes every fresh partial artifact.
 
-Public Ultra workflows run only after an explicit user command or Skill invocation.
-Completion of one workflow may return current Context diagnostics and a host-model
-recommendation, but it must not start another public workflow. SQLite does not choose
-or authorize that recommendation.
+When one invocation selects multiple hosts, the supplied path is a parent isolation
+root and each adapter receives `<path>/<runtime>`. Sharing one concrete config directory
+would collide host-native `skills/` and `plugins/` layouts.
 
-Host adapters prevent implicit model activation with the strongest native mechanism:
+OpenCode installation may remove a specifically recognizable Ultra registration from
+an older release. It must preserve unrelated configuration and files.
 
-- Claude Code and Kimi Code mark public workflow Skills as model-disabled;
-- Codex marks workflow metadata as implicit-invocation-disabled;
-- OpenCode exposes public workflows through commands backed by private plugin assets,
-  not through the model-discoverable skill catalog.
-- Grok Build uses explicit plugin Skills/commands and makes Skill-entry
-  `ultra.context` authoritative when a Hook output channel is not consumed.
+Before first install, each adapter records only the exact config files and directory
+shells that do not yet exist. Uninstall may prune those recorded paths only when they
+are still empty (or a zero-byte host-created file); it preserves every pre-existing,
+non-empty, modified, symlinked, or unowned path. Codex marketplace and Kimi registry
+files additionally remember whether Ultra created the registry itself, so an empty
+registry that existed before installation is retained.
+
+## Activation
 
-Internal review-rule skills remain available only to their bounded workers.
+Owner-invoked Skills activate only through the host's explicit Skill surface.
+Model-invoked Skills may be selected by the host model only as methods inside the
+current authorized task. Hooks activate only through host lifecycle registrations.
+
+One public Skill may recommend another but never launches it. Installation does not
+create project authority or start background work.
 
 ## Idle behavior
 
-Outside a repository containing `.ultra/.runtime/state.db`, all Ultra Hooks are silent.
-Inside an initialized repository, a Hook may inject one bounded Context Envelope when
-the host consumes that channel. The sole idle-time enforcement is protection against
-direct writes to the MCP-owned team checkpoint or generated Ultra projections; the DB
-remains checkout-local operational authority. Semantic incompleteness is advisory.
+Every hook resolves the current project and checks for `.ultra/` before reading,
+writing, injecting context, or denying an effect. Without `.ultra/`, it emits no stdout,
+exits zero, and leaves the project untouched.
+
+The only hook denial is a named dangerous shell effect in an active Ultra project. The
+denial identifies the protected effect and supplies an exact-command SHA-256
+authorization path. All other hook failures are fail-open diagnostics.
+
+## Project data boundary
 
-Installation tests preserve byte-for-byte snapshots of all supported user handbook
-paths. Runtime tests cover explicit activation, idle silence, active recovery, and
-projection protection.
+Canonical project data is owner-readable and Git-compatible. Derived hook, review, and
+delegation artifacts live only under ignored `.ultra/.runtime/`, `.ultra/progress/`, or
+`.ultra/reviews/`. Disabling or uninstalling Ultra leaves canonical project data intact
+and resumable by ordinary file reading.

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,158 +1,101 @@
 # Runtime compatibility matrix
 
-Claude Code, OpenCode, Codex, Kimi Code, and Grok Build are supported plugin
-hosts. The canonical asset boundary lives in
-`adapters/_shared/runtime-assets.cjs`.
-
-Legend: **FULL** means a native equivalent exists; **FUNCTIONAL** means the same
-outcome uses a different native primitive; **DEGRADED** means the missing host
-surface is stated and the Skill-entry Context read remains authoritative; **N/A**
-means intentionally absent.
-
-## Plugin and workflow surface
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Package form | `.claude-plugin` | config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` | native Grok plugin |
-| Public entry | `/ultra-builder-pro:ultra-*` | `/ultra-*` | `$ultra-builder-pro:ultra-*` | `/ultra-builder-pro:ultra-*` | native Ultra commands/Skills |
-| Public workflow Skills | 11 explicit-only | 11 command-backed private assets | 11 implicit-disabled | 11 model-disabled | 11 explicit-only |
-| Internal rule Skills | 4 worker-only | 4 worker-only | 4 implicit-disabled | 4 worker templates | 4 worker templates |
-| MCP tools | exactly 7 | exactly 7 | exactly 7 | exactly 7 | exactly 7 |
-| Automatic semantic chaining | N/A | N/A | N/A | N/A | N/A |
-
-Commands are thin launchers. The Skill contains adaptable semantic workflow prose;
-the adapter contains only host metadata, translation, and wiring.
-
-## Agents and collaboration
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Bundled review/debug workers | FULL, 10 native Markdown agents | FULL, 10 native agents | FULL, 10 managed TOML agents | FUNCTIONAL, 10 prompt templates | FUNCTIONAL, 10 prompt templates |
-| Immutable Worker Packet | FULL | FULL | FULL | FULL | FULL |
-| Native bounded delegation | native agent surface | native agent surface | native subagents | Agent/AgentSwarm | plugin agent surface |
-| Cross-host advisor | explicit read-only | explicit read-only | explicit read-only | explicit read-only | explicit read-only |
-| Final acceptance owner | primary host | primary host | primary host | primary host | primary host |
-
-Every Worker Packet binds Context, decisions, Git, Task, acceptance, evidence,
-output schema, and digest. A worker cannot write SQLite or accept its own result.
-
-## Hooks and Context
-
-| Lifecycle | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Session Context | FULL, SessionStart compact | FULL, system transform | FULL, session/prompt compact | FULL where native event consumes output | DEGRADED, ignored stdout is not claimed as injection |
-| Skill-entry Context | FULL | FULL | FULL | FULL | FULL and authoritative |
-| Managed-file protection | PreToolUse | tool.before | PreToolUse | PreToolUse | camelCase PreToolUse |
-| Compact recovery | PreCompact + SessionStart | compacting transform | pre/post compact | native pre/post where available | records lifecycle; Skill rereads Context |
-| Stop | non-blocking advisory | session.idle annotation | non-blocking advisory | non-blocking advisory | advisory only for `reason=end_turn` |
-| Subagent event | minimal ids | DEGRADED when host lacks event | minimal ids | native start/stop | minimal ids where exposed |
-
-All Hook context comes from the canonical Context Envelope generator. Hooks never
-capture prompts, transcripts, general memory, observations, or code-graph payloads.
-They do not create semantic records or block ordinary work for incomplete evidence.
-
-## MCP and native runtime
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| stdio registration | `.mcp.json` | local MCP entry | `.mcp.json` | `mcpServers` | native plugin MCP entry |
-| Public discovered tools | 7 | 7 | 7 | 7 | 7 |
-| Public write/read smoke | FULL | FULL | FULL | FULL | FULL |
-| Doctor backup/reopen | FULL | FULL | FULL | FULL | FULL |
-| Bundled `better-sqlite3` native | FULL | FULL | FULL | FULL | FULL |
-| ABI/provenance validation | FULL | FULL | FULL | FULL | FULL |
-| Git team checkpoint | `.ultra/tasks/tasks.json` | same | same | same | same |
-| Local authority | `.ultra/.runtime/state.db` | same | same | same | same |
-
-The installed runtime includes the externalized `better-sqlite3` package and its
-native `.node`. Provenance records native digest, platform, architecture, Node ABI,
-and runtime command. A mismatched ABI fails before authority is opened; Doctor
-repairs through staging and atomic swap.
-
-Archive finalization uses a packaged Python 3 worker with identity-checked
-descriptor-relative filesystem operations on POSIX. If this prerequisite is absent,
-archive fails closed with `ARCHIVE_RUNTIME_UNAVAILABLE`; other MCP tools remain usable.
-
-## Structured user interaction
-
-| Host | Native question surface | Fallback |
-|---|---|---|
-| Claude Code | `AskUserQuestion` | one concise direct question |
-| OpenCode | `question` | one concise direct question |
-| Codex | `request_user_input` when exposed by current mode | one concise direct question |
-| Kimi Code | `AskUserQuestion` outside auto mode | one concise direct question |
-| Grok Build | native structured question when exposed | one concise direct question |
-
-An interaction-disabled mode leaves the choice unresolved. The adapter never infers
-consent or stores an interaction receipt.
-
-## User instruction isolation
-
-| Host | Durable user instruction | Installer writes it? |
-|---|---|---|
-| Claude Code | `~/.claude/CLAUDE.md` | no |
-| OpenCode | `~/.config/opencode/AGENTS.md` | no |
-| Codex | `~/.codex/AGENTS.md` | no |
-| Kimi Code | `~/.kimi-code/AGENTS.md` | no |
-| Grok Build | host-owned instruction file | no |
-
-Install, update, Doctor, and uninstall preserve user instructions, repository
-instructions, project `.ultra`, unrelated plugins, and unrelated host configuration.
-
-## Install lifecycle
-
-| Capability | Claude Code | OpenCode | Codex | Kimi Code | Grok Build |
-|---|---|---|---|---|---|
-| Global flag | `--claude` | `--opencode` | `--codex` | `--kimi` | `--grok` |
-| Staging + atomic swap | FULL | FULL | FULL | FULL | FULL |
-| Exact-host preflight | FULL | FULL | FULL | FULL | FULL |
-| Native registration truth | host manifest | host config | plugin manifest/cache | installed registry | `grok plugin list/details` |
-| Active MCP truth | host MCP config | host MCP config | plugin cache | managed plugin config | `grok inspect` + `grok mcp doctor` |
-| Managed uninstall guard | FULL | FULL | FULL | FULL | FULL |
-| Preserve unrelated config | FULL | FULL | FULL | FULL | FULL |
-| Read-only Doctor | FULL | FULL | FULL | FULL | FULL |
-
-Preflight uses the final manifest command and verifies initialize, `tools/list == 7`,
-public write/read, Doctor backup, close/reopen consistency, native provenance, and
-lazy project initialization.
-
-The Grok adapter probes the installed CLI's command and flag capabilities rather
-than branching on a Grok version number. Global installation uses Grok's native
-plugin registry, keeps a durable managed local source for native refresh, and
-resolves the MCP launcher through `${GROK_PLUGIN_ROOT}` after Grok copies the plugin
-under its dynamic `installed-plugins/<repo-key>` path. An older raw
-`$GROK_HOME/plugins/ultra-builder-pro` installation is backed up and migrated; a
-failed native install restores the prior source and registration.
-
-`grok mcp list` is not the plugin-MCP inventory surface in current Grok releases;
-it reports explicit user/project MCP configuration. Ultra therefore does not add a
-second `[mcp_servers]` entry merely to make that command display the plugin. The
-authoritative plugin consumer checks are the native plugin registry, merged
-`grok inspect` MCP source, and the live `grok mcp doctor` handshake.
-
-## Durable compatibility
-
-| Capability | Contract |
-|---|---|
-| Current authority schema | `22.0` |
-| Runtime values | `claude`, `opencode`, `codex`, `kimi`, `grok` |
-| Legacy inputs | v4.4/v4.5 task projections, the legacy root-level state database, Task Contexts, v0.22/v0.23 DB and team ledger |
-| Preservation | exact-byte backup, row/ID/event/migration-history preservation, verified semantic promotion |
-| Failure | transactional rollback; no partial DB, ledger, native runtime, or host installation |
-
-Old workflow/dialogue rows are retained as non-authoritative history. Current
-Decisions, Stage Checkpoints, Context Envelopes, Worker Packets, and team checkpoint
-are reconstructed only from verified authority.
-
-## Verification sources
-
-- `adapters/tests/*.test.cjs` validates every native builder and manifest.
-- `tests/conformance/<runtime>/*.test.cjs` validates all five hosts.
-- `adapters/_shared/tests/runtime-assets.test.cjs` keeps docs and asset allowlists
-  synchronized.
-- `tests/install.test.cjs` verifies atomic install, rollback, Doctor, and instruction
-  preservation.
-- `tests/package-smoke.test.cjs` installs the npm tarball and performs five real
-  launcher write/read/backup/reopen round trips.
-- Grok acceptance runs capability probing, native install/list/details/enable,
-  merged inspect, MCP Doctor, migration rollback, and camelCase Hook fixtures.
+Ultra Builder Pro adapts one fourteen-Skill, five-hook contract to five native hosts.
+This document records the differences that belong in adapters rather than shared
+Skills.
+
+## Installed surface
+
+| Host | Managed plugin or bundle | Skills | Hook bridge |
+|---|---|---:|---|
+| Claude Code | `<config>/skills/ultra-builder-pro` | nested `skills/<name>` | direct Python commands in `hooks/hooks.json` |
+| Codex | `<home>/plugins/ultra-builder-pro` plus personal marketplace entry | nested `skills/<name>` with `agents/openai.yaml` | `hooks/adapters/codex.py` |
+| OpenCode | `<config>/.ultra-builder-pro` plus `<config>/plugins/ultra-builder-pro.js` | managed `<config>/skills/<name>` | native JS events call shared Python scripts |
+| Kimi Code | `<config>/plugins/managed/ultra-builder-pro` plus `installed.json` | nested `skills/<name>` | `hooks/adapters/kimi.py` |
+| Grok Build | `<GROK_HOME>/.ubp/plugin-sources/ultra-builder-pro` | nested `skills/<name>` | `hooks/adapters/grok.py` |
+
+Every host receives the same eight owner workflows, five model disciplines, and one
+router. Codex alone needs generated `agents/openai.yaml` files to express display data
+and implicit-invocation policy; those are host metadata, not custom agents.
+
+## Scope resolution
+
+| Host | Global default | Local default | Environment override |
+|---|---|---|---|
+| Claude Code | `~/.claude` | `<cwd>/.claude` | `CLAUDE_CONFIG_DIR` |
+| Codex | `~/.codex` for config; `~/plugins` and `~/.agents` for sidecars | `<cwd>/.codex` plus home-scoped plugin surface | `CODEX_HOME` |
+| OpenCode | `${XDG_CONFIG_HOME:-~/.config}/opencode` | `<cwd>/.opencode` | `OPENCODE_CONFIG_DIR` or `OPENCODE_CONFIG` |
+| Kimi Code | `~/.kimi-code` | no project plugin scope | `KIMI_CODE_HOME` |
+| Grok Build | `~/.grok` | no project plugin scope | `GROK_HOME` |
+
+An explicit `--config-dir` wins over all defaults and becomes the home for any
+host-owned sidecar as well. This rule makes isolated installation tests trustworthy.
+With multiple selected runtimes, the CLI passes `<config-dir>/<runtime>` to each adapter
+instead of merging incompatible host layouts.
+Kimi and Grok currently expose user-scoped plugin installation only. `--local` rejects
+them before mutating another host; an explicit `--config-dir` remains available for an
+isolated user-scope installation test.
+
+## Invocation policy
+
+| Role | Owner can route directly | Model can select implicitly |
+|---|---:|---:|
+| eight user-invoked Skills | yes | no |
+| five model-invoked Skills | no | yes |
+| `ultra-status` router | yes | no |
+
+Claude and Grok receive `user-invocable` / `disable-model-invocation` frontmatter.
+Kimi receives its native equivalent. Codex receives
+`policy.allow_implicit_invocation` in `agents/openai.yaml`. OpenCode uses portable
+source frontmatter and native discovery, but its current Skill schema has no equivalent
+owner/model routing bit: all fourteen Skills remain discoverable and their descriptions
+guide model selection. Ultra does not add a semantic interception hook to imitate a
+host feature OpenCode does not expose.
+
+## Hook compatibility
+
+| Hook | Claude | Codex | OpenCode | Kimi | Grok |
+|---|---:|---:|---:|---:|---:|
+| session context | yes | normalized | native bridge | normalized to message | executed; host stdout limits apply |
+| mid-workflow recall | yes | handles `apply_patch` | native bridge | normalized | executed |
+| compact context | pre/start | pre/post | native compact event | pre/post | pre-compact |
+| post-edit observation | Write/Edit | Write/Edit/`apply_patch` | write/edit/patch | Write/Edit | Write/Edit/patch |
+| dangerous command guard | Bash | Bash | bash | Bash | Bash deny mapping |
+
+All hooks share the same `.ultra/` idle guard. Wire adapters normalize payload and
+output fields only; they do not change semantic policy. Codex installation health and
+hook activation are distinct: Codex skips newly installed non-managed plugin hooks
+until the user reviews and trusts the current definition, so Doctor reports
+`hook_activation: user_review_required` without pretending the hook already ran.
+
+## Delegation argv
+
+`adapters/_shared/host-profile.cjs` records current non-interactive invocation for:
+
+- Claude print mode with structured output and an explicit file-tool allowlist; read-only
+  uses `plan`, while bounded write uses `acceptEdits` without Bash or web tools;
+- Codex ephemeral `exec` with user config ignored, project rules preserved, native
+  `read-only` or `workspace-write`, network disabled, and an output schema;
+- OpenCode `run --auto` only after an inline config explicitly denies Bash, web,
+  subagents, external directories, Skills and undeclared edit roots;
+- Kimi prompt mode with a launch-only read or write agent profile that exposes only
+  file tools and no Bash, web, MCP, Skills or subagents;
+- Grok single-turn mode with `read-only` or `workspace` OS sandbox, structured output,
+  no memory, web search or subagents.
+
+The launcher accepts no external-effect authority. It binds instruction, permission and
+output-schema digests, a clean Git worktree, allowed write roots, actual changed paths,
+strict result schema, timeout and cancellation. Empty roots select read-only mode. The
+model returns structured output and never authors the receipt. Host-native permissions
+are the execution boundary; the primary host still inspects and integrates the isolated
+diff.
+
+## Lifecycle verification
+
+Each adapter must pass isolated install, doctor, reinstall, and uninstall tests. Real
+global doctor additionally asks the native host where supported, but never repairs or
+installs. Codex still performs native registration under `--config-dir`; its host process
+inherits the same isolated `HOME` and `CODEX_HOME`. Grok native registration is skipped
+only in explicit isolated test mode. Lifecycle tests also require the isolated config
+and fake HOME to contain zero children after uninstall, while separate ownership tests
+prove that pre-existing empty Codex and Kimi registries survive.