ultra-builder-pro-cli 3.0.2 → 5.0.0

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
 
@@ -72,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
-
-`adapters/_shared/host-profile.cjs` records current non-interactive invocation for:
+## 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 +141,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 +183,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.

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.