@zq-silk/yui 0.15.7 → 0.15.9

package/docs/roles-and-configuration.zh-CN.md

@@ -0,0 +1,96 @@
+<p align="right"><a href="./roles-and-configuration.md">English</a> | <strong>简体中文</strong></p>
+
+# Role、Profile 与执行配置
+
+## 职责
+
+Agent 选择一个执行组件、连接方案和启动环境。Role 选择一个活动的 Agent 绑定和
+可移植行为。每个绑定保留独立的运行时选项。一个 Role 可以持有多个绑定，而不产生
+并行写者，也不把一个绑定的凭据/配置共享给另一个。
+
+Task Role 是 Task 局部的；global Role 提供已配置的默认值和全局对话。Role
+身份/配置不是可写的运行时状态。Session 与 Provider 观察描述实际活动。
+
+一次显式的 Task-final Review 使用既有的 Task 局部 Reviewer Role，不要求存在同名
+的 global Role。只有当请求的 Task Role 不存在时，global Role 才作为创建模板。
+可用性、producer 分离和冻结的审查候选仍然适用。
+
+## Profile
+
+Agent Profile 把可移植行为（指令、Skill 和访问意图）与运行时意图组合在一起。
+运行时要么沿用当前 Global Worker 绑定，要么显式选择一个 Agent 并可选 model 和
+effort。`config profile reset` 提供 `worker`、`explorer`、`implementer` 和
+`reviewer`。
+
+从 Profile 创建 Task Role 会冻结其解析后的行为和绑定。之后对 Profile 或 Global
+Worker 的编辑不会改写既有的 Task Role。重新套用一个 Profile 是一次显式配置变更。
+所选 Agent 必须与目标绑定匹配；显式的 Role 选项覆盖对应的模板字段。Profile
+不是 Session、工作区 owner 或资源 grant。
+
+原生子代继承其父 Agent 和权限。Profile 可以引导它们的行为；model/effort 覆盖
+需要真实的原生工具支持。它们不获得 Yui Role、独立 Assignment 或更大范围。
+
+## 期望、生效与观察
+
+期望设置是下一次启动的意图。AgentRun 和 Session 捕获生效启动：Agent/组件、
+协议、model、effort、权限策略、工作区/环境、Role 上下文以及 planning/delivery
+权限。
+
+对运行中配置的检查单独报告 Agent 实际声明的内容。unsupported 和 unknown 都是
+显式的；一个被接受的 setter 若没有回报当前值，并不算已观察到的匹配。读取配置
+不会修改 Agent 以让观察与期望一致。
+
+Worker 绑定变更保留活动 Assignment 的 Agent 和生效快照；之后的显式派发使用当前
+选择。Leader 替换撤销上一条管理入口，但不改写 Worker Assignment。更改期望配置
+不会热改原生 Session。一次显式的 `task role session new` 请求会在选择新 Session
+之前处理旧运行时清理；它不要求先手动结算 Run 状态。一个有用的 Session 可以复用，
+但它绝不是 Task 上下文的唯一持有者。
+
+## 权限与 Project 上下文
+
+Provider 权限策略、Profile 访问意图和 Project 写范围是不同的合同。Provider 旁路
+不授予对另一个 Project 的写入。受管工作区 owner、精确 Assignment 和资源 grant
+落实 Yui 操作；宽泛的原生权限不是 OS 沙箱。
+
+Yui 提供其通用 Role Skill 和 Context 指针。Project Skill 仍是由 Agent 原生发现的
+普通 Project 文件。Project Knowledge 维护在 `YUI_HOME` 下；把仓库材料复制进 prompt
+并不使其成为权威 Knowledge。
+
+## 原生认证
+
+账号配置比 Session 活得更久。Yui 保留 `HOME` 和所选的 `CLAUDE_CONFIG_DIR`；
+新建/恢复的 Session 不会复制、清除或伪造原生登录、key 批准或 onboarding 记录。
+
+对 Claude Code，标准的 API-key、base-URL、bearer/OAuth、model-alias 以及原生
+provider 选择相关环境变量只转发给 Claude。这些值留在 Controller 可替换的运行时
+环境和子进程中，不进入 Task/Role 记录。取消某个来源并刷新 Controller 环境，即可
+在后续启动中移除它。其他自定义凭据变量仍使用显式的 Agent 环境绑定或原生用户设置；
+Yui 不继承整个 shell 环境，也不推断云凭据。
+
+Claude 自身加载原生设置，并按其生效配置在 API key、既有 helper、登录凭据、profile
+和云认证之间做选择。Yui 不注入 `apiKeyHelper`、不复制凭据文件，也不覆盖原生认证
+优先级。显式的 `--settings` 路径和 settings 来源选择被原样透传。
+
+全新的原生配置仍可能需要 Claude 的初始化、key、工作区和安全确认，包括访问初始化
+服务。隔离 `YUI_HOME` 或替换 Session 都不要求一个全新的原生账号目录。受管的 Task
+执行使用 Claude 的非交互 stream-json 路径，并沿用同样的原生配置归属。
+
+## 命令
+
+```sh
+yui config agent capabilities <agent-id>
+yui config role show <global-role>
+yui config profile show <profile>
+yui task role add <task> <role> --profile <profile>
+yui task role show <task> <role>
+yui task role update <task> <role> --environment <preparation-id>
+yui task role update <task> <role> --managed-environment
+yui task role session inspect <task> <role>
+yui task role session new <task> <role> --reason "<why a fresh Session is useful>"
+```
+
+创建 Role 时，显式的 Agent 设置需要 `--agent`。更新时，省略 `--agent` 针对活动
+绑定；一个具名绑定会被更新但不被激活。`task role bind` 更改选择。在更改期望设置
+之前，活动 Session 需要该命令的显式确认。
+
+关于原生配置和实现限制，参见 [Provider Runtime](provider-runtime.zh-CN.md)。

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

@@ -0,0 +1,78 @@
+<p align="right"><strong>English</strong> | <a href="./sqlite-control-plane-design.zh-CN.md">简体中文</a></p>
+
+# SQLite control-plane storage
+
+Yui has one authoritative product Store: `YUI_HOME/yui.db` in WAL mode. The
+highest contiguous, checksummed row in `schema_migrations` is the one Home
+storage version accepted by the running release.
+
+## Authority
+
+- `yui.db` owns Tasks, WorkItems, AgentRuns, Messages, Decisions, results, Project
+  Knowledge references, managed workspace records, runtime bindings, mailboxes,
+  durable events, and configuration.
+- Provider Sessions, transcripts, processes, caches, telemetry, and runtime
+  observations support execution and diagnosis; they do not replace durable
+  Task facts.
+- Configuration and diagnostics outside the database do not define another
+  storage version or permit rebuilding Task truth heuristically.
+
+## Admission
+
+Ordinary commands open a Home only when all of these are true:
+
+1. `yui.db` exists and its migration ledger is a valid immutable prefix.
+2. The ledger head exactly matches the running CLI's current storage version.
+3. Current record validation and reference integrity succeed.
+
+An older Home inside the CLI's supported range fails ordinary admission but is
+classified as upgradeable. `yui doctor` and `yui upgrade --dry-run` report the
+ordered path without changing the Home. Explicit `yui upgrade` is the only
+standalone mutation boundary: it quiesces the Controller, backs up `yui.db`,
+applies all missing migrations transactionally, and validates the current
+model. A newer, below-minimum, incomplete, or malformed Home fails closed.
+There is no runtime normalization, repair worker, file-Store fallback, dual
+read/write path, or second migration authority.
+
+## Write and concurrency contract
+
+- Each mutation is one SQLite transaction.
+- WAL plus `synchronous=FULL` provides the durable commit boundary.
+- `home_meta.revision` is the Home-wide CAS/revision used by callers that need
+  a frozen read/modify/write boundary.
+- Typed columns support indexed identity and status queries; the full validated
+  record payload remains the durable domain representation.
+- Mailbox claim, exact AgentRun terminalization, active-pointer removal, result
+  persistence, and downstream wake creation are transactionally coupled where
+  they form one product fact.
+- Idempotency keys and unique constraints protect repeatable external-effect
+  acknowledgements; they do not form a second workflow state machine.
+
+## AgentRun and Session boundary
+
+An AgentRun is an explicitly requested execution. It records associated visible
+inputs and the original result, not hidden reasoning or the full tool trace.
+A Provider Session can contain multiple Runs, ordinary native chat and
+notifications. Native chat and notifications do not automatically create Runs.
+Only an exactly correlated native terminal settles the Run; the Leader remains
+the authority for WorkItem and Task acceptance.
+
+## Update behavior
+
+`yui update` stages an exact package and asks that staged binary to classify the
+Home as current, migration-ready, or blocked. It then stops the exact
+Controller, activates the same package, runs the staged release's complete
+migration chain when required, verifies the installed binary and current Home,
+and starts the replacement Controller.
+
+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
+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.

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

@@ -0,0 +1,62 @@
+<p align="right"><a href="./sqlite-control-plane-design.md">English</a> | <strong>简体中文</strong></p>
+
+# SQLite 控制面存储
+
+Yui 只有一个权威产品 Store：WAL 模式下的 `YUI_HOME/yui.db`。`schema_migrations`
+中连续且带校验和的最高一行，就是当前发行版接受的那一个 Home 存储版本。
+
+## 权威
+
+- `yui.db` 拥有 Task、WorkItem、AgentRun、Message、Decision、结果、Project
+  Knowledge 引用、受管工作区记录、运行时绑定、mailbox、持久事件和配置。
+- Provider Session、transcript、进程、缓存、telemetry 和运行时观察服务于执行
+  与诊断，不替代持久的 Task 事实。
+- 数据库之外的配置和诊断不定义另一个存储版本，也不允许启发式地重建 Task 真相。
+
+## 准入
+
+普通命令只有在同时满足以下条件时才打开 Home：
+
+1. `yui.db` 存在，且其迁移账本是一个有效的不可变前缀。
+2. 账本头恰好等于运行中 CLI 的当前存储版本。
+3. 当前记录校验与引用完整性均通过。
+
+落在 CLI 支持区间内的更旧 Home 无法通过普通准入，但被归类为可升级。
+`yui doctor` 和 `yui upgrade --dry-run` 会报告有序的升级路径而不改动 Home。
+显式的 `yui upgrade` 是唯一的独立变更边界：它让 Controller 静止、备份
+`yui.db`、以事务方式套用所有缺失迁移，并校验当前模型。更新的、低于最低版本的、
+不完整的或损坏的 Home 一律 fail closed。不存在运行时归一化、修复 worker、
+文件 Store 回退、双读写路径或第二套迁移权威。
+
+## 写入与并发合同
+
+- 每次修改是一个 SQLite 事务。
+- WAL 加 `synchronous=FULL` 提供持久提交边界。
+- `home_meta.revision` 是全 Home 范围的 CAS/revision，供需要冻结
+  read/modify/write 边界的调用者使用。
+- 类型化列支持按身份和状态建索引查询；完整且经校验的记录负载仍是持久的领域表示。
+- mailbox 认领、精确的 AgentRun 终结、活动指针移除、结果持久化以及下游唤醒创建，
+  在它们构成同一条产品事实时以事务方式耦合。
+- 幂等键与唯一约束保护可重复的外部效果确认，不构成第二套工作流状态机。
+
+## AgentRun 与 Session 边界
+
+AgentRun 是一次明确请求的执行。它记录相关的可见输入和原始结果，而不是隐藏的
+推理过程或完整工具轨迹。一个 Provider Session 可以包含多个 Run、普通原生对话
+和通知。原生对话和通知不会自动创建 Run。只有精确关联的原生终态才结算该 Run；
+WorkItem 与 Task 的验收权威仍归 Leader。
+
+## 更新行为
+
+`yui update` 暂存一个确切的包，并要求那个暂存二进制把 Home 判定为当前、可迁移
+或受阻。随后它停止那个确切的 Controller、激活同一个包、在需要时运行暂存发行版
+的完整迁移链、校验已安装二进制与当前 Home，再启动替换后的 Controller。
+
+每次持久 schema 或负载变更都追加一条不可变、连续的存储迁移。CLI 同时发布
+`storageVersion` 与 `minimumStorageVersion`；处在该闭区间内的每个有效 Home 都能
+直接升级到当前版本，无需安装中间发行版。当前源码在
+`src/storage/storageVersions.ts` 中声明存储版本 **18**、最低支持迁移版本 **1**。
+低于该下限的 Home 不是迁移输入，保持原样不动。目标二进制的
+`upgrade --update-preflight` 与 `--update-apply` 结果形态，以及由父进程持有的
+交接锁证明，对从存储版本 1 起发布的每个 updater 都保持向后兼容，因此一个旧的
+源码 CLI 仍能驱动一个新得多的目标的完整迁移链。

package/docs/task-dag-semantics.md

@@ -0,0 +1,80 @@
+<p align="right"><strong>English</strong> | <a href="./task-dag-semantics.zh-CN.md">简体中文</a></p>
+
+# Task dependencies and WorkItem semantics
+
+## Requirement and execution are separate
+
+A Task is one bounded outcome; a WorkItem is an independently acceptable
+requirement within it. Task type does not dictate execution topology: the Leader
+can work directly or create WorkItems delivered by separate owners. An
+implementation step, a single test, a review finding or a small fix does not
+become a new WorkItem on its own.
+
+The persistent WorkItem status is only `open / accepted / retired`:
+
+- `open`: the requirement is still in progress — not yet executed, executing,
+  awaiting acceptance or needing another attempt.
+- `accepted`: the Leader has explicitly accepted the current delivery.
+- `retired`: the requirement is explicitly retired, with its record and reason
+  preserved.
+
+Execution status belongs to AgentRun, and a Candidate records the result
+currently awaiting acceptance. Submission, rejection or execution failure does
+not turn a WorkItem into a second runtime state machine. Withdrawing acceptance
+is an explicit action.
+
+## One dependency authority
+
+`WorkItem.dependsOn` is the list of direct dependencies within the same Task. A
+prerequisite A → downstream B means B's `dependsOn` contains A. Saving checks
+same-Task references, existence and the acyclic constraint. It does not express
+Provider concurrency, Session occupancy or file locks.
+
+At dispatch, every direct dependency must exist and be `accepted`. An open,
+retired or missing dependency cannot satisfy it, and the error returns the exact
+ID and current status. A successful Run, an existing Candidate, a completed
+Review or an integrated Git change does not substitute for WorkItem acceptance.
+
+A retired WorkItem's replacement field only explains the substitution; it does
+not redirect or rewrite dependencies. The Leader must explicitly revise the
+requirement or its dependencies. The Controller does not release downstream work
+along a replacement chain, cascade cancellation, auto-skip, or turn the
+dependency list into a scheduling plan.
+
+## Editing and recovery
+
+A legal edit to an open WorkItem definition preserves the before/after values and
+keeps its identity and execution evidence. An already-started Run keeps its
+frozen Assignment; editing the current requirement does not retroactively rewrite
+that Run's Context or permissions. Accepted and retired definitions cannot be
+overwritten by an ordinary edit. Owner and resource-scope changes are checked at
+their own boundaries.
+
+On execution failure, the Leader inspects the original result, Session,
+dependencies and workspace, then decides to continue, retry, retire or revise the
+plan. After retirement, a late message keeps its source and non-delivery reason
+and does not auto-reopen. An InputRequest represents an open question; answering
+it does not accept a WorkItem or rewrite dependencies.
+
+## Acceptance, integration and Task completion
+
+Direct and replicated execution share one Leader acceptance boundary. A
+replicated Producer does not form a Candidate; only the explicitly synthesized
+main Run result enters the candidate path. Delivery the Leader manages directly
+must also satisfy the applicable Candidate, ChangeSet and Integration boundaries.
+
+An isolated code result captures a fixed per-Project ChangeSet and integrates via
+compare-and-swap after its checks; an uncaptured, unintegrated or stale latest
+result cannot satisfy delivery. Review is checked against the applicable rule and
+the Task contract. A Task main the Leader delivers itself needs a clean,
+committed, exact snapshot.
+
+The Task lifecycle is `draft / active / completed / cancelled / archived`. A
+Draft plans first and then explicitly adopts a workspace; completed and cancelled
+Tasks do not accept implicit new execution, and a reopen never replays old
+requests; an archived Task cannot reopen. Archive also requires resources to be
+quiescent, clean and removable, and never deletes a workspace merely because of
+the dependency graph or a completion status.
+
+CLI and Web derive their views and suggestions from these facts; they do not
+maintain a second writable DAG, acceptance state or plan.

package/docs/task-dag-semantics.zh-CN.md

@@ -0,0 +1,59 @@
+<p align="right"><a href="./task-dag-semantics.md">English</a> | <strong>简体中文</strong></p>
+
+# Task 依赖与 WorkItem 语义
+
+## 需求与执行分离
+
+Task 是一个有界结果，WorkItem 是其中可独立验收的需求。Task type 不决定
+执行拓扑；Leader 可以直接工作，也可以创建独立负责人交付的 WorkItem。
+实现步骤、一次测试、审查发现或小修补不因此成为新 WorkItem。
+
+WorkItem 持久状态仅为 `open / accepted / retired`：
+
+- `open`：需求仍在处理；可能尚未执行、正在执行、等待验收或需要重试。
+- `accepted`：Leader 已显式接受当前交付。
+- `retired`：需求已显式退役，保留记录和原因。
+
+执行状态归 AgentRun，Candidate 记录当前待接受的结果。提交、拒绝或执行失败
+不把 WorkItem 变成另一套运行状态。接受撤回是显式动作。
+
+## 唯一依赖权威
+
+`WorkItem.dependsOn` 是同一 Task 内的直接依赖列表。前置项 A → 下游 B
+表示 B 的 `dependsOn` 包含 A。保存时检查同 Task 引用、存在性和无环约束。
+它不表达 Provider 并发、Session 占用或文件锁。
+
+派发时，每个直接依赖必须存在且为 `accepted`。Open、retired 或 missing
+均不能满足依赖，错误返回具体 ID 和当前状态。Run 成功、Candidate 存在、
+Review 完成或 Git 已集成都不能代替 WorkItem 接受。
+
+退役的 replacement 字段只解释替代关系，不重定向或重写依赖。
+Leader 必须显式修订需求或依赖；Controller 不沿替换链自动释放下游，
+不级联取消、不自动跳过，也不把依赖列表变成调度计划。
+
+## 修改与恢复
+
+Open WorkItem 的合法定义编辑保存前后值，保留身份和执行证据。已经启动的
+Run 仍使用冻结 Assignment；修改当前需求不追溯改写其 Context 或权限。
+已接受和退役的定义不能借普通编辑覆盖。负责人与资源范围变更受各自边界检查。
+
+执行失败时，Leader 检查原始结果、Session、依赖与工作区，决定续作、重试、
+退役或修改计划。退役后迟到消息保留来源和未投递原因，不自动重开。
+InputRequest 表示待决问题；回答不自动接受 WorkItem 或改写依赖。
+
+## 接受、集成与 Task 完成
+
+Direct 和 replicated 共享一个 Leader 接受边界。Replicated Producer 不形成
+Candidate；只有显式综合的 main Run 结果进入候选路径。Leader 直接管理的
+交付也必须满足适用的 Candidate、ChangeSet 和 Integration 边界。
+
+隔离代码结果按 Project 捕获固定 ChangeSet，检查后 CAS 集成；未捕获、未集成
+或失效的最新结果不能满足交付。Review 依适用规则和 Task 合同检查。
+Leader 自己交付的 Task main 需要干净、已提交的精确快照。
+
+Task lifecycle 是 `draft / active / completed / cancelled / archived`。
+Draft 先规划再显式采用工作区；completed/cancelled 不接收隐式新执行，
+reopen 不重放旧请求；archived 不可重开。Archive 还要求资源静止、干净可移除，
+不因依赖图或完成状态自动删除工作区。
+
+CLI/Web 从这些事实派生展示和建议，不维护第二套可写 DAG、验收状态或计划。

package/docs/task-delivery.md

@@ -0,0 +1,105 @@
+<p align="right"><strong>English</strong> | <a href="./task-delivery.zh-CN.md">简体中文</a></p>
+
+# Task delivery and resource lifecycle
+
+## Lifecycle and planning
+
+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 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.
+
+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.
+
+## 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
+normal cwd is its managed Git root; for multiple Projects, the root and native
+additional-directory mechanism expose the explicit Project set.
+
+An isolated WorkItem has independent worktrees for writable Projects and
+Task-main context for the others. Write scope is explicit and can only be
+expanded by the authorized owner. Review owns a separate frozen workspace and
+cannot become a Develop or Integration source.
+Acceptance or retirement does not release a WorkItem's durable workspace.
+Task-main preparation preserves a Role's retained WorkItem/Review cwd until
+explicit cleanup or reassignment. Decision-support reads observe current Git
+heads without preparing workspaces or migrating Sessions.
+
+Before launch, actual Git lineage must descend from the recorded base. A reset
+outside that lineage is physical drift, not a reason to guess or repair ownership.
+An explicitly adopted environment can select a different native cwd while the
+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
+Review and Integration; Producers do not independently enter either path.
+
+Integration applies the fixed ChangeSet 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.
+
+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.
+
+Review follows the applicable Candidate rule or Task-final contract and frozen
+heads. The exact main Reviewer Run holds the report; successful execution is
+not a semantic pass. Acceptance belongs to the Leader.
+An explicit user requirement to delegate or obtain independent Review remains
+part of acceptance even if the default review policy is disabled. `next-action`
+reports stored facts and alternatives; it cannot weaken the Task Contract or
+infer that unrecorded WorkItems mean direct execution was requested.
+
+## Completion and remote delivery
+
+Completion checks the current WorkItems, latest captured/integrated results,
+applicable Review contract and exact clean committed Task-main snapshot.
+It also refuses completion while a new user/Operator message is still awaiting
+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.
+
+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.
+
+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.
+Archived Tasks cannot reopen.
+
+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

@@ -0,0 +1,82 @@
+<p align="right"><a href="./task-delivery.md">English</a> | <strong>简体中文</strong></p>
+
+# Task 交付与资源生命周期
+
+## 生命周期与规划
+
+Task 生命周期是 `draft / active / completed / cancelled / archived`。Draft 保存
+意图、Project 绑定、规划讨论和可变需求。它在创建时不采用可写的交付工作区。
+
+激活会校验当前 Role、依赖、Project 范围和资源，准备物理工作区，并原子地采用
+状态/所有权。准备失败会让 Task 停在 Draft，附带一个失败请求和投递给 Leader 的
+诊断。延迟激活保留确切意图并等待原生静止，无论它是在规划 Run 中还是在后续讨论中
+被请求的。
+
+Task type 描述被请求的结果，而不是强制的执行者。Leader 直接负责有界工作，或分派
+有独立价值的 WorkItem。直接执行没有 Group。复制是为了在同一个冻结 Assignment 上
+进行独立尝试而被显式请求的，随后由 Leader 选择综合。
+
+## 受管工作区
+
+稳定的 Project checkout 是只读参考。Task main 是一个逻辑上的多 Project 根，带有
+按 Project 划分的 Git worktree。对单个 Project，Agent 的正常 cwd 是其受管 Git 根；
+对多个 Project，根加上原生的附加目录机制暴露明确的 Project 集合。
+
+一个隔离的 WorkItem 为可写 Project 拥有独立 worktree，为其余 Project 提供 Task-main
+上下文。写范围是显式的，且只能由获授权的 owner 扩大。Review 拥有一个单独的冻结
+工作区，不能变成 Develop 或 Integration 来源。验收或退役不释放 WorkItem 的持久
+工作区。Task-main 准备会保留一个 Role 保留的 WorkItem/Review cwd，直到显式清理或
+重新分派。决策支持类读取观察当前 Git head，而不准备工作区或迁移 Session。
+
+启动前，实际 Git 血缘必须由已记录的基线派生而来。落在该血缘之外的 reset 是物理
+漂移，而不是猜测或修复所有权的理由。一个显式采用的环境可以选择不同的原生 cwd，
+而受管工作区仍是 Git/控制所有权记录。
+
+## Candidate、Review 与 Integration
+
+Provider 终态保存确切的原始 Run 结果。它不验收 WorkItem。Leader 评估结果，并为
+隔离代码捕获不可变的、按 Project 划分的 ChangeSet。治理 Candidate 为 Review 和
+Integration 提供来源；Producer 不独立进入这两条路径中的任何一条。
+
+Integration 在候选 worktree 中套用固定 ChangeSet，运行已配置的检查，然后只有在
+目标 head 仍匹配时才推进目标。冲突、检查失败、目标移动或拒绝都保留证据，绝不推进
+目标。Agent 在保留的工作区内选择重试或手动解决。
+
+当检查是一个 DurableJob 时，Integration 在运行期间保留那个确切的 jobId。Job 结算
+后，`task integration continue <task>/<integration>` 消费其结果并执行带守卫的收尾。
+这个直接操作不依赖单独 integration 队列中的条目。
+
+Review 遵循适用的 Candidate 规则或 Task-final 合同以及冻结的 head。确切的 main
+Reviewer Run 持有报告；执行成功不等于语义通过。验收归 Leader。即使默认审查策略
+被关闭，用户明确要求委派或获取独立 Review 仍是验收的一部分。`next-action` 报告已
+存储的事实和备选项；它不能削弱 Task Contract，也不能推断“没有记录 WorkItem”就
+意味着请求了直接执行。
+
+## 完成与远程交付
+
+完成会检查当前的 WorkItem、最新捕获/集成的结果、适用的 Review 合同以及确切的、
+干净且已提交的 Task-main 快照。当有一条新的 user/Operator 消息仍在等待 Leader
+投递时，它也会拒绝完成。当前原生轮次必须结束，待处理的通知才能到达；随后 Leader
+读取原始消息并重新评估完成。这派生自既有的 Message 和 mailbox 投递，而不是第二套
+确认或工作流状态。终态工作区清理在完成时可以只是建议，但在归档时不行。被选作
+结果的 Artifact 必须是固定的、存在的且 Task 局部的。
+
+发布记录一个远程 PR/MR 引用。被报告的合并、独立验证的合并以及确切的 Task-head
+覆盖是彼此独立的事实。Task 完成不证明其中任何一项。远程交付从确切的发布/head
+证据读取，而不从标题或分支名推断。
+
+取消意图不证明运行时已停止。user/Operator 可以重开已取消的 Task；Leader 可以重开
+已完成的 Task。重开需要全新的显式输入/工作选择，绝不重放先前的交付请求。
+
+## 归档
+
+归档是一次单独的授权动作，发生在活动工作已了结、资源干净可移除之后。显式选择
+集成交付或有意放弃。集成归档要求确切的已合并 head 和已验证的发布证据。一次显式
+授权的验证覆盖不能绕过缺失或陈旧的 head，也不能绕过一个未合并的结果。
+
+受管的 WorkItem 资源必须在清理前被集成或有意放弃。Review、Lane 和 Integration
+资源必须已结算。脏 worktree 留给 Agent 解决；不发生隐式 reset 或强制删除。Task
+main 分支和持久 Task 记录保留恢复信息。已归档的 Task 不能重开。
+
+清理前用每个命令的 `--help` 查看它确切的权限和选项；阅读一份生命周期文档不授权
+一次外部写入。

package/docs/task-local-identity.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./task-local-identity.zh-CN.md">简体中文</a></p>
+
 # Task-local identity
 
 Yui treats a Task as the aggregate boundary for durable workflow records. Each
@@ -5,7 +7,7 @@ Task owns an independent, monotonically increasing sequence for every record
 family:
 
 - WorkItem
-- Turn
+- AgentRun
 - ReviewRound
 - ChangeSet
 - IntegrationAttempt
@@ -18,11 +20,11 @@ family:
 The first record of each family in each Task is therefore local `-1`. Deleted,
 cancelled, completed, reopened, and archived records never lower the persisted
 high-water mark, so a local ID is never reused inside its Task. Each allocation
-advances that aggregate high-water mark under the storage process lock.
+advances that aggregate high-water mark inside the Store transaction.
 
 Candidate identity is narrower: `candidate-N` is a WorkItem-local sequence.
 Every Candidate stores its `taskId` and `workItemId`, in addition to the source
-Turn when one exists.
+AgentRun when one exists.
 
 ## Reference contract
 
@@ -37,13 +39,13 @@ JSON, mailbox, Controller, Hook, receipt, Web, and error paths retain the Task
 scope. Context-free commands reject a bare local ID instead of searching all
 Tasks, even if that ID currently happens to be unique.
 
-A managed Task session may use `work-item-1` or `turn-1` because its
+A managed Task session may use `work-item-1` or `run-1` because its
 `YUI_TASK_ID` is explicit. A command that already receives the Task as another
 argument may also use a subordinate local ID. Outside those two cases, use the
 qualified form. Delivery receipts use the same provenance, for example:
 
 ```text
-turn:task-7/turn-1
+run:task-7/run-1
 input-request:task-7/input-1
 ```
 
@@ -58,5 +60,5 @@ boundary and the migration phase of `yui update`; every valid Home at or above
 the CLI's minimum supported storage version can advance directly to current.
 
 This boundary keeps Task-local references, Role desired configuration, and
-immutable Turn/RoleSession effective snapshots under one unambiguous runtime
+immutable AgentRun/RoleSession effective snapshots under one unambiguous runtime
 contract while the append-only migration chain preserves supported history.