ultra-builder-pro-cli 0.26.2 → 5.0.0

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,6 +1,6 @@
 # Runtime compatibility matrix
 
-Ultra Builder Pro adapts one fourteen-Skill, five-hook contract to five native hosts.
+Ultra Builder Pro adapts one fourteen-Skill, five-hook contract to six native hosts.
 This document records the differences that belong in adapters rather than shared
 Skills.
 
@@ -13,6 +13,7 @@ Skills.
 | 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` |
+| ZCode | `~/.zcode/cli/plugins/marketplaces/ultra-builder-pro/plugin` plus managed local marketplace and `plugins.dirs` entry | nested `skills/<name>` | `hooks/adapters/zcode.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
@@ -27,40 +28,56 @@ and implicit-invocation policy; those are host metadata, not custom agents.
 | 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` |
+| ZCode | `~/.zcode` | no project plugin scope | adapter `ZCODE_HOME` override |
 
 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
+Kimi, Grok, and ZCode 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 |
+| Invocation class | 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 |
+| `explicit-entry` public mode | yes | no |
+| `grant-continuable` public mode | yes | only under a valid Execution Grant covering that mode |
+| five `model-discipline` Skills | no | as an internal method of a covered workflow |
+| `ultra-status` `router` modes | yes | no; other Skills derive their cards directly from the shared contract |
+
+The canonical per-mode map is `PUBLIC_SKILL_INVOCATION_MODES` in
+`adapters/_shared/runtime-assets.cjs`. Init and Delegate are explicit-only. Research has
+explicit `baseline` and grant-continuable `change-scoped`; Change has explicit
+intake/evidence/acceptance and grant-continuable same-Change reconciliation; Deliver has
+grant-continuable reconciliation and explicit finalization. Plan, Dev, and Test modes
+are grant-continuable. Every public mode remains directly owner-invocable.
 
 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.
+`policy.allow_implicit_invocation` in `agents/openai.yaml`. Those Hosts expose only a
+coarse Skill-level bit, so a Skill with any grant-continuable mode is discoverable to the
+model; the loaded Skill must still verify the selected mode, same active `change_id`,
+grant, effects, and material checkpoints. In particular, the coarse bit does not permit
+baseline Research, Change intake/acceptance, or Deliver finalization.
+
+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 plus the same in-Skill guard guide selection. Ultra
+does not add a semantic interception hook to imitate a Host feature OpenCode does not
+expose. ZCode likewise discovers all plugin Skills and relies on their portable
+descriptions and runtime guard rather than a fabricated routing flag.
 
 ## 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 advisory/deny | Bash advisory/deny | bash advisory/deny | Bash advisory/deny | Bash allow/deny mapping |
+| Hook | Claude | Codex | OpenCode | Kimi | Grok | ZCode |
+|---|---:|---:|---:|---:|---:|---:|
+| session context | yes | normalized | native bridge | normalized to message | executed; host stdout limits apply | normalized |
+| mid-workflow recall | yes | handles `apply_patch` | native bridge | normalized | executed | handles `ApplyPatch` aliases |
+| compact context | pre/start | pre/post | native compact event | pre/post | pre-compact | `SessionStart: compact` |
+| post-edit observation | Write/Edit | Write/Edit/`apply_patch` | write/edit/patch | Write/Edit | Write/Edit/patch | Write/Edit/ApplyPatch |
+| dangerous command guard | Bash advisory/deny | Bash advisory/deny | bash advisory/deny | Bash advisory/deny | Bash allow/deny mapping | Bash advisory/deny |
 
 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
@@ -68,9 +85,47 @@ hook activation are distinct: Codex skips newly installed non-managed plugin hoo
 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
+## Agent execution driver selection
+
+| Host | ACP candidate observed locally | Versioned conformance | 5.0 active driver | Fallback reason |
+|---|---|---|---|---|
+| Claude Code | pinned `@agentclientprotocol/claude-agent-acp@0.70.0` stdio adapter | PASS, real provider receipt | ACP when `npx` exists | `acp_command_unavailable` when absent |
+| Codex | pinned `@agentclientprotocol/codex-acp@1.6.2` stdio adapter | PASS, real provider receipt | ACP when `npx` exists | `acp_command_unavailable` when absent |
+| OpenCode | native `opencode acp` stdio server | PASS, real provider receipt | ACP when executable exists | `acp_command_unavailable` when absent |
+| Kimi Code | documented [`kimi acp`](https://moonshotai.github.io/kimi-code/en/reference/kimi-acp.html) stdio server | PASS, real provider receipt | ACP when executable exists | `acp_command_unavailable` when absent |
+| Grok Build | documented [`grok agent stdio`](https://docs.x.ai/build/cli/headless-scripting) | PASS, real provider receipt | ACP when executable exists | `acp_command_unavailable` when absent |
+| ZCode | source-pinned `zcode-acp` v0.1.0 plus digest-bound 0.16.5 patch translating to installed `app-server` | PASS, domestic BigModel provider receipt | ACP when bridge exists and `--ack-experimental` is supplied | `acp_command_unavailable` when absent |
+
+Selection is ACP-first only after the exact Host row is `passed` and names a non-empty
+evidence reference: stable protocol v1, stdio, executable availability, read-only,
+bounded write, permission denial,
+cancellation/no-orphan, cwd/diff parity, result parity, and credential/event redaction
+must all hold. Static capability inspection never starts the provider. A candidate,
+binary, help output, SDK version, or successful fake-agent suite alone cannot promote a
+Host. The stable wire contract follows the official
+[ACP v1 schema](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/schema/v1/schema.json);
+unstable v2 features are outside the 5.0 required path.
+
+All Driver receipts and terminal results expose the selected driver, ACP capability,
+and fallback reason. Doctor reports the same facts separately from installation health.
+`AcpDriver` stores a bounded redacted `events.jsonl`, never raw protocol messages or
+hidden reasoning. Status re-projects every displayed latest event through that fixed
+safe shape and treats a corrupted journal as unavailable. `CliDriver` bounds
+stdout/stderr while retaining the output tail so the existing exact Ultra result
+extractor remains compatible.
 
-`adapters/_shared/host-profile.cjs` records current non-interactive invocation for:
+During `session/new`, `AcpDriver` may temporarily buffer only the bounded creation-time
+metadata updates emitted by some conforming agents. It rejects message/tool content,
+wrong session identities, more than 32 updates, or more than 256 KiB before the response;
+accepted metadata is exposed only after every buffered `sessionId` matches the created
+session. `ULTRA_DELEGATE_FORCE_CLI=1` is an explicit per-run recovery seam: it selects
+the same bounded CLI result path and records `acp_forced_cli` without changing the
+Host's stored conformance status.
+
+## CLI fallback argv
+
+`skills/ultra-delegate/scripts/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;
@@ -81,14 +136,129 @@ until the user reviews and trusts the current definition, so Doctor reports
 - 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.
+  no memory, web search or subagents, and a twelve-turn ceiling;
+- ZCode headless prompt mode with native `plan` or `edit`; the current CLI accepts the
+  camel-case `--disallowedTools` surface used to deny Bash, web, subagents, and (in
+  read-only mode) write tools. The launcher's timeout remains the execution bound.
+
+The installed ZCode 0.16.5 runtime advertises `--max-turns`, `--allowed-tools`, and
+`--settings` in help but rejects them at the live root parser. Ultra therefore does not
+pass those flags. ZCode headless delegation also requires an explicit CLI model
+provider. Host/runtime identity and provider identity remain separate: the verified
+local path uses ZCode Desktop with the Owner's domestic BigModel Coding Plan provider,
+not international Z.AI OAuth. Ultra's package does not silently copy Desktop credentials;
+the user controls the provider entry in `~/.zcode/cli/config.json`.
+
+On macOS, the Skill-local host profile uses
+`/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` when that App-bundled CLI
+exists, then falls back to `zcode` on `PATH`. `UBP_DELEGATE_ZCODE_BIN` remains an explicit
+test or operator override; the normal source-to-ZCode path does not require it.
+
+The ACP bridge is independently installed from `jpalmae/zcode-acp` v0.1.0 at source
+revision `42fe149d4b501469343c01f23ba3801832306d53`, then patched by the shipped
+`zcode-acp-0.1.0-zcode-0.16.5.patch` with SHA-256
+`174dfd0feafe84320556a84b5ae08b10e44c5515fea4992fd1d58af54cee4e3d`. The patch
+answers the `session/requestRuntimePreferences` server request introduced by ZCode
+0.16.5 before and after session creation. The pinned source plus patch passes the locked
+Rust tests, reproduced RED, patched fake App-server E2E, release build, and real provider
+session before use. It stamps the bridge as
+`zcode-acp 0.1.0+ultra.zcode.0.16.5`; selection requires that marker and an installed
+runtime reporting `0.16.5`. Ultra records both source inputs and ships only the patch; it
+redistributes neither the bridge binary nor any ZCode Desktop bytes.
+
+**ZCode transport maturity is `experimental`** (recorded in
+`skills/ultra-delegate/scripts/host-profile.cjs`): the App-bundled CLI is a verified-local
+surface — it exists, launches, and passed the 2026-08-26 conformance drill — but
+the provider publishes no headless CLI, SDK, A2A, or ZCode Protocol stability
+contract. Promotion to `supported` requires both official documentation and a
+full recovery drill; a binary's existence, working help, or zero exit status is
+never sufficient. The other five delegate transports are documented and locally
+verified through the same launcher. The maturity is live-enforced, not just
+recorded: `delegate run --to zcode` refuses to launch without the explicit
+`--ack-experimental` flag, prints a stderr warning, and stamps
+`transport_maturity`, the exact `transport_surface` wording, and
+`experimental_ack: true` onto the receipt, worker spec, and every terminal
+result (including failure, cancellation, and timeout), so no delegation record
+can present an internal CLI run as the documented ZCode Desktop interactive
+surface. The documented interactive primary path for ZCode is the Desktop task
+surface itself, not this headless transport.
+
+## Installed delegation runner
+
+Every managed plugin contains `ultra-delegate/scripts/delegate.cjs`, its worker, the
+canonical Host profile, all three driver modules, and the Kimi launch-only profiles.
+The loaded Skill resolves
+that directory and invokes Node directly, so a clean plugin install does not require a
+persisted Ultra package binary on `PATH` and never uses `npx` to rediscover Ultra.
+The source-pinned Claude and Codex ACP adapters may themselves run through their exact
+`npx --yes <package>@<version>` profiles. Doctor
+reports `delegation_runner`, `acp_capability`, `agent_execution_driver`, its fallback
+reason, and ZCode maturity separately from Skill discovery and Hooks. The package
+`ubp delegate` surface remains a thin one-release compatibility wrapper around the same
+functions; receipts and recovery commands point to the canonical Skill-local entrypoint.
+
+### ZCode Desktop Workspace Memory (post-turn host effect)
+
+ZCode Desktop ships an optional Workspace Memory feature that extracts project
+memory after a completed turn into provider-local files under
+`~/.zcode/cli/memories/projects/<project>/memory`. Corrected facts
+(2026-08-17):
+
+- the feature is operator-controlled through the documented Workspace Memory
+  setting (`memoryEnabled` in `~/.zcode/v2/setting.json`); it is not always
+  default-off — it was observed enabled on this machine, and a fresh task
+  inherits the operator's current selection;
+- `memoryEnabled=false` is the single effective master gate: the App runtime
+  injects `memory:{enabled:false}`, and every recall, root access, and
+  post-turn extraction path resolves through one enabled-root resolver that
+  returns no root while it is false. The logged `memoryExtractionEnabled` and
+  `memoryUse` values are absent-key, disable-only defaults, not independent
+  owner-facing gates;
+- the extracted files are ordinary local files outside the repository that the
+  operator can browse and clear directly; they are non-authoritative and
+  non-portable — never Git content, never shared authority, never Ultra
+  evidence;
+- when the feature is enabled, the post-turn extraction is a Host external
+  effect: an owner-authorized transfer must allow it in the OFFER `effects`
+  and disclose it in the RESULT `external_effects`
+  (`skills/ultra-change/references/primary-transfer.md`); a strict
+  zero-external-effect pass requires a fresh task with the master setting off
+  plus an independent reviewer postflight;
+- Ultra never parses or mutates the provider setting.
+
+The accepted r3 design document's section 7.1 local-memory snapshot
+("local-only, default-off, cannot be browsed or cleared") is superseded by the
+current documented UI and the observed runtime behavior above; the frozen
+design bytes stay unedited.
 
 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.
+diff. The launcher embeds the digest-bound packet in the prompt because OpenCode's
+correct `external_directory: deny` policy prevents reading packet paths beside the
+worktree. Codex receives a native-schema-compatible projection; the launcher separately
+enforces non-empty strings, normalized unique paths, exact fields, and the observed diff.
+
+### Authenticated delegation conformance — 2026-08-14
+
+One clean, read-only seeded repository was used to exercise the current launcher against
+all six installed CLIs. Claude Code, Codex, OpenCode, Kimi Code, and ZCode each produced
+a validated `finished` result with an empty diff and found the seeded consequential
+defect. Grok Build 1.0.3 exited zero but repeatedly emitted truncated or malformed
+structured output; the launcher correctly published `failed/missing_result` and did not
+count partial text as evidence. This is a current host-result conformance ceiling, not a
+permission bypass or a semantic review result.
+
+ZCode was also exercised as the source host: one ZCode session invoked
+`ubp delegate run --to claude`, waited for the terminal artifact, and reported Claude's
+digest-bound read-only result without changing the worktree. Separately, one bounded
+ZCode Autonomy Envelope completed Plan, Plan review, TDD, task review, Test, and aggregate
+review for one task, then stopped before ungranted delivery and Git effects. Exact
+fixtures, session boundaries, checks, and residual risks are recorded in
+`docs/evals/adversarial-review-2026-08-14.md` and
+`docs/evals/zcode-automation-2026-08-14.md`.
 
 ## Lifecycle verification
 
@@ -96,7 +266,9 @@ Each adapter must pass isolated install, doctor, reinstall, and uninstall tests.
 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
+only in explicit isolated test mode. ZCode uses its documented inline-plugin directory
+configuration for immediate activation while also publishing an importable local
+marketplace; real global Doctor verifies the native plugin inventory. 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.
 

package/docs/SKILL-AUTHORING.md

@@ -7,12 +7,17 @@ owner boundaries; host-specific discovery and invocation policy belong in adapte
 
 Choose exactly one role before writing:
 
-- **user-invoked**: a complete owner-selected workflow with a durable outcome;
+- **public workflow**: an owner-invocable workflow with one or more declared modes and
+  a durable outcome;
 - **model-invoked**: a reusable discipline used by at least two canonical workflows;
 - **router**: read-only diagnosis that recommends the smallest next public route.
 
-A user workflow may recommend but must not invoke another user workflow. A discipline
-with only one real caller should be inlined.
+Every public mode is `explicit-entry` or `grant-continuable`. A public workflow may
+continue to another public mode only when a currently valid Execution Grant covers the
+same Change, exact mode, effects, and stop conditions, and only after showing the Route
+Card. Otherwise it stops and recommends the owner-invoked route. Host metadata never
+substitutes for that in-Skill check. A discipline with only one real caller should be
+inlined.
 
 ## Portable frontmatter
 
@@ -25,7 +30,8 @@ description: What this produces and the concrete situations that trigger it.
 ---
 ```
 
-Adapters generate Claude/Grok/Kimi invocation flags and Codex `agents/openai.yaml`.
+Adapters generate Claude/Grok/Kimi invocation flags, Codex `agents/openai.yaml`, and
+ZCode-native plugin metadata.
 Do not put host paths, dependency declarations, plugin policy, or release history in
 source frontmatter.
 
@@ -41,6 +47,12 @@ Every Skill has one outcome-led title and these semantic sections:
 ## References
 ```
 
+Every public workflow and router also has `## Route modes` with a `Mode | Entry |
+Observable exit | Next` table and references the canonical
+`ultra-status/references/route-contract.md`. Shared card fields, material checkpoints,
+continuation, and degraded recovery live only in that reference; each Skill owns only
+its modes and workflow-specific facts.
+
 User workflows first resolve at most one active `change_id`, then read only matching
 rows from `.ultra/tasks.json`, the frontier task's `context_file` and Resume Note,
 `CONTEXT.md`, and relevant decisions. Historical or abandoned rows never become current
@@ -72,7 +84,7 @@ wholesale into project authority.
 ## Language and host neutrality
 
 Model-facing Skills, references, scripts, comments, and identifiers are English.
-Shared Skills never mention `.claude`, `.codex`, `.opencode`, `.kimi`, `.grok`, or a
+Shared Skills never mention `.claude`, `.codex`, `.opencode`, `.kimi`, `.grok`, `.zcode`, or a
 host-only question surface. Use “host-native question surface” and put the translation
 in the adapter.
 
@@ -92,9 +104,10 @@ For every changed Skill:
 
 1. run the Skill Creator validator;
 2. resolve every relative reference in the source and installed artifact;
-3. verify its role metadata on all five hosts;
+3. verify its role metadata on all six hosts;
 4. test the accepted workflow with representative valid and adversarial inputs;
 5. confirm no retired runtime vocabulary or host-specific path entered portable text.
+6. run the Route Contract structural test and inspect the applicable owner journey.
 
 The repository's `tests/skill-authoring.test.cjs` and
 `tests/v026-contract.test.cjs` mechanize the portable parts of this contract.