@zq-silk/yui 0.15.9 → 0.15.12

package/docs/sqlite-control-plane-design.md

@@ -69,10 +69,232 @@ Every persistent schema or payload change appends one immutable, contiguous
 storage migration. The CLI publishes both `storageVersion` and
 `minimumStorageVersion`; every valid Home in that inclusive range can upgrade
 directly to the current version without installing intermediate releases.
-The current source declares storage version **18**, with minimum supported
+The current source declares storage version **25**, with minimum supported
 migration version **1**, in `src/storage/storageVersions.ts`. Homes below that
 floor are not migration inputs and remain untouched.
 The target binary's `upgrade --update-preflight` and `--update-apply` result
 shapes and parent-owned handover-lock proof remain backward compatible with
 every updater released from storage version 1 onward, so an old source CLI can
 still drive a much newer target's complete migration chain.
+
+## Unified Home layout
+
+Every Yui self-managed directory lives under the single canonical `YUI_HOME`
+(default `~/.yui`; an explicit `YUI_HOME` is honoured verbatim). `YUI_HOME` is
+never inferred from the current working directory and never substituted with a
+username. `src/storage/homeLayout.ts` is the one authority that derives each
+managed root from Home:
+
+| Root | Path | Holds |
+|---|---|---|
+| Managed worktrees | `<home>/workspaces/tasks/<taskId>/<owner>/<projectDirectory>` | Actual Task/WorkItem/Review/Integration Git directories, addressed by the bound Project directory. Owners are `main`, `work-items/<id>`, `reviews/<id>`, `integrations/<id>` and `execution-lanes/<group>/<lane>`. |
+| Read-only context views | Within the same owner directory | Regenerable symlinks to read-only Project context only; writable entries are actual Git directories, not links. |
+| Global Role workspace | `<home>/workspaces/global` | Default cwd for Yui-auto-created Global Roles (the `yui setup` Operator/Leader and ad-hoc Global Roles added without an explicit `--workspace`). A plain cwd, not a managed Git workspace. |
+| Task provider runtimes | `<home>/runtime/task-runtimes` | Task provider data/cache/tmp; also the planning cwd at `…/planning/<taskId>`. |
+| Integration runtimes | `<home>/runtime/integration-runtimes` | The integration check's provider data/cache/tmp (a separate partition from Task runtimes). |
+| Update staging | `<home>/runtime/update-staging` | `yui update`'s side-by-side package install (an upgrade artifact). |
+| Release workflow scratch | `<home>/runtime/release-workflow` | The release workflow's smoke-install dir and verified publish-snapshot tarball (release artifacts). |
+| Storage backups | `<home>/backups` | Pre-upgrade DB backups (the fenced upgrade's rollback anchor). |
+
+Published migrations 1–23 remain unchanged, including Task artifacts in local
+Git (19), Integration continuation (20), force-archive evidence (21), and
+Controller-owned Host ingress (22), and unified message input control (23).
+The two offline layout steps are now 23→24 (`unify-home-layout`) and
+24→25 (`collapse-worktree-layout`). Version 24's
+`workspaces/worktree` directory is an intermediate layout, not a second live
+root at version 25. A single upgrade applies the full pending chain.
+
+Stop this Home's writers and take a backup before upgrading. The layout steps
+copy and verify the registered Git trees, repair only the copies' links, and
+preserve old sources for manual recovery. Version 25 replaces registered
+Task-view symlinks with real writable directories; unrelated Task scratch is
+retained. Read-only context remains a view and can be promoted to a writable
+worktree when WorkItem scope expands. Do not delete the old sources until the
+new layout is verified; a failed upgrade requires manual residue cleanup and
+backup recovery, not automatic resume.
+
+Both runtime partitions (`runtime/task-runtimes`, `runtime/integration-runtimes`)
+are the ONLY Home subtrees a provider runtime root is allowed to overlap; a
+runtime root overlapping any other part of Home (the database, `workspaces/`,
+`projects/`) is still rejected by `assertTaskRuntimeIsolationPreflight`, so
+unifying the root does not weaken control-data or cross-owner isolation.
+
+`defaultWorkspace` is a user-facing cwd for external Project input only; it is
+**not** a second authority for internal managed paths, and is intentionally not
+an input to `homeLayout.ts`. A Yui-auto-created Global Role that carries no
+user-chosen cwd no longer falls back to it (or to `process.cwd()`): `yui setup`'s
+built-in Operator/Leader and `yui role add` without `--workspace` now default to
+the Home-internal `managedGlobalRoleWorkspace(home)` (`<home>/workspaces/global`),
+and `setup` no longer fabricates an external Home-sibling `workspace/` — a
+`default-workspace` is persisted only if the user configured one. A user who
+*names* an external directory (explicit `--workspace`, or a configured
+`default-workspace`) keeps external-resource semantics; the outside-Home guard
+still applies to it. The "planning/global cwd" that criterion 1 places under Home
+is thus both the *disposable runtime cwd Yui materializes itself* — the Draft
+planning cwd (`planningRuntimeCwd`, under `runtime/task-runtimes/planning`) — and
+the auto-created Global Role cwd above; only an operator's *explicitly named*
+external directory stays outside by design.
+
+Only genuine short-path IPC socket ENDPOINTS remain outside Home, and only
+because a Unix-domain `sockaddr_un` path has a small fixed length budget that a
+deep Home path would exceed. Each is a single socket path, never a data/cache/tmp
+root:
+
+- the Controller socket (`/tmp/yui-<uid>/<homeId>.sock`),
+- the tmux server socket (`/tmp/tmux-<uid>` via the tmux namespace),
+- the Agent Host socket (`/tmp/yui-<uid>/agent-host/…sock`), and
+- the integration check's tmux socket dir (`/tmp/yi-<uid>-<digest>`), bound only
+  into `TMUX_TMPDIR`.
+
+The integration check's ordinary runtime state is **not** an exception: its
+provider data, cache, and temp roots live in the Home partition above
+(`runtime/integration-runtimes`); `TMPDIR`/`TMP`/`TEMP` point there, and only
+`TMUX_TMPDIR` is redirected to the short `/tmp` socket dir.
+
+## Migration 23 → 24: unify managed paths under Home
+
+Historically the managed worktrees lived under the out-of-Home
+`defaultWorkspace` (`<ws>/worktree`, `<ws>/tasks`) and the provider runtimes
+under a string-built Home sibling (`<home>.task-runtimes`). The one forward
+migration `unify-home-layout` (`src/storage/migrations/unifyHomeLayout.ts`)
+brings that content under Home and rewrites the persisted absolute pointers the
+runtime dereferences as live, without re-cloning Git content or renaming the
+path-independent Git refs. It runs as the migration's `migrateData` step inside
+the upgrade transaction, so schema and data advance atomically or roll back
+together.
+
+**Exactly one tree is physically relocated: the managed Git worktree tree.** It
+is the sole subtree that holds durable, non-regenerable content (committed **and**
+uncommitted work), so it alone is copied on disk. Everything else that "moves"
+moves only by pointer:
+
+- the per-Task symlink views (`<ws>/tasks`) are regenerable — the pointer is
+  rewritten and `ensureWorkspaceView` rebuilds the links at the next launch;
+- the provider runtimes (`<home>.task-runtimes`) are disposable — the pointer is
+  rewritten and the roots are recreated at the next launch.
+
+The worktree copy is **non-destructive and verified** (see *Recovery and
+rollback*): the source is copied (never renamed away), the replica's content
+digest is checked against the source, and only a verified replica is atomically
+published. The original worktree tree is **preserved** as the rollback anchor;
+removing it is a later, authorized, post-restart cleanup step, never part of this
+transaction.
+
+The pointer rewrite is **surgical, not a table sweep** — only records the runtime
+treats as live launch pointers are touched:
+
+- `managed_workspaces` — the authoritative registry (`path` column, payload
+  `root`, every `entries[].path`). Every surviving row is live (dispositioned
+  rows are deleted at cleanup).
+- active (`status='active'`) `turns` — **both** `run.effective.workspace` (the
+  actual OS launch cwd source) and the `run.workspace` mirror, rewritten together
+  because `validateRun` requires them to stay identical; a run's
+  `.result.systemEvidence.workspaceSnapshot` is frozen Git evidence and is left
+  byte-for-byte intact.
+- `role_session_sets` / `global_role_session_sets` — each live session's
+  `effective.workspace` in the `sessions` map; terminal sessions in `history` are
+  preserved.
+- `review_rounds` — the mirrored workspace (only while its `managed_workspaces`
+  owner row still exists) and each OPEN execution lane; an orphaned mirror or a
+  terminal lane is frozen evidence and is preserved.
+- `work_items` — each OPEN execution lane inside `executionGroups`; candidate
+  snapshots (`work_item_candidates`) are frozen and preserved.
+- `task_roles.workspace` — the live launch cwd, including a Draft's planning Role
+  under the old runtime sibling (never self-healed until activation).
+- `task_records.cwd` — self-heals on the next `prepareTaskWorkspace`, but is
+  rewritten defensively to close the stale-read window.
+
+Everything else is preserved on purpose: `context_snapshots`, terminal `turns`
+(with their system evidence), terminal sessions, `work_item_candidates`, terminal
+execution lanes, terminal `durable_jobs`, `events`, and reports are frozen
+history. `resource_registry` is re-discovered from disk; `projects.path` is an
+external, user-owned checkout.
+
+The migration is applied **offline** and is **fail-closed and pre-checkable**.
+It is run by the standalone `yui upgrade` boundary AFTER the operator has stopped
+this Home's Controller, Agent Host, and any execution/Job writers; it does not
+orchestrate that shutdown, coordinate an online write-stop, or migrate a live
+Session. It keeps only the minimal preconditions it can implement directly:
+
+- It **refuses** if a queued or running `durable_jobs` step is bound to a tree
+  about to relocate. A durable Job's runner is detached and could outlive an
+  incompletely stopped Controller, so moving that tree would risk an in-flight
+  silent move; this is the one residual runtime signal the offline migration
+  still guards. Let the Job drain or cancel it, then re-run the upgrade.
+  (`active_turns` is steady state, not an in-flight signal, and is deliberately
+  not consulted.)
+- It **refuses** if a relocation target already exists at all — it is either a
+  foreign directory or residue from a failed prior run, and the offline migration
+  never adopts a pre-existing target. Confirm the source is intact, then move or
+  remove the target and re-run the upgrade.
+- Every refusal is surfaced as a **collected, read-only pre-check**: `yui
+  upgrade --dry-run` and the updater's `--update-preflight` run the same plan and
+  the same blocking conditions execute would throw on, opening the DB read-only
+  and reporting each independent blocker as `{reason, detail}` (blocked outcome)
+  without mutating the Home — a genuine pre-check, not a best-effort guess.
+- A Home already in the unified layout (or a fresh Home with nothing to relocate)
+  is a **no-op**.
+
+### Recovery and rollback
+
+The migration keeps **no recovery manifest and no resumable state machine** — it
+is a one-time offline transform, not an interruptible online orchestration. The
+worktree relocation is **copy → digest-verify → atomic-publish → preserve-source**:
+
+1. the relocation target must not already exist; a pre-existing target is refused
+   up front (foreign directory or failed-run residue — never adopted);
+2. the source is copied into a same-filesystem staging dir (`<to>.incoming`),
+   never renamed away;
+3. a content-addressed inventory digest of the replica is compared to the source
+   — a mismatch deletes the staging copy and aborts (nothing published, source
+   intact);
+4. only a verified replica is `rename`d into the final target (atomic on one
+   filesystem);
+5. the original source tree is left in place as the rollback anchor.
+
+There is **no automatic idempotent recovery**. Because a pre-existing target is
+always refused, a run interrupted after a partial publish does not silently
+resume or adopt the partial tree on the next attempt: the operator inspects the
+preserved source, removes the incomplete target (and any `<to>.incoming`
+staging), and re-runs the upgrade from a clean state. The `--dry-run` /
+`--update-preflight` pre-check surfaces exactly this `target-conflict` before the
+apply transaction is entered, so the residue is reported, not discovered
+mid-migration.
+
+After the copy, the worktrees are reconnected. `git worktree repair` chases the
+absolute pointer files inside a worktree, so running it on a verbatim copy whose
+pointers still address the OLD source would rewrite the OLD source's `.git`
+files and corrupt the rollback anchor. The migration therefore **relinks first**:
+it deterministically repoints, in the NEW copy only, the two cross-reference
+pointer files (a linked worktree's `.git` stub and each
+`main/.git/worktrees/<name>/gitdir`) from OLD to NEW, and only THEN runs `git
+worktree repair` from each main clone at its new path as a belt-and-braces
+reconciliation now confined to the new tree. This keeps the preserved source a
+fully independent, working Git: its `.git` is byte-for-byte unchanged and it
+still resolves HEAD/index/status after the migration (verified empirically on a
+private disposable Home). **A repair failure is fatal** — it aborts the migration
+so the transaction rolls back rather than advancing the version over unrepaired
+worktrees.
+
+Because the data step runs inside the upgrade transaction, any throw rolls the
+schema back to its original version; the fenced upgrade orchestrator additionally takes a
+`database.backup()` and restores it on failure. Recovery from a failed run is
+**manual, not automatic**: because the source is never removed and the copy is
+digest-verified before publish, the preserved source is always intact, so the
+operator clears any partial target and re-runs the upgrade. No re-run can lose or
+corrupt the original content, but the tool does not itself resume an interrupted
+move set.
+
+**Old-source cleanup** is intentionally deferred and out of band: after a
+successful upgrade the old external `worktree`, `tasks`, and `<home>.task-runtimes`
+roots are left **in place** (not emptied) until an operator-authorized cleanup
+removes them. This keeps a full rollback anchor available across the first
+restart.
+
+**Rollback limits:** once the Controller restarts against the unified layout and
+begins writing new records under Home, restoring the pre-upgrade DB backup no
+longer matches the newly written on-disk state. Until that first post-upgrade
+write, the preserved old source plus the DB backup are a complete rollback pair;
+after it, the supported recovery is forward (the layout is already unified), not a
+downgrade to the split layout. Verify an upgrade only on a private, disposable
+Home before applying it to a shared environment.

package/docs/task-delivery.md

@@ -13,6 +13,9 @@ prepares physical workspaces, and adopts status/ownership atomically. Failed
 preparation leaves the Task Draft with a failed request and a diagnosis delivered
 to the Leader. Deferred activation retains the exact intent and waits for native
 quiescence, whether requested in a planning Run or subsequent discussion.
+Project maintenance contention waits asynchronously before resource adoption.
+A lock timeout or cancelled wait preserves the original activation request;
+after acquiring the lock, activation rechecks current intent and authority.
 
 Task type describes the requested outcome, not the mandatory executor.
 Leader owns bounded work directly or assigns substantial independent WorkItems.
@@ -22,7 +25,8 @@ attempts at the same frozen Assignment, followed by Leader-selected synthesis.
 ## Managed workspaces
 
 Stable Project checkouts are read-only references. Task main is a logical
-multi-Project root with per-Project Git worktrees. For one Project, the Agent's
+multi-Project root with independent per-Project Git clones; WorkItem, Review and
+Integration worktrees belong to those Task repositories. For one Project, the Agent's
 normal cwd is its managed Git root; for multiple Projects, the root and native
 additional-directory mechanism expose the explicit Project set.
 
@@ -75,31 +79,147 @@ Leader delivery. The current native turn must end so the pending notification
 can arrive; the Leader then reads the original message and reassesses completion.
 This derives from existing Messages and mailbox delivery, not a second
 acknowledgement or workflow state.
-Terminal workspace cleanup can remain an advisory at completion, but not at
-archive. Artifacts selected as results must be fixed, present and Task-local.
+Terminal workspace cleanup can remain an advisory at completion. Ordinary
+archive requires it to be settled; explicitly authorized force archive may
+retain unresolved resources as described below. Artifacts selected as results
+must be fixed, present and Task-local.
 
 Publication records a remote PR/MR reference. Reported merge, independently
 verified merge and exact Task-head coverage are separate facts. Task completion
 does not prove any of them. Remote delivery is read from exact publication/head
 evidence, not inferred from a title or branch name.
 
+Completion heads remain the immutable acceptance baseline. A later, authorized
+integration may produce a different publication candidate (including a rebase
+or merge before a remote squash). Neither ancestry nor a successful Integration
+proves that the accepted behavior survived, or accepts additional changes.
+
+For a completed, unarchived Task, record the exact candidate as the Publication's
+`localCommit`, then read `task publication diff <task>/<publication>`. This reads
+only Task-owned local Git objects and returns the original completion reference,
+both commit/tree endpoints, the full diff (including binary changes), and a
+digest binding those facts. Review removals, additions and conflict resolutions
+against the original requirements. If they preserve the accepted result and all
+relevant increments are accepted, use
+`task publication adopt <task>/<publication> --reviewed-diff <sha256> --acceptance <text>`.
+The acceptance must explain that judgment and its verification/review evidence;
+Core checks fixed identity and facts, not the meaning of the code. If an existing
+Task Integration produced that exact candidate, pass its local ID with
+`--integration <id>` to both commands to bind its committed evidence as well.
+This records one Task event, not a new delivery status, Candidate lifecycle,
+Git operation, or permission to change completed work.
+
+`task publication verify` remains the explicit, authorized provider read. It
+records the remote source head, PR/MR state and merge commit independently of
+Task acceptance. A mismatched head or non-merged state is saved as **reported**,
+superseding earlier verification; provider errors or mismatched external identity
+write nothing. A merged provider observation verifies only that Publication's
+exact local candidate. A squash merge needs no fabricated commit ancestry.
+Metadata/verification successors preserve adoption only through an uninterrupted
+same-candidate Publication lineage. Candidate or referenced Integration changes
+cannot silently reuse the decision.
+
+CLI, current Leader Context and Web derive coverage from these same facts, with
+no provider reads or evidence writes. They distinguish not delivered, merged
+but uncovered, covering merge not verified, partial delivery and verified merge.
+Each Project retains its own accepted head, selected candidate, adoption reference
+and reason. Unknown historical heads remain unknown; old exact-SHA evidence stays
+valid without inventing adoption, and archive never proves remote delivery.
+
 Cancelled intent does not prove the runtime stopped. User/Operator may reopen
 cancelled Tasks; Leader may reopen completed Tasks. Reopening requires fresh
 explicit input/work selection and never replays previous delivery requests.
 
 ## Archive
 
-Archive is a separate authorized action after active work is settled and
-resources are clean and removable. Choose integrated delivery or deliberate
-abandonment explicitly. Integrated archive requires exact merged heads and
-verified publication evidence. An explicitly authorized verification override
-cannot bypass missing or stale heads or an unmerged result.
-
-Managed WorkItem resources must be integrated or deliberately abandoned before
-cleanup. Review, Lane and Integration resources must be settled. Dirty worktrees
-remain for the Agent to resolve; no implicit reset or force deletion occurs.
-Task main branches and durable Task records retain recovery information.
+Archive requires independent user/Operator authorization for an exact completed
+or cancelled (retired) Task. Completion alone grants none, and ordinary archive
+approval does not authorize force. Select one disposition explicitly:
+
+```sh
+yui task archive <task> --integrated
+yui task archive <task> --abandon
+# Only with explicit force authorization, preserving the chosen disposition:
+yui task archive <task> (--integrated|--abandon) --force
+```
+
+### Ordinary archive
+
+Active work and inputs must be settled, and managed resources clean and safely
+removable. WorkItem results must be integrated or deliberately abandoned;
+Review, Lane and Integration resources must be settled. With `--integrated`,
+each Project requiring code delivery needs a merged, verified Publication
+covering its accepted head, either exactly or through valid explicit candidate
+adoption. `--abandon` records deliberate non-delivery,
+not verified merge.
+
+Missing/stale coverage, unresolved execution or dirty worktrees prevent ordinary
+archive. Resolve the reported facts before an explicit retry; no implicit reset
+or force deletion occurs.
+
+### Explicit force archive
+
+`--force` is not merely a merge-verification override. It commits the archive
+and stops new Task scheduling before attempting safe foreground cleanup.
+Missing or stale delivery evidence, an unmerged result, unresolved execution
+and cleanup failures become warnings with retained resource references, rather
+than blocking that archive commit. Authority, eligible lifecycle, exact resource
+identity and mandatory audit persistence still fail closed.
+
+Force neither verifies a merge nor accepts work, proves quiescence, discards
+dirty data or implies `--abandon`. It preserves the selected disposition and
+original Publication/completion evidence. Unverified local commits and resources
+that cannot safely be released stay owned and traceable. A cleanup failure does
+not roll back archive; late runtime events remain source evidence without
+resuming the Task or settling unknown input.
+
+### Read the result before cleanup
+
+`yui task show <task> --json` exposes `data.archive.warnings`,
+`data.archive.retainedResources` and `data.archive.cleanupEvents`.
+`yui task context <task> --json` retains the original records and events;
+`yui task remote-delivery <task> --json` reports delivery separately.
+Warnings include historical cleanup attempts; retained references describe
+current ownership, not a second cleanup queue.
+
+An archive result with `archived=true` proves archival, not that cleanup fully
+succeeded. Even `cleanupFinished` means the foreground pass finished, not that
+every resource was removed. Repeating archive reports current facts and does
+not replay cleanup. After inspection, use explicit exact-owner resource
+operations for safe cleanup; no background retry or broader deletion authority
+is implied. Both archive paths preserve Task history and recovery information.
 Archived Tasks cannot reopen.
 
+`yui task archive-preflight <task> (--integrated|--abandon) [--force] [--json]`
+reads current admission, delivery and exact-owner cleanup checks in one report.
+It is available before and after archive, including to the Task's authorized
+Leader reader. `--force` here only selects the behavior to inspect. It never
+archives, prepares workspaces, refreshes Git indexes, stops Sessions, acquires
+maintenance locks, fetches remote data, or writes a cleanup plan.
+
+Each blocking/unknown check has a resource, reason code, expected and observed
+values, source references and existing inspection/disposition commands. Git
+paths outside the authorized Task are redacted. The report distinguishes
+missing Candidate workspace, changed workspace identity/metadata/path, missing
+frozen commit, moved HEAD, dirty worktree, missing/locked Git registration,
+unintegrated result, uncovered delivery, unsettled owner and unknown execution.
+Status inspection disables optional index writes and filesystem-monitor hooks.
+If a tracked file selects a configured clean/process filter (including an
+initialized submodule's), it reports `git-status-requires-filter` as unknown instead of
+executing the program or bypassing normalization and guessing clean/dirty.
+Historical Candidate paths remain immutable. A path difference, including one
+consistent with an earlier layout migration, does not itself prove a safe
+relocation: without an exact mapping the check reports the difference and
+retains the resource; it does not repair history or weaken commit/owner checks.
+
+Preflight is an observation, not a removal permit. Cleanup reloads the same
+checks and Git verifies ownership/dirt again at removal. A Task-main clone's
+dependent registrations are expected before child cleanup and must be absent
+before clone removal. Archive preserves new dirt even in a failed Integration
+workspace; the separate explicit Integration cleanup command keeps its existing
+disposable-conflict behavior. A finished force cleanup means the foreground
+attempt ended, not that every resource was released. Current retained references
+and exact physical runtime evidence remain separate from historical diagnostics.
+
 Use each command's `--help` to inspect its exact authority and options before
 cleanup; reading a lifecycle document does not authorize an external write.

package/docs/task-delivery.zh-CN.md

@@ -11,6 +11,8 @@ Task 生命周期是 `draft / active / completed / cancelled / archived`。Draft
 状态/所有权。准备失败会让 Task 停在 Draft，附带一个失败请求和投递给 Leader 的
 诊断。延迟激活保留确切意图并等待原生静止，无论它是在规划 Run 中还是在后续讨论中
 被请求的。
+Project 维护争用会在采用资源前异步等待。锁超时或等待被取消时保留原激活请求；
+获得锁后重新检查当前意图与权限。
 
 Task type 描述被请求的结果，而不是强制的执行者。Leader 直接负责有界工作，或分派
 有独立价值的 WorkItem。直接执行没有 Group。复制是为了在同一个冻结 Assignment 上
@@ -19,7 +21,8 @@ Task type 描述被请求的结果，而不是强制的执行者。Leader 直接
 ## 受管工作区
 
 稳定的 Project checkout 是只读参考。Task main 是一个逻辑上的多 Project 根，带有
-按 Project 划分的 Git worktree。对单个 Project，Agent 的正常 cwd 是其受管 Git 根；
+按 Project 划分的独立 Git clone；WorkItem、Review 和 Integration worktree 归这些
+Task 仓库所有。对单个 Project，Agent 的正常 cwd 是其受管 Git 根；
 对多个 Project，根加上原生的附加目录机制暴露明确的 Project 集合。
 
 一个隔离的 WorkItem 为可写 Project 拥有独立 worktree，为其余 Project 提供 Task-main
@@ -58,25 +61,111 @@ Reviewer Run 持有报告；执行成功不等于语义通过。验收归 Leader
 干净且已提交的 Task-main 快照。当有一条新的 user/Operator 消息仍在等待 Leader
 投递时，它也会拒绝完成。当前原生轮次必须结束，待处理的通知才能到达；随后 Leader
 读取原始消息并重新评估完成。这派生自既有的 Message 和 mailbox 投递，而不是第二套
-确认或工作流状态。终态工作区清理在完成时可以只是建议，但在归档时不行。被选作
-结果的 Artifact 必须是固定的、存在的且 Task 局部的。
+确认或工作流状态。终态工作区清理在完成时可以只是建议。普通归档要求清理已结算；
+明确授权的 force 归档可以保留下文所述的未解决资源。被选作结果的 Artifact 必须是
+固定的、存在的且 Task 局部的。
 
 发布记录一个远程 PR/MR 引用。被报告的合并、独立验证的合并以及确切的 Task-head
 覆盖是彼此独立的事实。Task 完成不证明其中任何一项。远程交付从确切的发布/head
 证据读取，而不从标题或分支名推断。
 
+完成 head 始终是不可变的验收基线。之后获授权的集成可能产生不同的发布候选
+（例如远端 squash 前的 rebase 或 merge）。祖先关系和 Integration 成功都不能
+证明验收行为未被撤销，也不验收额外增量。
+
+对于已完成但未归档的 Task，先把精确候选记为 Publication 的 `localCommit`，
+再读 `task publication diff <task>/<publication>`。此命令只读取 Task 自有的
+本地 Git 对象，返回原完成记录引用、两端 commit/tree、完整差异（含二进制变更），
+以及绑定这些事实的摘要。逐项核对删除、增加和冲突处理是否仍满足原需求；仅在原成果
+保留、相关增量也已验收时，执行
+`task publication adopt <task>/<publication> --reviewed-diff <sha256> --acceptance <text>`。
+验收依据应解释上述判断及其验证/审阅证据；Core 核验固定身份和事实，不裁定代码语义。
+如果已有本 Task 的 Integration 产出了该精确候选，在两个命令中都传入
+`--integration <id>`，一并绑定其已提交证据。这只新增一个 Task 事件，不新增交付
+状态表、Candidate 生命周期或 Git 操作，也不授权修改已完成成果。
+
+`task publication verify` 仍是显式且须获授权的 provider 读取。它独立于 Task
+验收，记录远端 source head、PR/MR 状态和 merge commit。head 不匹配或尚未合并时，
+保存为 **reported** 并取代旧验证；provider 错误或外部身份不匹配则不写任何证据。
+已合并的 provider 观察仅验证该 Publication 的精确本地候选；squash 不需要伪造
+提交祖先关系。元数据/验证更新只有沿连续同候选的 Publication 血缘才能继承采用；
+候选或所引用的 Integration 变化，不能悄悄复用旧决定。
+
+CLI、当前 Leader Context 和 Web 从同一组事实推导覆盖，不联网、不写证据。展示
+区分尚未交付、PR/MR 已合并但未覆盖、已覆盖合并但未验证、部分交付、已验证合并。
+每个 Project 保留自己的验收 head、候选、采用引用和原因。缺失的历史 head 仍然
+未知；旧精确 SHA 证据无需补造采用记录，归档也不能反推已交付。
+
 取消意图不证明运行时已停止。user/Operator 可以重开已取消的 Task；Leader 可以重开
 已完成的 Task。重开需要全新的显式输入/工作选择，绝不重放先前的交付请求。
 
 ## 归档
 
-归档是一次单独的授权动作，发生在活动工作已了结、资源干净可移除之后。显式选择
-集成交付或有意放弃。集成归档要求确切的已合并 head 和已验证的发布证据。一次显式
-授权的验证覆盖不能绕过缺失或陈旧的 head，也不能绕过一个未合并的结果。
-
-受管的 WorkItem 资源必须在清理前被集成或有意放弃。Review、Lane 和 Integration
-资源必须已结算。脏 worktree 留给 Agent 解决；不发生隐式 reset 或强制删除。Task
-main 分支和持久 Task 记录保留恢复信息。已归档的 Task 不能重开。
+归档需要针对确切的 completed 或 cancelled（retired）Task 获得独立的 user/Operator
+授权。完成本身不授予归档权限，普通归档批准也不授权 force。显式选择一种处置：
+
+```sh
+yui task archive <task> --integrated
+yui task archive <task> --abandon
+# 仅在明确授权 force 后使用，并保留所选处置：
+yui task archive <task> (--integrated|--abandon) --force
+```
+
+### 普通归档
+
+活动工作与输入必须已了结，受管资源干净且可安全移除。WorkItem 结果必须已集成或
+有意放弃；Review、Lane 和 Integration 资源必须已结算。使用 `--integrated` 时，
+每个需要代码交付的 Project 都要求已合并且已验证的 Publication，通过精确匹配
+或有效显式采用候选覆盖其验收 head。`--abandon` 记录有意不交付，而不是已验证合并。
+
+缺失或陈旧的覆盖、未解决的执行或脏 worktree 会阻止普通归档。先解决报告的事实，
+再显式重试；不会隐式 reset 或强制删除。
+
+### 明确授权的 force 归档
+
+`--force` 不只是覆盖合并验证要求。它先提交归档并停止新的 Task 调度，再尝试安全的
+前台清理。缺失或陈旧的交付证据、未合并结果、未解决的执行和清理失败会成为警告及
+保留资源引用，而不阻止这次归档提交。权限、合法生命周期、精确资源身份和强制审计
+持久化仍严格检查，失败时拒绝相应操作。
+
+Force 不验证合并、不验收工作、不证明物理静止、不丢弃脏数据，也不隐含 `--abandon`。
+它保留所选处置及原始 Publication/完成证据。未验证的本地提交和无法安全释放的资源
+仍有明确 owner 且可追溯。清理失败不回滚归档；迟到的运行时事件仍作为来源证据，
+不恢复 Task 或结算未知输入。
+
+### 清理前先读结果
+
+`yui task show <task> --json` 暴露 `data.archive.warnings`、
+`data.archive.retainedResources` 和 `data.archive.cleanupEvents`。
+`yui task context <task> --json` 保留原始记录与事件；
+`yui task remote-delivery <task> --json` 单独报告交付。警告包含历史清理尝试；
+保留引用描述当前所有权，不是第二套清理队列。
+
+归档结果中的 `archived=true` 证明已归档，不证明清理全部成功。即使 `cleanupFinished`
+也只代表前台清理已走完，不代表资源全部移除。重复归档只报告当前事实，不重放清理。
+检查后通过显式的精确 owner 资源操作进行安全清理；不隐含后台重试或更广泛的删除
+权限。两条归档路径都保留 Task 历史与恢复信息。已归档的 Task 不能重开。
+
+`yui task archive-preflight <task> (--integrated|--abandon) [--force] [--json]`
+一次读取归档条件、交付覆盖与各精确 owner 的清理检查。归档前后都可用，获授权的
+Task Leader reader 也可读取。这里的 `--force` 仅选择要检查的行为，不会归档、
+准备工作区、刷新 Git index、停止 Session、获取维护锁、抓取远端或保存清理计划。
+
+每项阻断/未知检查都有资源、原因码、预期/观察值、来源引用及既有检查/处置命令。
+无权访问的 Task 外路径会脱敏。报告区分 Candidate 工作区缺失、工作区身份/元数据/
+路径变化、冻结 commit 缺失、HEAD 变化、脏 worktree、Git 注册缺失或锁定、结果未集成、
+交付未覆盖、owner 未结算和执行未知。状态检查禁用可选 index 写入及 filesystem-monitor
+钩子；若已跟踪文件的属性选择了配置中的 clean/process filter（包括已初始化的 submodule），则返回
+`git-status-requires-filter` 未知诊断，不执行程序，也不绕过规范化猜测干净/脏状态。
+历史 Candidate 路径保持不可变。路径差异即使
+符合早期布局迁移的形状，也不单独证明安全迁址；没有确切映射时只报告差异并保留资源，
+不会改写历史或放宽 commit/owner 保护。
+
+预检是观察，不是删除凭据。清理会重新读取同一组检查，Git 删除时再验证身份和脏状态。
+Task-main clone 在子工作区清理前存在关联 Git 注册是正常现象，但移除 clone 前它们必须
+已释放。归档会保留失败 Integration 工作区中新出现的脏文件；独立的显式 Integration
+清理命令保留既有的可丢弃冲突现场合同。force 清理完成只表示这次前台尝试结束，不表示
+全部资源已释放；当前保留引用、精确物理运行时证据与历史诊断仍是不同事实。
 
 清理前用每个命令的 `--help` 查看它确切的权限和选项；阅读一份生命周期文档不授权
 一次外部写入。