@zq-silk/yui 0.15.8 → 0.15.9

package/docs/release-workflow.zh-CN.md

@@ -0,0 +1,237 @@
+<p align="right"><a href="./release-workflow.md">English</a> | <strong>简体中文</strong></p>
+
+# 获授权的发布操作
+
+发布工作流是一段被显式选择、获授权的外部发布效果序列——pull request、CI 确认、
+合并、版本 tag、npm 发布、全新安装冒烟、CLI 更新、Controller 替换、Project 迁移和
+后置验证。它是一个专用的外部效果设施，而不是 Yui 的 Task 规划或 Agent 执行模型。
+Agent 选择一个预先声明的计划，设施从持久状态驱动该计划：每次转换都在下一次外部调用
+之前持久化，因此崩溃、超时或被撤销的 grant 都不会让发布陷入猜测。
+
+两个 Task 级记录族支撑它：
+
+- **CapabilityGrant**（`capability-grant-N`）——权威。一个具名的授权者把 grant
+  限定到若干动作、参数边界、一个过期时间、一个使用次数和一个不可逆上限。
+- **ReleaseWorkflow**（`release-workflow-N`）——计划及其进展：一个确切来源（仓库 +
+  钉住的 commit，可选一个 artifact）、一份不可变的有序步骤计划，以及每步一条持久记录。
+
+引擎（`src/release/releaseWorkflowEngine.ts`）是一个纯库；`yui task workflow` 和
+`yui task grant` 命令驱动它。每个外部系统都位于 `ReleaseWorkflowPorts`
+（`src/release/releaseWorkflowPorts.ts`）之后，因此整个工作流可以用确定性的 fake
+测试，不产生任何真实的 GitHub、npm、git、Controller 或进程副作用。
+
+## 授权模型
+
+每一次（再）提交一个步骤，都在外部调用**之前**通过 `checkGrant(grant, request, now)`
+（`src/grant/capabilityGrant.ts`）。步骤 kind 就是 grant 动作：一个 grant 列出它授权的
+步骤 kind，例如 `--action npm-publish --action version-tag`。该判定是 fail-closed
+的——每个拒绝都带一个机器可读原因并停止这次运行：
+
+| 原因 | 含义 |
+| --- | --- |
+| `grant-missing` | 没有 grant 记录绑定到该工作流（引擎级）。 |
+| `grant-revoked` | 该 grant 已被 operator 撤销。 |
+| `grant-expired` | 墙钟已过该 grant 的 `expiresAt`。 |
+| `grant-uses-exhausted` | 该 grant 的 `maxUses` 已被消耗。 |
+| `grant-action-not-allowed` | 步骤 kind 不在该 grant 的动作中。 |
+| `grant-parameter-missing` | 步骤缺少一个受约束参数。 |
+| `grant-parameter-value-not-allowed` | 一个受约束参数的取值越界。 |
+| `grant-irreversibility-exceeds-ceiling` | 该步骤比 grant 的上限更不可逆。 |
+
+附加规则：
+
+- **每次获授权提交消耗一次。** 引擎在成功判定与外部调用之间记录一次 grant 使用，
+  因此一个 `maxUses` grant 会在那次将要超额的尝试上 fail closed。
+- **不可逆步骤需要一个已确认的前缀。** 一个标记为 `irreversible` 的步骤额外要求此前
+  每个步骤都是 `succeeded`；否则该步骤以 `prerequisite-not-confirmed` 失败并停止运行。
+  这正是让 `npm-publish` 不会跟在一个失败的 PR 之后运行的机制。
+- **拒绝会被记录。** 当一个待处理步骤被拒绝时，引擎会启动并把该步骤失败，日志里带上
+  这次拒绝，因此 `workflow status` 能准确显示授权在哪里停下。
+- **重新绑定。** 一个被撤销、过期或过窄的 grant 不会让工作流走进死胡同。签发一个新
+  grant 并用 `yui task workflow resume <task> <workflow> --grant <new-grant>` 恢复；
+  跨越这次重新绑定，计划、来源和所有已确认的步骤证据都不可变。
+
+## 稳定的 Task-final Review 合同
+
+兼容的 CLI 包更新和 Controller 替换不改变一个活动 Task 的 final-review 能力。受管
+Session 使用普通的 `yui` 命令，兼容性由协议和存储身份检查，一个替换 Leader 呈现由
+持久 Task 证据已确立的合同。不需要任何版本感知的 Operator 动作。Candidate 和
+Task-final 的 ReviewRound 记录必须全部携带那唯一的合同。冲突的记录 fail closed；
+不存在重新绑定事件、恢复命令或第二套合同状态机。
+
+## CLI 与 Controller 发布边界
+
+全局 `yui` 命令是稳定的用户与受管 Session 接口。对普通命令，它不跟随
+`runtime/active-release.json`：那个指针选择的是 Controller 发布，而不是 CLI 包。这让
+CLI、Operator Session 和 Controller 替换保持兼容，而不必把每个命令钉在一个不可变构建上。
+
+一个源码 checkout 或以其他方式未经验证的本地 CLI 不是这个已发布接口。当 `YUI_HOME`
+已经命名了一个活动发布时，这样的 CLI 会在打开存储之前失败，并报告它的构建/来源、
+持久的 Home 身份以及它的调用类别。`make install-local` 仍默认使用 checkout 隔离的
+`output/dev/home`；把那个 launcher 显式指向一个发布拥有的 Home 会被拒绝。
+
+一个显式的 `yui release activate <release-id|build-id>` 是唯一的例外。全局 CLI 校验
+已安装的目标发布及其匹配的冒烟回执，然后把未改动的激活参数委派给那个目标的
+`dist/cli.js`。因此目标发布拥有完整的交接协议和超时层级。一次无目标的激活、help、
+`--json` 以及其他每个命令都留在全局 CLI 上。激活不新增另一条普通 CLI 路由路径。
+
+## 步骤目录
+
+计划是一个固定、预先声明的操作子集。每个计划条目有一个 id（工作流内唯一）、一个
+kind、可选 params，以及一个可选的不可逆级别（`none` | `reversible` | `irreversible`）。
+
+| Kind | 外部效果 | 权威身份 |
+| --- | --- | --- |
+| `pr-create-or-reuse` | 创建发布 PR，或复用一个针对该 head 的开放 PR。 | `pull-request` 号 |
+| `ci-confirm` | 读取该来源 ref 的 CI 结论；仅在 `success` 时成功。 | — |
+| `merge` | 合并具名 PR（默认 squash）。 | — |
+| `version-tag` | 创建并推送带注释的版本 tag。 | `git-tag` 名 |
+| `npm-publish` | 把 tarball 发布到 registry。 | `npm-package` 版本 |
+| `fresh-install-smoke` | 从 registry 安装并运行已发布的包。 | — |
+| `cli-update` | 通过既有更新编排器更新 Yui CLI/Controller home。 | `controller-home` |
+| `controller-replace` | 停止并重启 file-task Controller。 | — |
+| `project-migrate` | 通过既有的 project 命令运行 Project 迁移。 | — |
+| `post-verify` | 运行一个任意的验证命令。 | — |
+
+步骤可以引用更早的证据：一个 param 值为 `$externalId:<step-id>` 时，会在运行时解析为
+被引用步骤已确认的 external id，因此一个 `merge` 步骤可以消费 `pr` 步骤产生的 PR 号，
+而 operator 事先并不需要知道它。对一个未确认步骤的引用会让运行失败，而不是猜测。
+
+## 恢复与 resume 语义
+
+一次运行总是从 **resume 游标**开始：第一个状态非终态（`succeeded` 或 `skipped`）的
+计划步骤。没有“从头再来”——已确认的步骤绝不重跑。
+
+因为每次状态转换都在下一次外部调用之前持久化，所以任意一点的进程退出都是可恢复的：
+重新调用 `run`（或 `resume`），引擎就从第一个未确认步骤继续。`--max-steps <n>` 限定
+单次运行；一次在工作流中途耗尽预算的运行返回 `budget-exhausted`，下一次调用继续。
+
+在途步骤通过**权威身份查询**解决，绝不盲目重新提交：
+
+- 一个留在 `running` 或 `unknown` 的步骤，先按其记录的 `externalIdentity` 查询。
+  - `exists` → 该步骤到达 `succeeded`，且**没有第二次提交**（`unknown` 被确认，
+    `running` 被完成）。
+  - `unknown` → 运行以结果 `unknown` 停止；在其命运不可知期间，该步骤绝不被重新提交。
+  - `absent` → 效果从未落地，因此该步骤被重试（一个 `running` 步骤会记录这次恢复尝试）。
+- 一个**没有** external identity 的 `running` 步骤在记录提交结果之前就崩溃了。一个
+  不可逆步骤无论如何都通过端口查询（适配器咨询其持久幂等存储）:`exists` 不经第二次
+  提交确认该步骤，`unknown` 以 `unconfirmed` 停止，只有权威的 `absent` 才恰好重试该
+  步骤一次。一个可逆步骤总是落到重试，并沿用同一个幂等键。
+- 一次**没有** external identity 的超时把该步骤标记为 `unknown`（unconfirmed），因此
+  它绝不被盲目重新提交；在 resume 时它以 `unconfirmed` fail closed。
+- 一个 `failed` 步骤在下一次运行时被重试；它的 `attempts` 计数和日志按尝试增长。
+
+运行结果：`succeeded`、`failed`、`unknown`、`unauthorized`、`unconfirmed`、
+`budget-exhausted`。每个都带一个机器可读的 `stopReason`（例如 `unknown:publish`、
+`unauthorized:grant-revoked`、`budget-exhausted:verify`）以及该次运行尝试过的步骤 id
+列表。
+
+## 幂等键合同
+
+每个步骤的幂等键在**创建时预先声明**且永不改变：
+
+```text
+<taskId>/<workflowId>/<stepId>
+```
+
+该键被传给该步骤的每一次 `executeStep` 调用，包括在一次确认为 absent 的超时之后的
+重试。端口合同要求 `executeStep` 在同一键下是幂等的：一次重试尝试不得产生第二次
+副作用。引擎侧的合同更严格——它绝不为一个已标记 `unknown` 的步骤调用 `executeStep`,
+而是按记录的身份重新查询。fake 记录每一个键，因此测试套件直接证明至多一次执行。
+
+## Operator 指南
+
+Session 权威依据当前持久绑定检查。Telemetry 按 Role/AgentRun 分组，进程 owner 使用
+PID/start 身份。存储变更遵循[唯一的显式升级边界](sqlite-control-plane-design.zh-CN.md);
+普通命令绝不改写 Home schema。
+
+grant 的签发与撤销是不可逆权威操作。它们需要当前已登记的全局 Operator 对话。它的
+原生 session ID 必须与持久的活动 session 绑定匹配：Codex 命令在存在时使用
+`CODEX_THREAD_ID`，否则使用 `YUI_NATIVE_SESSION_ID`;Claude 使用 `YUI_NATIVE_SESSION_ID`。
+Host generation 和启动时的 Agent 标签不是调用者身份。通过另一个入口恢复同一段对话
+不撤销其权威。一个未登记、被替换或已结束的对话没有这种权威。一个受管的 Task Agent
+不能自签发或自撤销 grant，清空子进程环境也不赋予用户权威。被记录的授权者/撤销者
+绑定到那个 Operator session（`operator:<agent-id>`）；不存在可伪造的 `--granter`/`--by`
+标签。
+
+```sh
+# 1. Operator session 为发布链签发权威。
+yui task grant issue task-15 \
+  --action pr-create-or-reuse --action npm-publish --action post-verify \
+  --irreversibility-ceiling irreversible
+
+# 2. 针对确切来源和预先声明的计划创建工作流。
+#    npm-publish 步骤需要一个内容寻址的来源 artifact：不可变的工作流来源以后
+#    永远无法再获得它，因此没有 --source-artifact 的计划在创建时即被拒绝。
+yui task workflow create task-15 \
+  --grant capability-grant-1 \
+  --source-repo acme/widget --source-commit abc1234deadbeef0000000000000000000000000 \
+  --source-artifact widget-1.0.0.tgz@sha512-<base64-integrity> \
+  --step pr:pr-create-or-reuse \
+  --step publish:npm-publish --step-irreversibility publish=irreversible \
+  --step-param publish:tarball=./dist/widget-1.0.0.tgz \
+  --step verify:post-verify --step-param verify:command='yui --version'
+
+# 3. 运行（或 resume）并检查。
+yui task workflow run    task-15 release-workflow-1
+yui task workflow resume task-15 release-workflow-1 [--grant capability-grant-2] [--max-steps 1]
+yui task workflow status task-15 release-workflow-1
+
+# 4. 随时撤销权威；下一个步骤以 unauthorized 停止。
+yui task grant revoke task-15 capability-grant-1
+```
+
+`workflow status` 渲染每个步骤的状态、尝试次数和已确认的 external id，因此 operator
+能准确看到一次发布在哪里停下以及为什么。
+
+## 真实资源边界
+
+真实执行只通过 `yui` CLI 发生，它接上真实适配器（`createReleaseWorkflowPorts`）。该
+适配器是既有原子操作——`gh`、`npm`、`git`、CLI 更新编排器、Controller stop/restart 和
+`project migrate`——之上的一层薄壳，并且只在一个人类授权者签发了对每个步骤都通过
+`checkGrant` 的显式 CapabilityGrant 时才运行。一个本地测试请求绝不替代那份权威。
+
+由 tag 触发的 `publish.yml` 工作流是唯一维护的发布冒烟。它复用那个通过了 core CI 的
+确切 commit，只增加发布所需的产物装配、全新安装和 provenance 检查。
+
+该工作流通过 npm Trusted Publishing（OIDC）认证，因此发布身份存在于 tag 之外的两处：
+`repository`、`bugs` 和 `homepage` 由 `assemble-runtime-package.mjs` 从源 `package.json`
+逐字复制进已发布 manifest，而该包的 npm Trusted Publisher 条目点明 GitHub owner、
+仓库、工作流文件和环境。npm 在接受 provenance 之前会区分大小写地将 `repository.url`
+与正在构建的仓库比较。因此重命名或转移 GitHub 仓库时，必须连同重命名一起更新这些 URL
+和 npm Trusted Publisher 条目；否则下一个 tag 会走到 `npm publish` 并在那里失败——此时
+tag 和已过门的构建都已成功。
+
+## 适配器安全加固
+
+真实适配器（`createReleaseWorkflowPorts`）在引擎的 grant 检查之外再施加额外防护：
+
+- **Tarball 选项注入。** 一个看起来像选项的 tarball 路径（以 `-` 开头）在任何子进程
+  ——`tar -xOf` manifest 检视和 `npm publish`——看到它之前就被拒绝，因此一个精心构造的
+  路径永远不会被当作 flag 解释。
+- **Tarball TOCTOU。** 在校验冻结的 `source.artifact.integrity` 之后，被校验的字节被
+  快照到一个工作流私有、只读的临时文件。`tar -xOf` manifest 检视和 `npm publish` 都
+  读取该快照，而不是活的 tarball 路径，因此校验之后对原文件的替换不能改变所发布的内容。
+  步骤完成时移除该快照。
+- **钉住的外部命令。** 适配器在构造时通过 `resolveExecutable` 把它 shell 调用的外部
+  命令（`gh`、`git`、`npm`、`tar`、`sh`）解析为绝对路径，只走一次调用者的 `PATH`。每次
+  子进程调用都使用解析后的路径，因此之后的 `PATH` 变化（或被操纵的工作目录）不能把一次
+  发布效果重定向到另一个二进制。一个无法解析的命令返回一个合成失败（exit 127），不调用
+  任何二进制。
+- **钉住的 cli-update 激活目标。** 在不可逆的更新效果之前，适配器把确切的激活目标——
+  Home 加上全局 npm 前缀（`bin/yui`）——持久化到 Home 下的一个持久文件
+  （`release/cli-update-identity/<idempotency-key>.json`）。一次硬退出的恢复查询（一个
+  没有记录身份的步骤）读取这个文件并调用那个钉住的目标；如果该文件不存在（进程在预效果
+  持久化之前退出），查询返回 `unknown`，而不是从 resume 调用者的 `npm prefix --global`
+  或 `PATH` 推导目标，因此 resume 环境中的另一个安装不能替这个步骤背书。
+- **Controller 生命周期校验。** 一次 `cli-update` 恢复查询会证明替换后的 Controller
+  确实拥有目标 Home：它运行 `yui --json controller status`（`YUI_HOME` 钉在记录的 Home
+  上），并要求一个 `current` controller 资源，其 `yuiHome` 解析到那个 Home，然后运行
+  `yui --json controller identity`，并要求已认证的 Controller 身份与已激活的产物匹配：
+  Node.js 可执行路径、由钉住的全局二进制派生的确切 Controller 入口点，以及包版本。仅有
+  二进制健康（doctor、`--version`）绝不确认这次交接，任何不可证明的状态都返回 `unknown`。
+  这适用于带身份的查询和硬退出查询（一个没有记录身份的步骤）两者。
+- **npm integrity 比较。** 一次 `npm-publish` 恢复查询不止步于已发布版本：它通过
+  `npm view <pkg>@<version> dist.integrity` 取 `dist.integrity`，并与冻结的
+  `source.artifact.integrity` 逐字节比较。匹配则确认该步骤；同一版本但字节不同是一个
+  冲突，返回 `unknown`（绝不确认，绝不重新发布）；一个缺失的版本是 `absent`。

package/docs/roles-and-configuration.md

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./roles-and-configuration.zh-CN.md">简体中文</a></p>
+
 # Roles, Profiles and execution configuration
 
 ## Responsibilities

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

@@ -1,3 +1,5 @@
+<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

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

@@ -1,57 +1,80 @@
-# 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、验收状态或计划。
+<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

@@ -1,3 +1,5 @@
+<p align="right"><strong>English</strong> | <a href="./task-delivery.zh-CN.md">简体中文</a></p>
+
 # Task delivery and resource lifecycle
 
 ## Lifecycle and planning