@zq-silk/yui 0.15.11 → 0.16.0

package/docs/task-delivery.md

@@ -8,21 +8,34 @@ Task lifecycle is `draft / active / completed / cancelled / archived`. A Draft
 stores intent, Project bindings, planning discussion and mutable requirements.
 It does not adopt a writable delivery workspace at creation.
 
+Activation requires a durable request with an explicit environment plan:
+use `task activation request <task> --request-id <id> --environment <plan>`.
+The Controller adopts eligible requests; `task activate <task>` may consume an
+existing request in the foreground but never creates implicit activation intent.
 Activation validates current Roles, dependencies, Project scope and resources,
 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.
 Direct execution has no Group. Replication is explicitly requested for independent
 attempts at the same frozen Assignment, followed by Leader-selected synthesis.
 
+Scope overlap is a read-only advisory in `task next-action`, not a text-matching
+creation gate. The Leader inspects original requirements and decides whether
+work is independent. Request identity, permissions, dependencies, workspace
+isolation and acceptance checks remain enforced independently.
+
 ## 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.
 
@@ -43,20 +56,82 @@ managed workspace remains the Git/control ownership record.
 ## Candidate, Review and Integration
 
 Provider terminal saves the exact original Run result. It does not accept the
-WorkItem. The Leader evaluates the result and captures immutable per-Project
-ChangeSets for isolated code. The governing Candidate supplies provenance for
+WorkItem. The Leader evaluates the result and its immutable per-Project Git
+snapshot. Optional ChangeSets supply diff evidence. The governing Candidate supplies provenance for
 Review and Integration; Producers do not independently enter either path.
 
-Integration applies the fixed ChangeSet in a candidate worktree, runs configured
+The Agent chooses the order and strategy, then starts one Integration from an
+exact WorkItem Candidate. There is no separate ChangeSet integration queue.
+Integration applies the fixed source commits in a candidate worktree, runs configured
 checks, then advances the target only if its head still matches. Conflict,
 failed checks, target movement or rejection retain evidence and never advance
 the target. The Agent chooses retry or manual resolution within the retained
 workspace.
 
+An existing merge/rebase/cherry-pick without the attempt's own progress receipt
+is not adopted from Git markers. Preserve the scene and choose explicit recovery;
+normal continuation uses the original receipt and never replays a completed step.
+
 When checks are a DurableJob, the Integration retains that exact jobId while
 running. Once the Job settles, `task integration continue <task>/<integration>`
-consumes its result and performs the guarded finalization. The direct operation
-does not depend on entries in the separate integration queue.
+consumes its result and performs the guarded finalization. Existing unsettled
+Integrations, including conflicts, remain completion blockers independently of
+how the Agent ordered them.
+
+### Verification reuse and explicit reruns
+
+A configured VerificationPlan reuses only complete, successful, log-verified
+evidence for the exact Project, commit, plan, toolchain and target/base boundary.
+A plan with no reusable evidence executes normally. Plans require
+`schemaVersion: 2` and contain no `l1` or `record/reuse/enforce` mode.
+Storage 34→35 preserves the original Project declarations, L1 artifacts and
+binary logs in migration audit storage, outside current execution and cache
+lookup. Historical `historical-change-sets` Integrations must be settled and
+free of execution/delivery references before their exact payloads become
+`integration.source-retired` Task Events. Their IDs are never reused.
+
+Request fresh checks when creating an operation:
+
+```sh
+yui task integration start <task> --work-item <id> --strategy ff --rerun-checks
+yui task upstream integrate <task> --project <project> --rerun-checks
+```
+
+The flag is immutable intent on that Integration, not a global configuration
+switch. `continue` consumes the same admitted Job; it cannot turn into a rerun.
+Create a new attempt for another execution, and settle any equivalent unfinished
+verification first. Rerun affects only cache reuse, never permissions, Job
+identity, workspace checks or the final target CAS.
+Explicit `--check` commands also request fresh execution. With a plan configured,
+they run after its checks; they are neither ignored nor rejected by text matching.
+Unstructured checks do not search historical Jobs for a substitute result.
+
+Fresh execution withdraws the old success before starting. Failure is recorded
+as failure; interruption, missing logs or a mutated candidate leave no reusable
+success. Both Job and local execution verify the exact clean candidate before
+publishing successful proof. The v5 L2-only execution digest excludes older proof without
+deleting its history. A stale
+cache consumer cannot restore an older result. Release lookup considers the
+newest recorded matching proof rather than searching past a failure for an
+older green result. The cache represents current reusable evidence, not Task
+execution history; original Job and Integration records remain separate.
+
+The public upstream CLI uses the same Controller Job port as other Integration
+commands. `--latest` may return independent pending Jobs for several Projects;
+continue each returned Integration ID rather than issuing another upstream
+request to poll it.
+
+Job admission, management and pre-spawn checks bind a non-Leader to its current
+Assignment, exact WorkItem workspace and writable Project scope. The existing
+Job owner contract does not represent Review/replica workspaces, so those
+requests fail explicitly rather than falling back to Task main. Leader/Operator
+supervision and settlement of already-running Jobs remain separate.
+
+The identity covers declared inputs, not every external service or untracked
+environment condition. Use explicit reruns for changing external inputs,
+flakiness investigation or a user-requested new check. A plan does not authorize
+real-model/paid/shared-resource validation. Reuse never substitutes for Review,
+acceptance or publication authority.
 
 Review follows the applicable Candidate rule or Task-final contract and frozen
 heads. The exact main Reviewer Run holds the report; successful execution is
@@ -75,31 +150,162 @@ 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.
+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:
 
-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.
+```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.
 
+Resource GC is a separate, opt-in quarantine path. A runtime subtree moves once:
+the parent receipt owns recovery of its contents, and redundant child registry
+entries are removed in the same registry transaction. Independently owned Git
+worktrees or retained descendants prevent moving their enclosing directory.
+Task records and results are never removed by this consolidation.
+Session process custody comes from SQLite `session_owners`, with live PID and
+start-identity checks. The retired JSON owner directory is not a parallel source.
+
+The plan is not cleanup authority. Apply and purge re-read Task status, managed
+workspaces, active Runs and unsettled Jobs under the existing SQLite writer
+fence, which spans the bounded physical mutation and registry update. A reopened
+Task or new durable owner prevents quarantine/deletion; uncertainty retains the
+resource with a diagnosis. Reopened quarantined resources can be restored.
+This adds neither a retry worker nor another persistent ownership protocol.
+
+`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

@@ -7,19 +7,30 @@
 Task 生命周期是 `draft / active / completed / cancelled / archived`。Draft 保存
 意图、Project 绑定、规划讨论和可变需求。它在创建时不采用可写的交付工作区。
 
+激活要求先保存带明确环境计划的请求：
+`task activation request <task> --request-id <id> --environment <plan>`。
+Controller 采用符合条件的请求；`task activate <task>` 可以在前台消费已有请求，
+但不会隐式创建激活意图。
 激活会校验当前 Role、依赖、Project 范围和资源，准备物理工作区，并原子地采用
 状态/所有权。准备失败会让 Task 停在 Draft，附带一个失败请求和投递给 Leader 的
 诊断。延迟激活保留确切意图并等待原生静止，无论它是在规划 Run 中还是在后续讨论中
 被请求的。
+Project 维护争用会在采用资源前异步等待。锁超时或等待被取消时保留原激活请求；
+获得锁后重新检查当前意图与权限。
 
 Task type 描述被请求的结果，而不是强制的执行者。Leader 直接负责有界工作，或分派
 有独立价值的 WorkItem。直接执行没有 Group。复制是为了在同一个冻结 Assignment 上
 进行独立尝试而被显式请求的，随后由 Leader 选择综合。
 
+工作范围重叠只在 `task next-action` 中作为只读建议，不再按文本匹配拦截创建。
+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
@@ -34,17 +45,65 @@ Task type 描述被请求的结果，而不是强制的执行者。Leader 直接
 
 ## Candidate、Review 与 Integration
 
-Provider 终态保存确切的原始 Run 结果。它不验收 WorkItem。Leader 评估结果，并为
-隔离代码捕获不可变的、按 Project 划分的 ChangeSet。治理 Candidate 为 Review 和
+Provider 终态保存确切的原始 Run 结果。它不验收 WorkItem。Leader 评估结果及其不可变的
+按 Project 划分的 Git 快照。ChangeSet 是可选的差异证据；治理 Candidate 为 Review 和
 Integration 提供来源；Producer 不独立进入这两条路径中的任何一条。
 
-Integration 在候选 worktree 中套用固定 ChangeSet，运行已配置的检查，然后只有在
+Agent 选择结果顺序与策略，再从精确 WorkItem Candidate 发起一次 Integration，
+不再维护单独的 ChangeSet 集成队列。
+Integration 在候选 worktree 中套用固定来源提交，运行已配置的检查，然后只有在
 目标 head 仍匹配时才推进目标。冲突、检查失败、目标移动或拒绝都保留证据，绝不推进
 目标。Agent 在保留的工作区内选择重试或手动解决。
 
+已有 merge/rebase/cherry-pick 若缺少原尝试的进度回执，不根据 Git 标记接管。
+保留现场并选择显式恢复；正常续作使用原回执，不重放已完成步骤。
+
 当检查是一个 DurableJob 时，Integration 在运行期间保留那个确切的 jobId。Job 结算
 后，`task integration continue <task>/<integration>` 消费其结果并执行带守卫的收尾。
-这个直接操作不依赖单独 integration 队列中的条目。
+未结算的 Integration（包括冲突）仍阻止完成，不依赖 Agent 采用了什么执行顺序。
+
+### 验证复用与显式重跑
+
+配置了 VerificationPlan 的项目，默认只复用完整成功、日志可校验，且 Project、
+提交、计划、工具链、目标 ref／基线都精确匹配的证据。存储 `34→35` 将原始 Project
+计划、L1 artifact 和二进制日志保存在迁移审计存档，不再进入当前执行与缓存读取。
+`historical-change-sets` Integration 必须先结算且不存在执行／交付引用，才能将
+完整 payload 转为 `integration.source-retired` Task 事件；旧 ID 不会复用。
+无匹配证据时正常执行。
+计划必须提供 `schemaVersion: 2`，不再包含 `l1` 或 `record/reuse/enforce` 模式。
+
+新建操作时显式要求重跑：
+
+```sh
+yui task integration start <task> --work-item <id> --strategy ff --rerun-checks
+yui task upstream integrate <task> --project <project> --rerun-checks
+```
+
+该选项是本次 Integration 的不可变意图，不是全局配置开关。`continue` 只消费原先
+接纳的 Job，不会变成重跑。再次执行需创建新尝试，并先结算等价的未完成验证。
+重跑只跳过缓存，不绕过权限、Job 身份、工作区检查或最终目标 CAS。
+显式 `--check` 同样要求实际执行。配置了计划时，它们在计划检查后执行，
+不会被忽略，也不会因命令文本相同而被拒绝。
+非结构化检查不再搜索历史 Job 来替代本次执行。
+
+新执行开始前撤下旧成功。失败如实记录；中断、缺失日志或候选被改写时，
+不会保留可复用成功。Job 和本地执行在发布成功证据前，共同检查候选的精确提交、
+分支和干净状态。v5 L2-only 执行摘要隔离旧证据，不删除原有历史。
+过期的缓存使用者不能恢复旧结果。发布查询查看最新匹配证据，不跳过失败去找旧绿灯。
+缓存只表示当前可复用证据，不充当 Task 执行历史；原 Job 和 Integration 记录独立保留。
+
+公开 upstream CLI 与其他 Integration 命令共用 Controller Job 入口。
+`--latest` 可以返回多个 Project 各自待处理的 Job；应继续返回的每个 Integration ID，
+而不是重新发起 upstream 请求来轮询进度。
+
+Job 的准入、管理操作及启动前检查把非 Leader 限定到当前 Assignment、
+精确 WorkItem 工作区和可写 Project。现有 Job owner 不能表达 Review/replica
+工作区时会明确拒绝，不退回 Task 主工作区。Leader/Operator 管理与已运行 Job 的
+结果结算保持独立。
+
+这些身份只覆盖已声明输入，不是所有外部服务和未跟踪环境的完整指纹。
+外部条件变化、排查偶发失败或用户要求再次检查时，应显式重跑。
+计划不赋予真实模型、付费或共享资源测试授权；复用也不替代 Review、验收或发布权限。
 
 Review 遵循适用的 Candidate 规则或 Task-final 合同以及冻结的 head。确切的 main
 Reviewer Run 持有报告；执行成功不等于语义通过。验收归 Leader。即使默认审查策略
@@ -58,25 +117,123 @@ 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 不能重开。
+
+资源 GC 是独立、显式启用的隔离路径。同一 runtime 子树只移动一次，由父目录
+回执负责恢复完整内容；重复的子目录 registry 记录在同一事务内移除。
+独立 Git worktree 或仍需保留的子资源会阻止移动其父目录，不删除 Task 记录或成果。
+Session 进程归属只读取 SQLite `session_owners`，并校验存活 PID 和启动身份；
+旧 JSON owner 目录不再作为并行来源。
+
+清理计划不是执行授权。Apply 与 purge 在现有 SQLite 写锁内重读 Task 状态、
+受管工作区、active Run 和未结算 Job，并保持写锁直到有界文件操作与 registry
+更新完成。Task 重新打开或新增持久所有者会阻止隔离、删除；无法证明安全时
+保留资源并给出原因。已经隔离、随后重新打开的资源可以恢复。
+不增加后台重试 worker 或第二套持久所有权协议。
+
+`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` 查看它确切的权限和选项；阅读一份生命周期文档不授权
 一次外部写入。

package/docs/task-discovery.md

@@ -0,0 +1,101 @@
+<p align="right"><strong>English</strong> | <a href="./task-discovery.zh-CN.md">简体中文</a></p>
+
+# Bounded Task discovery
+
+Agents discover candidates with `yui task list --json`, then
+read the selected Task's Context and original Messages. The catalog is a
+current read, not a summary database, a Context snapshot, an acknowledgement,
+or an execution/acceptance decision.
+
+The catalog is the only list contract; there is no `--view` selector or
+`--verbose` full-history list. Internal interactive selectors retain their
+complete `{id,title,status}` array and read only those columns. Web uses the
+same query at `GET /api/dashboard`. The per-Task detail endpoint retains
+execution, observability, usage and remote-delivery fields. Discovery itself
+does not change persistent records.
+
+## Query and page contract
+
+```sh
+yui task list --project project-1 --status active --limit 20 --json
+yui task list --attention openInputs --json
+yui task list --search "candidate title" --json
+yui task context task-1 --json
+yui task context inspect task-1 --store task --ref task-1 --digest <digest> --json
+yui task message show task-1/message-1 --json
+```
+
+`--project` accepts an exact Project ID. Search matches ID, title, tags and
+Project name using SQLite substring comparison (ASCII case-insensitive;
+non-ASCII characters compare literally). Default scope excludes archived
+Tasks; `--all` or `--status archived` includes them. Counts declare that scope,
+not an invisible global total. Status/search/Project/attention filters apply
+to `total` and the returned Tasks, not the scope-wide attention summary.
+
+The default limit is 20, maximum 100. Successful JSON responses, including the
+CLI envelope, fit 32 KiB. UTF-8 summaries are at most 512 bytes; titles are
+at most 256 bytes. Truncation is explicit. IDs, digests and cursors are never
+truncated. Oversized mandatory metadata produces a bounded error, not a
+non-progressing successful page. A missing Brief is reported as missing.
+
+Order is ascending `(createdAt, id)` with SQLite binary ID ordering. Repeat
+all filters and the limit with `--cursor <nextCursor>`. A null cursor ends the
+page sequence; byte limits can end a page before its requested item limit.
+The first page fixes the largest matching creation key. Newer creation keys
+are excluded until refresh. Each later page reads current facts: lifecycle or
+filter membership changes can affect the enumeration. This is not a frozen
+snapshot, and unrelated runtime events do not invalidate a cursor.
+
+Each Task and attention sample has a real Task Context ref
+(`taskId, store, refId, revision, digest`). The digest covers the original
+Task, not the clipped preview or Brief. Read Task Context for the current
+Brief and use Context inspect for a digest-checked original. A changed digest
+is rejected; a ref never grants authority or implies the requirement was read.
+
+## Attention without full history
+
+Every page, including a filtered empty page, reports the same authorized
+catalog's current attention. Each category contains a record/signal count,
+affected-Task count, up to four exact Task refs, omitted-Task-ref count, and a
+filter for enumerating all affected Tasks:
+
+Start that attention query without the previous status/search/Project filters
+and retain its `all` flag. This preserves the declared catalog scope, including
+archived Tasks when explicitly included.
+
+| Category | Current stored facts |
+| --- | --- |
+| `openInputs` | Open InputRequests |
+| `pendingOperations` | Queued/running durable Jobs |
+| `unknownOperations` | Jobs with `unknown-needs-attention` |
+| `executionSignals` | For active/draft Tasks: live Runs, open WorkItems or accepted WorkItems retaining a current replicated group, unresolved/failed Integrations, pending/running/failed Reviews, Leader failure, and pending/processing Leader mailbox |
+
+`executionSignals` is deliberately conservative discovery, **not** the detailed
+execution-status classifier. Healthy live work is included so runtime identity,
+stall, failed-work and recovery attention cannot be hidden behind pagination
+or require scanning every Task's historical events. Counts must not be read as
+failure counts. Open the affected Task for its precise execution state and
+source records; no report text is parsed into status. Web explicitly labels
+these facts and offers category navigation. Selected detail survives paging,
+filtering and refresh; only the detail read can establish absence.
+
+Task Leader Sessions see only their own Task. Assignment-scoped Workers and
+Reviewers use existing authorized Run Context instead of whole-Task discovery;
+the catalog rejects their request before counting. Global non-Operator and
+incomplete managed identities are rejected. Historical Leader diagnostic reads
+retain their original Task scope. A cursor is scope/filter-bound continuation,
+not a credential. Read operations do not consume messages, acknowledge jobs,
+wake Roles or query providers.
+
+## Cost boundary
+
+SQLite queries existing catalog/status indexes and aggregates narrow facts
+before selecting page rows. It does not decode all Task payloads, Runs,
+Messages or Events into JavaScript, build all overviews and delete fields, or
+construct per-Task Context. Only selected Tasks and bounded attention samples
+are decoded and hashed for original refs.
+
+Output and materialized rows are bounded. Database work still scales with
+authorized Tasks and relevant index rows; search can inspect Task/Project JSON
+inside SQLite. Exact refs still cost the selected original Task's payload size.
+These are local cost boundaries, not constant-time or model-effect claims.