ultra-builder-pro-cli 0.26.2 → 5.0.0

package/docs/ARCHITECTURE.md

@@ -1,24 +1,27 @@
 # Ultra Builder Pro architecture
 
-Ultra Builder Pro v0.26 is a file-first workflow asset package for five coding-agent
-hosts. Its architecture is deliberately asymmetric: the host model owns meaning and
-strategy; Ultra mechanizes only portable prompts, observable files, bounded effects,
-and recovery.
+Ultra Builder Pro is a file-first workflow asset package for six coding-agent hosts,
+implementing the provider-neutral **Ultra Core Protocol**: cognitive alignment,
+per-fact authority, explicit work-package grants, typed evidence, bounded effects,
+checkpoints, and terminal review convergence — carried entirely by Skills,
+owner-readable files, Git, host adapters, and optional Hooks. The host model owns
+meaning and strategy; Ultra mechanizes only portable prompts, observable files,
+bounded effects, and recovery.
 
 ## System boundary
 
 ```text
 Owner request
-    │ explicit selection
+    │ explicit selection or verified execution grant (session-local / durable)
     ▼
-User-invoked Skill ──────── recommends next public route and stops
+Public Skill mode ───────── stops at the next owner boundary
     │
     ├── model-invoked disciplines (reasoning methods)
     ├── source / tests / runtime / primary documentation
     └── canonical project files + Git
              │
              ├── optional five hooks (derived context and effect guard)
-             └── optional delegate CLI (bounded external host process)
+             └── optional delegation (ACP-first driver or CLI fallback)
 ```
 
 Ultra has no semantic runtime supervisor. Reading the files is the recovery protocol;
@@ -34,9 +37,20 @@ Fourteen `skills/*/SKILL.md` files carry the workflow:
 - five model-invoked reusable disciplines;
 - one read-only router.
 
-The exact allowlists live in `adapters/_shared/runtime-assets.cjs`. Public workflows
-never invoke another public workflow. They may use model-invoked disciplines and then
-recommend the next owner route.
+The exact allowlists and per-mode invocation map live in
+`adapters/_shared/runtime-assets.cjs`. Public modes are `explicit-entry`,
+`grant-continuable`, or read-only `router`. Under an accepted Change-scoped Execution
+Grant, change-scoped Research, same-Change reconciliation, Plan, Dev, Test, and Deliver
+reconciliation may be selected by the model only while `session-local` activation is
+live or a fresh Agent has stably verified a `durable work-package` grant. Host metadata
+does not preserve session activation: a fresh session, Host switch, or compaction stops
+`session-local` continuation until the Owner activates it again. Host metadata
+is a coarse discovery bit; each loaded Skill rechecks its mode, Change, effects, and
+material checkpoints. Stored text alone grants nothing, and neither mode grants Change
+intake/acceptance, primary transfer, Deliver finalization or archive; every external
+effect still stops. The derived Route Card makes each boundary owner-visible without
+becoming workflow state or authority. The router itself remains owner-invoked; public
+Skills derive their own cards from the shared Route Contract instead of invoking it.
 
 Research's seventeen references are workflow-owned semantic lenses. Its optional
 `wayfinding.md` maps a multi-lens question without becoming a new Skill or authority.
@@ -51,21 +65,44 @@ Canonical semantic authority consists of:
 - `.ultra/north-star.md` for the accepted direction, outcome or metric decision, hard
   constraints, and exclusions established by Research;
 - `.ultra/specs/*.md` for product, architecture, discovery, and research distillate;
-- `.ultra/changes/{active,archive,abandoned}/<id>/intent.md` for bounded outcomes with
-  one stable id across directory moves;
-- append-only `.ultra/tasks.json` rows carrying `change_id`, plus each task's `context_file`;
-- `.ultra/decisions/*.md`, `.ultra/evidence/`, `.ultra/test-report.json`, and research;
+- `.ultra/changes/{active,archive,abandoned}/<id>/intent.md` for bounded outcomes, North
+  Star Trace, and a required Execution Grant (`session-local` and inert without current-
+  session activation by default) with one stable id across directory moves;
+- append-only `.ultra/tasks.json` v2 rows carrying `change_id` and the sole task status,
+  plus each task's status-free `context_file`;
+- `.ultra/decisions/*.md`, typed `.ultra/evidence/`, `.ultra/test-report.json`, and research;
 - repository-root `CONTEXT.md` for ubiquitous language;
 - Git for revision identity, history, moves, diff, and rollback.
 
 Each semantic fact has one canonical representation. A summary can point to authority,
 but cannot become a second authority merely because it is convenient to read.
+Task status therefore lives only in `.ultra/tasks.json`. Legacy context Status and
+Complexity fields are migration observations; readers report them and the ledger wins.
+Current task evidence uses `ultra-task-evidence-v2`, whose typed command, inspection,
+owner-judgment, and external-observation entries retain distinct authorities. Only the
+owner can supply an owner-judgment result. Structural validators report exact facts and
+never decide semantic acceptance. Command and external evidence store a safe
+repository-relative raw ref plus `raw_evidence_sha256`; structural validation does not
+open that ref. Dev binds bounded stable ordinary non-symlink receipt bytes before record
+publication, while Test, Status, and Deliver recheck the raw digest and then the exact
+record `evidence_digest`. The product-worktree digest excludes `.ultra/evidence/**`, so
+evidence publication cannot invalidate the freshness value it records.
 
 One primary host model writes this authority in a worktree. Native subagents are
 read-only sensors; delegated CLIs write isolated non-`.ultra` roots and return receipts.
 Sequential Changes share the ledger by stable id, while current readers filter by the
 one unique active Change. This keeps concurrency explicit in Git instead of adding a
-semantic lock service or workflow engine.
+semantic lock service or workflow engine. When the canonical writer itself changes
+Agent, an owner-granted primary transfer moves the role exclusively — a derived
+OFFER binding canonical refs/hashes, HEAD, and worktree digest; a receiver ACK that
+is ready only on full stable-read match; sole-writer execution; a frozen terminal
+RESULT — with receipts under `.ultra/.runtime/handoffs/` kept as rebuildable
+observations and delegated workers never acquiring canonical write authority
+(`skills/ultra-change/references/primary-transfer.md`).
+
+Autonomous coding uses the host's existing model-tool loop, one canonical writer, and
+the same task/evidence/review files. Ultra adds no persisted route position: budgets are
+hard ceilings, while the model interprets whether acceptance and stop conditions hold.
 
 ### Adaptation plane
 
@@ -76,15 +113,18 @@ semantic lock service or workflow engine.
 - hook command paths and wire normalization;
 - atomic managed installation, provenance, doctor, and uninstall behavior.
 
-`adapters/_shared/plugin-core.cjs` owns the common copy and managed-publication
-mechanics. `host-profile.cjs` owns the five non-interactive delegation argv contracts.
-Adapters never rewrite workflow meaning.
+`adapters/_shared/plugin-core.cjs` owns the common copy, managed publication, and
+delegation-runner inventory and driver-reporting checks. The canonical six-host
+non-interactive profile lives
+beside the installed launcher at `skills/ultra-delegate/scripts/host-profile.cjs`;
+`adapters/_shared/host-profile.cjs` is a one-release compatibility re-export. Adapters
+never rewrite workflow meaning.
 
 ### Why the old Agents are Skill assets now
 
 The retired custom-agent files did not own product authority. They contained reusable
 review lenses, debugging, test execution, and review coordination. v0.26 keeps those
-methods on the common surface all five hosts actually share:
+methods on the common surface all six hosts actually share:
 
 - six review workers map to `ultra-review/references/{code,design,errors,tests,spec,comments}.md`;
 - review coordination and the former general code reviewer map to the parent
@@ -99,9 +139,20 @@ the parent model runs the same references sequentially.
 ### Observation plane
 
 Five hooks read canonical files and emit bounded context or observations. Their output
-under `.ultra/.runtime/`, `.ultra/progress/`, or `.ultra/reviews/` is derived and
-disposable. The dangerous-command hook is the only hard effect guard; it classifies a
-small named destructive set and provides an exact-command authorization repair.
+under `.ultra/.runtime/` and `.ultra/progress/`, and review artifacts under
+`.ultra/reviews/`, are derived rather than semantic authority. A current strict review
+session contains `WORKER-PACKET.json`, `ADMISSION.json`, every selected specialist
+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. The dangerous-command hook is the only
+hard effect guard; it classifies a small named destructive set and provides an
+exact-command authorization repair.
+
+ACP `session/update` telemetry follows the same rule. The Skill-local driver stores only
+bounded redacted event metadata under the delegation directory, drops hidden thought
+chunks and raw tool payloads, and exposes the latest safe observation through status.
+The journal, session id, capability report, permission decision, and stop reason are all
+disposable execution observations; none can select a route or establish completion.
 Additive protected-branch publication remains advisory when portable host wiring cannot
 project a trusted owner-approval receipt; history rewrites and branch deletion remain
 guarded.
@@ -109,16 +160,20 @@ guarded.
 ## Completion and recovery
 
 An operation is complete only when its accepted user outcome works through the real
-public seam. Route/schema/UI shells, local unit green, or an edited task status are not
-end-to-end evidence by themselves.
+public seam. Route/schema/UI shells, local unit green, or an edited ledger status are not
+end-to-end evidence by themselves. A task remains `in_progress` through its task review;
+only after blocking findings are resolved or authoritatively dispositioned and affected
+v2 evidence is refreshed may the primary model write `completed` to the ledger.
 
 Every user Skill starts by reading:
 
 1. zero or one active `change_id`, diagnosing more than one;
-2. `.ultra/tasks.json` tasks whose `change_id` matches it;
+2. `.ultra/tasks.json` tasks whose `change_id` matches it, treating that ledger as the
+   sole task-status authority;
 3. the matching frontier task's `context_file` and closing `## Resume Note`;
 4. `CONTEXT.md` and relevant decisions;
-5. the active Change, specifications, evidence, and current Git state.
+5. the active Change, specifications, current v2 task evidence and retained task-review
+   provenance, and current Git state.
 
 That same sequence works after compaction, a fresh process, disabled hooks, or a host
 change. Compact snapshots can accelerate recovery but never outrank the source files.
@@ -132,22 +187,49 @@ Three independent Skills protect the vertical path:
 2. `ultra-dev` records six separate evidence dimensions, including real persistence,
    default-on behavior, vertical execution, and spec trace.
 3. `ultra-test` searches exports for real consumers, exercises the primary flow, and
-   binds the result to Change id, task ids, intent, HEAD, and product-worktree digest.
+   binds the result to Change id, task ids, intent, HEAD, product-worktree digest, exact
+   raw receipt SHA-256 values, and the containing task-evidence digests.
 
 These are independent sensors. None rewrites a finding into product truth.
 
 ## Delegation
 
-`ubp delegate run` validates all paths inside the selected project, reads a bounded
-instruction and permission JSON, builds argv from one host profile, and starts a
-background worker. Declared writable roots must already exist inside the delegated
+The canonical installed `ultra-delegate/scripts/delegate.cjs` validates all paths inside
+the selected project, reads a bounded instruction and permission JSON, probes the
+Skill-local Host profile, and starts the Skill-local background worker. One
+`AgentExecutionDriver` boundary selects stable ACP v1 stdio only after the exact Host's
+versioned conformance row passes with a non-empty evidence reference and the declared
+executable and bounded candidate-identity probes succeed; otherwise the same packet
+runs through `CliDriver` and records the fallback reason. Capability inspection uses
+local version commands only and does not start a provider task. The
+one-release `ubp delegate` surface imports those same functions and owns no forked
+behavior. Declared writable roots must already exist inside the delegated
 worktree; no readable-root or external-effect grant can widen the host's native
 sandbox. Empty writable roots select native read-only mode. The model returns a
-schema-constrained final response; the Node worker validates `finished`, `blocked`, or
+schema-constrained final response; `AcpDriver` reconstructs only agent-message text as
+that same validator input, while ACP stop reasons remain observations. It accepts a
+bounded set of creation-time session metadata that some agents emit before
+`session/new` resolves, then validates every buffered session identity before exposing
+derived events; early message/tool content and unbounded startup traffic fail closed.
+The Node worker validates `finished`, `blocked`, or
 `failed` and atomically publishes `result.json` beside the instruction. The model never
 writes its own receipt; stdout, stderr, native final output, and the launch receipt
 remain diagnostic files.
 
+`ULTRA_DELEGATE_FORCE_CLI=1` is a per-run recovery seam that selects the same bounded
+CLI validator path and records `acp_forced_cli`; it does not erase conformance evidence.
+An `acp_auth_required` error from `session/new` before `session/prompt` also selects that
+already-bound CLI path once. The terminal result retains redacted ACP fallback metadata;
+no post-prompt or other ACP failure is automatically retried.
+ZCode uses the independently installed, source-pinned `zcode-acp` bridge plus the
+digest-bound 0.16.5 runtime-preferences patch to translate stable ACP v1 to the installed
+Desktop runtime. Ultra ships only the patch, neither the bridge binary nor App bytes.
+The profile verifies an Ultra build marker on that bridge plus the exact installed
+runtime version before ACP selection.
+The Host/runtime is ZCode Desktop while provider identity remains owner-controlled; the
+verified local receipt uses domestic BigModel rather than international Z.AI OAuth. The
+headless ZCode transport remains explicitly experimental even after conformance.
+
 The instruction binds the active `change_id` and one of three semantic scopes: task
 execution/continuation, scoped Research evidence, or aggregate Change
 review/verification. Only task execution requires a task row. The read-only Research
@@ -157,6 +239,25 @@ to make delegation reachable.
 Delegation does not grant authority or copy semantic state into another store. The
 worker reads and writes the same repository files in the specified worktree.
 
+## Optional Graph/Loop control plane
+
+Long-running, multi-Agent, cross-Host work can justify an external coordination
+layer (for example a LoopX-style kernel) that owns goal/todo identity, claims and
+leases, attention queues, quotas, human-gate records, handoff receipts, and
+append-only run/effect observations. Such a layer is **optional and currently not
+integrated**: no adapter, dependency, daemon, or scaffold for one ships in this
+package, and the Ultra Core Protocol remains fully usable on files plus Git with
+every optional layer absent.
+
+The boundary is fixed regardless of future integration: the control plane may
+observe and coordinate — it may never own the North Star, product meaning,
+acceptance, semantic severity, architecture or scope decisions, a "quality is
+sufficient" verdict, or the authority to start an unauthorized Agent. Enabling it
+requires a real coordination problem the owner accepts (multi-session parallel
+frontiers, claim/write conflicts, long external waits, explicit quotas, cross-Host
+handoff) plus an adapter with a live consumer; deleting or disabling it must always
+leave canonical project truth and human recovery intact.
+
 ## Deliberate absences
 
 The architecture does not include:
@@ -165,6 +266,7 @@ The architecture does not include:
 - an MCP server or tool protocol;
 - a workflow state machine or semantic validator;
 - a background orchestration daemon;
+- a resident ACP service, ACP session store, or semantic route ledger;
 - command or custom-agent prompt projections;
 - general memory, code graph, browser, deployment, or framework packages.
 

package/docs/ARTIFACT-AUTHORITY.md

@@ -1,7 +1,10 @@
 # Ultra artifact authority
 
 This document defines which project artifacts carry semantic authority, who may change
-them, how staleness is detected, and how recovery works in Ultra Builder Pro v0.26.
+them, how staleness is detected, and how recovery works in Ultra Builder Pro. Since the
+accepted 3.0 design it is the per-fact expression of the Ultra Core Protocol: one
+canonical representation per semantic fact, explicit authorization, bounded effects,
+and reachable recovery, on files plus Git alone.
 
 ## Rules
 
@@ -12,6 +15,94 @@ them, how staleness is detected, and how recovery works in Ultra Builder Pro v0.
 5. Git supplies revision identity, history, archive moves, comparison, and rollback.
 6. A Change keeps one stable `change_id`; directory position records lifecycle, not identity.
 
+## Routing precedence
+
+When workflow-route signals conflict, consumers resolve them in this order:
+
+1. the current explicit owner instruction, accepted decisions, and external-effect
+   authorization;
+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 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;
+7. the Resume Note;
+8. Hooks, progress records, compact snapshots, historical reviews, and other
+   derived observations.
+
+A lower layer never overrides a higher one. A conflict produces a typed diagnostic,
+preserves the original bytes, and routes to the nearest repair or owner checkpoint;
+nothing silently selects the "safer" semantic result. The Resume Note is
+navigational context — the current checkpoint, the next action a higher authority
+has already allowed, unresolved prerequisites, and the cheapest safe resume command
+or path — and never route authority: it cannot rewrite acceptance, a Review verdict,
+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
+budget accepted for the work package, under one precedence rule: an exact current
+owner grant overrides the versioned product default — the released default is one
+initial Review plus two P0/P1 delta Reviews. Budget exhaustion with a remaining
+blocker returns the choice to the owner instead of another round; no Agent,
+reviewer, Hook, or control plane extends a budget itself, and the same root
+surviving three failed fixes stops point-patching and reports an architecture
+problem.
+
+## Effect classes
+
+Every action belongs to exactly one class, and the class fixes who may perform it:
+
+| Effect class | Examples | Default rule |
+|---|---|---|
+| `observation` | read-only source inspection, search, test listing | an Agent may act freely inside its task scope |
+| `local-reversible` | editing files inside the authorized worktree, running local tests, creating deletable temporary files | allowed inside an accepted work package with a recovery point |
+| `canonical-authority` | modifying the North Star, an active intent, task status, or an evidence verdict | one designated writer per fact; material semantic deltas return to the owner |
+| `external-or-irreversible` | commit, push, tag, publish, deploy, real installation, provider spend, credential or production mutation | one separate owner authorization per effect; capability or readiness never implies permission |
+
+A durable work-package grant may cover exact `local-reversible` execution and the
+canonical status writes it names explicitly. It never inherits
+`external-or-irreversible` effects by default; those require the owner to list each
+one in the grant and the consuming Agent to verify the listing is current.
+
+## Owner checkpoint semantics
+
+Every owner-facing checkpoint — the WIP at a stop, a task's closing Resume Note, a
+delivery report, or a review's owner handoff — answers eight fixed semantics, in
+whatever length keeps the owner able to judge:
+
+1. **Why** — the real problem being solved.
+2. **Outcome** — what difference the owner will see.
+3. **Accepted boundary** — what is accepted, and what explicitly is not.
+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; 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
+review until the owner re-accepts an outcome.
+
 ## Canonical artifacts
 
 | Artifact | Canonical content | Primary writer | Required readers | Staleness or conflict signal |
@@ -24,11 +115,12 @@ them, how staleness is detected, and how recovery works in Ultra Builder Pro v0.
 | `.ultra/specs/research-distillate.md` | bounded synthesis of specification state | `ultra-research` | change, plan, delivery | stored source blob hash differs from Git blob hash |
 | `CONTEXT.md` | ubiquitous language and relationships | `ultra-domain-modeling`, first called by research and later by any qualifying workflow | every workflow and test naming | source/product use reveals ambiguity |
 | `.ultra/changes/{active,archive,abandoned}/<id>/intent.md` | one bounded requested outcome, reconciliation, Research Disposition, stable identity, and exact Abandonment closure when abandoned | `ultra-change`; Planning Posture by `ultra-plan` | active: research through delivery; all states: status and future Change history | more than one active Change, duplicate id across positions, missing Abandonment closure, or acceptance/scope change |
-| `.ultra/tasks.json` | append-only task ledger: globally unique identity, stable `change_id`, same-Change graph, status, trace, and context path | `ultra-plan` / `ultra-dev` | every user workflow and context Hook | dependency crosses Change, or ledger/context status disagrees |
-| task `context_file` | acceptance, seams, implementation, evidence pointers, Completion, Resume Note | plan/dev | dev, test, review, status, delivery, resume | differs from ledger or current implementation |
+| `.ultra/tasks.json` | `ultra-task-ledger-v2`: append-only task identity, stable `change_id`, same-Change graph, sole task status, trace, and context path | `ultra-plan` / `ultra-dev` | every user workflow and context Hook | dependency crosses Change, row shape is invalid, or a named context cannot be resolved |
+| task `context_file` | typed acceptance, seams, implementation, evidence pointers, Completion, Task Review, Resume Note; no v2 task status | plan/dev | dev, test, review, status, delivery, resume | acceptance identity, evidence pointer, or implementation differs from current source; a legacy Status or Complexity field is a migration diagnostic |
 | `.ultra/decisions/<id>.md` | durable consequential owner decision | `ultra-think` after acceptance | every workflow in scope | superseded by a newer decision file |
-| `.ultra/evidence/<task-id>/...` | command output and bounded task evidence | `ultra-dev` | review, test, delivery | evidence revision differs from affected code |
-| `.ultra/test-report.json` | whole-system audit, findings, and owner disposition for one Change/task/intent/product snapshot | `ultra-test`; `ultra-deliver` may add owner disposition without changing findings or `passed` | status and delivery | `change_id`, `task_ids`, `intent_digest`, `git_commit`, or worktree digest differs |
+| active Change `## Execution Grant` | the current work package's execution authorization: mode (`session-local` default or `durable work-package`), scope, Agent topology, allowed local effects, budgets/expiry, invalidation, and revoke; the exact durable grant bytes live in the cited owner decision, never in a second prose mirror | owner issues; `ultra-change` records the exact reference and fields; no workflow may widen it | executor, handoff, Status | a new Change, a recorded owner revocation, or a fired invalidation condition; stored grant text alone never activates |
+| `.ultra/evidence/<task-id>/...` | one final `ultra-task-evidence-v2` record: typed acceptance evidence, six dimensions, independent completion-snapshot freshness observation, separate task-review provenance, raw-output refs, and limitations | `ultra-dev` after validated task review | test, delivery; review consumes actual pre-review evidence instead | context acceptance, completion observation, cited artifacts, or review binding differs, or a legacy record has not been migrated |
+| `.ultra/test-report.json` | whole-system audit, ordered task-evidence identities, strict aggregate-review provenance, findings, and owner disposition for one Change/task/intent/product snapshot | `ultra-test`; `ultra-deliver` may add owner disposition without changing findings or `passed` | status and delivery | root identity, ordered task-evidence projection, or packet/admission/subject/summary review binding differs |
 | `.ultra/changes/active/<id>/delivery.md` | outcome, docs, verification, review, debt, risk, recovery, effects | `ultra-deliver` | owner and archived Change history | active evidence or accepted scope changes |
 | `.ultra/research/<run-id>/<step-id>.md` | cited investigation report for one selected lens | `ultra-research` | specs, change, plan, delivery | newer sources or later superseding run |
 
@@ -43,32 +135,74 @@ never becomes current merely because of its status. Before an abandoned move,
 evidence, and recovery or successor. Future Change reconciliation and Status consume
 that record as history, not as accepted current intent.
 
-Every completed task has exactly one `.ultra/evidence/<task-id>/evidence.json` with
-schema `ultra-task-evidence-v1`. It records `task_id`, forty-character `git_head`, exact
-commands (`command`, `exit_code`, `evidence_ref`), all six evidence dimensions,
-artifact paths, limitations, and timestamp. Each dimension uses `status` of
-`satisfied`, `gap`, or `not_applicable`, plus `evidence_refs` and a non-empty rationale.
-Optional raw logs live beside that record; they do not create another summary.
+Every current completed task has exactly one final
+`.ultra/evidence/<task-id>/evidence.json` with schema `ultra-task-evidence-v2`. The
+canonical field and type contract lives in
+`skills/ultra-plan/references/task-evidence-v2.md`; this document does not duplicate it.
+The record binds the task and Change, context acceptance bytes, typed acceptance
+evidence and dispositions, all six evidence dimensions,
+task-review provenance, artifacts, limitations, and timestamp. `command`, `inspection`,
+`owner-judgment`, and `external-observation` retain separate evidence authorities. The
+owner alone supplies an owner-judgment result. The CLI establishes only JSON shape,
+token syntax, and authority designation; it does not prove current identity, provenance,
+freshness, or semantic acceptance. Test takes stable bytes independently, recomputes the
+Acceptance-section SHA-256, aligns exact criterion IDs and verification types with the
+current context, and aligns task-review session and summary digest with the retained strict summary. The `subject` is an independently captured completion-snapshot freshness observation made after the final strict task Review validates and immediately before
+evidence publication. Its `task_review` separately binds the retained strict summary.
+Worker Packet v1 and its summary's null `worktree_digest` do not prove or
+cryptographically bind the completion subject. Test separately binds its report to the
+current whole Change, then rechecks the current Acceptance, criterion IDs and verification
+types, owner record, review summary, and cited affected artifacts instead of demanding
+digest equality with the earlier task observation.
+For `owner-judgment`, the durable owner record must exist and its cited statement and
+disposition must remain readable. Any mismatch is an evidence gap returned to Dev or,
+for missing owner judgment, to the owner. Optional raw logs live beside the record and
+do not create another summary. Historical v1 records stay readable evidence but produce
+a migration diagnostic and cannot satisfy a current Change's Test or Deliver input.
+
+Task-review provenance has two discriminated branches with one authority rule: a
+strict-v4 record binds its retained strict session artifacts, while an
+`external-manual` record binds a real external-reviewer receipt under
+`.ultra/evidence/<task-id>/` by exact stable bytes and SHA-256 through the task
+evidence sensor's verify mode. The external receipt is a reconstructable observation
+of reviewer identity, reviewed subject, verdict, and exact findings — never semantic
+authority, never owner acceptance, and never a substitute strict
+SUMMARY/ADMISSION/session. Consumers recheck whichever branch a record declares and
+never rewrite one into the other.
 
 ## Mutable workflow state
 
 Pure file state uses three mechanisms:
 
 - directory position, such as `changes/active/` versus `changes/archive/`;
-- an explicit field, such as a task or context status;
+- an explicit field, such as task status in `.ultra/tasks.json`;
 - an on-the-spot model judgment that is not persisted as state.
 
 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
 Test or Deliver. More than one active directory is a conflict for owner/model repair,
 not a reason for code to select the first entry.
 
-Task completion uses a dual write: `.ultra/tasks.json` and the task context header must
-agree. The writer reads both back. A mismatch is a visible recovery diagnostic; neither
-side silently wins.
+Task status has one writer and one authority: `.ultra/tasks.json`. New contexts carry no
+Status field. A legacy context Status or Complexity header is preserved as a migration
+diagnostic, but the ledger wins. During implementation the row remains `in_progress`.
+Task-review admission uses that row, task context, an immutable review packet, and
+actual pre-review evidence; it does not require the final record it is helping create.
+After the final summary validates, Dev writes the one canonical evidence record with
+every blocking finding, resolution or authoritative disposition, and affected evidence
+refresh. Only after that record and the context review facts are current may the primary
+model write `completed` to the ledger and read the row back. A validator may check this
+ordering and its references; it cannot decide that a finding is semantically resolved.
+
+Later invalidation uses one explicit recovery edge. The ledger-authoritative row changes
+from `completed` to `in_progress`; Dev must never silently demote it. Before the write,
+Dev records the affected criterion IDs and reason in the task context Change Log and Resume Note.
+It preserves the old frozen review as history, then writes and reads back the ledger
+transition. New evidence and review close the task again through the same path.
 
 ## Single-writer boundary
 
@@ -79,6 +213,14 @@ Parallel implementation uses separate worktrees and explicit Git integration. Ul
 does not add a lock service or semantic state machine to make concurrent canonical
 writes appear safe.
 
+The primary writer of a work package changes only through an owner-granted primary
+transfer (`skills/ultra-change/references/primary-transfer.md`): a derived OFFER
+binding canonical refs/hashes, HEAD, and worktree digest; a receiver ACK that is
+ready only on full stable-read match; sole-writer execution; and a frozen terminal
+RESULT. A delegated worker never becomes the canonical writer, and a delegation
+receipt never serves as an ACK or RESULT. While an ACK-ready transfer is open, at
+most that one receiver may write canonical files.
+
 ## Decisions and reductions
 
 Write a durable decision only when it is difficult to reverse, surprising without
@@ -105,9 +247,17 @@ into a second semantic ledger.
 
 A test result is current only for the code and environment it exercised. A report must
 carry the exact command, exit code, stable Change id, exact current task ids, intent
-SHA-256, Git commit, and product-worktree digest. Delivery metadata and moving the same
-Change between active and archive do not alter the product digest; changing intent
-bytes does alter `intent_digest`. Missing or stale evidence remains
+SHA-256, Git commit, product-worktree digest, ordered v2 task-evidence identities, and
+strict aggregate-review packet, admission, subject, and summary bindings. Delivery
+metadata and moving the same Change between active and archive do not alter the product
+digest. The product-worktree digest has one fixed boundary: it excludes
+`.ultra/evidence/**`, whose command and external-observation entries bind exact raw bytes
+as `raw_evidence_sha256` before stable record bytes are bound as `evidence_digest`
+through the ordered task-evidence projection. Test, Status, and Deliver independently
+recompute both bindings from bounded stable repository-contained regular non-symlink
+files; exact review receipts retain their own digest and consumer checks. No writer may
+add a caller-selected exclusion. Changing intent bytes does alter `intent_digest`.
+Missing or stale evidence remains
 `not_run`, `unknown`, or `stale`; it is never inferred as passing.
 
 ## Derived artifacts
@@ -119,26 +269,37 @@ These paths are intentionally non-authoritative:
 | `.ultra/research/<run-id>/brief.md` | optional Wayfinding question map for a multi-lens Research run | rebuild from Project Brief, accepted authority, evidence needs, and owner checkpoints |
 | `.ultra/.runtime/compact-snapshot.md` | compaction acceleration | rebuild from files and Git |
 | `.ultra/.runtime/delegations/` | delegated process receipts and logs | inspect result or rerun with new id |
+| `.ultra/.runtime/handoffs/` | primary-transfer OFFER/ACK/RESULT receipts, plus the optional CLOSEOUT receipt of the one prescribed post-review closeout | create a fresh handoff id from canonical authority; never reconstruct an old ACK or RESULT; close out a newest completed v2 RESULT by publishing its CLOSEOUT receipt, never by refreshing the RESULT or opening a handoff for the closeout |
 | `.ultra/.runtime/worktrees/` | delegated checkout locations | inspect Git worktrees and remove safely |
 | `.ultra/progress/<task-id>.json` | mechanical evidence observations | rerun sensors or inspect current diff |
-| `.ultra/reviews/<session>/` | bounded lens packets and findings | rerun review at a named revision |
+| `.ultra/reviews/<session>/` | `WORKER-PACKET.json`, `ADMISSION.json`, selected specialist artifacts, and `SUMMARY.json` | retain a current strict session through successful aggregate Test and Deliver consumption; after premature loss, run a fresh Review and Test and never reconstruct the old receipt |
 
 The canonical template's nested `.ultra/.gitignore` ignores `.runtime/`, `progress/`,
-and `reviews/` without rewriting the owner's repository-level ignore rules. Deleting
-those paths cannot delete accepted product intent, task contracts, or decisions.
+and `reviews/` without rewriting the owner's repository-level ignore rules. A current
+strict review session contains `WORKER-PACKET.json`, `ADMISSION.json`, every selected
+specialist artifact, and `SUMMARY.json`; it may be garbage-collected only after aggregate Test and
+Deliver have both consumed it successfully. Premature loss requires a fresh Review and
+Test, never reconstruction of the old receipt. Subject to that retention window,
+deleting derived paths cannot delete accepted product intent, task contracts, or
+decisions.
 
 ## Recovery order
 
 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;
 5. inspect the working tree and compare it with Completion and evidence claims;
-6. repair any ledger/context mismatch explicitly before relying on status;
-7. continue through the next observable acceptance boundary.
+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. 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.