ultra-builder-pro-cli 3.0.2 → 5.0.1

package/.ultra-template/contexts/TEMPLATE.md

@@ -18,6 +18,12 @@
 
 **Tech Notes**: [framework or library specifics]
 
+**Earliest observable slice**: [the first real consumer -> real data path ->
+owner-visible observation, or `not applicable` with the concrete reason]
+
+**Fresh-session recovery**: [repository root and HEAD -> active Change -> matching
+ledger row -> this context and Resume Note -> exact safe resume command or path]
+
 ## Planned Path Inventory
 
 `MODIFY`:

package/CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.1] — 2026-08-26
+
+### Fixed
+
+- Corrected Codex Doctor's Hook-trust observation. Codex owns persisted Hook trust but
+  does not expose the live decision through its plugin CLI, so Doctor now reports
+  `hook_activation: host_managed` with `observable: false` instead of permanently
+  claiming `user_review_required` and instructing already-trusted users to review again.
+  This changes no Hook registration, ACP transport, installation, or permission behavior.
+
+## [5.0.0] — 2026-08-26
+
+### Added
+
+- Added one owner-visible Route Contract for every public workflow transition:
+  invocation, mode, current position, observable exit condition, material checkpoint,
+  and next route are derived from repository authority rather than stored as another
+  semantic state machine.
+- Added a canonical installed Skill-local delegation runtime and one replaceable
+  `AgentExecutionDriver` boundary. The stable ACP v1 driver handles negotiation, fresh
+  absolute-cwd sessions, bounded/redacted updates, permission requests, cancellation,
+  timeouts, and terminal observation while preserving the existing immutable packet,
+  Git-diff, and exact result validator. `CliDriver` remains result-compatible fallback.
+- Added per-Host ACP capability/conformance selection and Doctor reporting for runner
+  health, selected driver, fallback reason, and transport maturity. ACP can activate
+  only for an executable stdio v1 candidate with a passed Host-specific evidence row.
+- Added a 3.x migration and fourteen-journey acceptance harness covering byte- and
+  mode-preserving install/update/Doctor/uninstall, fresh-session recovery, degraded
+  authority, early observable slices, delegation, cancellation, and truthful STOPs.
+
+### Changed
+
+- Made `ultra-change` the daily entry for an existing-project request. `ultra-research`
+  now owns the first baseline or one bounded evidence question; Change owns the delta
+  and its Research Disposition; Plan owns the smallest dependency-correct graph and the
+  earliest owner-observable vertical slice.
+- Made fresh-session recovery explicitly file-first: resolve the unique active Change,
+  task ledger and context, Acceptance, Resume Note, decisions, evidence, and Git without
+  replaying completed Research or treating conversation memory as authority.
+- Moved the canonical delegation launcher and its complete runtime closure under the
+  installed `ultra-delegate` Skill. The package-level `ubp delegate` command is a thin
+  one-release compatibility wrapper rather than a day-to-day runtime dependency.
+- Activated ACP-first delivery for all six shipped Host profiles only while each exact
+  executable, candidate identity, protocol version, and current conformance receipt
+  remain valid. Any unavailable or stale boundary still returns the typed,
+  result-compatible CLI fallback without an automatic provider retry.
+- Connected ZCode Desktop through the independently built `zcode-acp` v0.1.0 bridge at
+  commit `42fe149d4b501469343c01f23ba3801832306d53` plus the shipped digest-bound ZCode
+  0.16.5 runtime-preferences patch. The verified provider path is domestic 智谱
+  BigModel Coding Plan, not international Z.AI OAuth; transport maturity remains
+  `experimental` and requires explicit acknowledgment.
+- Kept Status and degraded Review read-only. Ambiguous authority reports the earliest
+  unsafe fact and reachable repair, retry, cancel, or abandon path without selecting an
+  intent, activating stored grant text, or writing semantic content.
+
+### Compatibility and scope
+
+- Preserved every seeded accepted 3.x project artifact byte and mode through the real
+  isolated install, update, Doctor, and uninstall lifecycle.
+- Deliberately excluded a daemon, remote workflow service, semantic state machine, A2A
+  network, Team Pack, remote marketplace, shared authority store, automatic ACP-to-CLI
+  retry after a started run, and unverified Host capability promotion.
+- This package has no service deployment target. npm publication and GitHub Release are
+  the only release surfaces; Team Pack, a daemon, remote workflow service, provider
+  purchase, credential export, force-push, and npm unpublish remain excluded.
+
+### Verified
+
+- Completed one bounded real ACP v1 provider session for Claude Code, Codex, OpenCode,
+  Kimi Code, Grok Build, and ZCode. Every receipt binds the exact Host candidate, clean
+  isolated Git subject, terminal worker observation, and redacted result facts.
+- Installed 5.0.0 into all six real user Host homes after a mode-0700 recovery backup.
+  Final Doctor reports six healthy adapters, installed Skill-local ACP selection, and
+  ownership-safe ZCode uninstall/reinstall without changing the domestic-provider config.
+- Passed the same-commit GitHub Actions matrix on Ubuntu and macOS with 661 Node tests,
+  89 Hook tests, and zero production dependency vulnerabilities, plus Windows 27/27
+  real ACP tests including cancel and timeout cleanup of an actual grandchild process.
+- Reproduced Windows checkout EOL and worktree-alias failures before fixing them with
+  LF-bound bridge patches and filesystem device/file-ID comparison; both failed
+  predecessor runs remain retained in the release evidence.
+
 ## [3.0.2] — 2026-08-18
 
 ### Added
@@ -1446,7 +1527,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v3.0.2...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v5.0.0...HEAD
+[5.0.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v3.0.2...v5.0.0
 [3.0.2]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.26.2...v3.0.2
 [0.26.2]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.26.1...v0.26.2
 [0.26.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.26.0...v0.26.1

package/README.md

@@ -1,5 +1,7 @@
 # Ultra Builder Pro
 
+**English** | [简体中文](README.zh-CN.md)
+
 Ultra Builder Pro is a file-first engineering workflow for Claude Code, Codex,
 OpenCode, Kimi Code, Grok Build, and ZCode. It implements the provider-neutral
 **Ultra Core Protocol**: owner–agent cognitive alignment, per-fact canonical
@@ -17,11 +19,13 @@ default is the current Agent continuing alone, and handing the work package's
 writing authority to a different Agent requires an explicit verified transfer
 (OFFER → ACK → RESULT over the repository files and Git).
 
-## Ultra Builder Pro 3.0
+## Ultra Builder Pro 5.0
 
-Version `3.0.2` is the first published release of Ultra as a cognitive-alignment harness for
-real software engineering. It is not a decentralized multi-agent platform and it
-does not prescribe one Agent topology. Instead, it keeps five promises:
+Version `5.0.1` is the current implementation of Ultra as a cognitive-alignment harness
+for real software engineering. It preserves the accepted 3.0 file-first and model-agency
+constitution, then makes workflow position, recovery, and cross-Agent execution directly
+observable. It is not a decentralized multi-agent platform and it does not prescribe one
+Agent topology. Instead, it keeps five promises:
 
 - establish the owner-accepted North Star before Research becomes a plan or code;
 - let the owner choose one Agent or several, and the provider, at every stage;
@@ -33,10 +37,21 @@ does not prescribe one Agent topology. Instead, it keeps five promises:
 - bound Review and repair so delivery converges instead of turning every observation
   into another automatic implementation loop.
 
-The portable protocol and native installation cover Claude Code, Codex, OpenCode,
-Kimi Code, Grok Build, and ZCode. ZCode plugin installation is supported; its
-App-bundled headless delegation transport remains explicitly `experimental` until an
-official stable interface and recovery drill satisfy the support bar.
+5.0 expresses those promises through one Route Contract, explicit Init/Research/Change/
+Plan responsibilities, file-only fresh-session recovery, an installed Skill-local
+delegation runtime, and a replaceable `AgentExecutionDriver`. Stable ACP v1 is preferred
+only after the exact Host has passed a recorded conformance drill; otherwise the same
+result contract uses a reported CLI fallback. The portable protocol and native
+installation cover Claude Code, Codex, OpenCode, Kimi Code, Grok Build, and ZCode. All
+six profiles expose stable ACP v1 candidates and have their own current real-provider
+receipt. Each selects ACP only while its recorded executable and candidate identity
+still match; otherwise it returns a typed CLI fallback. ZCode uses an independently
+installed, source-pinned bridge and remains `experimental`.
+
+5.0 deliberately does not add a daemon, workflow service, semantic state machine, A2A
+network, Team Pack, remote marketplace, or shared authority store. Package publication
+and real user installation remain independently verifiable effects; a source version
+alone never proves either one occurred.
 
 ## Why it exists
 
@@ -84,8 +99,13 @@ Git, and installation health without mutating the workflow.
 Public workflows are explicitly selected by the owner by default. Outside a live,
 owner-activated execution grant (session-local, or a durable work-package grant), one public workflow can recommend the
 next one but does not launch it. Inside that grant, the host model may select only
-the covered Research, Plan, Dev, Test, and reconcile-only Deliver routes; Init, Change,
-Delegate, Status, final archive, and every external effect remain owner-selected.
+the covered change-scoped Research, same-Change reconciliation, Plan, Dev, Test, and
+reconcile-only Deliver routes. Init, Change intake/evidence/acceptance/abandonment or
+primary transfer, Delegate, Deliver finalization, archive, and every external effect
+remain owner-selected; Status also remains owner-selected, read-only, and grants no continuation.
+Every public transition first displays the derived `UBP Route Card`; Host invocation
+metadata is only coarse discovery, and the loaded Skill revalidates its exact mode and
+grant without creating route state.
 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,
@@ -103,7 +123,7 @@ map, evidence convergence, owner checkpoints, and baseline promotion.
 
 ### What happened to the original Agents
 
-Version 3.0.2 does not install a custom `agents/` projection. The old review workers became the
+Version 5.0.1 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
@@ -184,19 +204,53 @@ Node.js 22 or newer is required.
 
 ```bash
 # Current project, one host
-npx ultra-builder-pro-cli@3.0.2 --claude --local
-npx ultra-builder-pro-cli@3.0.2 --codex --local
+npx ultra-builder-pro-cli@5.0.1 --claude --local
+npx ultra-builder-pro-cli@5.0.1 --codex --local
 
 # Global installation
-npx ultra-builder-pro-cli@3.0.2 --opencode --global
-npx ultra-builder-pro-cli@3.0.2 --kimi --global
-npx ultra-builder-pro-cli@3.0.2 --grok --global
-npx ultra-builder-pro-cli@3.0.2 --zcode --global
+npx ultra-builder-pro-cli@5.0.1 --opencode --global
+npx ultra-builder-pro-cli@5.0.1 --kimi --global
+npx ultra-builder-pro-cli@5.0.1 --grok --global
+npx ultra-builder-pro-cli@5.0.1 --zcode --global
 
 # All supported hosts
-npx ultra-builder-pro-cli@3.0.2 --all --global
+npx ultra-builder-pro-cli@5.0.1 --all --global
 ```
 
+ZCode ACP delegation additionally requires the independently built bridge and an
+installed ZCode Desktop runtime. Ultra ships the small source patch needed by ZCode
+CLI 0.16.5, but installs neither dependency and never records provider credentials:
+
+```bash
+git clone https://github.com/jpalmae/zcode-acp
+git -C zcode-acp checkout 42fe149d4b501469343c01f23ba3801832306d53
+git -C zcode-acp apply \
+  /path/to/installed/ultra-delegate/patches/zcode-acp-0.1.0-zcode-0.16.5.patch
+cargo test --locked --manifest-path zcode-acp/Cargo.toml
+cargo install --locked --path zcode-acp
+```
+
+The base commit, patch SHA-256
+`174dfd0feafe84320556a84b5ae08b10e44c5515fea4992fd1d58af54cee4e3d`, locked tests,
+fake E2E, release build, and real ZCode 0.16.5 session were verified for 5.0. Keep the
+binary on `PATH`; its `--version` must report
+`zcode-acp 0.1.0+ultra.zcode.0.16.5`. Use the platform's installed ZCode CLI path
+outside macOS.
+
+Provider identity is separate from the Host: ZCode Desktop is the runtime, while the
+model account may be domestic 智谱 BigModel or international Z.AI. A domestic BigModel
+Coding Plan config uses the official Anthropic-compatible endpoint
+`https://open.bigmodel.cn/api/anthropic` and a BigModel API key in
+`~/.zcode/cli/config.json`; it must not use the Z.AI OAuth login. The live 5.0 drill used
+`builtin:bigmodel-coding-plan/GLM-5.2`. See the
+[official BigModel Claude API compatibility guide](https://docs.bigmodel.cn/cn/guide/develop/claude/introduction).
+
+These pinned `npx` commands resolve the immutable registry version after publication.
+Source-tree verification uses `node bin/install.js --config-dir <isolated-path>` when
+it must not mutate the real user installation; the separate 5.0 release drill also
+verified an ownership-safe install, Doctor, ZCode uninstall, and reinstall in all six
+real Host homes.
+
 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.
@@ -207,13 +261,13 @@ Installation is managed, atomic, and provenance-checked.
 
 ```bash
 # Re-running install updates the managed artifact
-npx ultra-builder-pro-cli@3.0.2 --codex --global
+npx ultra-builder-pro-cli@5.0.1 --codex --global
 
 # Read-only diagnosis
-npx ultra-builder-pro-cli@3.0.2 --all --global --doctor --json
+npx ultra-builder-pro-cli@5.0.1 --all --global --doctor --json
 
 # Remove only managed Ultra assets
-npx ultra-builder-pro-cli@3.0.2 --all --global --uninstall
+npx ultra-builder-pro-cli@5.0.1 --all --global --uninstall
 ```
 
 `--config-dir <path>` isolates both the primary config and host-owned sidecars. It is
@@ -232,6 +286,12 @@ installation; all six support managed global installation and isolated
 
 ## Typical workflow
 
+For day-to-day work on an existing project, a new request starts with `ultra-change`,
+not an open-ended Research run. Enter `ultra-research` directly only to establish the
+first baseline, or to answer the bounded evidence question recorded by the same active
+Change. Every public transition shows a derived Route Card with its current Mode,
+Position, observable Exit condition, material checkpoint, and Next route.
+
 1. Select `ultra-init` once. It writes the skeleton, preserves the owner's raw one-line
    request and broad outline in the Project Brief, initializes Git when needed, and
    stops before product research.
@@ -248,8 +308,9 @@ installation; all six support managed global installation and isolated
    A profile never fixes task count. While that Change remains active, reconcile its
    same stable id; never open a second active Change for a separate request.
 4. Select `ultra-plan` to record public seams and produce resumable tracer-bullet tasks.
-   The model owns ordinary technical seams; the owner decides only a seam that changes
-   the public contract or another material trade-off.
+   Its earliest observable slice must cross a real consumer and real data path and name
+   the owner-visible observation. The model owns ordinary technical seams; the owner
+   decides only a seam that changes the public contract or another material trade-off.
 5. Select `ultra-dev` for one task at a time. `.ultra/tasks.json` is the sole task-status
    authority. Dev records typed v2 evidence and completes task review while the row is
    still `in_progress`; only after blocking findings and affected evidence are resolved
@@ -268,18 +329,23 @@ mode. A `session-local` grant lives only in the current conversation: when that
 activation is lost — a fresh session, another host, or compaction — the work stops and
 waits for a new owner activation. A `durable work-package` grant lets a fresh Agent or
 host continue one exact work package, but only after the Agent stably verifies the
-recorded grant itself. In both modes the model may select the covered Research, Plan,
-Dev, Test, and reconcile-only Deliver routes until the next semantic stop or declared
-budget, and neither mode grants finalization or archive: writing `delivery.md`, version
+recorded grant itself. In both modes the model may select the covered change-scoped
+Research, same-Change reconciliation, Plan, Dev, Test, and reconcile-only Deliver
+routes until the next semantic stop or declared budget, and neither mode grants
+finalization or archive: writing `delivery.md`, version
 or package posture, and archiving always require a current explicit owner invocation,
 as do commit, push, publication, deployment, installation, and every other external
 effect.
 
-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. It first
-filters the append-only ledger to tasks whose `change_id` matches the unique active
-Change; archived and abandoned unfinished rows are history, not the frontier.
+At any point, `ultra-status` can reconstruct the current position. A fresh session
+starts from repository root and `HEAD`, resolves exactly one active Change, then reads
+`.ultra/tasks.json`, the matching `context_file` and its `## Resume Note`, `CONTEXT.md`,
+relevant decisions, specifications, evidence, and the current Git diff. It never reruns
+completed Research merely because conversation memory is gone. If active authority is
+ambiguous or unreadable, Status switches to read-only recovery, names the unsafe fact,
+and gives the cheapest repair, retry, cancel, abandon, or fresh-session path without
+choosing an intent or writing semantic files. Archived and abandoned unfinished rows
+remain history, not the frontier.
 
 ## Three independent integration defences
 
@@ -311,8 +377,17 @@ All five hooks exit silently when `.ultra/` is absent. Details are in
 
 ## Delegation
 
-Delegation writes an immutable instruction and permission envelope, then starts the
-selected CLI in the background. Empty writable roots select native read-only mode;
+Delegation writes an immutable instruction and permission envelope, then selects one
+Host-local `AgentExecutionDriver` and starts it in the background. ACP is selected only
+for an executable stdio endpoint that negotiates stable v1 and has a passed per-Host
+conformance record with evidence; otherwise the same result contract uses `CliDriver`
+and reports the exact fallback reason. All six current Host rows have their own passing
+real-provider receipt; a missing executable, candidate-identity mismatch, or
+stale/missing receipt still returns the typed CLI fallback. An ACP authentication error
+detected before `session/prompt` runs the bounded CLI path once and records
+`acp_auth_required`; no other ACP failure is retried, so Ultra cannot duplicate a
+provider task. 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
@@ -320,20 +395,29 @@ beside the instruction. The digest-bound packet is embedded in the worker prompt
 strict host need not read instruction files outside its isolated worktree.
 
 ```bash
-ubp delegate run --to codex \
+node <loaded-ultra-delegate-skill-dir>/scripts/delegate.cjs 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
 ```
 
-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
+The loaded Skill path is canonical and works after a clean `npx` plugin install without
+a global `ubp` or another `npx` lookup for Ultra; the pinned Claude/Codex ACP adapters
+may themselves run through `npx`. `ubp delegate` remains a one-release compatibility
+wrapper. Use the installed Skill's `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.
 The immutable instruction names task execution/continuation, scoped Research evidence,
 or aggregate Change review/verification. The latter two may be read-only and do not
 require a task row, keeping pre-Plan Research and post-task cross-family review
 reachable without inventing ledger work.
+ZCode resolves only the installed Desktop runtime through the independently installed
+`zcode-acp` bridge and remains `experimental`. Its capability, read-only,
+permission, cancellation/no-orphan, cwd/diff, result-parity, and redaction drills pass;
+promotion still requires an official stability contract for the App-internal runtime.
+Doctor reports runner health, ACP capability, candidate identity, selected driver,
+fallback reason, and ZCode maturity independently.
 
 ## Host support
 
@@ -372,6 +456,12 @@ conformance rather than semantic acceptance.
 
 ## Documentation
 
+- [5.0 design and acceptance contract](docs/ULTRA-BUILDER-PRO-5.0.zh-CN.md) —
+  Route, Skill ownership, continuation, ACP/CLI execution, migration, and journey
+  boundaries implemented by 5.0.1.
+- [5.0 journey results](docs/evals/ultra-5-0-journey-results.md) — observable source,
+  isolated-runtime, real-provider, real-HOME, and cross-platform outcomes plus the
+  deliberately excluded service-deployment boundary.
 - [Current authority](.ultra/north-star.md) — this repository's accepted
   North Star, revision `north-star-v2-r3`, is the canonical current authority;
   `.ultra/tasks.json` and the stable Change under `.ultra/changes/active/` or