ultra-builder-pro-cli 3.0.2 → 5.0.1

package/docs/WORKFLOW-LIFECYCLE.md

@@ -1,14 +1,20 @@
 # Ultra Builder Pro workflow lifecycle
 
-Ultra v0.26 has no fixed runtime state machine. Skills define checkable entry and exit
+Ultra 5.0 has no fixed runtime state machine. Skills define checkable entry and exit
 criteria; repository files record facts; the host model chooses the route.
 
 ## Capability flow
 
 ```text
-ultra-init ──raw Project Brief──► ultra-research ──accepted baseline──► ultra-change
-                                      ▲                                  │
-                                      └──── scoped consequential evidence gap ────┘
+ultra-init/create|recover ──raw Project Brief──► ultra-research/baseline
+                                                       │
+                                                       ▼
+                                               ultra-change/intake
+                                                       │
+                   ┌── ultra-research/change-scoped ◄──┤ evidence-needed
+                   └── ultra-change/reconcile ─────────┘
+                                                       │ accepted
+                                                       ▼
 
 ultra-change ─► ultra-plan ─► ultra-dev (per task) ─► ultra-test ─► ultra-deliver
                      ▲                 │                    │
@@ -18,14 +24,16 @@ ultra-status    read-only router at any point
 ultra-delegate  orthogonal bounded execution on another CLI
 ```
 
-Arrows are recommendations, not automatic invocation by default. The owner explicitly
-selects each public workflow unless a live owner-activated execution grant
-(session-local activation or a stably verified durable work-package grant)
-authorizes the host model to 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. Delivery archives one
-stable `change_id`; the next request opens a new active id while prior task rows remain
-in the append-only ledger.
+Arrows are recommendations unless a live owner-activated Execution Grant authorizes the
+exact next mode. Public modes are either `explicit-entry`, `grant-continuable`, or
+read-only `router`; model-only methods are `model-discipline`. Scoped Research,
+same-Change reconciliation, Plan, Dev, Test, and Deliver reconciliation may continue
+only when the grant covers the same `change_id`, mode, effects, and stop conditions.
+Init, Change intake/evidence/acceptance/abandonment/primary transfer, Delegate, Deliver
+finalization, archive, and every external effect remain explicit-entry. Status remains
+owner-invoked, read-only, and supplies no continuation authority. Delivery archives one stable
+`change_id`; the next request opens a new active id while prior task rows remain in the
+append-only ledger.
 
 ## Topology and checkpoints
 
@@ -43,10 +51,14 @@ Every owner-facing checkpoint — a WIP at a stop, a closing Resume Note, a deli
 report — carries the eight fixed semantics defined in
 [artifact authority](ARTIFACT-AUTHORITY.md#owner-checkpoint-semantics): why, outcome,
 accepted boundary, delta, reality, decision needed, next bounded action, and not-done.
-Checkpoints are cognitive interfaces, not stage markers; alignment failure stops work
-until the owner re-accepts an outcome.
+The shared [Route Contract](../skills/ultra-status/references/route-contract.md) adds
+Route, Mode, Position, and Exit condition as navigation around those semantics. Every
+public Skill shows the card at entry, a material checkpoint, pause/blocked exit, normal
+exit, and before a public transition. Cards are derived observations, not stage markers,
+permission, or persisted route state; alignment failure stops work until the owner
+re-accepts an outcome.
 
-## Common entry contract
+## Common mode-aware entry contract
 
 Every user-invoked Skill reads, in order:
 
@@ -62,6 +74,11 @@ Every user-invoked Skill reads, in order:
 Missing files produce a precise recovery or initialization recommendation. They do not
 cause the Skill to invent a state transition.
 
+After reading these facts, the Skill chooses only one mode declared in its own Route
+table and emits the entry Route Card. If model-selected, it revalidates that this mode is
+grant-continuable and that the grant covers the same Change and effects. Host metadata
+is only coarse discovery; it never substitutes for this runtime check.
+
 ## Initialization
 
 Init writes the raw Project Brief and stable empty skeleton. `ultra-init` preserves the
@@ -73,22 +90,29 @@ launch another workflow.
 
 ## Research
 
-Research turns the brief into an accepted North Star and evidence-backed baseline.
-`ultra-research` uses Wayfinding only when a multi-lens path is unclear, then maps the
+Research has two modes. `baseline` explicitly turns the brief into an accepted North
+Star and evidence-backed baseline. `change-scoped` answers only one active Change's
+recorded Research Disposition and returns named evidence to that same Change for
+reconciliation. `ultra-research` uses Wayfinding only when a multi-lens path is unclear,
+then records entry question, selected lenses, omissions, dependencies, source plan,
+material checkpoints, observable stop condition, and return route before mapping the
 question to the smallest useful subset of seventeen focused references. The first six
 are semantic lenses with real dependencies: `00` precedes `01`; conditional `02` and
 `03` may fan out after the boundary is known; `04` consumes their relevant conclusions
 and is the first owner checkpoint; `05` extracts assumptions from `00` through `04`.
 Grilling controls how missing owner inputs are asked, Think tests one consequential
 decision, and Domain Modeling writes settled vocabulary; none owns the Research route.
-The final synthesis promotes accepted conclusions into the North Star, `CONTEXT.md`,
-three specifications, and a source-hash-bound distillate.
+The baseline synthesis promotes accepted conclusions into the North Star, `CONTEXT.md`,
+three specifications, and a source-hash-bound distillate. A change-scoped run updates
+only its mapped sections and never changes Change acceptance on its own. Lens counts are
+navigation facts, not semantic progress or a completion signal.
 
 ## Change reconciliation
 
-Change updates only the touched baseline rather than rebuilding it. `ultra-change`
-first compares requested behavior with accepted product truth and current code. It
-classifies changes by the resulting commitments:
+Change updates only the touched baseline rather than rebuilding it. Its visible modes
+are `intake`, `evidence-needed`, `reconcile`, and `accepted`. `ultra-change` first
+compares requested behavior with accepted product truth and current code. It classifies
+changes by the resulting commitments:
 
 - expansion and correction may proceed inside accepted intent;
 - a reduction waits for explicit owner authority.
@@ -99,6 +123,16 @@ existing evidence; `bounded` or `required` names the exact question, lenses, and
 evidence. Unsatisfied exit evidence routes to Research, then back through Change
 reconciliation before planning when the accepted contract needs an update.
 
+Draft intent is mutable. Revising a consequential accepted answer creates a superseding
+decision record so Status can reconstruct history without treating an event log as
+authority. Only same-Change, non-material `reconcile` may continue under a valid grant;
+opening or accepting a boundary, abandoning it, reducing a commitment, or changing the
+canonical writer is an explicit owner checkpoint.
+
+If the owner rejects the offered options as inadequate, Change preserves that answer,
+keeps the draft unresolved, and returns to evidence or materially different options. It
+never selects the closest rejected option or advances to Plan by default.
+
 A micro edit that makes no specification sentence false stays outside the Ultra
 lifecycle and uses ordinary repository TDD/verification. Once an active Change exists,
 Plan creates the smallest graph justified by the real seams, evidence, review, and
@@ -121,6 +155,12 @@ coupling and recovery risk justify a whole-path check. Cycles and broken trace p
 repaired before handoff. Complexity, file, task, line, and context counts are
 observations rather than plan-quality gates.
 
+Plan names the earliest executable tracer bullet's real consumer, real data path, and
+owner-visible observation. A product or contract evidence gap returns to
+`ultra-change/reconcile`; Change decides whether bounded Research is required. Ordinary
+technical uncertainty remains model-owned or becomes a bounded spike/tracer task, so
+Plan never bypasses Change by opening product Research directly.
+
 ## Task development
 
 `ultra-dev` writes the implementation plan into the task context before code. It uses
@@ -208,17 +248,17 @@ effects. Readiness grants none automatically.
 `ultra-status` infers the smallest next route from observable files:
 
 - no healthy skeleton or usable raw brief → init;
-- raw brief without an accepted baseline, or a consequential evidence gap → research;
+- raw brief without an accepted baseline → baseline research;
 - requested outcome without active Change → change;
 - draft or blocking active intent → change;
-- unsatisfied Research Disposition → research;
+- unsatisfied Research Disposition → change-scoped research, then the same Change reconciliation;
 - active Change without matching executable tasks → plan;
 - the unique matching `in_progress` task → dev;
 - only `pending` tasks remaining → report them as frontier candidates and recommend
   one exact task id for an explicit owner invocation of dev;
-  - a completed ledger row with missing, stale, or invalid v2 evidence/task review → dev
-    to record affected criteria and reason, explicitly reopen, and repair provenance;
-  - completed current-Change tasks with current v2 evidence and no matching fresh report → test;
+- a completed ledger row with missing, stale, or invalid v2 evidence/task review → dev
+  to record affected criteria and reason, explicitly reopen, and repair provenance;
+- completed current-Change tasks with current v2 evidence and no matching fresh report → test;
 - false report → route by finding and owner disposition, not by the boolean alone;
 - fresh, dispositioned report and unarchived Change → deliver.
 
@@ -229,6 +269,12 @@ replays the existing structural validators; they observe transport and freshness
 never decide semantic acceptance. Age, complexity, and file/task counts may be reported
 as context but never decide staleness or quality. It does not mutate artifacts.
 
+Status outputs the Route Card by default and expands `history`, `installation`,
+`delegation`, or `recovery` on request. An ambiguous or malformed active authority stops
+semantic routing and writes, but not diagnosis: recovery mode reports the typed fact,
+safe Git/directory observations, and the cheapest repair/retry/cancel/abandon path
+without selecting an ambiguous intent as truth.
+
 ## Delegation
 
 `ultra-delegate` is orthogonal to the lifecycle and requires explicit owner authority.
@@ -238,6 +284,10 @@ the latter two may be read-only and do not require a task, so both pre-Plan evid
 post-task review remain reachable. Every scope still binds the one active `change_id`, a
 clean isolated worktree, strict permission/result schemas, and primary-host inspection.
 The worker cannot write canonical `.ultra` files or perform external effects.
+Delegation itself is explicit-entry. Tool calls, plans, usage, permissions, process
+output, ACP updates, and terminal transport state remain execution observations; only
+the primary writer interprets the validated result against Research, task, review, or
+Test acceptance and selects the semantic route.
 
 ## Artifact closure
 
@@ -263,7 +313,7 @@ session contains `WORKER-PACKET.json`, `ADMISSION.json`, every selected speciali
 artifact, and `SUMMARY.json`; retain it until aggregate Test and Deliver have both consumed it
 successfully, then it may be garbage-collected. Premature loss requires a fresh Review
 and Test; never reconstruct the old receipt. Other derived observations keep their
-explicit rebuild or rerun paths. No route creates an unowned drift log, Change plan,
+explicit rebuild or rerun paths. No route creates an unowned drift log, parallel planning file,
 technical-debt report, or second delivery summary.
 
 ## Interruption and cross-host continuation
@@ -275,7 +325,11 @@ task, evidence, or report authority would lose meaning.
 
 Before stopping, the active task context records current facts, exact verification,
 open questions, Completion, and a closing Resume Note. The next session or host repeats
-the common entry contract and compares the working tree with those claims.
+the common entry contract, compares the working tree with those claims, and derives a
+fresh Route Card. It does not rerun completed Research merely because conversation
+memory is gone. When context pressure threatens a reliable continuation, the current
+Agent finishes the nearest safe write, refreshes the Resume Note, shows a stop card, and
+recommends a fresh session; context size does not become route authority.
 
 This path remains valid when hooks and `ubp` are disabled. A compact snapshot may be
 used as a hint, then checked against canonical files and Git.

package/docs/evals/ultra-5-0-journey-results.md

@@ -0,0 +1,62 @@
+# Ultra Builder Pro 5.0 journey 验收结果 — 2026-08-26
+
+## 结论
+
+14 条已接受 journey 都有可观察结果并全部为 `PASS`。2026-08-25 的初始候选曾把
+ZCode ACP promotion 记为诚实 `STOP`；2026-08-26 的 live activation 先复现并修复
+ZCode 0.16.5 runtime-preferences handshake，再通过国内 BigModel provider 完成真实
+receipt，因此该行已经由新证据取代。之后六 Host real user-HOME install/Doctor、
+Windows descendant cleanup 和 same-commit 三平台 CI 也分别完成；公共 registry 与
+GitHub Release 仍由最后的 release task 独立验证。
+
+这里的证据分为三类，不能互相冒充：
+
+- `source-contract`：验证 Skill 得到一致、可到达、可停止的导航合同，不断言任一模型的
+  实际表达质量；
+- `isolated-runtime`：运行真实 installer/Doctor/runner 代码，但只使用临时 config、fake
+  Codex registration 或 fake ACP/CLI target；
+- `live-provider`：六个 Host 分别完成 one bounded read-only ACP provider session；
+  receipt 只保留协议/result/进程/Git 事实和 digest，不保留 prompt 或 provider text。
+
+## Journey register
+
+| ID | Journey | Result | Observable success or stop | Executed evidence | Deliberate gap |
+|---|---|---|---|---|---|
+| J1 | Greenfield | PASS | `init/create` 停在 raw brief，`research/baseline` 以 selected coverage 与 stop condition 产出 accepted baseline，再推荐首个 Change | `tests/route-contract.test.cjs`; `docs/evals/ultra-5-0-route-journeys.md#j1--greenfield-baseline` | source-contract；六 Host live output 未跑 |
+| J2 | Existing project | PASS | 新请求先进入 Change；有界证据问题经 change-scoped Research 回到同一 `change_id`，accepted 后才进入 Plan | `tests/route-contract.test.cjs`; route journey J2 | source-contract；不把模型语义质量机械化 |
+| J3 | Micro edit | PASS | 不使 specification 失真的 edit 明确退出 Change lifecycle，使用 ordinary repository TDD/verification | `skills/ultra-change/SKILL.md`; `docs/WORKFLOW-LIFECYCLE.md#change-reconciliation` | source inspection；实际 edit 由调用项目验证 |
+| J4 | Owner revision | PASS | draft 原地修订；accepted consequential answer 以 `supersedes` record 保留旧 authority；拒绝现有选项不会默认进入 Plan | route journey J3；`skills/ultra-change/SKILL.md`; `skills/ultra-status/SKILL.md` | source-contract；owner judgment 不由 fixture 代替 |
+| J5 | Fresh session | PASS | 从 root/HEAD、唯一 active Change、matching ledger/context/Resume、baseline 与 Git 重建 Route Card，不重跑已完成 Research | `tests/ultra-5-journeys.test.cjs`; README；`docs/WORKFLOW-LIFECYCLE.md#interruption-and-cross-host-continuation` | 本地 artifact route；本轮未做六 Host live output 对比 |
+| J6 | Early value | PASS | Plan 的第一个 slice 必须穿过真实 consumer 与 data path，并命名 owner-visible observation | `tests/ultra-5-journeys.test.cjs`; `skills/ultra-plan/SKILL.md`; lifecycle | source-contract；真实产品 observation 由调用项目提供 |
+| J7 | Degraded state | PASS | 两个 active Change 产生 `active_change_ambiguous`；不读任一 intent body，不写 progress，并给出显式保留/archive/abandon/retry 路径 | `tests/ultra-5-journeys.test.cjs` 真实 SessionStart Hook scenario；Status/Review source | Review 在 ambiguity 时停在 packet write 前；不会制造 current scope |
+| J8 | Clean install delegation | PASS | isolated install 后从 loaded `ultra-delegate/scripts/delegate.cjs` 直接运行；不依赖 global `ubp`，Doctor 可见 runner；六个真实 Host home 的最终 Doctor 也都选择 ACP | `tests/install.test.cjs`; `tests/package-smoke.test.cjs`; migration fixture；`.ultra/evidence/v50-real-home-activation/` | published-registry consumer install 由 public-release task 验证 |
+| J9 | ACP happy path | PASS | stable v1 initialize -> session/new -> bounded derived updates -> exact Ultra terminal result | `tests/acp-driver.test.cjs`; `tests/delegate.test.cjs`; fake ACP agent | synthetic executable protocol evidence，不是 Host/provider conformance |
+| J10 | Permission denial | PASS | envelope 内写请求仅 `allow_once`；scope widening 立即拒绝，不能转成 successful Ultra result | `tests/acp-driver.test.cjs`; `tests/delegate.test.cjs` | fake agent；没有真实 provider permission UI |
+| J11 | Cancellation | PASS | cancel/timeout 到 typed terminal result，释放 delegation lock，POSIX process group 无 descendant orphan；`windows-latest` 的 cancel 与 timeout 也都终止真实 grandchild，可用 fresh id 重试 | `tests/delegate.test.cjs`; `tests/acp-driver.test.cjs`; GitHub Actions run `32935138736` | 若 Windows `taskkill` 不可用，fallback 只能保证 direct child cleanup |
+| J12 | CLI fallback | PASS | 六个 Host 都只在自己的 current receipt、stable ACP v1 和 executable 同时成立时选择 ACP；任一条件缺失仍选择 result-compatible CliDriver，并在 receipt/result/Doctor 显示 typed reason | `tests/acp-driver.test.cjs`; `tests/install.test.cjs`; six live receipts；migration Doctor scenario | provider retry 与 fallback 不自动改变 credential 或语义 authority |
+| J13 | ZCode bridge | PASS | installed ZCode 0.16.5 通过 `zcode-acp` v0.1.0 + digest-bound compatibility patch 接入 ACP v1，并用国内 BigModel provider 返回 exact Ultra result、clean Git 与 terminal worker | `skills/ultra-delegate/patches/zcode-acp-0.1.0-zcode-0.16.5.patch`; bridge receipt；`host-zcode.json`; live conformance report | transport maturity 仍为 `experimental`，因为 `app-server` 没有公开稳定性合同；缺 bridge/executable 时仍 typed fallback |
+| J14 | 3.x migration | PASS | 18 个 seeded project-owned files（覆盖 baseline、spec、active/archive Change、decision、task/context、Research、evidence、test report 与 binary bytes）在 install -> update -> Doctor -> uninstall 前后 mode、length 与 SHA-256 全相同；六 Host Doctor healthy 且显示 driver health | `tests/ultra-5-journeys.test.cjs` before/after digest 与 Doctor diagnostic | fixture 证明 updater 的真实文件边界，不声称覆盖未知第三方 artifact 语义 |
+
+## 可复现命令
+
+```bash
+node --test tests/ultra-5-journeys.test.cjs \
+  tests/route-contract.test.cjs \
+  tests/acp-driver.test.cjs \
+  tests/delegate.test.cjs \
+  tests/install.test.cjs \
+  tests/package-smoke.test.cjs
+```
+
+其中 migration case 会在临时目录执行六 Host install、第二次 install（update）、JSON
+Doctor 与 uninstall，并在 TAP diagnostic 中打印 canonical before/update/uninstall digest
+和每个 Host 的 selected driver/fallback reason。
+
+## 尚待 public-release task 完成的验证
+
+- 六个真实 Host 对同一 route fixture 的 Route Card 输出质量对比；
+- `v5.0.0` annotated tag、npm trusted publication、GitHub Release 与 published-package
+  consumer install 的同源性。
+
+六个 live ACP provider receipt、real-HOME activation、Windows cleanup 和三平台 CI
+已经完成；剩余 registry/release 缺口属于 public-release task，不会被本报告冒充完成。

package/docs/evals/ultra-5-0-live-acp-conformance.md

@@ -0,0 +1,93 @@
+# Ultra Builder Pro 5.0 live ACP conformance — 2026-08-26
+
+## 结论
+
+本报告把每个 Host 的 ACP 激活结论绑定到自己的真实 provider receipt；一个 Host 的
+结果不能提升另一个 Host。Claude Code、Codex、OpenCode、Kimi Code、Grok Build 与
+ZCode 当前全部为 `PASS`，六个 profile 都可以在对应 executable 存在时选择 ACP。
+
+`PASS` 的共同条件是：stable ACP v1、真实 provider、精确
+`ultra-delegation-result-v1`、只读 isolated worktree、Git unchanged，以及 worker
+进入 terminal state。`end_turn` 本身不是完成证据；它必须和 exact result/diff
+validator 一起成立。
+
+## 方法
+
+命令：
+
+```bash
+node skills/ultra-delegate/scripts/acp-conformance.cjs \
+  --host <host> \
+  --output .ultra/evidence/v50-live-acp-activation/host-<host>.json \
+  --timeout 240
+```
+
+Harness 经过真实 `delegate.cjs`、background worker、`AcpDriver`、exact result
+validator 和 Git-diff validator。Receipt 只保存候选命令、协议/result 状态、事件数量、
+子进程终态及临时 artifact digest；不保存 prompt、provider text、hidden reasoning、
+credential value 或 raw JSON-RPC。临时工作树和 raw artifacts 在计算 digest 后删除。
+
+## Host register
+
+| Host | Candidate | Result | Receipt SHA-256 | Observation |
+|---|---|---|---|---|
+| Claude Code | `npx --yes @agentclientprotocol/claude-agent-acp@0.70.0` | PASS | `9b1d88cbd5e5b66a56e0cf19f34e7f2107f9e4b8fde9d80b9eadcdfc8f4a25e3` | ACP v1, `end_turn`, exact result, clean Git, worker exited |
+| Codex | `npx --yes @agentclientprotocol/codex-acp@1.6.2` | PASS | `e82287609397807fb6968dff104d7f6569499b53c77be6a186aa33939a4c629e` | ACP v1, `end_turn`, exact result, clean Git; adapter was terminated after the logical turn |
+| OpenCode | `opencode acp` | PASS | `3575b148f6feb8c9f1472add705390e6d47b87be080403ec7006b66a29f7873b` | ACP v1, `end_turn`, exact result, clean Git, worker exited |
+| Grok Build | `grok agent stdio` | PASS | `370eeae12d63443188d519825ed8040fd8bba9b27fddb82e499d9cb590f4a33d` | ACP v1, exact result, clean Git; creation-time metadata was bounded and identity-checked before use |
+| Kimi Code | `kimi acp` | PASS | `30d8adec2877f80fadf0b20c3cb7fa6b732dea3598d7484c143f9835770301fe` | ACP v1, `end_turn`, exact result, clean Git, worker exited |
+| ZCode | `zcode-acp --zcode-path <installed-runtime> --no-browser` | PASS | `156080f88ed84a013fb26d93e5138230732d2ef0e2b5b10a7c3deb501d3548e9` | domestic BigModel provider, ACP v1, `end_turn`, exact result, clean Git, worker exited |
+
+## Claude Code
+
+The pinned official adapter completed the real read-only drill. Its profile may select
+ACP when `npx` is executable; `ULTRA_DELEGATE_FORCE_CLI=1` remains recovery.
+
+## Codex
+
+The pinned official adapter completed the real read-only drill. A nonzero adapter exit
+caused by client-owned stdin shutdown remains recorded separately and does not overturn
+an already validated protocol terminal and exact result.
+
+## OpenCode
+
+The native stdio server completed the real read-only drill through `opencode acp`.
+
+## Grok Build
+
+Grok emits bounded creation-time metadata before returning `session/new`. Ultra accepts
+only four metadata update kinds at that point, caps the transient buffer at 32 messages
+and 256 KiB, and validates each buffered session ID after the response. Early content,
+tool traffic, mismatched identity, or overflow remains a typed failure.
+
+## Kimi Code
+
+Kimi 1.49.0 completed an owner-authenticated, read-only ACP provider session and returned
+the exact Ultra result. Its profile may select native `kimi acp` when executable.
+
+## ZCode
+
+Ultra resolves independently installed `zcode-acp` v0.1.0 source commit
+`42fe149d4b501469343c01f23ba3801832306d53`, the digest-bound Ultra compatibility patch
+`174dfd0feafe84320556a84b5ae08b10e44c5515fea4992fd1d58af54cee4e3d`, and installed
+ZCode CLI 0.16.5. The patch answers the new `session/requestRuntimePreferences` request
+that otherwise deadlocks upstream v0.1.0 during `session/create`. Locked Rust tests,
+the 0.16.5 regression, patched fake app-server E2E, release build, installed binary
+digest, exact bridge build marker, and the real provider session all pass.
+
+Authentication uses the Owner's existing domestic BigModel Coding Plan provider at
+`https://open.bigmodel.cn/api/anthropic` with model `GLM-5.2`; it does not use the
+international Z.AI OAuth flow. Credential values are absent from this report and its
+receipt. The transport remains `experimental` because the downstream ZCode app-server
+is not a public stability contract.
+
+## Recovery
+
+- Missing adapter, bridge, candidate identity, protocol version, or evidence returns a
+  typed CLI fallback reason before provider execution. If `session/new` reports
+  `acp_auth_required` before a prompt is sent, Ultra invokes the bounded CLI fallback
+  once; it never retries any other ACP failure.
+- `ULTRA_DELEGATE_FORCE_CLI=1` selects the bounded CLI path explicitly.
+- A failed or stale Host receipt is replaced only by a fresh bounded drill for that Host.
+- Raw receipt bytes remain repository evidence under `.ultra/evidence/`; this packaged
+  report carries their SHA-256 bindings without packaging private provider output.

package/docs/evals/ultra-5-0-route-journeys.md

@@ -0,0 +1,145 @@
+# Ultra 5.0 Route Contract journey 评测 — 2026-08-25
+
+## 结论
+
+本轮以当前 Skill source 和 adapter policy 做静态 journey inspection。九个 public/router
+Skill 已共享一个 Route Contract；Greenfield、existing project、owner revision、early
+value、fresh session、degraded diagnosis 和 grant continuation 都有可达入口、可观察
+exit、material checkpoint 与 next/repair path。
+
+这不是 Host/provider 实跑。它验证的是模型拿到 Skill 后是否拥有一致的导航合同，不证明
+任何特定模型一定会生成高质量 Route Card，也不证明后续 ACP transport 已完成。live
+cross-host journey 留在 `v50-migration-journeys`。
+
+## 判定方法
+
+每个场景检查五个问题：
+
+1. 入口文件能否唯一判断 Route 与 Mode；
+2. Owner 能否看到 Why、Outcome、Accepted boundary、Position、Exit condition、Reality、
+   Decision needed、Next 与 Not done；
+3. 停止是否由 material checkpoint 或可观察 evidence 触发，而非计数器；
+4. 没有授权时是否推荐下一 route，有有效 Execution Grant 时是否只继续 covered mode；
+5. authority 损坏时是否仍有 read-only diagnosis 和最便宜恢复路径。
+
+`PASS` 表示当前 source 明确提供上述行为；它不是对业务语义或 live model output 的自动
+判定。
+
+## J1 — Greenfield baseline
+
+- 起点：无 `.ultra/`，Owner 给出一个原始产品想法。
+- 预期路线：`ultra-init/create` → 推荐 `ultra-research/baseline` → 推荐
+  `ultra-change/intake`。
+- 可观察 exit：Init read-back skeleton 与 raw Project Brief；Research read-back selected
+  reports、accepted North Star、specifications、vocabulary 与 synthesis。
+- material checkpoint：Owner 确认 raw outline；Research 的方向、scope、synthesis 和
+  North Star acceptance。
+- 禁止行为：Init 写 North Star；Research 没有 selected coverage/stop condition；任一
+  Skill 自动打开 Change。
+- source evidence：`skills/ultra-init/SKILL.md`、`skills/ultra-research/SKILL.md`。
+- 结果：`PASS (source inspection)`。
+
+## J2 — Existing project bounded evidence
+
+- 起点：已有 accepted baseline，无 active Change，Owner 提一个新 feature/fix。
+- 预期路线：`ultra-change/intake` → `evidence-needed` →
+  `ultra-research/change-scoped` → 同一 `change_id` 的 `ultra-change/reconcile` →
+  `accepted` → `ultra-plan/decompose`。
+- 可观察 exit：Change 先固定 bounded question 与 named exit evidence；Research 只完成该
+  question；Change 再决定 evidence 是否改变 intent；Plan 只消费 accepted Change。
+- 禁止行为：原始需求先自动进入 Research；Research 打开第二个 Change；Plan 直接打开
+  Research 或自己改变 product contract。
+- source evidence：`skills/ultra-change/SKILL.md`、`skills/ultra-research/SKILL.md`、
+  `skills/ultra-plan/SKILL.md`。
+- 结果：`PASS (source inspection)`。
+
+## J3 — Owner revision、拒绝选项与 history
+
+- 起点：Owner 修改尚未接受的 Change，或推翻一个已接受的 consequential decision。
+- 预期路线：draft 在同一 `intent.md` 内修订；accepted decision 以新的
+  `.ultra/decisions/<id>.md` 和 `supersedes` 保留历史；`ultra-status/history` 可按需解释
+  当前答案、被拒绝选项与旧边界。
+- Decision needed：只保留一个会实质改变 outcome/boundary 的问题；Owner 拒绝当前选项
+  时，Change 保持 draft/evidence-needed 并补证据或新选项，不假装 accepted，不进入 Plan。
+- 禁止行为：覆盖旧 accepted decision、用 event log 代替 authority、因 Owner 没选现有
+  选项就制造默认答案。
+- source evidence：`skills/ultra-change/SKILL.md`、`skills/ultra-status/SKILL.md`、
+  `docs/ARTIFACT-AUTHORITY.md#decisions-and-reductions`。
+- 结果：`PASS (source inspection)`。
+
+## J4 — Earliest observable value
+
+- 起点：accepted/evidenced Change 已进入 Plan。
+- 预期路线：`ultra-plan/decompose` 明确第一个 executable slice 的 real consumer、real
+  data path 与 owner-visible observation，再把 exact task 交给 `ultra-dev/execute`。
+- 产品或 contract evidence gap：返回 `ultra-change/reconcile`，由 Change 决定是否记录
+  bounded Research Disposition。
+- ordinary technical uncertainty：模型解决，或用 bounded spike/tracer task；不重新打开
+  product Research。
+- 禁止行为：先完成整层基础设施、用 task count 代表价值、Plan 直接启动 Research。
+- source evidence：`skills/ultra-plan/SKILL.md`。
+- 结果：`PASS (source inspection)`。
+
+## J5 — Fresh-session recovery
+
+- 起点：对话上下文丢失，但 repository 与 Git 仍在。
+- 预期路线：先读 root/HEAD，再唯一解析 active `change_id`，读取 matching task ledger、
+  context 与 closing Resume Note，然后核对 Brief、North Star、decisions、specs、evidence
+  和 worktree，重新推导 Route Card。
+- 可观察 exit：Owner 能看到当前 boundary、真实 diff/evidence、下一 exact task 或 repair；
+  已完成 Research 不被重跑。
+- context pressure：在最近 safe write 更新 Resume Note，显示 stop card，并建议 fresh
+  session；token/file count 不成为 semantic gate。
+- source evidence：`skills/ultra-status/references/route-contract.md`、
+  `skills/ultra-status/SKILL.md`、`skills/ultra-dev/SKILL.md`。
+- 结果：`PASS (source inspection)`。
+
+## J6 — Degraded authority diagnosis
+
+- 起点：两个 active Change、malformed intent、stale trace 或暂时不可读 authority。
+- 预期路线：`ultra-status/recovery` 停止从 ambiguous Change 做 semantic routing/write，
+  但仍用 typed diagnostic、安全的 Git/directory observations 和未冲突的 canonical files
+  显示原因与 repair/retry/cancel/abandon 路径。
+- 禁止行为：选第一个目录、把“不能写”表达为永久 in-progress、因为 authority 损坏而
+  关闭 Status/Review 的只读诊断。
+- source evidence：`skills/ultra-status/SKILL.md`、
+  `skills/ultra-status/references/route-contract.md`。
+- 结果：`PASS (source inspection)`。
+
+## J7 — Grant-aware continuation
+
+- 起点：同一 accepted Change 有当前有效 Execution Grant，覆盖 Plan、一个 exact Dev task、
+  Test 与 Deliver-reconcile 的 local reversible effects。
+- 预期路线：每次 public transition 先显示 Route Card；Skill 重新核对 Mode、`change_id`、
+  effects、budget 与 stop conditions，再继续 covered mode。
+- 必停点：Change acceptance/reduction、primary transfer、unresolved P0/P1、Deliver
+  finalization/archive，以及任何 commit/push/publish/deploy/provider spend。
+- 无 grant：同一路径在当前 Skill exit 停止，并把 `Next` 表达为 recommendation。
+- 禁止行为：Host implicit bit 授权 Change intake/acceptance 或 Deliver finalization；grant
+  自动扩展 scope；Route Card 自己成为 permission。
+- source evidence：`adapters/_shared/runtime-assets.cjs`、九个 public/router Skills、
+  `skills/ultra-status/references/route-contract.md`。
+- 结果：`PASS (source inspection)`。
+
+## J8 — Delegation event versus semantic route
+
+- 起点：Owner 显式授权一个 bounded task/research/aggregate worker slice。
+- 预期路线：`ultra-delegate` launch 前显示 primary Route Card；运行时 permission、tool、
+  plan、usage、process 或 ACP update 只进入 Position/Delta/Reality；terminal result 经验证
+  后回到原 primary Skill，由 primary writer 解释和集成。
+- 禁止行为：worker event 写 canonical `.ultra`、terminal `finished` 自动完成 task、
+  delegation 升级为 primary transfer。
+- source evidence：`skills/ultra-delegate/SKILL.md`、Route Contract。
+- 结果：`PASS (source inspection; ACP driver not implemented in this task)`。
+
+## Route Contract 冻结时本轮未证明
+
+- 尚未在六个真实 Host 上比较同一 fixture 的 Route Card 质量。
+- 本次 Route Contract inspection 没有证明 ACP v1 driver、CLI fallback、Skill-local
+  runner 或 ZCode bridge；这些能力必须由各自后续任务提供独立 evidence。
+- 尚未执行 3.x byte-preservation migration journey。
+- 尚未完成 5.0 package/release verification。
+
+这些缺口分别路由到 `v50-acp-execution-drivers`、`v50-skill-local-delegation`、
+`v50-migration-journeys` 与 `v50-release-candidate`，不会被本次 source inspection
+冒充为通过。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "3.0.2",
+  "version": "5.0.1",
   "description": "File-first Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, Grok Build, and ZCode.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
@@ -29,6 +29,7 @@
     "hooks/README.md",
     "LICENSE",
     "CHANGELOG.md",
+    "README.zh-CN.md",
     ".ultra-template",
     "docs/PHILOSOPHY.md",
     "docs/ARCHITECTURE.md",

package/skills/ultra-change/SKILL.md

@@ -8,17 +8,35 @@ description: Open or reconcile one bounded unit of work by comparing specificati
 A Change connects research, plan, implementation, verification, review, and delivery.
 Reconcile first so new intent does not bury an existing specification/code conflict.
 
+## Route modes
+
+| Mode | Entry | Observable exit | Next |
+|---|---|---|---|
+| `intake` | Explicit owner request with no active Change | One stable draft `change_id` captures outcome, acceptance, non-goals, seams, trace, and Research Disposition | Stay in `ultra-change` for acceptance or move to `evidence-needed` |
+| `evidence-needed` | The draft names one load-bearing question and required exit evidence | The bounded Research Disposition is owner-visible and records its return to this Change | Recommend `ultra-research/change-scoped` |
+| `reconcile` | Explicit invocation or a valid Execution Grant for the same active Change | Research or implementation evidence is dispositioned in the same intent and any material delta is accepted | Recommend or continue to `ultra-plan/decompose` when the intent is accepted |
+| `accepted` | Explicit owner acceptance of the Change outcome and boundary | Accepted intent, current trace, satisfied Research Disposition, and resolved material decisions are read back | Recommend `ultra-plan/decompose` |
+
+Follow `../ultra-status/references/route-contract.md`. A draft may be revised in place;
+an already accepted owner decision is revised by a superseding decision record so its
+history remains recoverable. Show a Route Card before each public transition. Under a
+valid grant only the non-material `reconcile` mode may continue implicitly.
+
 ## Before you start
 
-1. Read `references/change-contract.md` and apply its **Active Change authority
+1. If model-selected, require `reconcile` mode for the same active Change and verify a
+   live grant under `references/execution-grant.md`. Any intake, evidence-needed boundary,
+   acceptance, abandonment, reduction, or primary transfer stops and recommends current
+   explicit owner invocation; a coarse Host invocation bit cannot authorize it.
+2. Read `references/change-contract.md` and apply its **Active Change authority
    resolution** before reading any active `intent.md`, relying on a current `change_id`,
    or creating or writing a Change. Continue only from its positively observed stable
    zero-or-one result; return its typed repair for any other result. With one active
    Change, read `.ultra/tasks.json`, then only its unfinished `context_file` values.
    Update the same `change_id`; never open a second active Change.
-2. Read `.ultra/project-brief.md`, `CONTEXT.md`, relevant `.ultra/decisions/`, and
+3. Read `.ultra/project-brief.md`, `CONTEXT.md`, relevant `.ultra/decisions/`, and
    `.ultra/north-star.md` for raw provenance, accepted language, and direction.
-3. Grep archive and abandoned Changes that touched this area. Prefer archived
+4. Grep archive and abandoned Changes that touched this area. Prefer archived
    `delivery.md`; otherwise read `archive-summary.md`, `verification.md`, `intent.md`,
    and remaining Markdown. Read abandoned Changes as history of rejected boundaries and
    reusable evidence, never current intent. A missing `delivery.md` does not mean no history;
@@ -100,7 +118,9 @@ count.
 
 Output active `intent.md` under a stable id, justified specification patches, qualifying
 decision or vocabulary updates. For an evidence gap recommend `ultra-research`; when
-evidenced recommend `ultra-plan`. Invoke neither.
+evidenced recommend `ultra-plan`. Invoke neither without a covering grant; with a valid
+grant covering same-Change reconciliation and Plan, show the transition Route Card and
+allow Plan to re-verify its own entry contract.
 
 ## Abandoning a Change
 
@@ -128,6 +148,11 @@ Every non-empty bucket, the Change boundary, abandonment, and anything
 reconciliation turns up that shrinks a prior commitment. A change that makes no
 specification sentence false needs no permission at all.
 
+If the owner rejects the presented options or says none is adequate, preserve that
+answer as current intake and keep the intent draft or move it to `evidence-needed`.
+Gather the missing discriminating evidence or present materially different options; do
+not select the nearest rejected option, manufacture acceptance, or route to Plan.
+
 ## References
 
 - `../ultra-grilling/SKILL.md` — the loop for settling the boundary.
@@ -135,5 +160,6 @@ specification sentence false needs no permission at all.
   `intent.md` structure, and profile fields.
 - `references/execution-grant.md` — read when the owner requests bounded workflow continuation under a session-local or durable grant.
 - `references/primary-transfer.md` — read when the owner moves the work package's canonical writer to another Agent (OFFER → ACK → RESULT).
+- `../ultra-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
 - `../ultra-think/references/autonomy-boundary.md` — read before removing a promise.
 - `../ultra-tdd/SKILL.md` — read for an evidenced one-slice correction.