@xgent-ai/skills 0.7.8 → 0.7.9

package/docs/phoenix-diagram.md

@@ -2,7 +2,9 @@
 
 Phoenix Diagram 0.2.0 提供 architecture、workflow、sequence、dataflow、lifecycle、erd、class、tree、timeline、waterfall 十类的原生生成、独立 HTML 阅读与导出，可对固定提交核对仓库来源，阅读器界面支持 en、zh-CN、zh-TW、es、ko。新稿声明 `meta.input_contract: "phoenix-v1"`；原五类未标记的旧 JSON 按 `legacy-2.17` 解释，新五类只有 `phoenix-v1`，原 JSON/HTML 不被迁移。仓库以 phoenix-diagram 为唯一活跃图解入口；其他项目及个人旧安装须分别处理。数值图表、仪表盘及其他 infographic 不在范围内。
 
-`@xgent-ai/skills@0.7.6` 已公开发布，配套四平台引擎已托管，最终 npm 包已通过 Node 18 与维护 Node 的联合安装验证。P3 的完整交接（含真实 provider 会话和视觉审核）仍未完成。candidate 的 loopback 下载地址仅用于隔离验收，不能直接作为公开 npm/R2 发行资源。
+`@xgent-ai/skills@0.7.8` 已公开发布，配套四平台引擎已托管，最终 npm 包已通过 Node 18 与维护 Node 的联合安装验证。P3 的完整交接（含真实 provider 会话和视觉审核）仍未完成。candidate 的 loopback 下载地址仅用于隔离验收，不能直接作为公开 npm/R2 发行资源。
+
+UI 与 Diagram 共用 [Phoenix CI](../.github/workflows/phoenix.yml)：同一次运行完成两个工具的检查，发布仍使用同一个 `@xgent-ai/skills` npm 包。
 
 ## npm 发布安装
 
@@ -14,13 +16,13 @@ npm 发布包与仓库的 `xgent-skills install` 默认同时安装 Phoenix UI
 
 ```sh
 node "$PACKAGE_DIR/bin/xgent-skills.js" install "$PROJECT" \
-  --no-phoenix-ui --no-xgent-init --providers=claude,codex \
+  --no-phoenix-ui --providers=claude,codex \
   --diagram-release-dir="$RELEASE_DIR"
 ```
 
 这里跳过 UI 是候选消费范围：包内 UI 原资源保持原样，不能把它当作 diagram 四平台发行的证据。总安装器默认启用两个 Phoenix 工具；不支持 diagram 的平台默认跳过 diagram 并说明，显式指定 `--diagram-release-dir` 时仍在写项目前失败。`--release-dir` 只控制 UI，`--diagram-release-dir` 只控制 diagram，`--no-phoenix-diagram` 跳过且保留已有 diagram 安装。所有选项、XGENT、UI、diagram 预检均先于项目写入。执行顺序为 XGENT → UI → diagram；后段失败会报告前段已完成项，不回滚另一个工具。
 
-默认按项目已有 provider 目录选择，空项目用 `.claude`。`codex` 识别 `.agents` 或 `.codex`，diagram skill 仅进入 `$PROJECT/.agents/skills/phoenix-diagram`；本工具不新增 hooks、settings、AGENTS 或个人级 skill。新开 Claude Code/Codex 项目会话后核对实际加载的 skill 路径。安装状态位于 `$PROJECT/.phoenix-diagram/install/`，请按输出提示在本地忽略；不要删除整个目录作为恢复手段。
+默认按项目已有 provider 目录选择，空项目用 `.claude`。`codex` 识别 `.agents` 或 `.codex`，diagram skill 仅进入 `$PROJECT/.agents/skills/phoenix-diagram`；本工具不新增 hooks、settings、AGENTS 或个人级 skill。新开 Claude Code/Codex 项目会话后核对实际加载的 skill 路径。安装直接覆盖工具文件，不产生安装历史目录；成功后清理旧 `$PROJECT/.phoenix-diagram/install/`，保留图表输出等项目数据。
 
 引擎按 VERSION 的大小、SHA-256 与 probe 校验，缓存位于 `~/.phoenix-diagram/bin/<toolVersion>/<platform>/<engineSha256>/phoenix-diagram`；`PHOENIX_DIAGRAM_HOME` 可隔离缓存。普通命令不联网补装。缺引擎时只在用户明确请求安装后执行回执的 `setupCommand`（doctor 的 `recovery.engineInstall` 使用同一指引）。candidate/development 指向当前本地包或已安装 skill 的入口，不按同名版本去 registry 取另一个包；将命令中的 `MATCHING_RELEASE_DIR` 替换为该候选配套完整 release-dir 的实际绝对路径。用户或已提供材料尚未明确给出该路径时，先询问并停止安装，等待答复；安装授权不代替资源路径，不搜索项目外目录、猜路径、省略 `--release-dir` 试装或执行占位符。该目录按当前 VERSION/ENGINE 的原字节、引擎摘要和许可校验；遗失候选包或配套目录时须重新取得同一 tgz 和资源。只有 distribution=release 才输出 `npm exec --package=@xgent-ai/skills@<固定版本>`。candidate/release 离线目录必须含四平台；development 只校验清单声明的全部平台资源，单平台开发制品不计四平台验收。目录缺少声明的资源、清单或许可证时直接失败，不回退在线下载。
 
@@ -28,9 +30,9 @@ node "$PACKAGE_DIR/bin/xgent-skills.js" install "$PROJECT" \
 
 普通安装保留旧 Archify。只有明确请求迁移时，按[包内迁移合同](../skills/phoenix-diagram/references/migration.md)先 dry-run 查看精确项目/provider/来源及逐项路径，再以覆盖该范围的明确确认执行 `migrate --from-archify --confirm-remove-archify`。仅完整匹配固定来源的项目副本可移除；自定义、额外/缺失文件、链接、外部管理与个人安装保留。旧 skill 不备份，回滚不重建，恢复旧入口须按回执指引显式重装；原 JSON 和已有 HTML 保持。
 
-联合入口为 `node "$PACKAGE_DIR/bin/xgent-skills.js" install "$PROJECT" --migrate-archify --diagram-release-dir="$RELEASE_DIR"`，使用已存在的匹配引擎，先展示目标和后果。TTY 肯定答复后才移除；拒绝/EOF 不迁移。非交互须另加 `--confirm-remove-archify`；单独确认标志无效。此分支跳过 XGENT hooks/settings/AGENTS 和 UI，`--no-phoenix-diagram` 仍跳过并保留，普通联合安装继续原流程。
+联合入口为 `node "$PACKAGE_DIR/bin/xgent-skills.js" install "$PROJECT" --migrate-archify --diagram-release-dir="$RELEASE_DIR"`，使用已存在的匹配引擎，先展示目标和后果。TTY 肯定答复后才移除；拒绝/EOF 不迁移。非交互须另加 `--confirm-remove-archify`；单独确认标志无效。此分支跳过 XGENT hooks/settings 和 UI，`--no-phoenix-diagram` 仍跳过并保留，普通联合安装继续原流程。
 
-中断后读取真实 `transactionId`、已删/剩余旧项与 `recoveryCommand`，只恢复指定事务。`rollbackCommand` 仅逆向恢复当前 committed 事务的 Diagram 受管写入，支持 v1/v2；预检发现后来修改先保持零变更，同一 ID 幂等，不跨过后来安装。恢复旧 Diagram active 时原生重新绑定实际文件身份，不手工复制回执。若部分回滚已恢复旧 launcher，优先原样执行回执给出的已验证新原生引擎命令，不从 PATH 选择旧引擎。普通命令仍核 active，恢复入口不要求损坏/pending active 先完整提交；不自动下载或重装。
+中断后读取真实 `transactionId`、已删/剩余旧项与 `recoveryCommand`，只恢复指定事务。`rollbackCommand` 仅逆向恢复当前 committed 事务的 Diagram 受管写入，支持 v1/v2；预检发现后来修改先保持零变更，同一 ID 幂等，不跨过后来安装。恢复旧 Diagram active 时原生重新绑定实际文件身份，不手工复制回执。若部分回滚已恢复旧 launcher，优先原样执行回执给出的已验证新原生引擎命令，不从 PATH 选择旧引擎。迁移恢复入口不要求损坏/pending active 先完整提交；不自动下载或重装。普通工具启动不依赖迁移回执。
 
 回执的 `legacyBackupPolicy: "none"`、`legacyRestoration: "not-supported"` 与 `reinstallInstructions` 必须交接；`backup` 只指 Diagram 受管文件。重开 provider 会话核实际加载的新 skill 路径，未处理的外部/个人入口不计全机唯一入口已生效。迁移成功也不代表图像已重新验收。
 
@@ -138,7 +140,7 @@ ls -la "<原输出父目录>"
 | invalid | 参数或不支持的记录格式，读取 diagnostics | 2 |
 | failed | I/O 或运行失败，读取 diagnostics | 4 |
 
-返回的 `target` 只在可信记录核验后提供。文件恢复不生成 delivery/browser/visual 通过回执，后续交付仍需适用检查。项目安装中断则重跑原显式 install，让 Rust 在日志与 after 身份仍匹配时恢复；candidate/development 安装回执的 `recoveryCommand` 使用本次已验证的原生引擎与 bundle，不从 registry 另取同名包。引擎缓存也已遗失时先按上文恢复匹配引擎。用户后来修改不会被 before 备份盲覆盖。
+返回的 `target` 只在可信记录核验后提供。文件恢复不生成 delivery/browser/visual 通过回执，后续交付仍需适用检查。项目安装中断时重跑 install 即可：安装直接覆盖工具文件，不保留旧版本、备份或事务日志。成功安装会清理旧 `.phoenix-diagram/install/`，保留图表输出等项目数据。普通启动只校验固定的 ENGINE 清单及引擎摘要，不依赖安装回执。
 
 ## 阅读与导出
 

package/{skills/review-ui/references/phoenix-review.md → docs/phoenix-ui-review.md}

@@ -1,21 +1,16 @@
 # Phoenix managed 评审协议
 
-仅在识别或接入 Phoenix managed 循环时读取。纯 Markdown 循环继续按技能正文和四份合同人工执行；本参考不新增评分或处置规则。规则投影的唯一事实源为 [rules.v1.json](rules.v1.json)，绑定 [报告](report-contract.md)、[独立评审](judge.md)、[目标与采集](target-and-capture.md) 和 [修复记录](../../apply-ui-review/references/record-contract.md) 合同。
+仅在明确使用 Phoenix CLI 管理评审记录时读取。本协议描述工具接口，不定义独立的 review-ui / apply-ui-review 工作流；工具不可用不阻止 agent 依据目标、真实证据和 Markdown 历史继续评审或修复。工具的计分与裁定测试数据位于 [rules.json](../tools/phoenix-ui/crates/review/tests/fixtures/rules.json)，不绑定 skill 文档指纹或规则版本。
 
-## 先发现身份与能力
+## 先发现可用能力
 
-1. 从本循环的安装回执或固定版本包清单读取期望的 package/runtime/review schema；不能拿 PATH 中任意同名命令、上游 `impeccable` 或旧 CLI 当成匹配 engine。
-2. 用实际 `phoenix-ui engine-probe` 核对身份，再执行 `phoenix-ui review --help` 与 `phoenix-ui review schema --json`；可用 `--kind <kind>` 只取该操作的输入形状。核对返回的 `reviewSchema` 与所需类型、变体后才构造机器输入。发现结果是当前 serde 类型校验的完整样例与枚举变体，`format: typed-examples`，不是完整 JSON Schema。样例不是证据：其中 `EXAMPLE_ONLY` 文本、数字和布尔值均须换成实际操作或取证值；cycle、round、cell、packet、revision 取实际返回，hash、被测版本和取证声明取真实材料。帮助/查询不读写循环，退出 0 只证明发现查询成功；入口不存在、身份/版本或协议不匹配时保持只读，不猜字段。
-3. 读已有索引与 `review status`，确认前缀、当前轮、baseline、revision、状态和原记录位置。未来 schema、损坏或不能识别的索引不能按「无索引」处理。
-4. 已有 managed 索引而 engine 缺失或不匹配：只读历史，可采集未登记素材；不计分、不裁定、不改代码、目标、处置、计数或生成区。给出按实际固定包版本恢复 engine 的命令，例如 `npm exec --package=@xgent-ai/skills@<packageVersion> -- phoenix-ui engine install --project <项目路径>`，替换为回执中的真实值并正确引用路径；没有期望版本时先说明所缺的回执，不能填一个猜测版本。恢复后续接原轮次，不重置、不静默降级、不自动下载或升级。
+1. 查询实际可用的 `phoenix-ui review --help` 与 `phoenix-ui review schema --json`，按返回的能力和输入形状构造调用，不把某个包版本或 engine 身份作为 agent 工作流的前置条件。typed examples 是占位样例，必须替换成真实材料。
+2. 若使用工具续接记录，读原索引和 `review status`，沿用实际 round、revision 与历史。无法识别或写入工具状态时保留原文件，继续以 Markdown 记录真实证据、评审和修复结果，不猜字段、不清空历史。
+3. 工具恢复可用后，核对已有记录和期间新增材料，再按实际支持的接口登记；不能把未登记的材料声称为已同步。已有人工历史只经显式 import 接管，全新无历史且已选择工具管理时才 begin。
 
-循环索引的实际路径是 `<前缀>.ui-review.json`；当前识别口径为 `schemaVersion: 1`、`mode: managed`。缺 CLI 时直接读原文件识别既有状态；字段缺失、未知 schema 或损坏时保持只读，不能视作不存在。固定包清单声明的 `reviewSchema` 与 engine 身份都须核对；仅收到文本身份 probe 不能推断支持 review verbs。
+## CLI 操作与调用时机
 
-没有索引时还要检查旧 Markdown 轮次和修复历史：已有人工历史就继续人工或显式 import，不能 begin 清零。全新无旧历史且用户已要求验收时，匹配 engine 与实际 verbs 后可 begin managed；能力不可用则按人工流程。不能把「无索引」等同「永远人工」，也不能把旧历史自动接管。
-
-## 固定 verbs 与调用时机
-
-以下是操作形状，不是可直接写入的 JSON schema。路径、round、revision 和输入字段取自本项目的真实材料及匹配 engine 返回；工作流操作和 schema 查询带 `--json`，帮助也可用 `--json`。执行时保存实际 argv、输入、输出与退出码。
+以下是操作形状，不是可直接写入的 JSON schema。路径、round、revision 和输入字段取自本项目的真实材料及实际 CLI 返回；工作流操作和 schema 查询带 `--json`，帮助也可用 `--json`。执行时保存实际 argv、输入、输出与退出码。
 
 | 操作 | 参数 | 用途与边界 |
 | --- | --- | --- |

package/docs/phoenix-ui.md

@@ -1,4 +1,4 @@
-# XGENT Phoenix UI：安装、迁移与回滚
+# XGENT Phoenix UI：安装与使用
 
 Phoenix UI 是 XGENT 自主维护的设计工具，承接 [impeccable](https://github.com/pbakaus/impeccable) skill 4.5.0 / engine 0.1.11 的固定源码（Apache-2.0）。版本、规则、构建和发布都由本仓控制：不查询上游 latest，不从上游或 impeccable.style 下载任何东西。来源、修改标识与三方许可见包内 `dist/phoenix-ui/NOTICE.md`、`THIRD-PARTY-NOTICES.md`。
 
@@ -14,9 +14,9 @@ npx @xgent-ai/skills install
 一次安装分两段，先完成全部只读预检再写项目：
 
 1. **预检**：校验参数、`.claude/settings.json` 与 guard 配置；把包内 `dist/phoenix-ui/VERSION.json` 固定的 engine 下载或从 `--release-dir` 读取，按大小、SHA-256 和 `engine-probe` 身份核对后放进用户 cache；再以 dry-run 计算 Phoenix 的写入和合并。仅由待重装工具目录引起的冲突在清理后重新计算，其余预检失败不写项目。
-2. **写入**：按下节的选择删除待替换工具；再写 XGENT 部分（statusline hook、settings、可选 guard 与 AGENTS.md），最后由 Rust 安装执行器在项目锁内重读这些文件，事务化写入 Phoenix 的 skill、agents、hooks 和安装回执 `.phoenix-ui/install/active.json`。清理的旧工具不备份、不参与回滚；清理后被打断时重跑安装。Phoenix 写入中途失败（如磁盘已满）时状态为「待恢复」，可能已部分写入；重跑同一命令会先按日志回滚或补完上次事务再安装。
+2. **写入**：按下节的选择删除待替换工具，写入 XGENT 部分，随后直接覆盖 Phoenix UI 的 skill、agents 和启动文件。共享配置只替换 Phoenix hook，保留其他 handler 和配置。安装不创建回执、事务日志或旧版本备份；成功后删除旧 `.phoenix-ui/install/` 和 `.phoenix-ui/migrations/`，保留配置和业务数据。中断后重跑同一命令覆盖安装。
 
-安装输出逐项列出写入、合并与移除，状态为「已安装 / 未变 / 冲突,未激活 / 待恢复 / 已安装但融合未就绪」之一，并给出事务 ID、备份位置、完整回滚命令和各工具的重载步骤。只有状态为「已安装」或「未变」时才打印「完成」；冲突与融合未就绪以退出码 3 结束，engine 或文件环境失败以 4 结束，参数错误为 1（XGENT 部分）或 2（Phoenix 执行器）。
+安装输出列出写入、合并与移除及重载步骤；相同内容重复安装显示「未变」。预检失败不写项目，写入失败显示未完成并提示处理错误后重跑。
 
 | 选项 | 作用 |
 | --- | --- |
@@ -39,9 +39,7 @@ npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui engine install --p
 
 `npx @xgent-ai/skills install` 发现 impeccable 时询问是否替换。选择是，直接删除所选 provider 的旧 skill、固定 agents/commands 入口和旧 hooks，并关闭相应的 impeccable 插件启用项；项目级与个人级路径均在范围内，不创建工具备份，不留旧命令转跳入口。只移除引用旧 launcher 的 command handler，保留同组的其他 hooks、matcher 和未知配置。选择否则保留这些工具与配置，Phoenix 正常安装，不因旧入口、旧 live 状态或版本不同而阻止激活。
 
-无交互环境默认共存；自动化可用 `--replace-impeccable` 或 `--keep-impeccable` 明确选择。没有 `.phoenix-ui/install/` 事务状态的 Phoenix 副本属于待重装工具，直接删除对应 skill 目录后安装，不要求旧回执，也不备份。已有受管安装仍校验回执与事务日志；显式安装会按当前包刷新回执已认领的 `skills/phoenix-ui/` 文件（含 `ENGINE.json`），即使它们被 skills.sh 或手动复制覆盖，也不会仅因旧摘要不符而阻止重装。新事务保存重装前内容供回滚；共享 hooks、目录链接、事务恢复和项目数据继续执行原有校验。早期显式迁移留下的 Phoenix 受管兼容入口也由回执维护，不当作旧工具删除。
-
-旧回执曾管理的五个辅助 skill 在本次升级时释放归属，现有文件原样保留；后续由 skills.sh 更新，不再阻止 Phoenix 安装。
+无交互环境默认共存；自动化可用 `--replace-impeccable` 或 `--keep-impeccable` 明确选择。Phoenix UI 文件直接按当前包覆盖，包括 skills.sh 或手动复制修改过的文件，不要求旧回执或摘要一致。运行只检查 ENGINE 和引擎，不依赖安装日志。独立辅助 skill 由各自安装渠道管理，现有文件保留。
 
 这些操作不改业务代码、文档和 `.impeccable/` 数据。普通 npm 安装不显示文档中的旧入口引用和个人级旧分命令 skill 的迁移提示。个人级旧入口只在选择替换时删除。清理后若安装中断，直接重跑；需要旧工具时从 Git 或其安装渠道恢复。
 
@@ -67,9 +65,9 @@ npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui engine install --p
 | 固定旧状态路径或注入日志中记录的 live、注入或变体残留；显式迁移还检查源码中的孤立标记 | 用旧项目的 launcher 正常停止、`live-inject --remove`、接受或丢弃变体；不要按 PID 杀进程 |
 | 个人级（如 `~/.claude/skills/impeccable`）旧入口、旧 hook 或插件 | 安装器只读发现、不改个人配置；按输出在对应工具中禁用或移除后重载并重跑 |
 
-## 回滚与恢复
+## 显式迁移的回滚与恢复
 
-安装输出中的回滚命令只撤销该事务写入的条目：
+仅显式旧数据迁移保留原有回滚接口；普通安装不提供旧版本回滚，且会清除旧迁移备份。迁移输出中的回滚命令只撤销该迁移写入的条目：
 
 ```bash
 npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui migrate --rollback <事务ID> --project <项目>
@@ -78,7 +76,7 @@ npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui migrate --rollback
 - 独占文件按迁移后的摘要核对后还原；共享 JSON 只逆转本次加入或移除的条目，后来新增的 allow、guard 阈值和未知字段保留。受管条目被改过时返回 3 并列出冲突，不强制回退。
 - 回滚不撤销在 Phoenix 中做的产品代码修改，也不把新数据格式塞回旧工具；`.phoenix-ui/` 中的备份、日志与新数据保留，确认稳定后可手动删除。
 - 普通安装直接删除的 impeccable 工具和未受管 Phoenix 副本不在回滚范围内，不会从安装日志恢复。
-- 进程中断后，下一次安装会先读日志恢复；也可显式执行 `phoenix-ui migrate --recover --project <项目>`。遇到无法确认的新改动时停下并列出冲突，不覆盖。
+- 显式迁移中断后，下一次显式迁移会先读日志恢复；也可显式执行 `phoenix-ui migrate --recover --project <项目>`。遇到无法确认的新改动时停下并列出冲突，不覆盖。
 
 一致性保证覆盖进程崩溃或强制退出；不承诺突然掉电后零丢失，掉电损坏时从备份人工恢复。
 
@@ -159,20 +157,20 @@ npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui surface-brief link
 
 `link` 保存原文件路径、SHA-256 与接受记录，原 brief 留在选定仓库，不复制第二份可编辑正文。URL/route 是逻辑目标，`target.exists: null` 不表示文件缺失。设计流程详见包内 `design-reference`、`ui-pattern-research`、`design-md` 的实际指令。
 
-用 `review-ui` 评审、`apply-ui-review` 按报告修复，再由新的独立评审确认；修复方最多登记「已修改待评审」。先按固定包回执核对 `engine-probe` 身份，再查实际 `review` 帮助、输入形状和本循环状态，只有无旧历史的新循环才 begin：
+用 `review-ui` 评审、`apply-ui-review` 按报告修复，再由新的独立评审确认；修复方最多登记「已修改待评审」。这两个 skill 不依赖 Phoenix。选择 CLI 管理记录时，查询实际 `review` 帮助、输入形状和本循环状态，只有无旧历史的新循环才 begin：
 
 ```bash
-npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui review --help
-npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui review schema --json
-npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui review status --prefix "docs/ui/orders" --json
-npm exec --package=@xgent-ai/skills@<包版本> -- phoenix-ui review begin --prefix "docs/ui/orders" --target "docs/ui/orders.ui-target.md" --tested-version "docs/ui/orders.tested-version.json" --json
+npm exec --package=@xgent-ai/skills -- phoenix-ui review --help
+npm exec --package=@xgent-ai/skills -- phoenix-ui review schema --json
+npm exec --package=@xgent-ai/skills -- phoenix-ui review status --prefix "docs/ui/orders" --json
+npm exec --package=@xgent-ai/skills -- phoenix-ui review begin --prefix "docs/ui/orders" --target "docs/ui/orders.ui-target.md" --tested-version "docs/ui/orders.tested-version.json" --json
 ```
 
 `review schema --json` 返回 `reviewSchema: 1`、`discoveryVersion: 1` 的完整 typed examples 与枚举变体，可用 `--kind tested-version` 等选择一种输入。它描述当前 serde 字段形状，不是完整 JSON Schema；样例的文字、数字和布尔值均为占位，不证明执行成功或当前 UI 事实。真实身份、路径、hash、版本和 revision 取实际操作与取证。帮助和 schema 不读写循环；新前缀的父目录不存在时，`status` 可直接返回 `absent`，不创建目录或循环。
 
-`--tested-version` 的 JSON 由宿主提供真实 HEAD 加 clean/dirty 指纹，或可核对的 build ID，并与本轮应用/采集一致；省略时为 Unknown，不能判通过。context 提供目标和规范来源，不自动生产版本记录。后续 capture、judge-pack、judge add、finalize、apply record 使用返回的 round/current revision 和实际合同输入；**退出 0 不等于 UI 通过**，必须回读 verdict 与报告，`confirmation_required` 仍为草稿。参数与输入边界见 [Phoenix managed 评审协议](../skills/review-ui/references/phoenix-review.md)，目标、报告和处置沿 [review-ui 合同](../skills/review-ui/references/report-contract.md) 与 [修复记录合同](../skills/apply-ui-review/references/record-contract.md)。
+`--tested-version` 的 JSON 由宿主提供真实 HEAD 加 clean/dirty 指纹，或可核对的 build ID，并与本轮应用/采集一致；省略时为 Unknown，不能判通过。context 提供目标和规范来源，不自动生产版本记录。后续 capture、judge-pack、judge add、finalize、apply record 使用返回的 round/current revision 和实际合同输入；**退出 0 不等于 UI 通过**，必须回读 verdict 与报告，`confirmation_required` 仍为草稿。参数与输入边界见 [Phoenix managed 评审协议](phoenix-ui-review.md)，目标、报告和处置沿 [review-ui 合同](../skills/review-ui/references/report-contract.md) 与 [修复记录合同](../skills/apply-ui-review/references/record-contract.md)。
 
-已有 Markdown 历史无 managed 索引时继续 manual，只有显式 `review import --prefix <前缀> --input <映射.json> --json` 才接管；未知历史不能填零。`legacyMarkdown` 无法确定历史最佳时返回 3 并保持人工循环。managed 的 engine 缺失/不匹配、损坏或未知 schema 时只读历史，可收集未登记素材，不计分、裁定或修复产品代码；恢复匹配版本后续接原 round/revision，不删索引或换前缀绕过。生成区被手改时先另存原文与 hash，用 `projectionRebase` 显式核对副本、当前 hash 和 cycle revision 后恢复权威区块；要保留的采集/处置再以当前 revision 提交。封存报告与评审原文不覆盖。
+已有 Markdown 历史无 managed 索引时继续 manual，只有显式 `review import --prefix <前缀> --input <映射.json> --json` 才接管；未知历史不能填零。`legacyMarkdown` 无法确定历史最佳时返回 3 并保持人工循环。工具不可用或无法识别状态时保留原索引，agent 继续依据 Markdown 历史、真实证据和评审合同工作；恢复工具后核对并登记新增材料，不删索引或清空历史。生成区被手改时先另存原文与 hash，用 `projectionRebase` 显式核对副本、当前 hash 和 cycle revision 后恢复权威区块；要保留的采集/处置再以当前 revision 提交。封存报告与评审原文不覆盖。
 
 ## 维护者：统一候选与本地交接
 
@@ -192,7 +190,7 @@ mise exec --no-deps -- npm --prefix ../.. run test:phoenix
 
 prepare 显式联网准备锁定依赖、工具、浏览器、迁移包和公告快照；随后 audit/build/runtime 使用已准备缓存与离线合同，`CARGO_NET_OFFLINE` 不单独证明全部网络已禁止。`--development` 仅是本机开发制品。`check-phoenix-deps.mjs --distribution-dir <目录>` 另核对分发许可，真实 browser/provider 会话仍分别取证。完整维护入口见 [prepare](../scripts/prepare-phoenix-ui.mjs)、[build](../scripts/build-phoenix-ui.mjs)、[audit](../scripts/check-phoenix-deps.mjs)、[runtime tests](../scripts/test-phoenix-ui.mjs)。
 
-[CI workflow](../.github/workflows/phoenix-ui.yml) 在 macOS/Linux 四个平台同架构冷构建/运行，不恢复编译缓存，另有 Node18 consumer。固定成功 run 的四份 native、四份 phase evidence、一份 Node18 evidence 必须保留原始 ZIP/digest、HEAD/tree、工具链、输入/制品摘要、许可及全部真实 step/phase 结果。CI 不持 R2/npm 凭据；缺平台、失败 phase 或摘要不符不能交接。
+统一的 [Phoenix CI](../.github/workflows/phoenix.yml) 在同一次运行中检查 UI 和 Diagram，并给出共同结果。UI 在 macOS/Linux 四个平台同架构冷构建/运行，不恢复编译缓存，另有 Node18 consumer。固定成功 run 的四份 native、四份 phase evidence、一份 Node18 evidence 必须保留原始 ZIP/digest、HEAD/tree、工具链、输入/制品摘要、许可及全部真实 step/phase 结果。CI 不持 R2/npm 凭据；缺平台、失败 phase 或摘要不符不能交接。
 
 发布只用一条命令，在 **main 分支上干净、已推送且 Phoenix CI 成功**的 HEAD 上执行，不创建独立发布分支，也不从 detached HEAD 发布。版本号先在 `package.json` 改好，并用上面的开发构建同步 `VERSION.json`/`ENGINE.json`/`GENERATED.json`：
 
@@ -204,10 +202,10 @@ mise exec --no-deps -- npm run release:phoenix -- --prepare-only     # 只做到
 [release-phoenix-ui.mjs](../scripts/release-phoenix-ui.mjs) 依次执行，任一步失败即停：
 
 1. 核对当前分支为 `main`、工作树干净、Diagram 的四平台 release 清单、bundle、完整许可证与公共 HTTPS 下载地址齐备，npm 上还没有这个版本，找到该提交成功的 Phoenix CI run（也可用 `--run-id` 指定）。
-2. 下载 CI 的九个原始 ZIP，逐个核对 GitHub digest。
+2. 从统一 CI 下载 UI 的九个原始 ZIP，逐个核对 GitHub digest。
 3. 用 [publish-phoenix-ui-r2.mjs](../scripts/publish-phoenix-ui-r2.mjs) 条件上传四个 engine（已存在即拒绝覆盖），公共 URL 回读通过后冻结 release manifest。凭据取已导出的 `AGENT_RELEASE_R2_*`，没有时读仓根 `.env.cf` 里的同名行。
 4. 用 [pack-phoenix-ui-release.mjs](../scripts/pack-phoenix-ui-release.mjs) 只打一次联合 tarball：保留 `package.json` 声明的 UI 和 Diagram bin、skill、文档及发行资源，最终包再次通过发布校验。`xgent-skills install` 默认安装两者。Diagram 默认使用仓库中已准备好的 release 资源，也可用 `--diagram-release-dir DIR` 指定同版本的完整正式资源目录，在打包阶段注入；本脚本不构建或上传 Diagram 引擎，缺少资源时在上传 UI 前停止。
-5. 用 [check-phoenix-ui-release.mjs](../scripts/check-phoenix-ui-release.mjs) 在 Node 18 和维护 Node 上联合新装（两个 engine 从公共 URL 下载），核对 Diagram 引擎摘要、可运行入口及重复安装；另检查 0.3.0/0.6.0 工具保留共存、直接删除替换、无回执 Phoenix 副本重装与受管安装回滚。删除的旧工具不会回滚恢复。
+5. 用 [check-phoenix-ui-release.mjs](../scripts/check-phoenix-ui-release.mjs) 在 Node 18 和维护 Node 上联合新装（两个 engine 从公共 URL 下载），核对 Diagram 引擎摘要、可运行入口及重复安装；另检查 0.3.0/0.6.0 工具保留共存、直接删除替换、无回执 Phoenix 副本覆盖重装、旧安装目录清理和重复安装。
 6. `npm publish` 这个 tarball，再从 registry 下载回来核对 shasum、integrity 和 SHA-256。
 
 每步产物保存在 `local/phoenix-ui/releases/v<版本>-<短SHA>/`，中断后重跑会复核已有产物再续接。预发布版本必须加 `--tag`。CI 测过的提交之后 main 又有新提交时，等待 main 当前 HEAD 的 CI 成功后再发布；不另建发布分支或检出旧提交发布。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgent-ai/skills",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "description": "XGENT skills 与项目辅助工具:安装 hooks、settings、Phoenix UI 与独立 Phoenix Diagram 图解候选",
   "keywords": [
     "claude-code",
@@ -29,6 +29,7 @@
     "bin",
     ".claude/hooks",
     "docs/phoenix-ui.md",
+    "docs/phoenix-ui-review.md",
     "docs/phoenix-diagram.md",
     "skills",
     "dist/phoenix-ui/bundle",

package/skills/apply-ui-review/SKILL.md

@@ -16,7 +16,7 @@ disable-model-invocation: true
 `references/` 相对本文件解析。启动方式、组件库、设计规范和检查命令从目标仓发现。语言跟随用户。
 
 本技能是独立的 SDLC 执行流程。
-依据报告、目标包和修复记录续接；独立工具缺失或不兼容不阻止核实、修复与补证。
+依据报告、目标包和修复记录续接，不绑定工具版本、规则版本或 skill 文档指纹；独立工具缺失或不兼容不阻止核实、修复与补证。
 
 ## 1. 锚定输入
 

package/skills/optimize-agents-md/SKILL.md

@@ -10,6 +10,12 @@ compatibility: "需要已安装的 use-prompt-dsl；缺失时建议完整安装
 
 用 Odyssey（ODC）精简仓库 AGENTS.md，保留规则含义和项目事实。补缺时读取[原则素材](assets/coding-principles.md)。
 
+在目标 AGENTS.md 的首个 `formal` 代码围栏之前、所有代码围栏之外，使用目标文件的语言加入以下醒目的自然语言声明；已有等义声明时合并或保留：
+
+**本文 `formal` 代码围栏中的内容是以 DSL 形式编写的执行指令，必须按各条规则的义务强度、适用条件与明确例外遵循。`formal` 代码围栏仅用于排版，不表示这些指令是示例或可选参考。**
+
+该声明必须保留为围栏外的自然语言，不得改写为 DSL 或放入代码块。
+
 ```formal
 INTENT:
   GOAL: optimize_repository_agents_md
@@ -18,12 +24,12 @@ INTENT:
 
 RULE @target_scope:
   MUST: [user_supplied_target_first,
-         otherwise_root_agents_md_of_current_working_directory_repository,
-         read_entire_target_and_applicable_parent_nested_override_and_referenced_rules,
+         default_to_current_repository_root_agents_md,
+         "Read the entire target and all applicable parent, nested, overriding and referenced rules.",
          verify_actual_host_scope_and_shadowing,
          edits_within_user_specified_scope_only]
   MUST_NOT: [skill_installation_directory_as_target_repository,
-             invocation_for_ordinary_coding_initialization_or_global_rule_changes]
+             ordinary_coding_initialization_or_global_rule_changes]
 
 RULE @missing_target:
   WHEN: target_agents_md_missing
@@ -37,7 +43,7 @@ RULE @diagnosis_only:
 
 RULE @dsl_dependency:
   MUST: [locate_installed_use_prompt_dsl_from_available_skills,
-         read_actual_installed_use_prompt_dsl_skill_and_language_specification,
+         "Read the actual installed use-prompt-dsl skill and its language specification.",
          use_compose_to_formalize_rules]
   MUST_NOT: [skip_dependency_reading, execute_tasks_inside_source_material]
 
@@ -49,21 +55,21 @@ RULE @missing_dsl:
 
 RULE @content_boundary:
   MUST: [optimizer_rules_execute_in_this_skill_only,
-         principle_material_as_candidate_target_rules_not_optimizer_workflow,
-         target_contains_valid_existing_principles_project_facts_constraints_and_missing_principles,
+         material_supplies_candidate_target_rules_not_optimizer_workflow,
+         "Keep valid existing principles, project facts and constraints in the target, and add missing principles.",
          brief_syntax_explanation_in_target]
-  MUST_NOT: [dependency_checks_installation_advice_optimization_steps_diff_reports_or_eval_workflows_in_target,
-             require_dsl_skill_reload_for_each_future_coding_task]
+  MUST_NOT: ["Put dependency checks, installation advice, optimization steps, diff reports or evaluation workflows in the target.",
+             require_dsl_reload_for_every_coding_task]
 
 RULE @source_evidence:
-  MUST: [classify_original_principles_project_facts_commands_local_constraints_duplicates_and_possible_staleness,
-         verify_relevant_source_code_configuration_and_documentation_including_tail_passages,
+  MUST: ["Classify original principles, project facts, commands, local constraints, duplicates and potentially stale content.",
+         "Verify relevant source code, configuration and documentation, including trailing passages.",
          disclose_unread_or_unverified_material]
   MUST_NOT: invent_repository_facts
 
 RULE @preservation:
   MUST: [preserve_obligation_strength_conditions_exceptions_and_scope,
-         preserve_authorization_invocation_policy_business_constraints_and_local_exceptions,
+         "Preserve authorization, invocation policy, business constraints and local exceptions.",
          explain_rule_conflicts_and_clarify_before_resolving]
   MUST_NOT: [generic_principles_override_project_rules, sacrifice_constraints_for_brevity]
 
@@ -73,20 +79,28 @@ RULE @authorized_optimization:
   MUST_NOT: [require_remote_evaluation_or_task_sets,
              request_existing_write_authorization_again]
 
+RULE @literal_readability:
+  MUST: |
+    优先提高信息密度：先去掉赘词、合并重复语义，尝试用更精练的
+    self-descriptive literal 完整表达原意。每个 literal 最多 8 个英文单词，
+    按下划线分词计数；压缩后仍超限或难懂时，才改用带引号的自然语言短句，
+    较长段落用 | 承载。不得靠生僻缩写、合并单词、删除条件或拆散完整约束
+    来规避上限。此约定适用于本 skill 及其生成的规则。
+
 RULE @principle_expression:
   MUST: [compact_odyssey_rule_fragments_embedded_directly_in_target,
          only_necessary_must_must_not_should_prefer_clauses,
          merge_semantic_duplicates, remove_obsolete_content_only_with_evidence,
-         retain_usable_commands_paths_project_operations_and_necessary_links]
+         retain_usable_commands_paths_operations_and_necessary_links]
   MUST_NOT: [outer_or_module_wrappers,
-             force_intent_ontology_output_or_review_blocks_into_target,
+             force_intent_ontology_output_review_blocks_into_target,
              cryptic_abbreviations_or_layered_references_for_compression]
 
 RULE @principle_completion:
   MUST: [read_principle_material,
-         semantically_check_think_before_coding_and_twelve_coding_principles,
+         semantically_check_all_rules_in_principle_material,
          fill_only_missing_coverage, integrate_in_original_language_and_structure]
-  MUST_NOT: [duplicate_covered_principles, require_original_numbering_or_thirteen_separate_sections,
+  MUST_NOT: [duplicate_covered_principles, require_original_numbering_or_separate_sections_per_rule,
              drop_trust_boundary_validation_under_internal_contract_trust,
              omit_necessary_work_under_do_less,
              skip_required_acceptance_under_milestone_execution]
@@ -94,13 +108,17 @@ RULE @principle_completion:
 RULE @write_and_verify:
   MUST: [recheck_current_file_before_writing, preserve_concurrent_user_edits,
          reread_diff_after_scoped_edits,
-         map_every_original_rule_to_preservation_merge_or_evidence_based_removal,
+         "Account for every original rule as preserved, merged or removed with evidence.",
          verify_added_principles_complete_without_duplicates_or_conflicts,
-         verify_template_conditions_preserved_and_project_commands_paths_links_valid,
+         "Verify that template conditions are preserved and project commands, paths and links remain valid.",
          verify_no_optimizer_workflow_leaked_into_target,
-         run_change_relevant_and_repository_required_checks]
-  MUST_NOT: [rewrite_already_compact_and_complete_target_just_to_produce_diff,
-             unrelated_tests_or_behavior_search]
+         "Before each check, state the specific unresolved failure it detects and how failure changes the next action.",
+         "Run only checks that address that live uncertainty, including applicable required acceptance.",
+         "Reuse valid results; add checks only for new concrete failures."]
+  MUST_NOT: [rewrite_compact_complete_target_merely_to_produce_diff,
+             unrelated_tests_or_behavior_search,
+             "Add a redundant smoke check after a real full run covers the same path.",
+             manufacture_findings_when_existing_rules_are_correct]
 
 WORKFLOW @optimize:
   TRIGGER: repository_agents_md_optimization_or_diagnosis_requested
@@ -118,7 +136,7 @@ RULE @delivery_evidence:
          compare_semantics_rule_by_rule_when_reporting_compression,
          explain_no_change_when_no_file_modified]
   MUST_NOT: [delete_rules_to_hit_compression_ratio,
-             infer_agent_behavior_or_task_quality_improvement_from_shorter_text]
+             infer_behavior_or_task_quality_gains_from_brevity]
 
 OUTPUT:
   FORMAT: markdown

package/skills/optimize-agents-md/assets/coding-principles.md

@@ -3,17 +3,22 @@
 Odyssey 片段：`RULE` 声明本文作用域内的常驻规则；`MUST` 必须，`MUST_NOT` 禁止，`SHOULD` 通常应满足，`PREFER` 在不冲突时优先；`=>[a, b]` 表示若 a 则 b，`&&[a, b]` 表示同时满足。直接嵌入 AGENTS.md，不加外层包装。
 
 ```formal
+RULE @execution_basis:
+  MUST: ["Execute based on the current user request, applicable AGENTS.md or active development plan.",
+         "Treat historical plans, handoffs, old prompts and old audit feedback as factual background only."]
+  MUST_NOT: historical_material_independently_authorizes_or_expands_current_work
+
 RULE @think_before_coding:
   MUST: [state_assumptions_explicitly_before_implementation,
          when_uncertain_or_confused_stop_identify_and_ask,
-         when_multiple_interpretations_exist_present_all_and_explain_tradeoffs,
+         present_competing_interpretations_and_tradeoffs,
          surface_simpler_approaches, push_back_when_warranted]
   MUST_NOT: silently_choose_or_hide_alternative_interpretations
 
 RULE @simplicity:
   MUST: [simplest_correct_solution,
-         validate_only_at_system_boundaries_including_user_input_external_apis_and_files,
-         trust_internal_code_established_contracts_invariants_and_framework_guarantees,
+         "Validate only at system boundaries, including user input, external APIs and files.",
+         "Trust internal code, established contracts, invariants and framework guarantees.",
          handle_only_real_actionable_failures]
   MUST_NOT: [speculative_abstractions, unnecessary_fallbacks,
              excessive_defenses, impossible_scenario_guards,
@@ -23,11 +28,11 @@ RULE @simplicity:
 RULE @scope:
   MUST: [implement_requested_scope_only, preserve_existing_patterns,
          reuse_or_simplify_before_abstracting,
-         allow_complete_deletion_of_confirmed_unused_code_within_agreed_scope]
+         allow_deleting_confirmed_unused_code_within_agreed_scope]
   PREFER: small_changes
-  MUST_NOT: [unrequested_features_configuration_compatibility_layers_ui_or_architecture_changes,
-             feature_flags_or_backward_compatibility_shims_when_direct_code_changes_suffice,
-             compatibility_hacks_using_unused_variable_underscore_renames_or_type_reexports]
+  MUST_NOT: ["Add unrequested features, configuration, compatibility layers, UI or architecture changes.",
+             "Add feature flags or backward compatibility shims when direct code changes suffice.",
+             "Add compatibility hacks through underscore renaming of unused variables or type reexports."]
 
 RULE @requirement_confirmation:
   WHEN: non_brainstorming
@@ -42,40 +47,58 @@ RULE @legacy_compatibility:
 
 RULE @user_experience:
   MUST: [design_around_user_expectations, user_facing_copy_serves_users]
-  MUST_NOT: [unnecessary_engineering_internal_state_or_obvious_interaction_explanations_in_ui,
-             developer_notes_implementation_comments_or_internal_instructions_in_ui,
-             prompts_or_warnings_unless_helping_meaningful_decisions_or_preventing_major_errors]
+  MUST_NOT: ["Put unnecessary engineering details, internal state or obvious interaction explanations in the UI.",
+             "Put developer notes, implementation comments or internal instructions in the UI.",
+             "Add prompts or warnings unless they help meaningful decisions or prevent major errors."]
 
 RULE @current_documentation:
   MUST: [comments_explain_why,
-         add_comments_only_for_nonobvious_logic_or_non_self_descriptive_code,
-         update_or_remove_stale_comments_and_docs_when_behavior_changes,
-         current_concise_searchable_sources_of_truth]
-  MUST_NOT: [add_docstrings_comments_or_type_annotations_to_otherwise_unchanged_code,
-             comments_paraphrasing_code_or_recording_development_history,
-             accumulated_historical_annotations_or_corrections_appended_to_stale_text,
+         "Add comments only for nonobvious logic or code that is not self explanatory.",
+         "Update or remove stale comments and documentation when behavior changes.",
+         current_concise_searchable_sources_of_truth,
+         code_comments_and_docs_present_correct_current_result,
+         explain_current_rationale_without_discarded_alternatives,
+         task_status_discloses_actual_failures_and_unverified_items]
+  MUST_NOT: ["Add docstrings, comments or type annotations to otherwise unchanged code.",
+             comments_paraphrasing_code,
+             "Leave development error stories, discarded plans, historical corrections or explanations of why X was not done in code comments and documentation.",
+             accumulate_history_or_append_corrections_to_stale_text,
+             "Add AI attribution markers such as Generated by or AI Co-authored-by signatures.",
+             "Add formulaic model transitions or openers such as here is to authored output.",
              duplicate_documentation]
 
 RULE @evidence:
-  MUST: [read_relevant_source_specs_and_doc_passages_fully_before_conclusions,
-         cover_all_relevant_sections_and_tail_in_long_documents,
+  MUST: ["Read relevant source, specifications and documentation passages fully before drawing conclusions.",
+         cover_relevant_sections_and_tail_of_long_documents,
          disclose_unverified_items,
-         investigate_existing_behavior_and_contracts_before_changes]
-  MUST_NOT: [infer_unread_content, invent_requirements_or_constraints]
+         investigate_existing_behavior_and_contracts_before_changes,
+         acknowledge_correct_work_when_supported_by_evidence]
+  MUST_NOT: [infer_unread_content, invent_requirements_or_constraints,
+             manufacture_findings_for_appearances_or_review_quotas]
 
 RULE @meaningful_tests:
   MUST: [protect_meaningful_behavior_key_boundaries_and_real_regressions,
          exercise_interfaces_from_external_caller_perspective,
          assert_actual_caller_observable_outcomes,
-         delete_tests_that_still_pass_when_all_tested_function_bodies_are_empty_and_return_no_data,
+         "Delete tests that still pass when all tested function bodies are empty and return no data.",
          remove_obsolete_or_redundant_tests_within_agreed_scope,
-         reuse_valid_verification_when_relevant_code_configuration_and_conditions_unchanged,
-         retest_only_after_meaningful_change_new_failure_or_discovered_concrete_acceptance_evidence_gap,
+         "Reuse valid verification when relevant code, configuration and conditions are unchanged.",
          run_smallest_relevant_check]
   MUST_NOT: [redundant_tests, trivial_assertions, implementation_coupled_tests,
              per_function_coverage_chasing, exhaustive_imaginary_failures,
              add_unnecessary_regression_burden,
-             whole_suite_repetition_for_reassurance_or_report_challenge_alone]
+             "Repeat the whole suite solely for reassurance or because a report was challenged."]
+
+RULE @live_uncertainty:
+  MUST: |
+    Before any check, state in one sentence the specific unresolved failure it will
+    detect and how failure would change the next action; if either cannot be stated,
+    do not run it. Default to one minimal real-data sanity check and one recheck
+    directly tied to the change, only when each answers a live uncertainty.
+    Reuse a completed real full run that covers the same path; do not add a smoke
+    check for that path. Add further checks only for a newly observed concrete failure.
+    Scope required acceptance up front from the current execution basis; this default
+    does not waive explicit acceptance requirements or authorize extra checks at milestones.
 
 RULE @automated_test_scope:
   MUST: automated_tests_assert_outcomes_produced_by_deterministic_code
@@ -84,35 +107,52 @@ RULE @automated_test_scope:
 
 RULE @complete_milestones:
   MUST: [prioritize_quality_and_completeness_over_token_savings,
-         full_effort_in_required_reasoning_investigation_implementation_and_verification,
+         "Apply full effort to required reasoning, investigation, implementation and verification.",
          concise_communication, respect_agreed_scope_and_stopping_rules,
          autonomously_finish_actual_remaining_work_within_agreed_scope,
-         fix_related_defects_found_during_verification_within_agreed_scope,
+         fix_related_in_scope_defects_found_during_verification,
          understand_full_scope_and_acceptance_before_long_tasks,
          deliver_coherent_complete_milestones,
-         targeted_verification_coverage_during_development,
-         broad_regression_coverage_at_meaningful_milestones_and_before_delivery,
+         working_first_correct_before_delivery,
+         treat_forward_progress_as_part_of_delivery,
+         verification_at_each_stage_follows_live_uncertainty,
          measure_progress_by_complete_usable_deliverables]
-  MUST_NOT: [repeated_stops_after_fragmentary_changes,
+  MUST_NOT: [stall_unfinished_functionality_with_excessive_defensive_work,
+             repeated_stops_after_fragmentary_changes,
              full_suite_after_every_micro_edit, test_frequency_as_progress,
-             stop_at_findings_list_while_actionable_in_scope_work_remains,
+             stop_at_findings_despite_actionable_in_scope_work,
              open_ended_hunts_for_hypothetical_or_unrelated_problems]
 
 RULE @temporary_resource_cleanup:
   WHEN: code_and_test_reviews_completed
-  MUST: [inspect_task_related_temporary_directories_git_worktrees_branches_and_docker_containers,
+  MUST: ["Inspect task-related temporary directories, Git worktrees, branches and Docker containers.",
          identify_resources_safe_to_remove,
          verify_no_background_task_dependencies_before_cleanup,
-         promptly_remove_safe_temporary_resources_to_reclaim_disk_space]
+         promptly_delete_safe_temporary_resources_to_reclaim_space]
+
+RULE @proportionate_recovery:
+  MUST: |
+    Choose failure handling from actual user impact and the cost of starting over.
+    For cheap, safely repeatable work with disposable intermediate state, default to
+    reporting failure and allowing a fresh attempt; preserve existing user data and
+    perform only the cleanup needed to make that attempt safe.
+    Add transaction journals, checkpoints, resumable execution or recovery state
+    machines only for an explicit requirement or demonstrated material loss of user
+    data, nonrepeatable side effects or expensive rework, within the authorized scope.
+    Use the smallest mechanism that addresses that concrete consequence.
+  MUST_NOT: [infer_recovery_requirements_merely_because_interruption_is_possible,
+             treat_optional_tools_as_critical_infrastructure_without_evidence,
+             "Add old-version restoration or downgrade support without an explicit user requirement."]
 
 RULE @complexity_budget:
-  MUST: [each_added_check_abstraction_dependency_error_branch_test_or_ui_element_justifies_maintenance_cost,
-         remove_existing_redundant_complexity_before_adding_abstractions_or_dependencies,
+  MUST: ["Ensure every added check, abstraction, dependency, error branch, test or UI element justifies its maintenance cost.",
+         remove_redundant_complexity_before_adding_abstractions_or_dependencies,
          rethink_overcomplicated_design, complete_necessary_work_correctly,
-         =>[adding_complexity_for_speculative_or_vanishingly_unlikely_race_or_security_edge_cases,
-            &&[explain_concrete_failure_mode_likelihood_and_complexity_cost_to_user,
-               obtain_user_buy_in_after_explanation_and_before_adding_complexity]]]
-  MUST_NOT: [add_layers_to_an_overcomplicated_design,
+         =>["Adding complexity for speculative or vanishingly unlikely race conditions or security edge cases.",
+            &&["Explain the concrete failure mode, its likelihood and the complexity cost to the user.",
+               explain_then_obtain_buy_in_before_adding_complexity]]]
+  MUST_NOT: ["Add hashes, checksums or fingerprints unless they replace a materially more expensive operation AND their result changes the next action.",
+             add_layers_to_an_overcomplicated_design,
              silently_expand_scope_for_theoretical_robustness]
   PREFER: fewer_additions
 ```

package/skills/phoenix-diagram/ENGINE.json

@@ -3,37 +3,37 @@
   "distribution": "release",
   "tool": "phoenix-diagram",
   "toolVersion": "0.2.0",
-  "npmPackageVersion": "0.7.8",
-  "sourceCommit": "4e2a4e4dccbbceb84152eb93bc74662aa4b759d0",
-  "sourceInputSha256": "51b65bd3f53b989e1f242cae99542ed67c5fe3e855edf906f7f5fab23939ab94",
+  "npmPackageVersion": "0.7.9",
+  "sourceCommit": "7229a8ba08f7d37bc37530e00e4d933903f1b5cf",
+  "sourceInputSha256": "910df91b4e857da6e30d8982aea308d2e1bf2d99c2d7644cb5455b37762740d9",
   "inputContractSchema": 1,
   "receiptSchema": 1,
   "viewerRevision": "phoenix-v2",
-  "bundleSha256": "58d1580a3a443f79a3aa41ee2c9000542de5a8d4b799377a4be673298ad8589e",
+  "bundleSha256": "e573234de7918dc87e1630c30a4ea1ba5862cc647dc0023a6d578ccb114e2ab6",
   "engines": {
     "darwin-arm64": {
       "asset": "phoenix-diagram-darwin-arm64",
-      "size": 17566448,
-      "sha256": "f85846e9a0967847eaf3f3b0a290d4009c069821c028495b047db358176ce17c",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.8/darwin-arm64/phoenix-diagram-darwin-arm64"
+      "size": 17549968,
+      "sha256": "5f432a278a433bd456e8b65e0eb7a4128665f31d8c992609d6eb1cd9c48b7429",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/darwin-arm64/phoenix-diagram-darwin-arm64"
     },
     "darwin-x64": {
       "asset": "phoenix-diagram-darwin-x64",
-      "size": 19576864,
-      "sha256": "b3df962d82d3f731d9641184cceec5516c082aa1fbc871ac41692cc7acd85dc8",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.8/darwin-x64/phoenix-diagram-darwin-x64"
-    },
-    "linux-x64": {
-      "asset": "phoenix-diagram-linux-x64",
-      "size": 21880592,
-      "sha256": "59ef4d6ac3f08e000c387a668915e31a8f44a83cc01ba9b89381fadc193e09f6",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.8/linux-x64/phoenix-diagram-linux-x64"
+      "size": 19556424,
+      "sha256": "236384da35f4f65e892966b5912b1c1631fb4819194a7d51085076f2bc3b1a79",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/darwin-x64/phoenix-diagram-darwin-x64"
     },
     "linux-arm64": {
       "asset": "phoenix-diagram-linux-arm64",
       "size": 19406792,
-      "sha256": "f86c8610dde3af5c01cf70275d3a8241d35e937916e34367963c1a728bfba7ac",
-      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.8/linux-arm64/phoenix-diagram-linux-arm64"
+      "sha256": "0df998aed2c0d1968a94151e01e1be0ea73b62f279ff3f33fbaa2ec037e3c215",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/linux-arm64/phoenix-diagram-linux-arm64"
+    },
+    "linux-x64": {
+      "asset": "phoenix-diagram-linux-x64",
+      "size": 21861536,
+      "sha256": "502c95c538ab6db7c4b3de80c65e7188a84a4326ba6a5a965a1c23e7b6033037",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.9/ci-41410951647/linux-x64/phoenix-diagram-linux-x64"
     }
   }
 }