ultra-builder-pro-cli 3.0.2 → 5.0.1

package/docs/ARTIFACT-AUTHORITY.md

@@ -24,7 +24,7 @@ When workflow-route signals conflict, consumers resolve them in this order:
 2. the current accepted North Star and the active Change intent;
 3. the current owner-issued Execution Grant — `session-local` while its conversation
    activation is live, or a `durable work-package` grant a fresh Agent has stably
-   verified — its scope, budget, and allowed workflows;
+   verified — its exact Change, modes, effects, topology, budget, and stop conditions;
 4. the task ledger, task acceptance, planned paths, and dependencies;
 5. the current validated Review SUMMARY verdict;
 6. current evidence and Test observations;
@@ -42,6 +42,11 @@ scope, or budget, and it cannot promote P2/P3 findings into blockers or reopen a
 review that returned a current verdict. Historical reviews, progress records, and
 Hook observations are provenance only.
 
+The Route Card is a projection of this precedence, not another layer in it. Its Route,
+Mode, Position, Exit condition, Delta, and Next fields are recalculated from the same
+authorities and current observations whenever a public Skill enters, pauses, exits, or
+transitions.
+
 A formal terminal outcome — an accepted result, an owner decision, an external
 blocker, a review-budget stop, or an abandonment — outranks every Resume, Hook, or
 Status suggestion that appears to continue the same work. Review stays inside the
@@ -81,11 +86,18 @@ whatever length keeps the owner able to judge:
 4. **Delta** — what materially changed since the last checkpoint.
 5. **Reality** — how far the live path actually works; what is still fake, unknown,
    or unverified.
-6. **Decision needed** — what the owner must decide now; omit the section when
-   nothing is genuinely blocking.
+6. **Decision needed** — what the owner must decide now; a Route Card says `none` when
+   nothing is genuinely blocking, while a free-form handoff may omit the section.
 7. **Next bounded action** — the smallest authorized next step.
 8. **Not done** — what remains owed when stopping or pausing.
 
+The canonical
+[`UBP Route Card`](../skills/ultra-status/references/route-contract.md#route-card) adds
+four navigation fields — Route, Mode, Position, and Exit condition — around these eight
+semantics. It is emitted output only: it has no canonical project path, never becomes a
+route ledger, and cannot grant continuation. Counts and transport events may explain
+Position or Reality but cannot produce a semantic completion verdict.
+
 A checkpoint is a cognitive interface, not a mechanical stage marker: no line count,
 token budget, or coverage percentage gates it, and alignment failure ("I don't know
 what you are doing", or the same concept re-explained repeatedly) stops execution and
@@ -168,6 +180,7 @@ Pure file state uses three mechanisms:
 
 A state field records a mechanically checkable fact. Route selection remains a model
 judgment. Do not add a workflow-position field merely to decide which Skill should run.
+The Route Card is derived each time and is disposable in exactly this sense.
 
 At most one Change is active in one worktree. Zero active Changes is valid before a new
 request and after delivery; completed current tasks may remain active while awaiting
@@ -275,7 +288,9 @@ decisions.
 After interruption or host change:
 
 1. identify the repository root and current `HEAD`;
-2. resolve zero or one active `change_id`, then read `.ultra/tasks.json`;
+2. resolve zero or one active `change_id`, then read `.ultra/tasks.json`; if authority
+   resolution returns a typed conflict or unavailable observation, stop semantic writes
+   but keep Status recovery diagnosis reachable without selecting an ambiguous intent;
 3. select only matching tasks and read the frontier task's full context and closing Resume Note;
 4. read the Project Brief, accepted North Star, `CONTEXT.md`, relevant decisions, active
    Change, specifications, and evidence;
@@ -283,7 +298,8 @@ After interruption or host change:
 6. rely only on ledger task status; preserve any legacy context Status or Complexity as
    a migration diagnostic, and use the explicit recorded reopen before repairing an
    invalid completed task's current v2 evidence or task-review bindings;
-7. continue through the next observable acceptance boundary.
+7. derive a fresh Route Card and continue only through the next observable acceptance
+   boundary covered by the current owner instruction or valid Execution Grant.
 
 Hooks and the `ubp` executable may be unavailable. Recovery must still work through
 these files and Git alone.

package/docs/DECISIONS.md

@@ -24,6 +24,19 @@ exact grant (see `.ultra/decisions/2026-08-17-ultra-builder-pro-3.0-mode-b.md`);
 file, status, Hook, or Resume note ever implies activation. Optional Graph/Loop
 coordination layers own observations only and none is integrated.
 
+## Ultra 5.0 workflow projection (accepted 2026-08-25)
+
+The owner accepted the 5.0 scope and interaction boundary in
+`.ultra/decisions/2026-08-25-ultra-5-0-scope.md`; the versioned contract is
+`docs/ULTRA-BUILDER-PRO-5.0.zh-CN.md`. One shared Route Contract projects the existing
+owner-checkpoint semantics into every public Skill without adding route state. Research
+has explicit baseline and grant-continuable Change-scoped modes; Change makes
+intake/evidence/reconcile/accepted visible and permits only same-Change non-material
+reconciliation under a valid grant; Plan returns product evidence gaps through Change.
+Host invocation bits remain coarse discovery metadata and every Skill rechecks mode,
+grant, effects, and material checkpoints. Team Pack, remote shared assets, a semantic
+state machine, daemon, and resident ACP service remain outside 5.0.
+
 ## Primary transfer between Agents (r3, accepted 2026-08-17)
 
 A work package's canonical writer moves to another Agent only through an
@@ -58,13 +71,13 @@ ownership of route and meaning.
 
 ## Three Skill roles
 
-The product exposes eight user workflows, five model-invoked disciplines, and one
-router. Public workflows require explicit owner selection by default. Research, Plan,
-Dev, Test, and Deliver reconciliation have one narrow exception: an activated
-Change-scoped execution grant may let the model select the next covered workflow —
-session-local activation in the current conversation, or a stably verified durable
-work-package grant. A model discipline needs at least two canonical callers or it is
-inlined.
+The product exposes eight owner-invocable public workflows, five model-invoked
+disciplines, and one router. Public modes are `explicit-entry` or
+`grant-continuable`. Scoped Research, same-Change reconciliation, Plan, Dev, Test, and
+Deliver reconciliation may be selected under an activated Change-scoped execution
+grant — session-local activation in the current conversation, or a stably verified
+durable work-package grant. All other public modes stay explicit-entry; Status stays
+owner-invoked and read-only. A model discipline needs at least two canonical callers or it is inlined.
 
 This keeps reusable reasoning in one place without turning it into another user-facing
 route or custom-agent registry.
@@ -136,6 +149,11 @@ Directory position and explicit fields record mechanically checkable facts. The
 model reads those facts and chooses the next route. There is no persisted “current
 workflow stage” whose value can override the actual files.
 
+The `UBP Route Card` is the owner-visible projection of those facts: it adds Route,
+Mode, Position, and Exit condition around the eight accepted checkpoint semantics. It
+is derived at public boundaries, has no canonical path, and provides neither completion
+nor continuation authority.
+
 Task status lives only in the `ultra-task-ledger-v2` row and is read back there. New task
 contexts do not duplicate it; legacy context Status and Complexity fields remain
 migration diagnostics and the ledger wins. Tasks retain a stable `change_id` in the
@@ -186,11 +204,14 @@ their repair is authorization scoped to the exact command digest.
 
 ## Delegation is a process boundary
 
-`ubp delegate run` starts a supported CLI with an immutable instruction, explicit
-permission JSON, and named worktree. Their exact digest-bound sources are embedded in
+The installed `ultra-delegate/scripts/delegate.cjs` starts a supported CLI with an
+immutable instruction, explicit permission JSON, and named worktree. Its exact
+digest-bound sources are embedded in
 the worker prompt because some native sandboxes correctly deny reads outside the
 worktree. Files remain the cross-host state; the embedded copy is transport, not another
-authority. The parent reads a stable terminal result instead of worker chatter.
+authority. The parent reads a stable terminal result instead of worker chatter. The
+package `ubp delegate` surface is a one-release compatibility import of that same
+launcher, not a second implementation or a runtime installation requirement.
 Delegation adds no semantic store and no authority. The instruction selects task
 execution, scoped Research evidence, or aggregate Change review/verification; only task
 execution requires a task row.

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -1,19 +1,25 @@
 # Plugin isolation contract
 
-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.
+Ultra Builder Pro owns a narrow install surface. Installation and discovery create no
+project authority. A public workflow becomes active only through an explicit owner
+entry or one mode covered by a currently valid Execution Grant; Hooks separately use
+the presence of `.ultra/` as their idle guard.
 
 ## Owned surfaces
 
 Per host, Ultra may install:
 
 - exactly fourteen managed Skills;
+- the launcher, worker, Host profile, and launch-only profile assets below the managed
+  `ultra-delegate/scripts/` Skill directory;
 - 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 package also owns `ubp delegate run`, its worker, and rule-side Skill references.
+For one release cycle the package also owns thin `ubp delegate` launcher/worker
+compatibility imports. They execute the Skill-local implementation and contain no
+forked behavior.
 
 ## Surfaces Ultra does not own
 
@@ -29,9 +35,10 @@ Ultra must not create or rewrite:
 
 ## Installation lifecycle
 
-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
+Install builds a complete staging tree, including the Skill-local delegation runtime,
+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 and reports runner reachability separately. Uninstall removes only assets
 whose ownership can be proven.
 
 Host-owned sidecars must resolve from the same isolation root as `--config-dir`. For
@@ -63,12 +70,21 @@ the owner.
 
 ## Activation
 
-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.
+Public Skill modes are `explicit-entry`, `grant-continuable`, or read-only `router`.
+Explicit-entry modes activate only through the Host's owner-facing Skill surface.
+Grant-continuable modes may be model-selected only after the loaded Skill verifies the
+same active Change, valid grant, allowed effects, and material checkpoints. A router may
+diagnose read-only state only on explicit owner invocation and creates no continuation
+authority. Model-discipline Skills
+may be selected only as methods inside the current covered workflow.
+
+Host invocation metadata is a coarse discovery aid. It cannot express every per-mode
+boundary, so the in-Skill check remains mandatory and Hosts without an equivalent bit
+rely on discriminating descriptions plus that same check. A public Skill may transition
+to another only when a valid grant covers the exact next mode and effects, after showing
+the Route Card; otherwise it stops and recommends the explicit route. Installation does
+not create a grant, launch a workflow, or start background work. Hooks activate only
+through Host lifecycle registrations and retain their independent idle guard.
 
 ## Idle behavior
 

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -40,21 +40,34 @@ 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. ZCode likewise discovers all plugin Skills and
-relies on their portable descriptions plus the Change-scoped execution grant rather
-than a fabricated routing flag.
+`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
 
@@ -68,13 +81,52 @@ than a fabricated routing flag.
 
 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:
+Hook trust are distinct. Codex owns the persisted trust decision, while its plugin CLI
+does not expose that live decision to Ultra. Doctor therefore reports
+`hook_activation: host_managed` with `observable: false`; it claims neither trusted nor
+untrusted and emits no remediation action without an authoritative Host observation.
+
+## 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.
+
+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;
@@ -90,20 +142,34 @@ until the user reviews and trusts the current definition, so Doctor reports
   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.
 
-ZCode 0.16.3 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; desktop provider
-state is not silently copied into `~/.zcode/cli/config.json` because provider choice and
-credentials remain owner-controlled.
+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 shared host profile uses
+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
-`adapters/_shared/host-profile.cjs`): the App-bundled CLI is a verified-local
-surface — it exists, launches, and passed the 2026-08-14 conformance drills — but
+`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
@@ -118,6 +184,20 @@ 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

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
 
@@ -42,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
@@ -96,6 +107,7 @@ For every changed Skill:
 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.