@zq-silk/yui 0.14.1 → 0.15.0

package/README.md

@@ -72,12 +72,12 @@ export YUI_HOME=/absolute/path/to/yui-home
 yui setup
 ```
 
-The home contains `schema.json`, the authoritative SQLite database `yui.db`,
-Project Catalog and knowledge, and Controller discovery files. Stable Project
-checkouts and managed worktrees live under the configured workspace, outside
-Yui home. Runtime storage accepts only the exact current contract; it never
-falls back to `state.json`, normalizes an older shape, or repairs a historical
-Home in place.
+The home contains the authoritative SQLite database `yui.db`, Project Catalog
+and knowledge, and Controller discovery files. Stable Project checkouts and
+managed worktrees live under the configured workspace, outside Yui home.
+Legacy `schema.json` and `state.json` files are evidence only. Runtime storage
+accepts only the exact current contract; supported earlier storage versions
+enter only through the explicit upgrade boundary.
 
 Every Task-owned record family allocates a monotonically increasing local ID
 inside its Task. Different Tasks may therefore both contain `work-item-1`,
@@ -89,51 +89,84 @@ and `task integration start`, keep their subordinate IDs local to that Task.
 Candidate IDs are local to their WorkItem and carry both Task and WorkItem
 provenance.
 
-Yui records layout, aggregate, and per-record-family versions in `schema.json`,
-but runtime admission has only two outcomes: exact current, or rejected. A
-missing, older, newer, or malformed contract is never converted by the running
-release. `yui doctor` and `yui upgrade [--dry-run]` are read-only diagnostics;
-`yui upgrade` does not stage, repair, back up, or switch a Home.
+Yui has one Home storage version, recorded by the append-only SQLite migration
+ledger. Every CLI reports both its current storage version and its minimum
+supported migration version. Runtime admission still has only two outcomes:
+exact current, or rejected; a Controller never migrates storage while serving
+work. `yui upgrade --dry-run` is read-only. `yui upgrade` quiesces a running
+Controller, creates a consistent backup, applies every missing migration in
+one transaction, validates the current contract, and then restarts the
+Controller when it was running before the upgrade.
 
 `yui update` stages and pins one exact package, runs that staged binary's
-current-contract preflight, stops the exact old Controller, activates the same
-artifact, verifies the installed binary and current Home, and starts the
-replacement Controller. Storage is not copied or migrated. If the staged
-release cannot open the Home exactly, the update stops before activation and
-leaves both the Home and current installation unchanged.
-
-To retain an old Home, keep it byte-for-byte and open it only with its original
-Yui version for read-only inspection. For unfinished work, initialize a new
-Home and let the Operator create a new Task from the old Task's objective,
-relevant WorkItems, current repository state, and available result summaries.
-The Operator creates new identities; it does not import old runtime/session
-state or pretend that the old Task continued.
+storage preflight, stops the exact old Controller, activates the same artifact,
+applies the staged release's migration chain when required, verifies the
+installed binary and current Home, and starts the replacement Controller. A
+Home inside the staged release's supported range can upgrade directly across
+multiple versions without installing intermediate releases. A newer Home, a
+Home below the migration floor, an incomplete migration ledger, or malformed
+data fails closed without a guessed repair.
+
+Yui 0.15.0 establishes storage version 1 and the migration floor. Homes created
+by earlier releases, including 0.14.2, are not on this compatibility line:
+preserve them for inspection with their matching Yui release or initialize a
+new Home. From 0.15.0 onward, each release retains the complete chain, so later
+`yui update` invocations can cross versions directly.
 
 See [Task-local identity](docs/task-local-identity.md) for the current reference
 contract.
 
-Schema work across Tasks is not serialized: any Task may advance a version axis
-(`layout`, `aggregate`, or a `record` family) on its own isolated branch without
-waiting for another Task's schema change to land. The later-integrating branch
-owns the reconciliation — rebasing onto the latest project head, resolving schema
-and code conflicts, re-advancing the schema versions and record-version-map
-entries the rebase requires, rebuilding and re-validating the wiring, and
-re-running the isolated E2E and docs. This is a deliberate scheduling trade-off
-that avoids cross-Task blocking, not an accident to repair ad hoc. The
-current manifest descriptor map is re-derived against the newest head, while the
-post-baseline descriptor snapshot remains frozen. If another Task later lands a
-record-schema change, the integrating branch must supply the complete adjacent
-path (including an explicit `0->1` introduction for a new family) and re-test to
-convergence.
+Schema work across Tasks is not serialized: any Task may propose the next
+storage migration on its own isolated branch without waiting for another Task's
+schema change to land. The later-integrating branch owns the reconciliation:
+rebase onto the latest project head, preserve every already released migration
+unchanged, allocate the next contiguous storage version, resolve schema and code
+conflicts, and re-run the bounded validation. A migration may update physical
+tables and current record payloads together; it must not introduce another
+writable compatibility axis.
 
 Yui provides four reusable Worker Profile definitions through
-`yui config profile reset`; minimum setup leaves them unconfigured:
+`yui config profile reset`; minimum setup makes each one inherit the current
+Global Worker runtime:
 
 ```text
 worker  explorer  implementer  reviewer
 ```
 
-Profiles are versioned, provider-neutral Worker behavior templates. They hold portable prompt instructions, Skills, access expectations, and optional model and effort selections, but do not bind an Agent or own a Session or workspace. A Task Role is the Task-bound Worker instance: applying a Yui Agent Profile copies the behavior plus model/effort into that Role's active Agent binding; explicit Role options may override the copied values. This is separate from a Codex native config profile selected with `--profile`.
+Profiles are versioned Worker templates with two independent parts: portable
+behavior (prompt instructions, Skills, and access intent) and runtime intent.
+Runtime either follows the current Global Worker binding dynamically, or names
+one explicit Agent with optional model and effort. `profile list` and `profile
+show` resolve the effective Agent from current configuration and display the
+Global Worker launch revision when inherited; that read does not rewrite or
+revise the Profile. Profiles do not own Sessions or workspaces.
+When an explicit Profile's Agent has a Global Worker binding, active or
+dormant, its other binding settings come from that binding; an unbound Agent
+uses provider defaults. A Worker binding referenced this way cannot be unbound
+until the Profile is updated, changed to inheritance, or removed. The Profile
+still owns model and effort, and omitting either means the provider default
+rather than the Worker's value.
+
+Creating a Task Role from a Profile freezes the Profile behavior and its fully
+resolved runtime binding into the Role. Later Profile or Global Worker changes
+do not rewrite existing Task Roles. On `task role add`, model, effort, and
+other Agent settings require `--agent` so Yui can validate and persist one
+complete explicit binding atomically. When `--profile` and `--agent` are both
+present during creation, the Agent must match the Profile's resolved Agent;
+the Profile runtime remains the base binding and explicit Agent settings
+override corresponding fields. On `task role update`, omitted `--agent`
+updates the active binding, while a provided `--agent` updates that binding
+without activating it; only `task role bind` switches the active Agent. An
+explicit Profile must resolve to that update target, where its runtime is the
+base binding and explicit Agent settings override corresponding fields. An
+inherited Worker Profile used by itself may update portable Role behavior
+without retargeting a differently bound Agent; if `--agent` or Agent settings
+are also present, its currently resolved Worker Agent must match the target.
+Applying a Profile replaces the portable fields owned by AgentProfile
+(`defaultAccess`, description, instructions, skills, and access-derived
+constraints); explicit Role options in the same command apply afterward.
+This Yui Agent Profile is separate from a Codex native config profile also
+named `--profile`.
 
 ## Quick start
 
@@ -150,6 +183,10 @@ yui task create "Fix CSV escaping" --project app --type bugfix
 yui task create "Ship CSV export" --project app --type feature
 yui task update <task-id> --priority high --tags release,csv --due-at 2026-08-01T00:00:00Z
 yui task update <task-id> --clear-priority --clear-tags --clear-due-at
+yui task message update <task-id>/<message-id> --body-file updated-message.md --wake-policy none
+yui task work edit <task-id>/<work-item-id> --objective "Revised outcome" \
+  --accept "New observable criterion"
+yui task work retire <task-id>/<work-item-id> --summary "Removed from the current Draft"
 yui task show <task-id>
 yui task context <task-id>
 yui task activate <task-id>
@@ -160,6 +197,15 @@ writable managed Workspace. `task activate` prepares every bound Project first,
 then commits the Task's `active` status and Task-owned Workspace together. A
 preparation or consistency failure leaves the Task Draft and reports the
 workspace diagnosis instead of exposing a partially adopted execution root.
+Draft Message and WorkItem edits replace only the named mutable fields while
+preserving record identity and audit history. Repeated options replace the
+whole collection; matching `--clear-*` flags make an empty collection explicit.
+Retired records remain visible in history but leave the current Draft. A
+retired WorkItem never satisfies a dependency and does not redirect downstream
+dependencies through its optional replacement; fix the remaining Draft before
+activation. These Draft-only mutations do not create, stop, or clean runtime
+resources, and activation validates the current dependency graph, Roles, and
+Project scope before any Workspace is adopted.
 
 Task type describes intent rather than selecting an execution protocol.
 Software Projects use `bugfix` or `feature`: a bugfix is Leader-owned; if it
@@ -169,10 +215,10 @@ small enough to deliver on Task main or large enough for independently owned Wor
 one substantial requirement for one Worker, not a development step, test run,
 review finding, or local fix. Multiple WorkItems are useful only when distinct
 Workers can advance meaningful requirements independently. A WorkItem's
-governing Candidate defines its delivery obligation: its current ChangeSets
-must reach committed Integration or an explicit superseded queue disposition
-before Task-final Review or completion. Older Candidate and ChangeSet records
-remain audit evidence without keeping the Task open.
+governing Candidate defines its delivery obligation: each writable Project's
+exact start and result commits must be represented by a committed Integration
+before Task-final Review or completion. Older Candidate, ChangeSet, and queue
+records remain audit evidence without keeping the Task open.
 
 `project refresh` is the explicit network operation for a stable Project checkout. It fetches the
 configured stable branch directly from the Project remote URL and advances only through a clean,
@@ -294,9 +340,34 @@ to route evidence to the original Worker, accept, reject and redispatch that
 Worker in its existing Session, review again, or request user input.
 A failed review remains visible evidence and wakes the Leader, but does not
 take that decision away from the Leader.
-Task context and next-action expose direct Review facts: every frozen Project
-commit, its relation to the current candidate, the active Turn, and the Reviewer
-workspace. A request that fails after Round creation retains the ReviewRound
+
+An explicit WorkItem Candidate or Task-final Review is direct unless the
+Leader names Producer Roles. Policy-triggered WorkItem Review remains direct
+by default:
+
+```sh
+yui task work review <task-id>/<work-item-id>
+yui task work review <task-id>/<work-item-id> \
+  --lane-role security-reviewer --lane-role correctness-reviewer
+
+yui task review request <task-id> --role reviewer
+yui task review request <task-id> --role reviewer \
+  --lane-role security-reviewer --lane-role correctness-reviewer
+```
+
+Direct Review creates one main Reviewer Turn with no ExecutionGroup or Lane.
+Replicated Review requires at least two distinct Producer Roles, all inspecting
+the identical frozen Assignment in isolated Lane workspaces. Yui waits for
+every Lane to settle and requires at least two successful Producer results
+before creating one idempotent main Reviewer synthesis Turn. Successful
+Producers are never rerun during Lane or main retry. Producer output is durable
+non-authoritative evidence; only the exact completed main Reviewer Turn
+completes the Round. The Leader reads that Turn's original result and decides
+what it means.
+
+Task context and next-action expose the Review shape, every frozen Project
+commit, its relation to the current candidate, Producer and main Turns, and
+their owned workspaces. A request that fails after Round creation retains the ReviewRound
 and reports its exact reason; the Leader opens that Round and decides whether
 to retry, inspect or clean the workspace, use another Reviewer, or continue
 other work.
@@ -399,19 +470,18 @@ yui task work isolate <task-id>/<work-item-id>
 yui task work reject <task-id>/<work-item-id> \
   --summary "Write scope expanded; continue in the refreshed workspace."
 yui task work dispatch <task-id>/<work-item-id>
-yui task work capture <task-id>/<work-item-id>
-yui task integration start <task-id> --project backend \
-  --change-set <backend-change-set-id> --check "<validation command>"
+yui task integration start <task-id> --work-item <work-item-id> \
+  --project backend --strategy cherry-pick --check "<validation command>"
 yui task integration cleanup <task-id>/<integration-id>
 yui task work cleanup <task-id>/<work-item-id> --integrated
 ```
 
-`capture` records one immutable ChangeSet per modified Project. Repeat capture
-at the same HEAD reuses the record; a repaired HEAD produces a new candidate.
-Integration remains a single-Project Git transaction, so the Leader integrates
-each Project independently. Acceptance succeeds only after every modified
-Project's latest candidate is integrated. Yui refuses integrated cleanup while
-any result remains unintegrated. Use `--abandon` only for deliberate discard.
+The WorkItem Candidate records its exact start and result commits. Integration
+remains a single-Project Git transaction, so the Leader integrates each Project
+independently and chooses fast-forward, cherry-pick, merge, or manual
+application. Acceptance succeeds only after every writable Project result has
+a committed Integration, including an explicit successful no-op when the
+result is already represented. Use `--abandon` only for deliberate discard.
 Dirty worktrees are retained. Native Agent Sessions may be scoped to their
 launch directory, so Yui retires a stopped Role Session whenever the Role moves
 between Task main and an isolated WorkItem worktree. The next dispatch starts a
@@ -460,11 +530,12 @@ resumes the newest entry directly. Starting a conversation is never a resume
 choice: the explicit `operator new` command starts a clean conversation and
 preserves the previous one in history.
 
-Create a Task-bound Worker instance from the configured global Worker, apply a
-Profile, and dispatch a WorkItem:
+Create a Task-bound Worker instance from a Profile's resolved runtime and
+dispatch a WorkItem:
 
 ```sh
 yui config role show worker
+yui config profile show implementer
 yui task role add <task-id> implementer --profile implementer
 yui task role show <task-id> implementer
 
@@ -474,62 +545,35 @@ yui task work isolate <task-id>/<work-item-id>
 yui task work dispatch <task-id>/<work-item-id> --input "Implement and run focused tests"
 ```
 
-Dispatch remains `single` by default. A Leader can explicitly enable bounded
-multi-route exploration on a fresh WorkItem; each accepted stage advances
-`Plan → Generate → Compare → Synthesize → Verify → Resolve`, and only the
-accepted Resolve stage materializes the existing single Candidate:
+Without `--lane-role`, the assignee performs the WorkItem directly in its main
+workspace. To request independent production attempts over exactly the same
+frozen Assignment, provide at least two distinct Task Roles; one role is
+rejected, roles cannot repeat, and the assignee cannot be a Lane:
 
 ```sh
 yui task work dispatch <task-id>/<work-item-id> \
-  --mode parallel-diverse --max-rounds 2 --stage-max-attempts 2 \
-  --strategy fixed:2 --lane-role critic \
-  --stage-max-tokens 240000 --stage-max-tool-calls 200 \
-  --stage-max-seconds 1800 --stage-quorum 2
-yui task work group resolve <task-id>/<work-item-id> \
-  --decision accept --summary "Plan evidence is sufficient"
+  --input "Implement and run focused tests" \
+  --lane-role producer-a --lane-role producer-b
 ```
 
-Every stage is a new immutable ExecutionGroup. Its ContextSnapshot and selected
-parent Lane results are durable references; `retry` repeats a stage within its
-attempt budget, while `retry` at Resolve begins the next bounded round.
-
-Each new stage also freezes one Resource Broker contract: behavioral tool-call
-and wall-clock budgets; a display-only token threshold; quorum and deadline; a
-straggler window; and the minimum marginal value for more Lane spend. Omitted
-values reuse the existing context budget and runtime-health windows; stage
-retries share the original cumulative observations and absolute deadline.
-Observed token totals and the configured token threshold are cost context only:
-they never close spend, block admission, suppress scheduling, or stop a Lane.
-Execution, Lane retry, and Reviewer-panel
-admission all count active Lanes at Home, Task, WorkItem, Group, Provider,
-Agent, and model scopes. Capacity pressure keeps the excess Lane durably
-pending instead of failing the Group. Capacity release or deadline arrival
-wakes the Leader through the existing actionability path; rerunning the same
-dispatch resumes the frozen input. Released capacity is reserved for the
-oldest currently admissible waiter, while a Provider- or Agent-blocked queue
-head does not prevent independent scopes from making progress. Provider rate
-limits still use the existing in-place retry window and therefore never fan
-out into sibling failures.
-
-The Leader may add `--early-stop <0-100>` to an accepting Group resolution.
-Yui permits it only after quorum and T5's passed Verify/Resolve evidence prove
-sufficiency. It may skip Lanes that never started; active stragglers are
-reported and retained, never killed automatically for cost. If evidence is
-insufficient, behavioral tool-call/wall-clock budget or deadline exhaustion
-blocks the stage for Leader judgment instead of turning thin evidence into
-success.
-
-New exploration histories also freeze the structured candidate-convergence
-contract. Yui appends the exact stage-local JSON shape to every Lane assignment
-and validates selected reports before the Leader can advance: Compare must
-partition duplicate clusters and justify each selected route with a direct
-source, executable check, or frozen artifact; Synthesize uses a claim/evidence
-table for research, a decision matrix for architecture, and one frozen Git
-snapshot for code. Verify must use a Role independent from the selected
-Synthesize author. Only complete criterion evidence can produce `passed` and
-an accepted Resolve Candidate; explicit gaps produce `next-round` and can only
-continue through bounded Resolve `retry`. Votes and derived analysis remain
-reportable context, but never substitute for direct evidence.
+Each Lane is a recoverable logical slot. A successful Lane points to its
+immutable Producer Turn result; a failed Turn leaves the Lane open and visible
+as `needs-attention`. The Leader retries or explicitly settles that exact Turn:
+
+```sh
+yui task turn retry <task-id>/<failed-turn-id>
+yui task turn settle <task-id>/<failed-turn-id>
+```
+
+Yui waits until every Lane is settled. At least two successful Producer results
+create one idempotent main Turn for the WorkItem assignee; fewer results fail
+the WorkItem attempt without falling back to a single result. A main Turn retry
+keeps the same source Group and never reruns successful Lanes. Only a successful
+main Turn can become the Candidate used by Review and Integration. `task work
+show`, `task work list`, Task context, and the Web control room derive execution
+shape, recovery targets, synthesis eligibility, main Turn, Candidate provenance,
+next action, and owner from the same persisted facts. Missing facts stay
+`unknown` or `unobserved`; token, duration, and tool-call totals are display-only.
 
 Permission is one adapter-specific enum configuration on each Agent binding:
 `default` follows the provider, `bypass` compiles the provider's supported
@@ -539,16 +583,16 @@ set. Codex options are `sandbox` and `approval`; Claude options are `mode`,
 Profile behavior and Project write authority: only an exact WorkItem scope and
 matching managed workspace grant normal Project writes. A ReviewRound is the only non-WorkItem write
 purpose and must match its Turn, reviewRoundId, frozen base, and
-ReviewRound-owned workspace; every mismatch fails closed. Its diagnostic commit
+ReviewRound-owned main workspace or exact isolated Producer Lane workspace;
+every mismatch fails closed. Its diagnostic commit
 is visible history but is
 explicitly rejected by capture, ChangeSet, Integration, and acceptance paths.
 The Reviewer's final Provider response is its complete free-form Markdown or
-JSON report. If a JSON report
-includes known `checks` or `evidenceCommit` fields, Yui records them as
-structured evidence and verifies the reported commit against the managed
-Review branch HEAD; unknown fields remain part of the report. Dirty uncommitted
-diagnosis may end without a commit; the worktree is retained and cleanup
-refuses it until it is clean.
+JSON result. Yui stores that text unchanged and does not parse headings, field
+names, checks, severities, findings, or verdicts. Core-owned workspace and Git
+evidence remains separate from Agent prose. Dirty uncommitted diagnosis may end
+without a commit; the worktree is retained and cleanup refuses it until it is
+clean.
 
 Every Role desired launch change increments its revision and applies only to a
 future launch. Each Turn and native Role Session stores the complete actual
@@ -614,7 +658,8 @@ still matches:
 
 ```sh
 yui task integration start <task-id> \
-  --change-set <change-set-id> \
+  --work-item <work-item-id> \
+  --strategy cherry-pick \
   --check "npm test"
 ```
 
@@ -694,6 +739,78 @@ yui task context <task-id>
 
 Use the narrower `task work`, `task message`, `task turn`, and Task Knowledge commands when you need one collection or record.
 
+Record a Task's confirmed PR/MR delivery state with one idempotent command:
+
+```sh
+yui task publication upsert <task-id> --project <project> \
+  --provider github --repository <owner/name> --kind pull-request --id <number> \
+  --url <url> --state open --reported
+```
+
+The required provider/repository/external ID selects the current Publication.
+The first upsert creates it. Later upserts inherit omitted metadata and omitted
+merge evidence only while the full evidence context remains unchanged. That
+context is the local commit, PR/MR state, remote commit, evidence text, and
+merge time. If any explicitly supplied context value differs, omitted
+verification resets to `reported` and omitted merge-evidence fields are
+cleared; changing the local commit without an explicit state also resets the
+Publication to `open`. Resupplying identical values remains idempotent. Each
+semantic change appends a new immutable record linked to the previous version,
+while identical input creates no event. `list`, `show`, and `task context`
+retain the complete history. This records facts already known to the caller;
+it does not query a provider or replace Review, Integration, or Task completion
+gates.
+
+Verify one current GitHub or GitLab Publication against the real PR/MR state:
+
+```sh
+yui task publication verify <task-id>/<publication-id>
+```
+
+Verification is an explicit external read. GitHub uses a trusted, PATH-pinned
+local `gh` executable; GitLab uses a trusted, PATH-pinned local `glab`
+executable. Both reuse the CLI's existing authentication, and Yui stores no
+provider token. The command requires the current unsuperseded Publication to
+record the exact Task delivery head, then requires the provider to report the
+same PR/MR head as merged and expose the integrated remote commit. It rechecks
+the Task head and Publication after the remote call before appending a new
+immutable `verified` record. Missing provider CLIs, unavailable
+authentication, ambiguous provider output, open/closed PRs or MRs, moved
+heads, and concurrent local changes fail without recording verification.
+GitLab repositories may use nested namespaces; a recorded self-hosted MR URL
+selects that GitLab host.
+
+Query whether every delivered Project head is represented by a current merged
+Publication:
+
+```sh
+yui task remote-delivery <task-id>
+yui task remote-delivery <task-id> --json
+```
+
+This is a read-only derived projection, not a Task status or writable `merged`
+flag. Active and reopened Tasks use the current clean Task-main heads and mark
+them provisional; completed and archived Tasks use the latest frozen
+`task.completed` heads. For each Project, Yui reports the expected local
+commit, the matching current unsuperseded Publication, PR/MR state,
+verification, and remote commit. Aggregate coverage is `none`, `unavailable`,
+`pending`, `partial`, or `merged`, with independent `allMerged` and
+`allVerified` values.
+Only a current Publication whose `localCommit` exactly matches the expected
+head and whose state is `merged` contributes merged coverage. Missing commits,
+open/closed records, stale heads, and superseded Publications never imply
+remote delivery. Projects whose Task head equals their managed base need no
+Publication. `task show`, `task context`, `task next-action`, and the Web detail
+projection use this same selector.
+`Archive --integrated coverage` requires both `allMerged=true` and
+`allVerified=true`.
+
+When a valid older completed Task has no frozen completion heads, Yui reports
+`unavailable` and keeps integrated archive fail-closed. Reopen and complete the
+Task again to record exact heads, then retry archive. Yui does not guess the
+missing head from a Publication or worktree, and `--force` never overrides
+missing head evidence.
+
 When the requested outcome is finished, complete the Task to stop automatic Leader wakes without deleting its sessions or Task main worktree:
 
 ```sh
@@ -733,9 +850,17 @@ worktrees are non-blocking completion advisories, but they must be settled
 before archive. Every isolated WorkItem worktree is explicitly cleaned as
 integrated or abandoned; that cleanup also removes its managed branch. Archive
 requires `--integrated` or `--abandon` to state the Task main outcome and is
-allowed only after Task main is clean. It removes managed worktrees but retains
-Task and WorkItem records. The Task main branch is retained as a recovery
-artifact instead of being silently deleted.
+allowed only after Task main is clean. `--integrated` additionally requires
+remote-delivery `allMerged=true` and `allVerified=true`; Task completion or a
+reported merge alone is never treated as verified remote delivery. When every
+exact Task head is merged but one or more Publications remain `reported`, the
+command identifies those Publications and refuses archive. An explicitly
+authorized `task archive <task-id> --integrated --force` may override only that
+verification gap and records the override in the archive event; it never
+bypasses missing, stale, open, or closed merge evidence. An intentional
+non-merge uses the existing explicit `--abandon` path. Archive removes managed
+worktrees but retains Task and WorkItem records. The Task main branch is
+retained as a recovery artifact instead of being silently deleted.
 Task lifecycle completion/selection only suggests valid source states: Draft for activate, active for complete, and completed for reopen.
 
 ## Sessions and tmux
@@ -790,10 +915,9 @@ Global Context entry:
 yui session enter <global-role>
 ```
 
-`yui update` accepts only the current Home contract and never migrates storage.
-For an older Home, keep its Sessions stopped, inspect it with the original Yui
-version, and let the current Operator recreate unfinished intent as new Tasks in
-a newly initialized Home. Runtime ids and mailbox state are not copied.
+`yui update` accepts either the current Home contract or any valid historical
+contract at or above the staged CLI's minimum supported migration version.
+Unsupported newer Homes and Homes below that floor remain untouched.
 
 tmux fixes a pane's history capacity when that pane is created. Existing panes
 retain their configured capacity; managed runtime output remains observable in
@@ -875,38 +999,41 @@ hiding the resources that remain. Use `--all` to include discovered Yui homes.
 
 `controller restart` replaces the Controller process and its scheduler/socket services with the currently installed Yui version. It can recover a lost discovery record only when the old process still matches the current UID, Controller entrypoint, physical Home, PID, and process-start identity. It does not stop or restart managed tmux/Agent sessions.
 
-Successful `setup`, `upgrade`, and `update` commands ensure that the current
-Home has a running Controller, starting one when the Home was previously idle.
-Read-only commands and `upgrade --dry-run` do not start a Controller. `update`
-also replaces an already-running Controller only after the new binary passes its
-health checks.
+Successful `setup` and `update` commands ensure that the current Home has a
+running Controller, starting one when the Home was previously idle. A
+successful `upgrade` restores a Controller only when it stopped one for the
+migration. `update` starts the replacement only after migration and health
+checks pass.
 
 Its recovery reconciliation runs every 120 seconds by default. Normal durable state changes enqueue a Task, Role, or Operator key and return immediately; keys received in the same fixed 100 ms window trigger one non-overlapping targeted pass. Operator presentation has an independent lane, so a blocked Task workspace operation cannot delay a user question. Periodic Git/worktree work is limited to Tasks with durable Task-mailbox work, while active Role liveness uses one tmux inventory. Structured Agent Driver observations, whether received from native provider events or supported Hooks, are exact-fenced before they reach the durable runtime inbox. A terminal Turn observation atomically records the exact Turn result. Durable mailboxes freeze the current batch while new signals merge into the next batch. Task-orchestration failures retain the exact Controller-owned processing batch for two bounded fast retries and later periodic recovery; a successful retry completes that batch before newer pending work is claimed. Recommended InputRequest and pending Turn deadlines share one nearest-deadline selector and therefore do not wait for the recovery interval. Explicit `task reconcile` still requests an immediate recovery pass. The retained loop is:
 
 1. dispatch pending Leader wakes whose Task workspaces are already ready;
 2. prepare active Project Task main worktrees with durable orchestration work;
-3. deliver queued Worker Turns;
+3. deliver active Role Turns from durable active-Turn state, using ordinary
+   Role mailboxes only as optional delivery hints;
 4. resolve due Turn completions and reconcile Role liveness;
 5. dispatch Leader work created or unblocked by the later recovery phases.
 
 Automated input is sent only through tmux. Each pass performs one non-blocking process-state readiness check; a busy startup is retried through a small bounded mailbox timer, while later busy sessions are woken by canonical Agent Driver terminal observations. A pane-local receipt prevents the same Turn input from being typed twice after a Controller retry.
 
-If a Role process exits without a terminal Provider result, the Controller fails that Turn and running WorkItem and queues the Leader. Recovery failures are exposed through the small Jobs view:
+If a Role process exits without a terminal Provider result, the Controller fails that Turn and queues the Leader. A replicated WorkItem or Review Producer Lane remains open for exact retry or explicit settlement; completed sibling results remain reusable. Recovery failures are exposed through the small Jobs view:
 
 ```sh
 yui jobs list
 yui jobs retry leader-recovery:<task-id>
 yui task reconcile <task-id>
 yui task turn retry <failed-turn-id>
-yui task turn settle <obsolete-failed-review-turn-id>
+yui task turn settle <failed-turn-id>
 ```
 
 `jobs` is not a restored generic queue: it presents durable pending Leader wakes and Leader recovery failures only.
 
-`task turn settle` is a Leader-only repair for one exact failed Reviewer Turn whose
-matching Task-final ReviewRound was stranded running by an older lifecycle. It
-closes only an obsolete frozen candidate, preserves the Turn, Round, workspace,
-and evidence, and never creates a retry Round.
+`task turn settle` records that the Leader will no longer recover the exact
+current failed Producer Lane Turn. Only then does the Lane become failed and the
+settled Group become eligible for WorkItem or Review synthesis when at least
+two Producer results succeeded. The same command retains its narrow repair for an obsolete failed
+Reviewer Turn whose Task-final ReviewRound is stranded on an old frozen
+candidate; that repair never creates a retry Round.
 
 Completion is the reversible execution fence. Archiving is terminal and is accepted only after active work is settled: it stops the Task's tmux session and removes clean managed worktrees. Dirty worktrees keep the Task completed and are preserved for deliberate resolution.
 
@@ -945,7 +1072,8 @@ with an execution band that consolidates the Task's owner, current action,
 attention list, blockers, and fail-closed indicators; Work items surface
 their current ExecutionGroup with per-lane status, Candidates, and
 retirement disposition; Turns show purpose, execution lineage, final result,
-and Leader disposition.
+and Leader disposition; Reviews show direct or replicated shape, frozen
+Assignment, Producer Lane state, main synthesis Turn, and authoritative result.
 
 The control room supports English and Simplified Chinese, selecting an initial locale from the browser and remembering manual changes. The theme selector switches between the dark Control Room, the light Paper Ledger, and the dark-blue Atlas themes. Both choices are stored only in browser `localStorage`; they do not modify `YUI_HOME`.
 
@@ -967,15 +1095,17 @@ yui project reset|replace|retire|delete
 ```
 
 `yui update` stages the newly published package side by side and asks that exact
-binary to verify that the Home already matches its current storage contract.
-Only then does it stop the exact old Controller, activate the same concrete
-package version, validate the actually installed binary and Home, and start the
-replacement Controller. It never migrates or switches storage. An older or
-otherwise unsupported Home blocks preflight and remains untouched.
-
-`yui upgrade [--dry-run]` is retained as a read-only storage admission
-diagnostic. It reports current, uninitialized, invalid, or unsupported state and
-the Operator action; it never performs an upgrade.
+binary to classify the Home. Only then does it stop the exact old Controller,
+activate the same concrete package version, apply the complete missing
+migration chain when needed, validate the actually installed binary and Home,
+and start the replacement Controller. Unsupported Homes block preflight and
+remain untouched.
+
+`yui upgrade --dry-run` prints the ordered migration plan without writing.
+`yui upgrade` creates a timestamped SQLite backup and upgrades any valid Home
+from the CLI's minimum supported storage version to its current version. Yui
+0.15.0 is storage version 1; pre-0.15.0 Homes remain outside that migration
+line and are never rewritten.
 
 Agent environment bindings store process-environment variable names, never secret values. Adapter-owned lifecycle arguments cannot be overridden through raw arguments.
 
@@ -996,7 +1126,7 @@ npm test
 ```
 
 The permanent suite is intentionally one seconds-scale core smoke. It checks
-CLI startup, a normal SQLite Task path, the supported migration graph, and the
+CLI startup, a normal SQLite Task path, exact-current storage admission, and the
 built-in Agent Drivers. Change-specific TDD fixtures and abnormal-data repros
 are temporary development evidence and are removed when the change is complete;
 they do not accumulate as permanent regression tests. See