Sync third-party and MCP marketplace plugins

Constraint: Public skills are published only by explicit administrator action unless they are tracked third-party market sources. Confidence: high Scope-risk: narrow Directive: Keep private/internal skills out of the public marketplace and preserve normal incremental market Git history. Tested: Marketplace validation passed.
2026-09-03 00:01:59 +08:00
parent ddff47784c
commit 30aa782719
50 changed files with 1102 additions and 660 deletions
@@ -33,8 +33,8 @@
      "repo": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git",
      "ref": "main",
      "adapter": "claude-skill",
-      "commit": "e2effd57755d580318cce65ea1b2f98d896d5d40",
+      "commit": "58c220ff9d02be80523b06c03471925c52e8ab5d",
-      "syncedAt": "2026-09-02T10:37:18Z"
+      "syncedAt": "2026-09-02T16:00:01Z"
    },
    {
      "id": "caveman",
@@ -42,8 +42,8 @@
      "repo": "https://github.com/JuliusBrussee/caveman.git",
      "ref": "main",
      "adapter": "codex-plugin",
-      "commit": "b4de606fb871b0d9d454495f3d636b744d560875",
+      "commit": "3b74643f4d910f496babd4e634b1ba7168816f14",
-      "syncedAt": "2026-09-02T10:37:18Z"
+      "syncedAt": "2026-09-02T16:00:01Z"
    },
    {
      "id": "taste-skill",
@@ -60,8 +60,8 @@
      "repo": "https://github.com/shadcn-ui/ui.git",
      "ref": "main",
      "adapter": "claude-skill",
-      "commit": "b2a1ec864a87ba66c63fc4e51c9223c7eb4f8335",
+      "commit": "4c43e943d7998be45bbb5a2606e095bbf1ffaa8a",
-      "syncedAt": "2026-09-02T10:37:18Z"
+      "syncedAt": "2026-09-02T16:00:01Z"
    },
    {
      "id": "frontend-slides",
@@ -96,8 +96,8 @@
      "repo": "https://github.com/hugohe3/ppt-master.git",
      "ref": "main",
      "adapter": "claude-skill",
-      "commit": "e33b81eaa737a21821aff948ea117a095d6b1f22",
+      "commit": "1fd7ba6a72dfea7918106b4da7c665a58321454e",
-      "syncedAt": "2026-09-02T10:37:18Z"
+      "syncedAt": "2026-09-02T16:00:01Z"
    },
    {
      "id": "grill-me",
@@ -123,8 +123,8 @@
      "repo": "https://git.playones.com/chenmingxuan/EP-Hub-Skill.git",
      "ref": "main",
      "adapter": "claude-skill",
-      "commit": "127bcc4ad3b6eb6efc8e0221258959e7ae85acb1",
+      "commit": "af8596a8a251c6a783b2f44a45047bebb2a7d68a",
-      "syncedAt": "2026-09-02T10:37:18Z"
+      "syncedAt": "2026-09-02T16:00:01Z"
    },
    {
      "id": "next-skills",
@@ -132,8 +132,8 @@
      "repo": "https://github.com/vercel/next.js.git",
      "ref": "canary",
      "adapter": "skill-collection",
-      "commit": "8ea76d64ca3931c1beccceb15d32df5d770f4957",
+      "commit": "5cca033c416427f26dbfc7baecb0ecfbb9757e41",
-      "syncedAt": "2026-09-02T10:37:18Z"
+      "syncedAt": "2026-09-02T16:00:01Z"
    }
  ]
 }
@@ -2,8 +2,8 @@
  "sourceId": "caveman",
  "repo": "https://github.com/JuliusBrussee/caveman.git",
  "ref": "main",
-  "commit": "b4de606fb871b0d9d454495f3d636b744d560875",
+  "commit": "3b74643f4d910f496babd4e634b1ba7168816f14",
  "adapter": "codex-plugin",
  "sourcePath": "plugins/caveman",
-  "syncedAt": "2026-09-02T10:37:18Z"
+  "syncedAt": "2026-09-02T16:00:01Z"
 }
@@ -2,8 +2,8 @@
  "sourceId": "etunel-role-collaboration",
  "repo": "https://git.playones.com/chenmingxuan/EP-Hub-Skill.git",
  "ref": "main",
-  "commit": "127bcc4ad3b6eb6efc8e0221258959e7ae85acb1",
+  "commit": "af8596a8a251c6a783b2f44a45047bebb2a7d68a",
  "adapter": "claude-skill",
  "sourcePath": "etunel-role-collaboration",
-  "syncedAt": "2026-09-02T10:37:18Z"
+  "syncedAt": "2026-09-02T16:00:01Z"
 }
@@ -5,40 +5,40 @@ description: "用于 Etunel 多 Agent 项目的角色识别、Hub 中介、依
 # Etunel 多角色项目协作
-一个 WORK_ID 使用一个持续的项目Hub会话贯穿生命周期。默认角色为项目Hub、业务、产品、技术负责人、嵌入式应用层、嵌入式底层、硬件和测试；已完成契约并由 Hub 真人负责人在 Etunel 中手动添加的自定义角色也可参与。
+一个项目使用一个持续的项目Hub会话贯穿生命周期。默认角色为项目Hub、业务、产品、技术负责人、嵌入式应用层、嵌入式底层、硬件和测试；已完成职责契约并由 Hub 真人负责人在 Etunel 中手动添加的自定义角色也可参与。
-## 先确认身份与任务
+## 先确认当前任务
 从当前 Hook、Etunel 角色契约和入站任务确认：
- semantic role、实际 role ID、role member ID、session ID 和 human owner；
+- 当前角色、项目名称、项目模式、流程基线和所处阶段；
- WORK_ID、SUBTASK_ID、项目模式、流程基线、阶段、任务波次和本任务范围；
+- 任务目标、唯一主责角色、协作角色、上游依赖和完成时间；
- 唯一主责角色与主责成员、协作角色、上游依赖和要求完成时间；
+- 已有资料、要求产出的文件或成果包、最低内容、证据、完成条件和下游用途。
 - 要求产出的文件或连贯成果包、最低内容、证据、完成条件和下游用途。
-不要根据文件夹名、历史消息或记忆猜身份。成员、会话、职责或任务归属不清时，先报告边界问题，不自行换角色。
+Etunel 负责当前角色和会话绑定。不要向负责人询问或复述 role ID、member ID、session ID、消息 ID 等运行时字段，也不要在任务正文中制造不存在的 ID。Hub 需要识别角色时调用 `mcp__etunel__etunel_list_roles`，用 `role` 路由、用 `display_name` 面向人显示。
 ## 共享硬约束
-1. 项目Hub是成员 Agent 之间唯一的跨角色中介。现阶段 Etunel 不支持成员间直接通信；成员只交 Hub，Hub 再定向路由，且不替角色改写或作出专业结论。
+1. 项目Hub是成员 Agent 之间唯一的跨角色中介。成员只把任务结果、问题或阻塞交 Hub，由 Hub 定向路由；成员之间不直接通信。
 2. 正常阶段顺序为：业务需求、产品定义、方案设计、项目规划、软硬件实现、测试验证、业务验收、发布结项。阶段按有效流程基线和依赖推进。
-3. 同一阶段中，依赖已满足的任务可组成任务波次；一个工具调用只有一个接收方，同一角色的多项工作可以内聚成任务包或连续派发多个 SUBTASK_ID。
+3. 依赖已满足的任务可以组成任务波次。一个 Etunel 调用只面向一个接收角色；同一角色的紧密相关工作可以组成一个任务包。
-4. 每个 SUBTASK_ID 只有一个主责角色、一个主责成员和一个可独立判定的结果。协作角色不等于共同主责。
+4. 每项任务只有一个主责角色和一个可独立判断的结果。Etunel 的角色绑定决定实际接收会话，不另造“主责成员 ID”。
-5. Hub 给足当前任务需要的已登记信息，但不默认广播完整计划、全部资料或私有对话。缺口应聚合后经 Hub 定向补齐。
+5. Hub 必须给足执行所需的背景、有效输入、边界、产出和完成条件，但不默认广播完整计划、全部资料或私有对话。
-6. 正式执行任务必须要求具体产出文件或连贯成果包，且派发要求与预期产出一致。纯信息查询、确认或决定请求不虚构文件。
+6. 正式执行任务必须形成指定文件或连贯成果包，任务要求与实际产出一致。纯信息查询、确认或决定不虚构空文件。
-7. 角色 AI 收到任务后先与本角色 human owner 对齐，形成成果后完成专业自审并取得负责人确认，才可正式返回。
+7. 成员收到任务后先用简明中文与当前负责人对齐；形成成果后完成专业自审并取得负责人确认，再通过 Etunel 正式返回。
-8. Hub 只校验身份、结构、版本、证据、确认状态、跨角色冲突、依赖和门禁，不替专业角色判断内容是否充分。
+8. 面向负责人、角色或钉钉的内容使用自然、简洁的中文。机器字段和枚举只留在工具参数或机器记录中，不把内部术语和 ID 倾倒给人。
-9. 项目模式、任务结果、成果生命周期、成果适用性、阶段门禁、测试结论、业务验收和消息通知是不同状态层；不适用项统一只写 NA，也不混用状态。
+9. Hub 只校验角色、结构、版本、证据、确认状态、跨角色冲突、依赖和门禁，不替专业角色补写内容或作出专业结论。
-10. 正式项目只在已有成果覆盖且取得必要确认时受控跳转。明确的流程模拟可记录 BYPASSED_WITH_RISK 和 SIMULATION_ONLY，并只能以 SIMULATION_COMPLETED 结束。
+10. Hub 按阶段保存角色提交的文件，维护项目进度、阶段记录和成果索引。必要成果未保存且不可访问时，不宣布正式阶段交接完成。
-11. Etunel 运行时负责队列、投递、重试、去重、会话授权和文件传输；本 Skill 不另造这些软件机制。
+11. 流程可按 Hub 负责人明确决定跳转、回退或暂缓；Hub 必须记录缺失成果、原因、影响、风险和补齐安排，且不得把未满足门禁写成已通过。正式交付仍需补齐适用成果与必要确认；模拟流程不能冒充真实交付。
-12. 当前 Hook、工具 schema、项目角色契约、成员登记和已确认流程基线高于本 Skill 的通用说明；不存在的工具、角色或参数不得伪造。
+12. Etunel 运行时负责队列、投递、重试、去重、会话授权和文件传输；本 Skill 不重复设计这些软件机制。
 13. 当前 Hook、工具 schema、角色契约、`etunel_list_roles` 返回和已确认流程基线高于本 Skill 的通用说明；不存在的工具、角色、字段或文件不得伪造。
 ## 渐进式路由
 只读取当前工作需要的引用：
 - Hub：先读 [Hub 工作流](references/hub-workflow.md)。
- 创建项目、选择成员、配置自定义角色、成员交接、维护状态或发送状态快照：读 [成员与项目状态](references/project-status-and-membership.md)。
+- 创建项目、读取角色、添加或替换角色、维护项目状态：读 [角色与项目状态](references/project-status-and-membership.md)。
 - 选择阶段、正式成果、任务波次或交接：读 [项目生命周期](references/project-lifecycle.md)。
 - 成员：先读 [成员通用工作流](references/member-workflow.md)，再只读当前角色文件：
  - [业务](references/roles/business.md)
@@ -51,6 +51,8 @@ description: "用于 Etunel 多 Agent 项目的角色识别、Hub 中介、依
 - 准备派发、回复、跨角色中继、完成或报告阻塞：读 [Etunel 任务消息流程](references/etunel-message-lifecycle.md)。
 - 定义或校验成果、状态、版本、证据、额外产出或豁免：读 [成果与完成判定](references/artifacts-and-evidence.md)。
 - 缺信息、错投、阻塞、会议决定、返工、变更、流程跳转或模拟：读 [异常与协调](references/exceptions-and-coordination.md)。
 - 编写给负责人、角色或群组的任务、提问、结果和状态消息：读 [人类可读沟通](references/human-readable-communication.md)。
 - 创建项目资料目录、保存成员清单、归档成果、更新进度或阶段记录：读 [项目文件与进度留档](references/project-files-and-progress.md)。
 - 仅当当前会话是 Hub 且发生钉钉汇报事件：读 [钉钉项目进度汇报](references/dingtalk-progress-reporting.md)。
 - 测试角色仅在任务类型匹配时，按 [测试职责](references/roles/testing.md) 中的二级链接读取更深细则。
@@ -58,19 +60,20 @@ description: "用于 Etunel 多 Agent 项目的角色识别、Hub 中介、依
 ## 每项任务的控制循环
-1. 确认身份、成员映射、有效流程与成果基线、任务目标、主责边界和 human owner。
+1. 从运行时确认当前角色、项目、阶段、目标、输入、产出和负责人，不向人核对内部 ID。
-2. 向负责人复述任务；一次核对输入、输出、证据、版本、期限、完成条件和下游用途。
+2. 用简明中文一次说明要做什么、已有资料、还缺什么、会产出什么以及需要负责人确认什么。
-3. 信息足够后执行本角色工作；缺少跨角色输入时，先走负责人路径，再向 Hub 提交聚合请求。
+3. 信息足够后执行本角色工作；缺少跨角色输入时先问当前负责人，再向 Hub 提交一组聚合问题。
-4. 形成产出文件或成果包，完成专业自审并取得负责人确认。
+4. 形成指定文件或成果包，完成专业自审并取得负责人确认。
-5. 通过当前 Hook 和 Etunel schema 对应的工具返回结果、补充请求或正式阻塞。
+5. 使用当前 Etunel schema 对应的工具返回成果、补充请求或具体阻塞。
-6. Hub 校验并登记；合格则更新成果、状态、依赖和下一波次，不合格则精确补齐或按异常流程路由。
+6. Hub 校验并按阶段留档；合格则更新成果索引、项目进度、依赖和下一波次，不合格则只说明具体缺口。
 ## 提交前检查
- 身份、成员、会话、WORK_ID、SUBTASK_ID 和流程基线是否来自运行时？
+- 是否只确认了人需要知道的任务信息，没有要求负责人核对运行时 ID？
- 是否只有一个主责角色和主责成员，且未越过其他角色专业或批准边界？
+- 是否只有一个主责角色，且未越过其他角色的专业或批准边界？
- 输入是否足够，输出文件、证据、期限和完成条件是否与任务要求一致？
+- 输入是否足够，产出文件、证据、期限和完成条件是否与任务一致？
 - 自审、版本、负责人确认、开放项和风险是否明确？
- 状态层是否正确，NA、DEFERRED、WAIVED 和模拟状态是否被混用？
+- 人类可读内容是否使用简洁中文，机器字段是否留在工具或机器记录中？
- 是否把并行任务波次误当成无依赖广播，或把消息排队、通知接受误当成业务完成？
+- 必要成果是否已由 Hub 放入正确阶段目录并更新进度和成果索引？
 - 是否把任务波次误当成无依赖广播，或把排队、通知接受误当成业务完成？
 - 是否只使用当前 schema 中与本次意图匹配的 Etunel 工具？
@@ -1,4 +1,4 @@
 interface:
  display_name: "Etunel 多角色协作"
-  short_description: "约束 Hub 中介、成员状态、依赖任务波次、正式成果与消息流程"
+  short_description: "约束 Hub 中介、中文沟通、阶段成果与项目留档"
-  default_prompt: "Use $etunel-role-collaboration to identify my Etunel role and member mapping, load only the relevant workflow and role rules, and complete the current project task through the Hub-mediated Etunel process."
+  default_prompt: "使用 $etunel-role-collaboration 确认我的当前角色，只读取本任务需要的流程和职责规则，并通过 Hub 中介完成任务与阶段留档。"
@@ -4,50 +4,49 @@ Hub 定义任务产出、成员提交结果、判断状态或校验门禁时读
 ## 正式成果集合
-正式门禁成果只使用以下名称：
+人工可读的正式成果统一使用以下中文名称：
 | 阶段 | 正式成果 |
 |---|---|
-| 1 业务需求 | Project Background Brief；Project Milestone Plan |
+| 1 业务需求 | 项目背景说明；项目目标与里程碑计划 |
-| 2 产品定义 | Project Initiation Package；Test & Acceptance Criteria；Milestone Requirements |
+| 2 产品定义 | 立项资料；测试验收标准；里程碑要求 |
-| 3 方案设计 | Solution Architecture；Software/Hardware Interface Contract；Hardware Design Package；Architecture Decision Record；Test Plan |
+| 3 方案设计 | 总体技术方案；软硬件接口契约；硬件设计包；架构决策记录；测试计划 |
-| 4 项目规划 | Project Plan；Risk Register；Role Assignment；Product Documentation Package；Project Status Record |
+| 4 项目规划 | 项目计划；项目风险；角色分工；产品资料整合；项目状态内部记录 |
-| 5 软硬件实现 | Hardware Implementation Package；Low-Level Implementation Package；Application Firmware Package |
+| 5 软硬件实现 | 硬件实现资料；嵌入式底层实现资料；嵌入式应用层固件包 |
-| 6 测试验证 | Functional Test Report；Reliability Test Report；Specialized Test Report；Test Evidence Package；Defect Analysis Report |
+| 6 测试验证 | 功能测试报告；可靠性测试报告；专项测试报告；测试证据包；缺陷分析报告 |
-| 7 业务验收 | Platform Test Approval Report；Customer Acceptance Approval Report；Conditional Acceptance Items |
+| 7 业务验收 | 平台提测通过报告；客户验收通过报告；附条件验收事项 |
-| 8 发布结项 | Closure Documentation Archive；Change Log；Closure Report；Process Closure Summary |
+| 8 发布结项 | 结项资料归档；变更记录；结项报告；流程闭环总结 |
-角色自定义文件可作为 supporting、internal 或 ADDITIONAL 材料，但不能替代适用正式成果。阶段 6 的质量结论和通用证据必须归入对应测试报告、Test Evidence Package 或 Defect Analysis Report，不另立正式成果类别。
+角色自定义文件可以作为支持材料、内部材料或额外成果，但不能替代适用的正式成果。阶段 6 的质量结论和通用证据必须归入对应测试报告、《测试证据包》或《缺陷分析报告》，不另立正式成果类别。
-## 先定义产出契约
+## 先定义产出要求
 正式执行任务派发时明确：
-1. 正式成果或内聚成果包名称及主责角色、主责成员；
+1. 正式成果或成果包名称及唯一主责角色；
 2. 每项最低内容、适用子项和协作边界；
-3. 输入基线、版本、supersedes 和可追踪引用；
+3. 输入基线、版本、旧版替代关系和可追踪引用；
-4. 所需证据及未执行验证的表达方式；
+4. 所需证据及未执行验证应如何说明；
-5. 下游用途、期限和可检查完成条件；
+5. 下游用途、期限和可以检查的完成条件；
 6. 本角色必须给出的专业结论；
-7. 专业自审和 human owner 确认要求。
+7. 专业自审和负责人确认要求。
-任务要求和实际产出应一一对应。纯信息、澄清和批准决定不为形式创建空文件，但答复仍需可追踪、经有权角色确认且结论明确。
+任务要求和实际产出必须一一对应。纯信息、澄清和批准决定不为形式创建空文件，但答复仍需来源清楚、经有权角色确认且结论明确。
-## 任务结果最低结构
+## 正式结果最低内容
-不强制统一复杂 JSON，但正式结果必须让 Hub 找到：
+不强制所有角色填写复杂 JSON，但正式结果必须让 Hub 找到：
- WORK_ID、SUBTASK_ID、模式、流程基线、阶段、波次；
+- 当前阶段和使用的输入基线；
- semantic role、实际 role ID、主责成员、session、human owner 和输入基线；
+- 实际完成内容和期限状态；
- 实际完成内容和要求完成时间状态；
+- 成果中文名称、文件位置或附件、版本和旧版替代关系；
 - 成果名称、位置或传输引用、版本及 supersedes；
 - 每项完成条件对应的证据；
- NA、未执行项、开放问题、依赖和剩余风险；
+- 不适用项、未执行项、开放问题、依赖和剩余风险；
 - 本角色明确结论：满足、部分满足或无法满足；
- self_check_result；
+- 专业自审结果；
- internal_approved，以及确认人、时间、范围和条件。
+- 负责人、确认时间、确认范围和附带条件。
-一句“已完成”“没问题”或“测试通过”不能关闭任务。
+一句“已完成”“没问题”或“测试通过”不能关闭任务。运行时消息标识由 Etunel 工具关联，不进入成果正文。
 ## 状态分层
@@ -62,57 +61,55 @@ Hub 定义任务产出、成员提交结果、判断状态或校验门禁时读
 7. 业务验收结论；
 8. Etunel 消息或钉钉通知状态。
-按当前运行时或角色规则记录状态属于哪一层。任务成功不等于成果已基线；成果存在不等于门禁满足；测试 PASS 不等于业务验收；消息 Consumed 或通知 ACCEPTED 不等于项目完成。
+任务成功不等于成果已经成为基线；成果存在不等于门禁满足；测试通过不等于业务验收；消息已处理或钉钉已接受不等于项目完成。机器记录可以保留运行时枚举，但面向负责人时使用中文解释。
-internal_approved=true 是本次消息／提交的人工确认字段；INTERNALLY_APPROVED 是成果生命周期语义。前者不能自动替代后者，成果状态仍需按其版本、证据和流程明确更新。
+## 任务包与多任务
-## 内聚任务包与多任务
+- 同一角色、同一基线、紧密相关且共同交付的成果可以组成一个任务包；全部必需产出满足才算完成。
-
+- 能独立验收、失败或服务不同依赖的工作保持独立任务，即使在同一波次发送。
- 同一角色、同一基线、紧密相关且共同交付的成果可组成一个任务包；全部必需产出满足才成功。
+- 包内有效成果保留，未完成部分可以拆成后续任务；一个子项失败不能被其他成功掩盖。
 - 能独立验收、失败或服务不同依赖的工作使用独立 SUBTASK_ID，即使同批发送。
 - 包内有效成果保留，未完成部分可拆为关联新任务；一个子项失败不能被其他成功掩盖。
 ## 专业自审和人类确认
-self_check_result 说明角色如何按任务契约检查产出，可为 PASS、PARTIAL 或 FAIL，并列出依据与例外。
+自审结果说明角色如何按任务要求检查产出，可以是“通过”“部分通过”或“未通过”，并列出依据与例外。
-internal_approved 表示本角色 human owner 实际查看本次结果并确认可作为角色正式提交。至少记录确认人、时间、文件／版本／范围和附带条件。AI 不得自行设为 true；模拟项目只确认模拟使用和流程推进，不证明模拟值真实。
+负责人确认表示当前负责人实际查看本次结果并确认可以作为该角色正式提交。至少记录确认人、时间、文件或版本、范围和附带条件。AI 不得自行声称已获确认；模拟项目只确认模拟材料的使用和流程推进，不证明模拟值真实。
-## 适用性、NA 与豁免
+## 不适用、延期与成果豁免
- 适用内容必须形成；不适用统一标记 NA，并说明条件和依据。
+- 不适用内容写“不适用”，机器记录可以使用 `NA`，并说明条件和依据。
- NA 只表示不适用，不能表示时间不足、环境缺失、尚未执行、失败或阻塞。
+- 不适用不能表示时间不足、环境缺失、尚未执行、失败或阻塞。
- DEFERRED 是延后；WAIVED 是完成正式豁免；二者都不等于 NA。
+- 延期和正式豁免都不等于不适用。
- 适用内容缺失不能用 NA 掩盖；固定成果不能靠空文件或虚假 PASS 通过。
+- 适用内容缺失不能靠空文件或虚假“通过”穿过门禁。
-Artifact Waiver 由成果主责角色提出，提供成果标识、阶段、NA 原因、替代证据、下游影响、风险和内部确认。Hub 识别受影响角色与门禁：
+《成果豁免申请》由成果主责角色提出，提供成果名称、阶段、不适用原因、替代证据、下游影响、风险和负责人确认。Hub 识别受影响角色与门禁：
 1. 受影响角色负责人确认不会产生需求、接口、实现、测试、发布或审计缺口；
-2. 低影响、无专业争议时，Hub AI 可完成形式审查、批准和登记；
+2. 低影响且无专业争议时，Hub 可以完成形式审查、批准和登记；
-3. 涉及范围、质量、安全、合规、客户承诺、重大风险、不可逆影响或存在争议时，升级业务和相关专业角色，必要时由 Hub 负责人介入；
+3. 涉及范围、质量、安全、合规、客户承诺、重大风险、不可逆影响或争议时，升级业务和相关专业角色，必要时由 Hub 负责人介入；
-4. 只有状态为 WAIVED、批准记录完整才满足对应门禁；
+4. 只有正式豁免记录完整，才满足对应门禁；
-5. 条件变化使成果重新适用时撤销豁免并恢复 REQUIRED。
+5. 条件变化使成果重新适用时，撤销豁免并恢复为必需。
 ## 额外产出
-角色可提交职责内有价值的额外文件，标记 ADDITIONAL 并说明与原任务的关系、对完成结论的影响、下游用途以及新增依赖、风险和维护责任。
+角色可以提交职责内有价值的额外文件，说明它与原任务的关系、对完成结论的影响、下游用途以及新增依赖、风险和维护责任。
-Hub 可将其纳入成果索引。若改变范围、接口、成员责任、基线、排期、正式成果或验收，先走 Change Request，不静默生效。
+Hub 可以将其纳入成果索引。若改变范围、接口、角色责任、基线、排期、正式成果或验收，先走《变更申请》，不能静默生效。
 ## 事实、判断和证据
-结果应区分：已确认事实、原始证据、本角色专业判断、未验证假设、已批准决定、开放问题、外部依赖、剩余风险、客户期望、内部目标、正式承诺、REAL 与 SIMULATED 数据。
+结果应区分：已确认事实、原始证据、本角色专业判断、未验证假设、已批准决定、开放问题、外部依赖、剩余风险、客户期望、内部目标和正式承诺。模拟数据必须清楚标明，不能混入真实结果。
 研发自测不能替代测试独立结论；测试不能替代产品或业务验收。无法执行的检查说明原因、影响和恢复条件。
-## 版本与可追踪性
+## 版本、留档与可追踪性
-代码、固件、硬件、配置、设计、计划或报告给出足以唯一识别对象的版本／引用，并说明上游输入、产生或验证版本、被替代旧版本、与接口／板卡／BOM／ECO／构建／环境的匹配关系和下游约束。
+代码、固件、硬件、配置、设计、计划或报告给出足以识别对象的版本或引用，并说明上游输入、产生或验证版本、被替代旧版本、与接口、板卡、BOM、ECO、构建或环境的匹配关系和下游约束。
-新结果不能静默覆盖旧基线。正式变更保留旧版本、新版本、生效范围和 supersedes 关系。
+新结果不能静默覆盖旧基线。Hub 按 [项目文件与进度留档](project-files-and-progress.md) 保存文件、更新成果索引和阶段记录；正式变更保留旧版本、新版本和生效范围。
 ## Hub 校验边界
-Hub 检查文件存在、最低结构、身份、版本、证据引用、自审、负责人确认、冲突、依赖、状态层和门禁；不替专业角色判断内容是否充分。专业冲突定向交拥有决定权的角色。
+Hub 检查文件存在、最低结构、来源角色、版本、证据引用、自审、负责人确认、冲突、依赖、状态层、留档和门禁；不替专业角色判断内容是否充分。专业冲突定向交拥有决定权的角色。
 向下游只传递任务需要的已登记成果、版本、约束、风险和证据引用，不复制完整聊天或全部资料。
@@ -8,71 +8,69 @@
 - 项目配置为启用时视为持续发送授权，不需每条消息再次询问。
 - 只能调用项目封装入口：
-  `./scripts/dingtalk-progress <start|milestone|blocked|complete|failed> "<简短、人类可读的摘要和下一步>"`
+  `./scripts/dingtalk-progress <start|milestone|blocked|complete|failed> "<中文 Markdown 摘要>"`
 - Agent 不得直接调用底层 OpenAPI、`dws api` 或其他消息入口绕过封装脚本。
 - Agent 不读取、修改、输出或请求 Client Secret、DING_SEC、App Token、Client ID、robotCode、openConversationId 等凭据和内部标识。
 - Skill 与消息正文不得硬编码项目 Client ID、robotCode、openConversationId、Client Secret 或群名；项目差异只由 `.dingtalk/config.env` 和封装脚本处理。
-## 汇报单位
+## 汇报单位与顺序
-汇报以整个 WORK_ID 生命周期为单位。Hub 聚合阶段、任务波次和 SUBTASK_ID 的结果，不为每条队列消息、普通回复、单个小步骤或短小只读问答发送通知。
+汇报以整个项目生命周期为单位。Hub 合并同一阶段或任务波次的相关结果，不为每条队列消息、普通回复、单个小步骤或短小只读问答发送通知。
 Hub 必须先确认进展真实有效，并完成成果文件、成果索引和项目进度留档，再发送钉钉消息。钉钉发送失败不回滚留档，也不阻塞 Etunel 主任务。
 ## 事件判定
 ### start
-每个 WORK_ID 最多一次。在第一个真实可执行任务或任务波次已经通过 Etunel 实际派发后发送。仅建立计划、等待输入或讨论想法时不发送。
+每个项目最多一次。在第一个真实可执行任务或任务波次已经通过 Etunel 实际派发后发送。仅建立计划、等待输入或讨论想法时不发送。
 ### milestone
-在可验证、会改变下一步的实质进展发生时发送，例如：
+在可验证、会改变下一步的实质进展完成并已留档时发送，例如：
- 关键基线／成果包经校验成为有效版本；
+- 关键成果或版本成为当前有效版本；
 - 一个有意义的任务波次完成并触发角色或阶段交接；
 - 门禁、受控跳转、回退或豁免完成真实记录和必要确认；
 - 正式阻塞解除，项目恢复到明确下一动作；
 - 统一固件、版本矩阵、测试结论、验收或发布组合形成。
-同一处理轮或同一波次的相关结果合并成一条，不逐个 SUBTASK_ID 刷屏。没有固定时间间隔；依靠事件语义和去重控制频率。
+同一处理轮或同一波次合并成一条，不逐个小任务刷屏。没有固定时间间隔；依靠事件语义和去重控制频率。
 ### blocked
 出现下列实际阻塞时立即发送：
- 角色已完成负责人询问和必要线下协调，仍需用户、Hub 负责人或外部条件才能继续；
+- 角色已经询问负责人并完成必要线下协调，仍需用户、Hub 负责人或外部条件才能继续；
 - 关键路径等待有权决定；
 - Etunel 的任务投递、成员返回、会话或消息链路实际中断。
-普通排队、正常等待、角色仍可自行推进或尚未完成产出不算 blocked。阻塞解除后用 milestone 汇报恢复，不修改历史消息。
+普通排队、正常等待、角色仍可自行推进或尚未完成产出不算阻塞。阻塞解除后用 `milestone` 汇报恢复，不修改历史消息。
 ### complete
-整个 WORK_ID 或用户明确指定的整体目标最终完成时发送一次。模拟项目必须写 `SIMULATION_COMPLETED`，不得表达真实发布、客户验收或生产就绪。
+整个项目或用户明确指定的整体目标最终完成时发送一次。模拟项目必须明确写“模拟完成”，不得表达真实发布、客户验收或生产就绪。
 ### failed
-整个 WORK_ID／整体目标已最终终止、无法恢复或明确失败时发送。可返工的测试 FAIL、单个 SUBTASK_ID 失败或临时脚本异常不使用 failed。
+整个项目或整体目标已经最终终止、无法恢复或明确失败时发送。可返工的测试失败、单个任务失败或临时脚本异常不使用 `failed`。
 ## 消息写法
-写成一段短摘要，或 2–4 条简洁要点，像项目负责人向团队说明进展，不像日志转储。优先包含：
+使用中文 Markdown 自然排版，可以使用标题、短段落和列表，不要求固定模板，也不要把全部内容挤成一行。像项目负责人向团队说明进展，不像日志转储。
- 可公开的项目名或 WORK_ID、正式／模拟模式；
+根据事件选择必要内容：项目名称、当前阶段、已验证进展、关键成果、下一步和责任角色；阻塞时再说明问题、影响以及需要谁采取什么动作。通常保持一屏内可读。
 - 当前阶段或任务波次；
 - 已验证进展、关键成果或版本；
 - 下一步和主责角色；
 - blocked 时补充原因、影响和需要谁采取什么动作。
-只写已验证结论。不得包含密钥、Token、个人数据、客户敏感信息、大段日志、完整内部对话或未经验证的根因推断。
+不在正文中写运行时 ID、英文成果名、机器状态码或内部字段。只写已验证结论，不得包含密钥、Token、个人数据、客户敏感信息、大段日志、完整内部对话或未经验证的根因推断。
 ## 调用与结果
-1. Hub 判断事件并合并摘要。
+1. Hub 判断事件并形成中文 Markdown 摘要。
 2. 调用封装脚本一次；脚本自行处理配置检查、发送和有限重试。
-3. 只有真实发送响应含非空 `processQueryKey`，才记为 `ACCEPTED`，含义仅是钉钉服务端接受，不证明群成员已读。
+3. 只有真实发送响应包含非空 `processQueryKey`，才表示钉钉服务端已经接受；不证明群成员已读。
-4. 缺少或未启用配置记为 `SKIPPED`；dry-run 记为 `DRY_RUN`；没有有效 key 或最终发送错误记为 `FAILED_OR_UNKNOWN`。
+4. 缺少或未启用配置时安全跳过；预览模式只检查请求，不视为真实发送。
-5. `SKIPPED`、`DRY_RUN` 和发送前配置／依赖校验错误不重试。真实发送失败或响应无有效 key 时，由脚本最多总计尝试 3 次，尝试间隔 10 秒；首次成功立即停止。未知响应重试可能造成极少量重复通知，按当前项目策略接受。
+5. 真实发送失败或没有有效 key 时，脚本最多总计尝试 3 次，间隔 10 秒；首次成功立即停止。
-6. 三次仍失败只终止本次钉钉发送，Etunel 主任务继续。Hub 在本地最终结果中向负责人说明一次，不再递归发送 blocked／failed，不自动补发历史事件。
+6. 三次仍失败只终止本次钉钉发送，Etunel 主任务继续。Hub 在本地结果中向负责人说明一次，不递归发送新的阻塞或失败通知，也不自动补发历史事件。
-脚本输出和退出码用于判断通知调用，不得把钉钉结果升级成项目门禁。Agent 不自行在脚本外追加重试循环。
+脚本输出和退出码只用于判断通知调用，不得把钉钉结果升级成项目门禁。Agent 不在脚本外追加重试循环。
@@ -2,98 +2,87 @@
 准备派发、补充、跨角色中继、返回、完成、阻塞或结算 Hub 入站消息时读取。当前 Hook 和 MCP schema 是工具名、参数与授权的最终依据；本文只约束职责和消息意图。
-## 标识与身份
+## 真实工具边界
-| 标识 | 含义 |
+Etunel 是严格的 Hub 星型拓扑：成员只能向 Hub 发送，只有 Hub 可以向角色发送。
 |---|---|
 | WORK_ID | 贯穿项目生命周期的工作容器 |
 | 流程基线／阶段 | 当前 WORK_ID 已登记的流程版本与位置 |
 | 任务波次 | 同一有效基线下依赖已满足、可连续派发的一组任务 |
 | SUBTASK_ID | 一个主责角色和主责成员可独立判定的一项任务 |
 | role/member/session | 语义角色、实际角色实例、主责成员和绑定会话 |
 | message_id | 一条 Etunel 消息的单跳关联或结算标识 |
-正文已有有效标识时复用。已终态 SUBTASK_ID 不重新作为活动任务；运行时字段命名不同则按实际 schema 映射。
+| 意图 | 调用者 | 工具 |
 ## 工具职责
 | 意图 | 调用者 | Etunel 工具 |
 |---|---|---|
-| 向一个角色派发一条任务消息 | Hub | etunel_send_to_role，kind=task |
+| 读取实际角色 | Hub | `mcp__etunel__etunel_list_roles` |
-| 向同一来源角色返回信息或终态状态 | Hub | etunel_send_to_role，kind=reply 或 kind=status，并按 schema 关联来源 message_id |
+| 向一个角色发送任务、回复或状态 | Hub | `mcp__etunel__etunel_send_to_role` |
-| Hub 已处理入站且无需回复 | Hub | etunel_complete_coordination |
+| 结算无需回复的成员协调消息 | Hub | `mcp__etunel__etunel_complete_coordination` |
-| 成员向 Hub 补充、聚合询问或报告非终态状态 | 成员 | etunel_send_to_hub |
+| 成员向 Hub 补充或提问 | 成员 | `mcp__etunel__etunel_send_to_hub` |
-| 成员成功结束自己的任务 | 主责成员 | etunel_complete_task |
+| 成员完成任务并交付成果 | 成员 | `mcp__etunel__etunel_complete_task` |
-| 成员以具体阻塞结束自己的任务 | 主责成员 | etunel_report_blocked |
+| 成员以具体阻塞结束任务 | 成员 | `mcp__etunel__etunel_report_blocked` |
-| 读取当前消息列出的必要附件 | 当前绑定会话 | etunel_receive_message |
+| 读取必要附件或旧式消息 | 当前绑定会话 | `mcp__etunel__etunel_receive_message` |
-工具未暴露、名称或参数不同，以当前 Hook 和 schema 为准并报告能力缺口；不得猜参数或请求内部授权字段。
+工具未暴露、名称或参数改变时，以当前 schema 为准并报告能力缺口；不得猜参数或请求内部认证字段。
 ## 机器字段不进入人类正文
 - Hub 用 `role` 路由，面向人使用 `display_name`。
 - `message_id` 是 Etunel 消息标识；需要完成、阻塞或结算时从入站消息取值。
 - `correlation_id` 只用于把回复或状态关联到来源消息。
 - 这些字段只进入工具参数。任务正文、负责人对话、成果标题和钉钉消息不要求抄写或确认。
 - Etunel schema 没有 member ID；Skill 不得创造 member、session 或任务 ID 字段。
 ## 任务波次如何发送
-etunel_send_to_role 一次调用只发送一个接收角色和一条消息：
+`mcp__etunel__etunel_send_to_role` 一次调用只发送一个接收角色和一条消息：
- 同一角色多个独立 SUBTASK_ID 可连续发送，由 Etunel 队列处理；
+- 同一角色的多个独立任务可以连续发送，由 Etunel 队列处理；
- 同一角色紧密相关且共同交付的内容可合并为内聚任务包；
+- 同一角色紧密相关且共同交付的内容可以合并为任务包；
 - 不同角色的依赖就绪任务分别发送、独立返回；
- 排队不代表角色业务并行完成，也不代表下游依赖已经满足。
+- 排队不代表业务并行完成，也不代表下游依赖已经满足。
-Hub 不实现队列、ACK、锁、重试、去重或文件传输；这些由 Etunel 软件承担。
+Hub 不实现队列、确认包、锁、重试、去重或文件传输；这些由 Etunel 软件承担。
 ## Hub 发送任务
-每条正式任务消息应包含：
+Hub 调用 `mcp__etunel__etunel_send_to_role` 时：
- WORK_ID、SUBTASK_ID、模式、流程基线、阶段和波次；
+- `role` 使用 `etunel_list_roles` 返回的实际值；
- semantic role、实际 role ID、主责成员、session、human owner 和协作角色；
+- `kind` 按当前 schema 使用任务、回复或状态意图；
- 目标、背景、上游成果、输入版本和成果引用；
+- `text` 使用简洁中文说明目标、背景、有效输入、范围、产出文件、证据、期限、完成条件和负责人确认要求；
- IN_SCOPE、OUT_OF_SCOPE、依赖、接口、限制和风险；
+- `attachment_paths` 只附当前任务实际需要的文件；
- 指定成果及最低内容、证据、版本、下游用途；
+- 回复同一来源角色时，按 schema 使用 `correlation_id`，不把该值写入正文。
 - 要求完成时间、完成条件和职责内结论；
 - 专业自审和 human owner 确认要求；
 - 信息不足、额外产出和阻塞的处理边界。
-纯信息、澄清或授权消息写清问题、已确认事实、影响、选项和所需答复，不要求空文件。不要转发无关聊天、全量计划或无法消化的资料堆。
+纯信息、澄清或授权消息写清问题、已确认事实、影响和所需答复，不要求空文件。不要转发无关聊天、全量计划或无法消化的资料堆。
 ## 成员请求补充
-成员先询问自己的负责人并完成必要线下沟通。仍需 Hub 时，用一条 etunel_send_to_hub 写清：
+成员先问当前负责人并完成必要线下沟通。仍需 Hub 时，用一条 `mcp__etunel__etunel_send_to_hub` 写清：
- SUBTASK_ID、已完成工作和现有成果；
+- 已经完成什么、现有成果在哪里；
- 聚合后的缺失信息／决定及用途；
+- 还缺什么信息或决定，为什么需要；
- 已向负责人询问和线下协调的结果；
+- 已经询问和协调的结果；
- 对结论、范围、期限、风险和下游的影响；
+- 缺失对范围、期限、风险和下游的影响；
- 建议的信息所有者角色；
+- 建议向哪个角色获取；
- 当前仍可继续的范围与希望 Hub 返回的具体内容。
+- 当前还能继续什么，希望 Hub 返回什么。
-Hub 已有登记答案时一次补足；没有时才产生必要的跨角色查询或任务。
+Hub 已有登记答案时一次补足；没有时才创建必要的跨角色查询或任务。
 ## 经 Hub 的跨角色中继
-当前 Etunel 没有成员间直连工具。跨角色交流必须是：来源成员 → Hub → 目标成员 → Hub → 来源成员。
+跨角色交流必须是：来源成员 → Hub → 目标成员 → Hub → 来源成员。
 - Hub 忠实保留问题、适用范围和来源，不替任一角色作专业改写；
 - 目标角色返回前完成专业自审和负责人确认；
- Hub 校验并登记确认结论后，才向来源角色返回最小必要内容；
+- Hub 校验并登记确认结论后，才向来源角色返回最少必要内容；
- 给另一个角色的新 task 是独立消息，不能拿来源角色的 message_id 充当跨角色结算；
+- 给另一个角色的新任务是独立消息，不能拿来源消息标识充当跨角色结算；
- 只有按当前 schema 返回同一来源角色的关联 reply/status 才结算该来源协调项；
+- 对同一来源角色的回复或状态按当前 schema 关联，其他情况由 Hub 明确结算来源协调项。
 - 一个跨角色 task 的发送不能替代对原入站消息的正确处理。
-默认一次聚合请求和一次答复；复杂异常使用 Meeting Decision Record，不把多轮聊天当成项目事实。
+普通问题默认一次聚合请求和一次答复；复杂异常使用《会议决定记录》，不把多轮聊天当成项目事实。
 ## Project Status Snapshot
 状态快照只由 Hub 向受影响角色发送，是裁剪后的状态同步，不是新专业任务、成果或门禁。写明变化、有效版本、对接收方影响、下一步、责任方和期限；同一处理轮聚合一次。若需要角色执行动作，应另有明确 task 或按当前 schema 明确消息意图。
 ## 成员完成或阻塞
-调用 etunel_complete_task 前，确认指定成果、证据、版本、期限状态、专业自审、负责人确认和明确结论均已包含。
+调用 `mcp__etunel__etunel_complete_task` 前，成员确认指定成果、证据、版本、期限状态、专业自审、负责人确认和明确结论都已包含，并通过 `attachment_paths` 发送实际文件。
-调用 etunel_report_blocked 时至少说明：
+调用 `mcp__etunel__etunel_report_blocked` 时，用简明中文说明：
- 阻塞条件；
+- 当前阻塞；
- 已完成成果和已尝试排查／负责人／线下协调；
+- 已完成成果和已尝试的排查、负责人沟通及线下协调；
- 缺失输入或决定及建议责任人；
+- 缺失输入或决定及建议责任角色；
 - 对本任务和下游的影响；
 - 恢复条件和建议下一步。
@@ -103,13 +92,13 @@ Hub 已有登记答案时一次补足；没有时才产生必要的跨角色查
 Hub 对每条入站消息选择：
- 需要向同一来源角色回复：按 schema 发送关联 reply/status；
+- 需要回复同一来源角色：发送关联回复或状态；
- 无需回复且已处理：调用 etunel_complete_coordination；
+- 无需回复且已经处理：调用 `mcp__etunel__etunel_complete_coordination`；
- 需要其他角色：正确处理来源协调项，并按依赖创建一个或多个必要任务；
+- 需要其他角色：先正确处理来源协调项，再按依赖创建必要任务；
- 同一轮到达多个相关结果：先更新成果、状态和依赖，再统一选择下一波次。
+- 同一轮到达多个相关结果：先更新成果、留档、状态和依赖，再选择下一波次。
-消息结算、排队和送达不代表 SUBTASK_ID、成果、阶段或 WORK_ID 完成。
+消息结算、排队和送达不代表任务、成果、阶段或项目完成。
 ## 附件
-直接使用当前消息正文和内嵌内容。仅当消息明确列出附件且为当前任务必要输入时，调用 etunel_receive_message 获取所需附件。不要为探测队列或重复确认而读取。
+直接使用当前消息正文和内嵌内容。仅当消息明确列出附件且为当前任务必要输入时，调用 `mcp__etunel__etunel_receive_message` 获取所需附件。Hub 收到成果文件后按 [项目文件与进度留档](project-files-and-progress.md) 归档；不要为探测队列或重复确认而读取。
@@ -7,24 +7,25 @@
 成员按以下顺序处理：
 1. 检查任务和本会话已有的已确认资料；
-2. 一次向本角色负责人列清缺什么、用途、影响和建议来源；
+2. 一次向当前负责人列清缺什么、用途、影响和建议来源；
 3. 负责人能回答时记录来源、时间、范围和条件后继续；
 4. 负责人不能回答时，提醒其线下寻找能解决问题的人；
-5. 线下结果回到本角色会话，经本角色负责人确认；
+5. 线下结果回到本角色会话，经负责人确认；
-6. 仍无法解决，或必须取得另一角色正式成果时，向 Hub 发送一组聚合问题或正式阻塞。
+6. 仍无法解决，或必须取得另一角色正式成果时，向 Hub 发送一组聚合问题或具体阻塞。
 Hub 有登记答案时直接补足；没有时只向实际信息所有者角色创建必要查询或任务。取得确认结果后返回原任务，不广播无关角色。
 ## 结果不完整
- 原任务目标不变；Hub 只列缺失成果、字段、证据、版本、自审或确认。
+- 原任务目标不变；Hub 只列缺失成果、内容、证据、版本、自审或确认。
- 已终态任务使用关联的新 SUBTASK_ID 补齐；有效部分保留，不要求无关重做。
+- 已经有效的部分保留，不要求无关重做；未完成部分由 Hub 派发关联的后续任务。
- 补齐后按原契约重新校验。
+- 补齐后按原要求重新校验。
- Hub 不用推测补专业结论，也不为一个格式字段增加虚假评审层。
+- Hub 不用推测补专业结论，也不为一个格式问题增加虚假评审层。
 - 影响进度或具有复盘价值的退回按 [项目文件与进度留档](project-files-and-progress.md) 记录。
 ## 错投与职责冲突
-成员保留本角色已完成部分，向 Hub 说明错误身份／成员、越界内容、影响和建议责任方。Hub 按决定权路由：
+成员保留本角色已完成部分，向 Hub 说明错投或越界内容、影响和建议责任方。Hub 按决定权路由：
 - 目标、业务范围、优先级、资源、组织授权和最终业务风险接受：业务；
 - 产品行为、需求含义、用例与验收标准：产品；
@@ -32,93 +33,95 @@ Hub 有登记答案时直接补足；没有时只向实际信息所有者角色
 - 应用逻辑、状态机、应用协议和应用服务：嵌入式应用层；
 - BSP、Bootloader、驱动、RTOS、系统服务和 HAL：嵌入式底层；
 - 电路、PCB、器件、BOM、电源、信号、热和板卡：硬件；
- Test Plan、环境、用例、证据、缺陷复验与质量结论：测试；
+- 测试计划、环境、用例、证据、缺陷复验与质量结论：测试；
- 已登记自定义领域：按其角色契约，不隐式夺取默认角色权责。
+- 已登记自定义领域：按其职责契约，不隐式夺取默认角色权责。
-跨多个领域时，技术负责人界定接口和依赖；每项后续任务仍只有一个主责角色和成员。
+跨多个领域时，技术负责人界定接口和依赖；每项后续任务仍只有一个主责角色。
 ## 阻塞与异常提醒
-正式阻塞说明原因、已完成成果、负责人沟通、线下协调、影响、需要谁采取什么动作以及恢复条件。
+正式阻塞用简明中文说明原因、已完成成果、负责人沟通、线下协调、影响、需要谁采取什么动作以及恢复条件。
 - Hub 评估关键路径；不受影响的任务继续。
- Hub 主动提醒当前主责和实际关联角色，提供问题、证据、冲突点、影响、原流程位置、所需回应和期限；不机械通知全体角色。
+- Hub 主动提醒当前主责和实际关联角色，提供问题、证据、影响、原流程位置、所需回应和期限；不机械通知全体角色。
- 能由一个角色解决时只派该角色；多个独立问题可形成波次。
+- 能由一个角色解决时只派该角色；多个独立问题可以形成波次。
 - 没有现成责任人时提醒当前负责人线下找能解决问题的人。
 - 需要用户、业务、项目发起人或重大争议决定时，Hub 负责人介入。
- 阻塞解除后，终态任务使用关联的新 SUBTASK_ID。
+- 阻塞解除后由 Hub 派发新的恢复或返工任务。
-Etunel 投递、成员返回、会话或消息链路实际中断是流程阻塞；正常排队和等待不是阻塞。
+Etunel 投递、成员返回、会话或消息链路实际中断是流程阻塞；正常排队和等待不是阻塞。阻塞发生和解除都更新项目进度与阶段记录。
-## 复杂线下会议与 Meeting Decision Record
+## 复杂线下会议与会议决定记录
 普通线下补充不强制会议记录。跨角色冲突复杂、证据矛盾或在线任务已阻塞时：
-1. Hub 准备问题包和结论模板，不主持专业裁决；
+1. Hub 准备问题包和结论结构，不主持专业裁决；
-2. 当前主责角色的真人负责人组织线下会议；
+2. 当前主责角色的负责人组织线下会议；
-3. 参与者把各自专业结论带回对应角色会话，完成角色负责人确认；
+3. 参与者把各自专业结论带回对应角色会话，完成负责人确认；
-4. 当前主责角色汇总一份 Meeting Decision Record，至少包含参与角色、问题、证据、各专业确认、统一结论、适用范围、版本、不同意见、风险、行动项、责任人和期限；
+4. 当前主责角色汇总一份《会议决定记录》，包括参与角色、问题、证据、各专业确认、统一结论、适用范围、版本、不同意见、风险、行动项、责任人和期限；
-5. 当前主责角色向 Hub 提交该记录及参与方确认引用，其他角色不重复提交整份记录；
+5. 当前主责角色向 Hub 提交记录及参与方确认引用，其他角色不重复提交整份记录；
-6. Hub 只校验身份、确认、版本、证据、冲突和可执行性，登记后从原阻塞点恢复；
+6. Hub 只校验来源、确认、版本、证据、冲突和可执行性，登记并留档后从原阻塞点恢复；
-7. 结论改变正式基线时转入 Change Request。
+7. 结论改变正式基线时转入《变更申请》。
 会议记录不能让主责角色代替参与角色作出专业批准；缺少有权确认时仍保持阻塞。
 ## 缺陷与返工
-1. 测试创建并持续维护 Defect Analysis Report，记录被测组合、环境、复现、期望／实际、证据、风险、建议责任边界、复验和状态。
+1. 测试创建并持续维护《缺陷分析报告》，记录被测组合、环境、复现、期望与实际、证据、风险、建议责任边界、复验和状态。
 2. 根因边界不清时由技术负责人确认系统边界、版本关系或架构影响；Hub 不自行归因。
-3. Hub 向实际责任角色派发修复任务；相关缺陷可形成修复包，独立角色可形成修复波次。
+3. Hub 向实际责任角色派发修复任务；相关缺陷可以组成修复包，独立角色可以形成修复波次。
-4. 实现角色提交 Root Cause Analysis、Fix Plan、修复成果和版本、角色自测、影响与建议回归范围。
+4. 实现角色提交根因分析、修复计划、修复成果和版本、角色自测、影响与建议回归范围。
 5. 底层修复先交应用层重新合版；硬件 ECO 同步评估底层兼容、应用固件有效性和版本关系。
 6. 技术负责人确认新版本组合后，测试在目标组合独立复验。
-7. 只有测试可把 Defect Analysis Report 更新为 VERIFIED／CLOSED；实现角色和 Hub 无权替换或关闭。
+7. 只有测试可以确认缺陷已经复验或关闭；实现角色和 Hub 无权替换或关闭测试记录。
 产品负责需求含义，业务负责业务风险接受；这些决定不修改测试原始观察和质量结论。
-## Change Request
+## 变更申请
-任何改变已确认范围、方案、任务、正式成果、成员职责、接口、版本、排期或门禁的事项都走正式变更：
+任何改变已确认范围、方案、任务、正式成果、角色职责、接口、版本、排期或门禁的事项都走正式变更：
 1. Hub 冻结受影响任务，登记来源、原因、目标、当前基线、影响对象和紧急性；
-2. 产品、技术负责人、实际受影响实现／自定义角色和测试分别评估；
+2. 产品、技术负责人、实际受影响实现或自定义角色和测试分别评估；
 3. Hub 汇总范围、技术、实现、测试、资源、成本、质量、风险、完成工作和里程碑影响；
 4. 需要组织授权的变更由业务批准、拒绝或延期；
-5. 批准后创建新基线，保留旧版本和 supersedes，重开受影响阶段、成果、任务和门禁；
+5. 批准后创建新基线，保留旧版本，重开受影响阶段、成果、任务和门禁；
 6. 未批准不得边评估边实施，也不得用状态纠正规避变更。
-只联系真正受影响角色，不固定全角色参与。
+只联系真正受影响角色，不固定全角色参与。变更决定、受影响文件和新旧版本按阶段留档。
 ## 成果豁免
-固定正式成果不适用时，按 [成果与完成判定](artifacts-and-evidence.md) 发起 Artifact Waiver。NA、DEFERRED、SKIPPED、口头同意或空文件都不能替代 WAIVED。
+固定正式成果不适用时，按 [成果与完成判定](artifacts-and-evidence.md) 发起《成果豁免申请》。不适用、延期、跳过、口头同意或空文件都不能替代正式豁免。
-## 正式项目的受控跳转、暂缓与回退
+## 受控跳转、暂缓与回退
-正式项目只有在已有正式成果实际覆盖目标阶段并取得必要角色确认时才能受控跳转：
+正常正式推进应先取得目标阶段需要的成果和确认。流程验证、紧急协调或负责人明确要求时，也可以在存在缺口的情况下跳转、回退或暂缓，但这只是改变当前流程位置，不代表缺失门禁已经通过：
 - 记录发起人、原因、时间、现阶段、目标位置、复用成果及版本、未满足项、影响、风险、批准和恢复点；
- 使用当前运行时支持的真实受控跳转、回退或 DEFERRED 状态；任何正式要求未被既有成果覆盖时都不能通过门禁，也不得用 BYPASSED_WITH_RISK 代替；
+- 使用当前运行时支持的真实跳转、回退或暂缓状态；任何正式要求未被成果覆盖时都不能伪装成门禁通过；
 - Hub 负责人确认；影响范围、日期、资源、成本、质量、验收或专业结论时取得业务和相关角色确认；
- 下游明确知道缺失基线和风险；固定成果确实无需补做时另走 WAIVED。
+- 下游明确知道缺失基线和风险；记录后续补齐任务、责任角色和恢复条件；固定成果确认无需补做时另走成果豁免。
-跳转是流程状态，不是专业批准，也不保证可发布。
+按 [项目文件与进度留档](project-files-and-progress.md) 保留来源阶段与目标阶段记录，不移动或覆盖旧成果。跳转是流程状态，不是专业批准，也不保证可以发布。
-## 模拟／流程验证项目
+## 模拟与流程验证项目
-只有用户明确对整个 WORK_ID 启用模拟后可使用：
+只有用户明确对整个项目启用模拟后可使用：
- 可使用真实已知数据和为流程验证构造的数据；关键值标记 REAL 或 SIMULATED；
+- 可以使用真实已知数据和为流程验证构造的数据，清楚区分真实与模拟；
- 模拟值影响结论时，相关成果整体标记 SIMULATION_ONLY；
+- 模拟值影响结论时，相关成果整体标记为模拟；
- 可按明确指令临时跳过或进入后续节点，并记录 BYPASSED_WITH_RISK、假设、风险和恢复项，不让门禁卡死流程验证；
+- 可以按明确指令临时跳过或进入后续节点，并记录假设、风险和恢复项，不让门禁卡死流程验证；
- human owner 确认的是模拟使用和流程推进，不是数据真实性；
+- 负责人确认的是模拟使用和流程推进，不是数据真实性；
 - 不静默切回正式模式，不让模拟结论进入客户承诺、真实测试或生产发布；
- 结束状态只能是 SIMULATION_COMPLETED，不能写 CLOSED、RELEASED、CUSTOMER_ACCEPTED 或 PRODUCTION_READY。
+- 结束状态只能表达“模拟完成”，不能表达真实关闭、发布、客户验收或生产就绪。
 模拟文件和阶段记录必须明确标注，不能混入正式成果目录中的当前有效版本。
 ## 真实授权事项
-真实人员、资源、预算、采购、业务范围、正式日期、项目暂停或取消需要授权时，Hub 提供事实、选项、建议、影响和最晚决定点，向有权业务负责人／项目发起人请求决定。未决定前保持真实等待或阻塞，不解释为默认批准。
+真实人员、资源、预算、采购、业务范围、正式日期、项目暂停或取消需要授权时，Hub 提供事实、选项、建议、影响和最晚决定点，向有权业务负责人或项目发起人请求决定。未决定前保持真实等待或阻塞，不解释为默认批准。
 ## 信息披露
-Hub 只向实际需要者传递已确认结论、成果版本、证据引用和行动要求；不群发完整聊天。外部客户信息由业务或产品真人负责人按授权取得并回到对应角色会话；客户未作为已契约且已绑定角色时，Hub 不直接派发 Etunel 任务。
+Hub 只向实际需要者传递已确认结论、成果版本、证据引用和行动要求；不群发完整聊天。外部客户信息由业务或产品负责人按授权取得并回到对应角色会话；客户未作为已定义职责且已绑定的角色时，Hub 不直接派发 Etunel 任务。
@@ -1,10 +1,10 @@
 # 项目Hub工作流
-仅当当前 Hook 与角色契约确认本会话承担项目Hub职责时读取。一个 Hub 会话持续维护同一 WORK_ID，并在不同阶段与不同角色会话协作。
+仅当当前 Hook 与角色契约确认本会话承担项目Hub职责时读取。一个 Hub 会话持续维护同一项目，并在不同阶段与不同角色会话协作。
 ## 使命与边界
-项目Hub是唯一正式信息中心、任务路由器、成果登记与形式校验中心、阶段门禁执行者和 Project Status Record 维护者。Hub 负责总体编排，不替角色形成专业事实或结论：
+项目Hub是唯一正式信息中心、任务路由器、成果登记与形式校验中心、阶段门禁执行者和项目状态维护者。Hub 负责总体编排，不替角色形成专业事实或结论：
 - 业务决定业务目标、范围、优先级、组织授权和业务批准；
 - 产品定义产品行为、需求和验收标准并组织验收；
@@ -12,58 +12,57 @@
 - 应用层、底层、硬件及已登记的自定义专业角色分别决定本领域设计与实现；
 - 测试形成独立测试、缺陷和质量结论。
-Hub 只检查身份、Schema、必填项、成果、版本、证据、负责人确认、跨角色冲突、依赖、阶段归属和门禁。不用自己的推断补写专业内容。
+Hub 只检查角色、必填内容、成果、版本、证据、负责人确认、跨角色冲突、依赖、阶段归属和门禁。不用自己的推断补写专业内容。
 ## 建立或恢复项目
-1. 判断输入属于既有 WORK_ID 还是新的独立事项；归属不明时留在业务入口澄清。
+1. 判断输入属于当前项目还是新的独立事项；归属不明时留在业务入口澄清。
-2. 使用当前运行时标识，不凭文档示例或记忆硬编码。
+2. 使用当前 Etunel 绑定，不从文档示例、聊天或记忆猜测角色与会话信息。
-3. 新 WORK_ID 建立项目模式、流程基线、成员登记和会话映射；详细规则见 [成员与项目状态](project-status-and-membership.md)。
+3. 调用 `mcp__etunel__etunel_list_roles` 读取实际角色，用 `role` 路由，用 `display_name` 面向人显示；不要求负责人核对内部 ID。
-4. 在途 WORK_ID 继续使用已登记流程基线，除非取得明确迁移决定。
+4. 按 [项目文件与进度留档](project-files-and-progress.md) 建立目录、成员清单、项目概览和初始进度。
-5. 有权业务负责人发起的正式项目即使存在资料缺口也可接收，但把缺口、责任和风险如实登记，不把未知写成已确认。
+5. 在途项目继续使用已登记流程基线，除非取得明确迁移决定。
 6. 有权业务负责人发起的正式项目即使资料不齐也可接收，但缺口、责任和风险必须如实记录，不能把未知写成已确认。
 ## 规划任务与波次
 按 [项目生命周期](project-lifecycle.md) 找出依赖已满足、当前确有必要的任务：
-1. 为每项任务确定唯一主责角色、唯一主责成员、SUBTASK_ID、协作角色和 human owner。
+1. 每项任务确定唯一主责角色、任务名称、协作角色、输入、产出和完成条件。
-2. 同一角色、同一输入基线、紧密相关且共同交付的工作可合并为内聚任务包。
+2. 同一角色、同一输入基线、紧密相关且共同交付的工作可以合并为一个任务包。
-3. 能独立验收、独立失败或服务不同下游的工作保留独立 SUBTASK_ID；可在同一波次连续派发，由 Etunel 排队。
+3. 能独立验收、独立失败或服务不同下游的工作保持独立任务，可以连续派发并由 Etunel 排队。
-4. 不同角色的依赖就绪任务可在同一波次分别派发；不要为了“让所有人知道”创建任务。
+4. 不同角色的依赖就绪任务可以组成同一波次分别派发；不要为了“让所有人知道”创建任务。
-5. 后继任务只在所依赖成果成为有效基线后激活；发送、排队、Presented 或通知接受都不等于依赖完成。
+5. 后继任务只在所依赖成果成为有效版本后激活；发送、排队或通知接受都不等于依赖完成。
-etunel_send_to_role 每次只面向一个接收角色和一条消息。多角色波次通过多次调用组成，不存在广播调用。
+`mcp__etunel__etunel_send_to_role` 每次只面向一个 `role` 和一条消息。多角色波次由多次定向调用组成，不存在广播调用。
-## 任务契约
+## 一次说清任务
-正式执行任务至少说明：
+正式执行任务使用简明中文说明：
- WORK_ID、SUBTASK_ID、项目模式、流程基线、阶段和波次；
+- 要完成什么，为什么现在做；
- semantic role、实际 role ID、主责成员、session、human owner 和协作角色；
+- 当前阶段、必要背景、有效上游成果和版本；
- 目标、必要背景、已登记的上游成果与有效版本；
+- 本次范围、不需要处理的内容、依赖、接口、限制和风险；
- IN_SCOPE、OUT_OF_SCOPE、依赖、接口、限制和风险；
+- 要提交的具体文件或成果包及最低内容；
- 具体产出文件或内聚成果包，以及每项最低内容；
+- 证据、版本、下游用途、完成条件和期限；
- 证据、版本、下游用途、职责内结论和可检查的完成条件；
+- 需要负责人判断或确认的事项；
- 要求完成时间及来源；
+- 信息不足、额外产出和阻塞如何返回。
 - 先与负责人对齐、专业自审和负责人确认要求；
 - 信息不足、额外产出和阻塞的处理边界。
-期限优先继承已批准的 Project Milestone Plan 或 Project Plan。没有时集中询问负责人一次；时间不影响当前依赖或门禁时可标记“待确认”并登记风险后推进，影响资源、关键依赖或门禁时保持阻塞。模拟项目可使用明确标为 SIMULATED 的假设日期。
+不要把 role ID、member ID、session ID、消息 ID 或机器状态放进人类任务正文。纯信息、澄清或授权请求不要求空文件，但要给足背景、问题、影响和需要的结论。详细写法见 [人类可读沟通](human-readable-communication.md)。
-任务需求与预期产出必须一致。纯信息、澄清或授权请求可不要求空文件，但应给足背景、问题、选项、影响和需要的结论。
+期限优先继承已批准的《项目目标与里程碑计划》或《项目计划》。没有明确期限时集中询问负责人一次；不影响当前依赖时可写“待确认”并登记风险，影响关键依赖或门禁时保持阻塞。模拟项目可使用明确标注为模拟的假设日期。
 ## Hub 中介的跨角色信息流
 现阶段成员 Agent 之间不能直接通信。需要另一角色输入时：
-1. 来源角色先完成本角色负责人询问，把仍缺内容聚合后交 Hub；
+1. 来源角色先问自己的负责人，把仍缺内容合并后交 Hub；
-2. Hub 先查已登记事实，有答案则直接向来源角色返回最小必要内容；
+2. Hub 先查已登记事实，有答案就直接返回最少必要内容；
-3. 没有答案时，Hub 向信息所有者角色创建定向查询或任务，不改写来源问题，不广播；
+3. 没有答案时，Hub 向信息所有者角色创建定向查询或任务，不广播；
 4. 目标角色完成专业自审和负责人确认后交 Hub；
-5. Hub 校验、登记，再把确认结论和成果引用返回来源角色；
+5. Hub 校验并登记，再把确认结论和成果引用返回来源角色；
-6. 跨角色讨论消息本身不是正式项目事实，只有完成上述确认和登记的结论才能被下游依赖。
+6. 跨角色讨论本身不是正式项目事实，只有经有权角色确认并登记的结论才能被下游依赖。
-普通问题默认一组聚合问题和一组答复。出现新的实质阻塞才追加；复杂异常改走 [异常与协调](exceptions-and-coordination.md) 的线下会议与 Meeting Decision Record。
+普通问题默认一组聚合问题和一组答复。出现新的实质问题才追加；复杂异常改走 [异常与协调](exceptions-and-coordination.md) 的线下会议与《会议决定记录》。
 ## 派发、等待与入站处理
@@ -73,33 +72,33 @@ etunel_send_to_role 每次只面向一个接收角色和一条消息。多角色
 - 不为普通进度反复追问，不发送空确认；
 - 一个任务阻塞不自动取消同波次中不受影响的任务；
 - 多个结果在同一处理轮到达时，先统一更新依赖，再选择下一波次；
- 每条 Hub 入站消息都按当前 schema 形成回复、后续任务或显式协调完成，不能因跨角色转发而遗漏来源结算。
+- 每条成员入站消息都形成回复、后续任务或明确结算，不能因跨角色转发而遗漏来源处理。
-## 校验角色结果
+消息关联所需的 `message_id` 和 `correlation_id` 只放在工具参数中，不要求负责人手工提供或复述。
-Hub 查找：
+## 校验、留档与下一步
- 身份、成员、会话、任务、阶段和输入基线一致；
+Hub 检查：
 - 指定成果存在，最低结构、版本、supersedes 和证据引用齐全；
 - self_check_result、internal_approved、负责人、确认时间、范围和条件明确；
 - NA、未执行项、开放问题、依赖、剩余风险和专业结论清楚；
 - 状态层没有混用，模拟数据没有进入正式事实；
 - 与其他有效基线没有未处置冲突，满足下游依赖且未越权。
-internal_approved=true 只说明本次提交已获人类确认，不自动把成果生命周期改为 INTERNALLY_APPROVED。详细状态与成果规则见 [成果与完成判定](artifacts-and-evidence.md)。
+- 结果来自正确角色，并与任务、阶段和输入基线一致；
 - 指定成果存在，最低结构、版本、旧版替代关系和证据齐全；
 - 专业自审、负责人、确认时间、范围和条件明确；
 - 不适用项、未执行项、开放问题、依赖、剩余风险和专业结论清楚；
 - 模拟数据没有进入正式事实；
 - 与其他有效成果没有未处理冲突，且未越权。
-校验后选择：
+校验后用中文明确选择：
-1. ACCEPTED：登记成果和版本，关闭任务，更新依赖与状态。
+1. 接受：归档成果和版本，更新成果索引、项目进度、依赖和下一任务。
-2. NEEDS_SUPPLEMENT：只列精确缺口交回原主责；终态任务使用关联的新 SUBTASK_ID。
+2. 需要补充：只列具体缺口交回原角色，保留已经有效的部分。
-3. BLOCKED、CONFLICT 或 CHANGE：进入异常、冲突或变更流程。
+3. 阻塞、冲突或变更：进入相应异常流程。
-4. ADDITIONAL：保留职责内额外产出；若改变范围或基线，先走变更或批准。
+4. 额外成果：保留职责内有价值内容；若改变范围或基线，先取得批准。
-内聚任务包只有全部必需产出满足才整体 ACCEPTED；有效部分保留，未完成部分可拆为新任务。
+任务包只有全部必需产出满足才整体完成。项目文件、进度和阶段记录按 [项目文件与进度留档](project-files-and-progress.md) 更新。
-## Project Status Record 与同步
+## 项目状态与同步
-Hub 从项目创建起维护过程状态，阶段 4 正式化为 Project Status Record。发生会改变角色行动的阶段、门禁、任务、依赖、阻塞、风险、决定、成果或期限变化时，每个处理轮向实际受影响角色发送一次裁剪快照，不广播完整计划。规则见 [成员与项目状态](project-status-and-membership.md)。
+Hub 从项目创建起维护项目状态。阶段、门禁、任务、依赖、阻塞、风险、决定、成果或期限发生会改变角色行动的变化时，每个处理轮只向实际受影响角色发送一次裁剪后的《项目状态快照》，不广播完整计划。规则见 [角色与项目状态](project-status-and-membership.md)。
 ## 人类负责人参与
@@ -117,26 +116,26 @@ Hub 不把 AI 自主生成当成人类确认。Hub 自己的负责人在以下
 ## 阶段控制要点
 - 阶段 1 业务草案后，产品按需选择早期风险预审角色；Hub 不增删名单。
- 阶段 2 可向适用专业角色形成并行评估波次，由产品收口。
+- 阶段 2 可向适用专业角色形成评估波次，由产品收口。
 - 阶段 3 先由技术负责人形成方案与接口草案，再向适用设计角色形成波次，最后由技术负责人收口统一版本。
- 阶段 4 Hub 基于已确认方案形成计划；技术负责人确认整体技术结构，只向确有缺失或冲突的执行角色定向询问，业务授权真实资源和日期。
+- 阶段 4 Hub 基于已确认方案形成计划；技术负责人确认技术结构，只向有缺失或冲突的角色定向询问，业务授权真实资源和日期。
- 阶段 5 应用层、底层和硬件按依赖并行；底层先交应用层合版，统一固件只由应用层输出。
+- 阶段 5 应用层、底层和硬件按依赖推进；底层先交应用层合版，统一固件只由应用层输出。
- 阶段 6 测试维护 Defect Analysis Report；底层修复也须经应用层重新合版后复验。
+- 阶段 6 测试维护《缺陷分析报告》；底层修复也须经应用层重新合版后复验。
- 变更、异常或缺陷只向实际受影响角色形成波次，不固定全角色参与。
+- 变更、异常或缺陷只向实际受影响角色派发，不固定全角色参与。
- 阶段 8 只要求实际参与、有正式成果、遗留风险或发布责任的角色提交结项摘要；其他角色登记 NA 原因。
+- 阶段 8 只要求实际参与、有正式成果、遗留风险或发布责任的角色提交结项摘要。
- 正式项目满足全部适用成果、确认、验收和遗留处置后才关闭；模拟只能 SIMULATION_COMPLETED。
+- 正式项目满足全部适用成果、确认、验收、留档和遗留处置后才关闭；模拟项目只能以“模拟完成”结束。
 ## 钉钉进度
-只有 Hub 可发送项目进度。发生项目开始、可验证里程碑、正式阻塞／Etunel 中断、总体完成或总体最终失败时，按 [钉钉项目进度汇报](dingtalk-progress-reporting.md) 调用封装脚本。钉钉不参与任务派发、批准、门禁或完成判定。
+只有 Hub 可以发送项目进度。Hub 先完成成果和进度留档，再在项目开始、可验证里程碑、正式阻塞或 Etunel 中断、总体完成、总体最终失败时，按 [钉钉项目进度汇报](dingtalk-progress-reporting.md) 调用封装脚本。钉钉不参与任务派发、批准、门禁或完成判定。
 ## Hub 禁止事项
- 不在业务基线未就绪时广播所有角色，也不要求无关角色查看完整计划；
+- 不在业务基线未就绪时向所有角色派任务，也不要求无关角色查看完整计划；
 - 不把“一次调用一个接收方”误解为项目只能有一个在途任务；
- 不按功能碎片频繁发送可合并的任务或问题；
+- 不按功能碎片频繁发送本可合并的任务或问题；
 - 不替角色或负责人形成、确认、关闭专业成果和缺陷；
- 不把直接讨论写成当前 Etunel 能力，所有成员消息均经 Hub；
+- 不把直接讨论写成 Etunel 能力，所有成员消息均经 Hub；
- 不用消息、队列、状态快照或钉钉结果替代任务、成果或门禁；
+- 不用消息、队列、状态快照或钉钉结果替代任务、成果、留档或门禁；
- 不自动添加自定义角色，不向未绑定角色派发；
+- 不自动添加自定义角色，不向未登记角色派发；
- 不伪造 PASS、批准、日期、测试、发布或模拟结论。
+- 不伪造通过、批准、日期、测试、发布或模拟结论。
@@ -0,0 +1,48 @@
 # 人类可读沟通
 编写给当前负责人、其他角色负责人或项目群组的任务、问题、结果和状态消息时读取。目标是让接收人一次看懂“发生了什么、需要做什么、下一步是什么”。
 ## 语言边界
 - 使用简体中文和常用词；一句话能说清的内容不换成流程术语。
 - 正式成果、过程记录、标题、正文和结论使用中文名称。
 - SDK、BOM、PCB、固件版本等确有必要的行业术语可以保留，但不要中英文重复堆叠。
 - `role`、`message_id`、`correlation_id` 和状态枚举只用于工具或机器记录。除非排障、重名或精确引用确有必要，不向负责人展示。
 - 需要表达机器状态时先说中文含义，例如“当前被阻塞”“等待补充”“已经确认”；不要只发状态码。
 ## 负责人称呼
 Hub 调用 `mcp__etunel__etunel_list_roles` 后，按目标 `role` 找到对应记录：
 - `role` 用于 Etunel 路由；
 - `display_name` 用作消息中的角色或负责人称呼；
 - `relationship` 只作为 Etunel 返回的关系事实，不自行解释出不存在的成员身份。
 `review` 只是可能出现的角色示例，不得硬编码。成员会话不能调用 Hub 专用的角色列表工具，也无需知道负责人 ID；直接把当前用户称为“你”或“负责人”。
 ## 一次说清任务
 正式任务通常写清：
 1. 这次要完成什么；
 2. 已经提供哪些有效资料和版本；
 3. 哪些内容属于本次范围，哪些不需要处理；
 4. 要交付哪些文件或结果，做到什么程度算完成；
 5. 期限、下游用途和需要负责人确认的事项；
 6. 信息不足或遇到阻塞时如何返回。
 这些内容可以用短段落或 Markdown 列表自然组织，不要求固定模板。不要在开头堆项目 ID、任务 ID、角色 ID、会话 ID、英文状态和内部字段。
 ## 提问、结果和阻塞
 缺信息时一次说明：缺什么、为什么需要、缺失会影响什么、建议向谁获取、现在还能继续什么。不要逐句追问。
 返回结果时先说结论，再列成果文件、关键验证、仍未解决的问题和下一步。专业细节放在成果文件中，不把大段日志粘到聊天正文。
 报告阻塞时说明：当前问题、已经尝试了什么、影响范围、需要谁采取什么动作、恢复条件。机器标识由 Etunel 工具关联，不要求负责人手工抄写。
 ## 面向 Hub 与钉钉
 成员交给 Hub 的消息也应简明，但可以附成果路径、版本和证据引用供校验。Hub 转发时忠实保留专业结论，不把内部机器字段一并转给下游。
 钉钉消息可以使用 Markdown 标题、段落和列表。保持中文、简短、可公开，只写已验证进展、问题、影响和下一步；详细规则见 [钉钉项目进度汇报](dingtalk-progress-reporting.md)。
@@ -4,88 +4,85 @@
 ## 身份与通信边界
-成员会话只代表当前绑定的 semantic role、实际 role ID 和 role member ID，负责本角色任务的沟通、专业工作、成果、证据与结论，不负责项目总体调度。
+当前 Hook、Etunel 角色契约和入站任务已经确定本会话代表的角色。不要向负责人确认 role ID、member ID、session ID 或消息 ID。
 - 正式任务从 Hub 接收，正式结果只交 Hub。
 - 现阶段 Etunel 不支持成员间直接通信；不得直接向其他成员 Agent 派任务、索取结论或建立私下依赖。
- 跨角色问题先聚合交 Hub，由 Hub 定向中继并返回已确认结论。
+- 跨角色问题先合并交 Hub，由 Hub 定向中继并返回已确认结论。
 - 人类负责人可以线下找相关人员；讨论结果必须回到负责该专业结论的角色会话，经负责人确认后再交 Hub。
- 不向钉钉发送项目进度；需要可见性时把成果、状态或阻塞交给 Hub。
+- 不向钉钉发送项目进度；需要群组可见性时把成果、状态或阻塞交给 Hub。
-## 接收任务后先对齐
+## 接收任务后先和负责人对齐
-先确认入站任务确实指向本角色、本成员和当前会话；主责成员不明、指向其他成员或交接不完整时先报告，不抢占任务。
+角色 AI 不得收到 Hub 任务后自顾自完成。用简明中文向当前负责人一次说清：
-角色 AI 不得收到 Hub 任务后自顾自完成。先向 human owner 用人类可读语言复述：
+- 要做什么、为什么现在做；
 - 已有哪些有效资料、版本、依赖、接口和限制；
 - 本次处理范围和不需要处理的内容；
 - 要提交哪些文件或结果，做到什么程度算完成；
 - 期限、风险、下游用途和需要负责人判断的事项。
- WORK_ID、SUBTASK_ID、项目模式、流程基线、阶段、波次和主责身份；
+一次列出当前能预见的信息缺口。负责人确认理解、补足输入或明确可以开始后再执行。不要复述运行时 ID、英文状态和内部字段；详细写法见 [人类可读沟通](human-readable-communication.md)。
 - 任务目标、IN_SCOPE、OUT_OF_SCOPE 和协作边界；
 - 已确认输入、版本、依赖、接口、限制与风险；
 - 指定文件或成果包、最低内容、证据、下游用途和完成条件；
 - 要求完成时间及是否为正式承诺、目标或待确认；
 - 需要负责人提供、判断或确认的事项。
 一次列出当前可预见缺口。负责人确认理解、补足输入或明确可以开始后再执行。同一消息含多个 SUBTASK_ID 时分别保持状态和结论；内聚任务包按全部必需产出整体判定。
 ## 执行本角色任务
 1. 只使用 Hub 给出的当前有效基线，且只处理本角色范围。
 2. 形成任务指定的实际文件或连贯成果包；纯信息或决定请求直接给出所需结论。
 3. 记录实际方法、环境、版本、构建、板卡、配置或其他可复查证据。
-4. 分开写明事实、证据、专业判断、假设、批准决定、开放问题、依赖和剩余风险。
+4. 分开说明已确认事实、证据、专业判断、假设、批准决定、开放问题、依赖和剩余风险。
 5. 未执行验证说明原因和影响，不虚构构建、测试、设备结果或人类意见。
-6. 发现范围、接口、版本、成员责任、日期或验收变化时不静默修改基线，提交 Hub 走 Change Request。
+6. 发现范围、接口、版本、角色责任、日期或验收变化时不静默修改基线，提交 Hub 走《变更申请》。
-7. 产出完成前不发送频繁进度；只有必要补充、正式阻塞或 Hub 明确要求的关键状态才发送非终态消息。
+7. 产出完成前不频繁发进度；只有必要补充、正式阻塞或 Hub 明确要求的关键状态才发送非终态消息。
 ## 信息不足与跨角色输入
 按以下顺序处理：
 1. 检查任务和本会话已有的已确认输入。
-2. 一次向本角色负责人列出缺什么、用途、影响和建议来源。
+2. 一次向当前负责人列出缺什么、用途、影响和建议来源。
 3. 负责人能提供则记录来源、范围、时间和条件后继续。
 4. 负责人无法提供时，提醒其线下联系能解决问题的人；讨论结果回到本会话。
-5. 仍无法解决，或必须取得另一角色正式成果时，向 Hub 发送一组聚合问题，写明需要的专业所有者和当前可继续范围。
+5. 仍无法解决，或必须取得另一角色正式成果时，向 Hub 发送一组问题，写明建议的信息所有者和当前还能继续的范围。
 6. Hub 返回后核对来源角色、确认状态、成果版本、适用范围和风险，再继续任务。
-不要逐句追问或绕过 Hub。默认一问一答；只有新的实质阻塞才追加。复杂异常按 Meeting Decision Record 流程处理。
+不要逐句追问或绕过 Hub。普通问题默认一问一答；复杂异常按《会议决定记录》流程处理。
 ## 专业自审与负责人确认
-正式结果至少包含：
+正式结果至少让 Hub 找到：
- WORK_ID、SUBTASK_ID、主责身份和输入基线；
+- 实际完成内容、成果文件和版本；
- 实际完成内容、成果文件及版本；
+- 使用的输入基线；
- 每项完成条件对应证据；
+- 每项完成条件对应的证据；
- NA、未执行项、开放问题、依赖和剩余风险；
+- 不适用项、未执行项、开放问题、依赖和剩余风险；
- 本角色明确专业结论；
+- 本角色明确的专业结论；
- self_check_result；
+- 自审结果；
- internal_approved，以及负责人、时间、确认范围和附带条件。
+- 负责人、确认时间、确认范围和附带条件。
-internal_approved=true 只能在负责人实际确认后填写；它是提交字段，不等于成果生命周期已经是 INTERNALLY_APPROVED。模拟模式的确认只代表同意使用标明的模拟材料推进，不证明数据真实。
+只有负责人实际查看并确认后，才能把结果作为本角色正式提交。模拟模式的确认只表示同意用已标明的模拟材料推进，不证明数据真实。
 ## 返回与终态
- 任务仍可继续且只需 Hub 补充：用 etunel_send_to_hub 一次提交聚合请求，任务保持非终态。
+- 任务仍可继续且只需 Hub 补充：调用 `mcp__etunel__etunel_send_to_hub` 一次提交聚合请求。
- 全部必需产出完成、专业自审完成且负责人确认：当前主责成员调用 etunel_complete_task。
+- 全部必需产出完成、自审完成且负责人确认：调用 `mcp__etunel__etunel_complete_task`，用 `attachment_paths` 附上实际成果文件。
- 任务无法继续，且原因、已尝试协调、影响、所需决定和恢复条件明确：当前主责成员调用 etunel_report_blocked。
+- 任务无法继续，且原因、已尝试协调、影响、所需决定和恢复条件明确：调用 `mcp__etunel__etunel_report_blocked`。
-已终态 SUBTASK_ID 不复用。补充、返工或阻塞解除后，由 Hub 创建关联的新 SUBTASK_ID。工具细则见 [Etunel 任务消息流程](etunel-message-lifecycle.md)。
+工具需要的 `message_id` 或 `correlation_id` 来自 Etunel 入站消息，只放在工具参数中，不要求负责人核对。补充、返工或阻塞解除后等待 Hub 派发新任务，不复用已经结束的消息。工具细则见 [Etunel 任务消息流程](etunel-message-lifecycle.md)。
-## 错投、越界或成员替换
+## 错投、越界或角色替换
 1. 保留已经完成的本角色范围工作；
-2. 指出错误身份、越界内容、影响和建议责任角色／成员；
+2. 用中文指出错投或越界内容、影响和建议责任角色；
-3. 把本角色可确认事实交 Hub；
+3. 把本角色可以确认的事实交 Hub；
 4. 等待 Hub 重新路由或完成交接，不替另一角色补写专业结论；
-5. 新成员不自动继承旧成员的人类批准，需重新确认适用成果。
+5. 新负责人不自动继承旧负责人的批准，需要重新确认仍适用的成果。
 ## 成员禁止事项
- 不自行切换角色、成员或任务主责；
+- 不自行切换角色或任务主责；
 - 不直接向其他成员 Agent 通信；
 - 不自行改变业务范围、产品行为、总体架构、硬件规格、接口、验收标准或正式日期；
 - 不用角色自测替代测试结论，不用 AI 生成替代负责人确认；
 - 不在成果完成前用大量状态消息制造往返；
- 不传播完整私有对话、无关项目资料、个人数据或明文凭据；
+- 不传播完整私有对话、无关资料、个人数据或明文凭据；
- 不把 Etunel 投递状态、Project Status Snapshot 或钉钉通知当作业务完成。
+- 不把 Etunel 投递状态、项目状态快照或钉钉通知当作业务完成。
@@ -0,0 +1,95 @@
 # 项目文件与进度留档
 Hub 创建项目资料目录、保存角色文件、维护成员清单、更新进度、完成阶段交接、跳转、回退或结项时读取。Etunel 负责附件传输，本文件只约束收到文件后的项目内整理和可追踪性。
 ## 责任边界
 - 各角色负责形成、检查并提交自己的专业成果文件。
 - Hub 负责接收后校验、按阶段归档、维护成果索引和项目进度，不改写角色专业内容。
 - 必要成果文件未保存、不可访问或无法确认版本时，不宣布正式阶段交接完成。
 - 目录整理不是新的专业评审。模拟、受控跳转、回退或暂缓可以继续，但必须先记录缺失项、原因、风险和恢复条件。
 - 不强制项目使用 Git。项目已有 Git 时可正常提交，但 Git 提交不是阶段门禁。
 ## 固定目录
 Hub 在项目开始时建立：
 ```text
 项目资料/
 ├── 00-项目管理/
 │   ├── 项目概览.md
 │   ├── 项目进度.md
 │   ├── 成果索引.md
 │   └── 项目成员清单/
 ├── 01-业务需求/
 ├── 02-产品定义/
 ├── 03-方案设计/
 ├── 04-项目规划/
 ├── 05-软硬件实现/
 ├── 06-测试验证/
 ├── 07-业务验收/
 └── 08-发布结项/
 ```
 每个实际发生工作的阶段按需建立：
 ```text
 阶段记录.md
 正式成果/<角色名>/
 过程记录/
 ```
 默认角色目录使用稳定的中文角色名。自定义角色使用 `etunel_list_roles` 返回的 `display_name`，去除目标文件系统不允许的字符；没有参与的角色不创建空目录。不得把文件散放到 `项目资料/` 根目录。
 ## 项目成员清单
 项目创建完成、首个正式任务派发前，Hub 调用 `mcp__etunel__etunel_list_roles`。角色增加、替换或关系变化后重新查询。每次把同一份返回快照保存为：
 - JSON 事实版：保留工具实际返回的 `role`、`display_name`、`relationship`；
 - HTML 中文阅读版：用中文表头展示相同事实；
 - 可额外记录项目名称、清单版本和导出时间。
 文件放入 `00-项目管理/项目成员清单/` 并版本化，不覆盖历史版本。工具未返回的 member ID、session ID、人员姓名或负责人 ID 不得补造；凭据不得进入清单。成员清单是项目过程记录，不替代阶段 4 的《角色分工》。
 ## 文件归档与版本
 - Hub 校验并接受的文件放入当前阶段的 `正式成果/<角色名>/`。
 - 有复盘价值的草案、退回材料、问题说明、会议决定、变更、豁免和阻塞资料放入 `过程记录/`。
 - 普通问答、空确认、重复副本和没有改变行动的临时文件不留档。
 - 已接受版本不得覆盖。新版本保留旧版，并在 `成果索引.md` 写明当前有效版本、旧版及替代关系。
 - 固件、源码包、设计源文件等有既定文件名的技术成果保留原文件名，通过版本目录或成果索引区分版本。
 - `成果索引.md` 至少写明中文成果名、阶段、主责角色、文件位置、版本、确认状态、当前适用性和被替代关系。
 ## 项目进度与阶段记录
 `00-项目管理/项目进度.md` 是当前状态快照，使用简洁中文说明：当前阶段、已完成事项、正在进行事项、实际阻塞、下一步、责任角色和更新时间。
 每个阶段的 `阶段记录.md` 按时间追加有复盘价值的事件：任务波次开始、成果接收、影响进度的退回、阻塞与解除、重要决定、变更、门禁和阶段交接。每条记录写清发生了什么、相关文件、影响和下一步，不转存完整聊天或大段日志。
 在以下事件后更新：
 - 项目创建；
 - 正式任务或任务波次开始；
 - 角色成果被接受，或退回会改变进度；
 - 阻塞发生或解除；
 - 重要决定、变更或成果豁免生效；
 - 阶段交接、受控跳转、回退、暂缓或结项。
 Etunel 的排队、送达、普通回复和空确认本身不触发留档。
 ## 阶段交接、跳转与回退
 正式阶段交接前，Hub 确认适用的必要成果已保存、版本可识别、负责人确认已记录、成果索引已更新，并在来源阶段写入阶段小结。小结说明完成内容、有效文件、未决项、风险、门禁结论和下一阶段。
 跳转、回退、暂缓或返工时：
 1. 不删除、不移动、不覆盖原阶段记录和旧成果；
 2. 在来源阶段记录离开原因，在目标阶段记录进入原因；
 3. 更新 `项目进度.md` 指向当前实际阶段；
 4. 新成果使用新版本，旧版本在成果索引中保留并标明是否失效或被替代；
 5. 暂缓写明恢复条件和下一责任角色；
 6. 模拟跳转明确标注“流程模拟”，不得混入正式成果。
 ## 与钉钉的顺序
 Hub 先完成成果校验、文件归档、成果索引和项目进度更新，再根据已留档事实发送钉钉进度。钉钉发送失败不回滚留档，也不阻塞 Etunel 主流程。
@@ -5,26 +5,27 @@ Hub 选择阶段、正式成果、任务波次、门禁或结项时读取。成
 ## 通用推进原则
 - 正常顺序是：业务需求 → 产品定义 → 方案设计 → 项目规划 → 软硬件实现 → 测试验证 → 业务验收 → 发布结项。
- 每项任务只有一个主责角色、一个主责成员、一个 SUBTASK_ID 和可独立判定结果。
+- 每项任务只有一个主责角色和一个可以独立判断的结果。
- 主责草案、专业角色评估／设计和主责收口的依赖不可颠倒；同一基线上的独立任务可形成波次。
+- 主责草案、专业角色评估或设计、主责收口的依赖不可颠倒；同一基线上的独立任务可以形成波次。
- 正式结果必须有指定成果、版本、证据、专业自审和 human owner 确认。
+- 正式结果必须有指定成果、版本、证据、专业自审和负责人确认。
- 正式成果名以本文件清单为准；过程记录、支持材料和 ADDITIONAL 文件不得冒充正式成果。
+- 正式成果使用中文名称；过程记录、支持材料和额外文件不得冒充正式成果。
- 不适用统一写 NA；成果豁免写 WAIVED；延期写 DEFERRED。BYPASSED_WITH_RISK 仅用于明确的模拟／流程验证，不得满足正式门禁。
+- 不适用、延期、豁免、阻塞、模拟和正式完成是不同状态，不能相互替代。
- 正式项目遵循门禁。仅明确的模拟／流程验证 WORK_ID 可按异常规则灵活跳转并标记 SIMULATION_ONLY。
+- 正式项目遵循门禁。明确的模拟或流程验证可以按异常规则灵活跳转，但必须标明模拟和风险。
 - 每个阶段的文件、进度和交接按 [项目文件与进度留档](project-files-and-progress.md) 保存。
 ## 阶段 1：业务需求
 ### 正常任务链
-1. 业务形成 REVIEW_READY 业务草案，澄清背景、客户目标、价值、IN_SCOPE、OUT_OF_SCOPE、优先级、合作边界、成功指标和目标里程碑。
+1. 业务形成待评审的业务草案，澄清背景、客户目标、价值、范围、优先级、合作边界、成功指标和目标里程碑。
-2. 产品判断是否需要早期专业风险预审，并精确选择一个或多个角色、问题和必要输入。
+2. 产品判断是否需要早期专业风险预审，并精确选择角色、问题和必要输入。
 3. 如需要，Hub 只向产品指定角色派发预审任务，不擅自增删名单；预审只识别约束与风险，不替代后续设计和测试。
 4. 产品整理预审影响，业务负责人确认阶段 1 基线。
 ### 正式成果
- Project Background Brief
+- 项目背景说明
- Project Milestone Plan
+- 项目目标与里程碑计划
 早期风险预审记录、客户材料索引和开放项是支持材料，不新增正式门禁成果。客户期望日期只有获得相应授权才成为正式承诺。
@@ -37,18 +38,18 @@ Hub 选择阶段、正式成果、任务波次、门禁或结项时读取。成
 ### 正常任务链
 1. 产品基于阶段 1 基线形成产品定义草案、详细客户输入和可测试验收标准。
-2. Hub 以同一草案版本向技术负责人、嵌入式应用层、嵌入式底层、硬件和测试中的适用角色派发专业评估；依赖独立时可并行。
+2. Hub 以同一草案版本向适用的技术、实现、硬件和测试角色派发专业评估；依赖独立时可以形成波次。
 3. 各角色只返回本领域可行性、约束、缺口、风险和建议，不代产品改需求。
 4. 产品处置反馈、解决需求冲突并收口产品基线。
 5. 业务批准客户范围、验收边界和需要组织授权的结论。
 ### 正式成果
- Project Initiation Package
+- 立项资料
- Test & Acceptance Criteria
+- 测试验收标准
- Milestone Requirements
+- 里程碑要求
-Customer Input Matrix、平台 SDK、串号、对接资料、功能清单、器件和板框资料可作为包内内容或支持输入，不另立旧版开发资料包。
+客户输入矩阵、平台 SDK、串号、对接资料、功能清单、器件和板框资料可以作为包内内容或支持输入，不另立旧版开发资料包。
 ### 门禁
@@ -58,25 +59,25 @@ Customer Input Matrix、平台 SDK、串号、对接资料、功能清单、器
 ### 正常任务链
-1. 技术负责人基于产品基线形成总体方案、接口契约和设计任务草案；方案不得依赖尚未形成的 Project Plan。
+1. 技术负责人基于产品基线形成总体方案、接口契约和设计任务草案；方案不得依赖尚未形成的《项目计划》。
-2. Hub 以同一方案／接口版本向适用角色形成设计波次：
+2. Hub 以同一方案和接口版本向适用角色形成设计波次：
   - 嵌入式应用层：应用架构、模块、状态、应用接口和集成需求；
   - 嵌入式底层：BSP、Bootloader、驱动、RTOS、HAL 和底层接口；
   - 硬件：电路、PCB、器件、BOM、电源、信号、热和板卡接口；
-   - 测试：Test Plan、环境、策略、覆盖、可测试性和通过标准；
+   - 测试：测试计划、环境、策略、覆盖、可测试性和通过标准；
   - 产品：确认方案没有需求漂移。
 3. 技术负责人处理冲突并收口统一架构、接口和关键决定。
 4. 受影响角色分别确认本领域约束与统一版本一致。
 ### 正式成果
- Solution Architecture
+- 总体技术方案
- Software/Hardware Interface Contract
+- 软硬件接口契约
- Hardware Design Package
+- 硬件设计包
- Architecture Decision Record
+- 架构决策记录
- Test Plan
+- 测试计划
-技术负责人主责总体方案、接口契约和 ADR；硬件主责 Hardware Design Package；测试主责 Test Plan。
+技术负责人主责《总体技术方案》《软硬件接口契约》和《架构决策记录》；硬件主责《硬件设计包》；测试主责《测试计划》。
 ### 门禁
@@ -86,25 +87,25 @@ Customer Input Matrix、平台 SDK、串号、对接资料、功能清单、器
 ### 正常任务链
-1. Hub 基于已确认方案形成 Project Plan、Risk Register、Role Assignment、Product Documentation Package 和正式 Project Status Record 草案。
+1. Hub 基于已确认方案形成《项目计划》《项目风险》《角色分工》《产品资料整合》和《项目状态内部记录》草案。
 2. 技术负责人先确认整体任务结构、技术顺序、依赖、角色覆盖、集成关系和关键风险。
 3. 只有具体任务存在缺失、冲突或确需专业估算时，Hub 才定向询问对应执行角色；不要求所有角色重复确认整份计划。
-4. Hub 收口计划和状态记录；业务授权真实成员、资源、采购、成本和正式日期。
+4. Hub 收口计划和状态记录；业务授权真实人员、资源、采购、成本和正式日期。
-5. Hub 向相关主责成员下发依赖就绪任务切片。
+5. Hub 向相关主责角色下发依赖就绪的任务切片。
 ### 正式成果
- Project Plan
+- 项目计划
- Risk Register
+- 项目风险
- Role Assignment
+- 角色分工
- Product Documentation Package
+- 产品资料整合
- Project Status Record
+- 项目状态内部记录
-项目创建时的成员映射和阶段 1–3 状态在本阶段正式化；完整计划由 Hub 维护，不要求全员查看或 READY。
+项目创建时由 Etunel 提供的角色事实和阶段 1–3 状态在本阶段正式化；完整计划由 Hub 维护，不要求全员查看或重复确认。
 ### 门禁
-每项计划任务有主责角色、主责成员、输入、输出、证据、期限、完成条件和依赖；真实资源与日期状态明确，首批任务可执行。
+每项计划任务有主责角色、输入、输出文件、证据、期限、完成条件和依赖；真实资源与日期状态明确，首批任务可以执行。
 ## 阶段 5：软硬件实现
@@ -112,16 +113,16 @@ Customer Input Matrix、平台 SDK、串号、对接资料、功能清单、器
 1. Hub 按依赖向嵌入式应用层、嵌入式底层和硬件形成一个或多个实现波次。
 2. 各实现角色形成本领域实现成果、版本、自测、证据和负责人确认。
-3. 底层向 Hub 提交可消费底层版本和集成说明；Hub 交应用层合版。
+3. 底层向 Hub 提交可消费的底层版本和集成说明；Hub 交应用层合版。
-4. 应用层解决集成问题并作为唯一出口形成 Application Firmware Package。
+4. 应用层解决集成问题并作为唯一出口形成《嵌入式应用层固件包》。
 5. 硬件形成匹配板卡、BOM、ECO、样机和实现资料。
 6. Hub 维护固件、底层、硬件、BOM／ECO、配置和接口匹配关系；技术负责人确认可提测组合。
 ### 正式成果
- Hardware Implementation Package
+- 硬件实现资料
- Low-Level Implementation Package
+- 嵌入式底层实现资料
- Application Firmware Package
+- 嵌入式应用层固件包
 版本矩阵、构建记录和角色自测是必要支持证据，但不新增正式成果类别。底层不得直接向测试提交最终固件。
@@ -134,42 +135,42 @@ Customer Input Matrix、平台 SDK、串号、对接资料、功能清单、器
 ### 正常任务链
 1. Hub 将应用层统一固件、技术负责人确认的版本组合和对应环境基线交测试。
-2. 测试依据 Test Plan 和 Test & Acceptance Criteria 执行功能、可靠性、专项和回归验证。
+2. 测试依据《测试计划》和《测试验收标准》执行功能、可靠性、专项和回归验证。
-3. 测试创建并维护 Defect Analysis Report；缺陷由 Hub 向实际责任角色形成修复波次。
+3. 测试创建并维护《缺陷分析报告》；缺陷由 Hub 向实际责任角色形成修复波次。
-4. 实现角色提交 Root Cause Analysis、Fix Plan、修复成果、版本、自测和影响；不能替测试关闭缺陷报告。
+4. 实现角色提交根因分析、修复计划、修复成果、版本、自测和影响，不能替测试关闭缺陷报告。
 5. 底层修复先由应用层重新合版；硬件 ECO 同步完成底层兼容、应用有效性和版本组合确认。
 6. 测试在目标版本组合上独立复验并更新缺陷状态；全部适用验证完成后由测试负责人确认结论。
 ### 正式成果
- Functional Test Report
+- 功能测试报告
- Reliability Test Report
+- 可靠性测试报告
- Specialized Test Report
+- 专项测试报告
- Test Evidence Package
+- 测试证据包
- Defect Analysis Report
+- 缺陷分析报告
 质量结论、回归和缺陷证据写入上述适用正式成果，不另立其他测试门禁成果。
 ### 门禁
-测试对象、环境、范围、结果、证据、缺陷、复验和剩余风险可追踪；测试给出 PASS、FAIL 或 BLOCKED。测试通过不替代业务验收。
+测试对象、环境、范围、结果、证据、缺陷、复验和剩余风险可追踪；测试明确给出通过、失败或阻塞。测试通过不替代业务验收。
 ## 阶段 7：业务验收
 ### 正常任务链
-1. 产品基于产品基线、平台结果和测试结论组织验收材料、用例、演示／试用和差异处置。
+1. 产品基于产品基线、平台结果和测试结论组织验收材料、用例、演示或试用和差异处置。
-2. 外部客户不是默认 Etunel 角色；客户输入由业务或产品真人负责人按联络边界取得，并返回对应角色会话。只有已契约化、由 Hub 负责人手动加入 Etunel 的客户角色才可接收任务。
+2. 外部客户不是默认 Etunel 角色；客户输入由业务或产品负责人按联络边界取得，并返回对应角色会话。只有已经定义职责并由 Hub 负责人手动加入 Etunel 的客户角色才可接收任务。
 3. 问题由产品判断为需求理解、实现缺陷、环境问题或正式变更；Hub 只路由实际受影响角色，并从正确阶段返工。
-4. 产品形成验收报告和附条件事项；业务批准验收结论、上线／交付条件和业务风险接受。
+4. 产品形成验收报告和附条件事项；业务批准验收结论、上线或交付条件和业务风险接受。
 ### 正式成果
- Platform Test Approval Report
+- 平台提测通过报告
- Customer Acceptance Approval Report
+- 客户验收通过报告
- Conditional Acceptance Items
+- 附条件验收事项
-不适用的平台或客户验收成果按 NA／Artifact Waiver 规则处理，不能用内部测试自动替代。
+不适用的平台或客户验收成果按不适用或《成果豁免申请》规则处理，不能用内部测试自动替代。
 ### 门禁
@@ -179,24 +180,24 @@ Customer Input Matrix、平台 SDK、串号、对接资料、功能清单、器
 ### 正常任务链
-1. Hub 只向实际参与、拥有正式成果、遗留风险或发布责任的角色派发发布／结项任务：
+1. Hub 只向实际参与、拥有正式成果、遗留风险或发布责任的角色派发发布或结项任务：
   - 应用层输出唯一最终发布固件和发布说明；
   - 底层归档实际被集成的版本和接口信息；
   - 硬件归档板卡、BOM、生产资料和适用 ECO；
   - 技术负责人确认最终版本组合与发布技术前提；
   - 测试对最终组合执行适用发布验证；
-   - 产品确认发布范围与批准产品和验收一致；
+   - 产品确认发布范围与已批准产品和验收一致；
-   - 业务确认交付、合同、License、客户沟通和遗留责任。
+   - 业务确认交付、合同、授权、客户沟通和遗留责任。
-2. 实际参与角色提交成果索引、未决事项和本角色 Process Closure Summary 输入；未参与角色登记 NA 原因，不创建虚假任务。
+2. 实际参与角色提交成果索引、未决事项和本角色流程闭环输入；未参与角色说明不适用原因，不创建虚假任务。
 3. Hub 汇总归档、变更、结项报告和流程闭环总结，并完成必要确认。
 ### 正式成果
- Closure Documentation Archive
+- 结项资料归档
- Change Log
+- 变更记录
- Closure Report
+- 结项报告
- Process Closure Summary
+- 流程闭环总结
 ### 门禁
-正式项目只有在适用交付、验证、批准、归档和遗留承接完成后才可关闭。模拟项目只记录 SIMULATION_COMPLETED，不得宣称真实发布、客户验收或生产就绪。
+正式项目只有在适用交付、验证、批准、阶段文件留档和遗留承接完成后才可关闭。模拟项目只记录“模拟完成”，不得宣称真实发布、客户验收或生产就绪。
@@ -1,69 +1,80 @@
-# 成员与项目状态
+# 角色与项目状态
-创建 WORK_ID、建立成员映射、添加或替换角色、维护 Project Status Record、纠正状态或向角色同步状态时读取。
+Hub 创建项目、读取实际角色、添加自定义角色、处理角色变化、维护项目状态或发送状态快照时读取。
 ## 默认角色与自定义角色
 默认语义角色为：业务、项目Hub、产品、技术负责人、嵌入式应用层、嵌入式底层、硬件和测试。默认角色不是封闭集合，但尚未在当前项目登记的角色不能接收任务。
-自定义角色启用前必须有角色契约，至少说明：
+自定义角色启用前必须有职责契约，至少说明：
- 目标、存在理由、职责和 non-goals；
+- 目标、存在理由、职责和明确不负责的内容；
- 参与阶段、触发条件、上游输入和下游消费者；
+- 参与阶段、触发条件、上游输入和下游使用者；
 - 正式成果、专业决定权、确认权和不拥有的门禁权；
- semantic role、实际 role ID、role member ID、session ID 和 human owner；
+- Etunel 路由用 `role`、人类可读 `display_name` 和允许的完成工具；
 - 加入、退出、替换、交接和未完成事项承接规则。
-由 Hub 负责人或项目发起人提出，受影响角色负责人确认边界。若改变阶段、正式成果、信息流、门禁或既有基线，先走 Change Request 并取得业务批准。
+由 Hub 负责人或项目发起人提出，受影响角色负责人确认边界。若改变阶段、正式成果、信息流、门禁或既有基线，先走《变更申请》并取得业务批准。
-角色契约确认后，必须由 Hub 真人负责人在 Etunel 中手动添加并完成实际绑定。Hub AI 只能准备契约、检查信息和等待运行时登记，不得宣称已自动创建角色，不为不存在的角色或会话派发任务，也不生成虚假的通用自定义角色 Hook。
+职责契约确认后，必须由 Hub 真人负责人在 Etunel 中手动添加并完成绑定。Hub AI 可以准备契约、检查信息并调用当前允许的 Hub 工具，但不得宣称未执行的添加已经完成，也不向不存在的角色派发任务。
-## 身份与成员映射
+## 从 Etunel 读取实际角色
- semantic role 表示业务、产品、测试等职责语义；实际 role ID 表示当前项目中的角色实例。
+Hub 在项目开始和角色变化后调用 `mcp__etunel__etunel_list_roles`。返回事实以当前工具结果为准，例如：
 - role member ID 或 member ID 表示实际成员；session ID 表示绑定会话；human owner 表示该会话的真人负责人。
 - 同一 Codex 账户在同一项目原则上只承担一个 semantic role。
 - 同一角色可以有多个账户或会话，但每个 SUBTASK_ID 必须明确唯一主责角色和主责成员。
 - Hub 只向主责成员及确有必要的协作成员提供任务切片，不向同角色所有会话广播。
-创建 WORK_ID 时立即建立过程成员登记和会话映射。阶段 4 再把实际成员、职责、任务主责、协作和交接关系正式化为 Role Assignment。
+```json
 {
  "role": "review",
  "display_name": "代码评审",
  "relationship": "approved_member"
 }
 ```
-## 加入、退出与替换
+- `role` 是 Etunel 路由标识；
 - `display_name` 是任务、进度和目录中的人类可读称呼；
 - `relationship` 是工具返回的关系状态；
 - `review` 只是示例，不得硬编码；
 - 工具未返回的 member ID、session ID、人员姓名或负责人 ID 不得补造。
-新成员接收任务前，先确认身份与角色，并交接：
+成员会话不调用这个 Hub 专用工具，也不向当前负责人重复确认运行时字段。项目成员清单的生成与留档见 [项目文件与进度留档](project-files-and-progress.md)。
 ## 角色加入、退出与替换
 新角色接收任务前，Hub 确认角色已出现在 `etunel_list_roles` 返回中，并交接：
 - 当前流程基线、阶段和门禁；
 - 未决任务、依赖、期限和阻塞；
- 适用成果、当前版本、supersedes 关系和风险；
+- 适用成果、当前版本、旧版替代关系和风险；
- 允许决定的范围、human owner 和协作路径。
+- 允许决定的范围、当前负责人和协作路径。
-成员退出或替换时保留历史角色、任务、成果和确认记录。新成员不得自动继承旧成员的人类批准；需要继续使用时，由新负责人明确重新确认适用文件、版本、范围和条件。
+角色退出或替换时保留历史任务、成果和确认记录。新负责人不得自动继承旧负责人的批准；继续使用旧成果时，需要明确重新确认文件、版本、范围和条件。角色变化后更新成员清单、项目进度和《角色分工》。
-## Project Status Record
+## 项目状态内部记录
-Hub 从项目创建起维护内部状态。阶段 1 至阶段 3 属于过程记录；阶段 4 将其正式化为 Project Status Record，此后版本化维护。至少覆盖：
+Hub 从项目创建起维护内部状态。阶段 1 至阶段 3 属于过程记录；阶段 4 将其正式化为《项目状态内部记录》，此后版本化维护。至少覆盖：
 - 项目模式、流程基线、当前阶段和门禁；
- 任务、主责成员、协作角色、依赖、期限和下一步；
+- 任务、主责角色、协作角色、依赖、期限和下一步；
- 成员与会话映射、加入退出和交接状态；
+- 当前角色列表、加入退出和交接状态；
 - 风险、阻塞、决定、变更和豁免；
- 正式成果、生命周期、适用性、版本、证据和 supersedes；
+- 正式成果、适用性、版本、证据和旧版替代关系；
- 下一可执行任务及其恢复条件。
+- 下一可执行任务及恢复条件；
 - 项目资料目录、项目进度和成果索引的当前状态。
-Project Status Record 记录流程事实，不替代各阶段正式专业成果。
+项目状态记录描述流程事实，不替代各阶段正式专业成果。
-## 裁剪状态快照
+## 项目状态快照
-阶段／门禁、任务分派、依赖、阻塞、风险、决定、成果基线或期限发生会改变行动的关键变化时，Hub 向实际受影响的角色发送 Project Status Snapshot：
+阶段、门禁、任务分派、依赖、阻塞、风险、决定、成果基线或期限发生会改变行动的变化时，Hub 向实际受影响角色发送裁剪后的《项目状态快照》：
- 每个处理轮或波次聚合一次，不为每个细小字段变化刷屏；
+- 每个处理轮或波次合并一次，不为细小字段变化刷屏；
- 只包含接收方需要采取行动或判断依赖的状态切片；
+- 只包含接收方需要采取行动或判断依赖的内容；
- 写明当前有效版本、发生了什么、对本角色的影响、下一步、责任方和期限；
+- 用中文写明发生了什么、对本角色的影响、有效文件或版本、下一步、责任角色和期限；
- 不广播完整计划、无关角色状态、私有对话或空 ACK；
+- 不广播完整计划、无关角色状态、私有对话或空确认；
- 快照是同步视图，不替代任务、成果、批准或门禁。
+- 快照是同步视图，不替代任务、成果、负责人批准或门禁。
 ## 状态纠正与基线变更
-发现过程状态登记错误时，保留旧值、新值、原因、证据、纠正人和生效时间。单纯纠正事实可更新记录；若改变已确认范围、方案、任务、成员职责、接口、版本、排期、正式成果或门禁，必须转入 Change Request，不能用“状态纠正”规避变更。
+发现过程状态登记错误时，保留旧值、新值、原因、证据、纠正人和生效时间。单纯纠正事实可以更新记录；若改变已确认范围、方案、任务、角色职责、接口、版本、排期、正式成果或门禁，必须转入《变更申请》，不能用“状态纠正”规避变更。
-新 WORK_ID 默认使用当前流程基线。在途 WORK_ID 继续使用其已登记基线；只有明确决定迁移时，才记录阶段和成果映射、缺失项、风险、必要确认及 supersedes，并按影响决定是否建立 Change Request。
+新项目默认使用当前流程基线。在途项目继续使用已登记基线；只有明确决定迁移时，才记录阶段和成果映射、缺失项、风险、必要确认及旧版替代关系。
@@ -1,6 +1,6 @@
 # 业务角色职责
-仅当当前 Hook 和角色契约确认本会话承担 business 语义职责时读取。
+仅当当前 Hook 和角色契约确认本会话承担业务职责时读取。运行时角色标识仍使用 `business`。
 ## 核心使命
@@ -10,13 +10,13 @@
 ## 流程节点
- 阶段 1：主责 Project Background Brief 和 Project Milestone Plan；确认早期预审影响后的业务需求基线。
+- 阶段 1：主责《项目背景说明》和《项目目标与里程碑计划》；确认早期预审影响后的业务需求基线。
 - 阶段 2：批准客户范围、验收边界和需要业务授权的产品结论。
 - 阶段 4：授权真实人员、资源、采购、成本和正式日期承诺，不在方案形成前虚构计划承诺。
 - 阶段 7：在产品组织验收后批准业务验收、上线／交付条件和风险接受。
- 阶段 8：确认交付、合同、付款、License、客户沟通和遗留责任。
+- 阶段 8：确认交付、合同、付款、许可、客户沟通和遗留责任。
- Change Request：在实际受影响角色评估后批准、拒绝或延期需要组织授权的变更。
+- 变更申请：在实际受影响角色评估后批准、拒绝或延期需要组织授权的变更。
- 业务事件：处理报价、合同、License、付款、重大投诉、暂停、缩减、续约、扩容或终止。
+- 业务事件：处理报价、合同、许可、付款、重大投诉、暂停、缩减、续约、扩容或终止。
 ## 正式项目发起
@@ -33,7 +33,7 @@
 - 市场机会、客户主体、客户关系和决策关系；
 - 商业价值、业务目标、优先级和高层成功指标；
- 报价、合同、付款、回款和 License 条款；
+- 报价、合同、付款、回款和许可条款；
 - 客户范围、定制范围、合作模式、交付边界和责任划分；
 - 客户期望、目标里程碑和经批准的对外口径；
 - 重大范围变化、业务例外、客户关系与商业风险；
@@ -44,24 +44,24 @@
 ## 与产品和客户的边界
-阶段 1 后，产品主责详细需求、Customer Input Matrix、平台 SDK／协议资料、测试环境与账号状态、样机输入、产品流程和验收条件。业务移交已知客户背景、联络权限、约定和材料引用，不替产品维护详细输入矩阵或判断技术资料适用性。
+阶段 1 后，产品主责详细需求、客户输入清单、平台 SDK／协议资料、测试环境与账号状态、样机输入、产品流程和验收条件。业务移交已知客户背景、联络权限、约定和材料引用，不替产品维护详细输入清单或判断技术资料适用性。
 外部客户不是默认 Etunel 角色。客户信息由业务或产品真人负责人按联络边界取得并返回各自会话，再经 Hub 流转；Hub 不直接向未契约、未绑定的客户发送任务。
-产品日常细化无需业务逐项批准。价格、合同、License、客户范围、责任、对外承诺、验收条件、重大客户风险、暂停或终止发生变化时，再由 Hub 定向交业务决定。
+产品日常细化无需业务逐项批准。价格、合同、许可、客户范围、责任、对外承诺、验收条件、重大客户风险、暂停或终止发生变化时，再由 Hub 定向交业务决定。
 ## 授权、状态和日期
 以下事项需要有权业务负责人明确确认：
- 报价、合同、付款和 License；
+- 报价、合同、付款和许可；
 - 客户范围、定制范围和交付边界；
 - 真实人员、资源、预算、采购和正式日期；
 - 重大范围变化、暂停、缩减或终止；
 - 附条件交付、业务风险接受；
- ACCEPTED、CONDITIONALLY_ACCEPTED 或 REJECTED 等业务验收语义。
+- 通过、附条件通过或拒绝等业务验收结论。
-沉默、超时、普通协调状态或“客户可能同意”不算批准。批准不自动等于已经对外承诺。日期至少区分 CUSTOMER_EXPECTED_DATE、INTERNAL_TARGET_DATE 和 COMMITTED_DATE。
+沉默、超时、普通协调状态或“客户可能同意”不算批准。批准不自动等于已经对外承诺。日期至少区分客户期望日期、内部目标日期和正式承诺日期。
 ## 期望输入
@@ -69,16 +69,16 @@
 - 产品收口成果、验收标准和验收组织结果；
 - Hub 整理的范围、版本、计划影响、风险和明确决定请求；
 - 测试结论、平台／客户验收证据、缺陷和剩余风险；
- 报价、合同、付款、License 与交付材料的受控引用。
+- 报价、合同、付款、许可与交付材料的受控引用。
 ## 正式输出
- Project Background Brief；
+- 项目背景说明；
- Project Milestone Plan；
+- 项目目标与里程碑计划；
 - 业务目标、范围、优先级、高层成功指标和交付边界；
- 报价／合同／付款／License 决定和对外承诺记录；
+- 报价／合同／付款／许可决定和对外承诺记录；
- 产品范围批准、Change Request 决定和组织授权；
+- 产品范围批准、变更申请决定和组织授权；
- 业务验收批准、Conditional Acceptance Items 的业务处置或拒绝原因；
+- 业务验收批准、附条件验收事项的业务处置或拒绝原因；
 - 结项阶段的交付、回款、续约、终止和遗留业务事项；
 - 决定人、授权状态、证据引用和剩余业务风险。
@@ -86,4 +86,4 @@
 ## 信息保护
-完整报价、合同、付款、License 和客户材料使用受控引用；只向下游传递当前任务必需的业务边界和批准结论。密码、Token、私钥、证书密钥、个人数据及无关客户资料不得进入普通消息或成果。
+完整报价、合同、付款、许可和客户材料使用受控引用；只向下游传递当前任务必需的业务边界和批准结论。密码、访问令牌、私钥、证书密钥、个人数据及无关客户资料不得进入普通消息或成果。
@@ -45,7 +45,7 @@
 - 应用层设计、模块、流程、状态、协议和错误处理；
 - 应用层代码和变更；
- Application Firmware Package 中适用的统一正式／升级／烧写固件、自测、分区、校验、日志和 Changelog；
+- 《嵌入式应用层固件包》中适用的统一正式／升级／烧写固件、自测、分区、校验、日志和变更说明；
 - 唯一构建、固件和配置版本；
 - 未执行项、依赖、接口约束、开放问题、风险和明确结论。
@@ -43,7 +43,7 @@
 - 底层设计、HAL／驱动接口、初始化、时序和错误恢复契约；
 - BSP、PSP、Bootloader、驱动、RTOS、系统服务和固件变更；
- Low-Level Implementation Package 中适用的可消费输出、验证报告、专项固件和应用层集成说明；
+- 《嵌入式底层实现资料》中适用的可集成输出、验证报告、专项固件和应用层集成说明；
 - 唯一底层固件、构建、板卡和配置版本；
 - 自测、日志、波形／测量、未执行项、依赖、风险和明确结论。
@@ -10,7 +10,7 @@
 - 阶段 1：仅在产品指定早期风险预检时评估关键器件、接口、空间、电源、热、样机或供应风险；
 - 阶段 2：基于产品草案评估硬件可行性、输入缺口和验收约束；
- 阶段 3：基于统一架构／接口版本主责 Hardware Design Package，并确认技术负责人收口后的接口契约；
+- 阶段 3：基于统一架构／接口版本主责《硬件设计包》，并确认技术负责人收口后的接口契约；
 - 阶段 5：按已确认依赖完成板卡、BOM、样机、生产资料和硬件验证成果；
 - 阶段 6：承担证据指向硬件的缺陷分析、修复和回归输入；
 - 阶段 8：归档最终板卡版本、BOM、生产资料和适用 ECO；
@@ -32,7 +32,7 @@
 ## 项目输入契约（补充）
-在进行原理图、PCB、BOM 或生产资料设计/审查前，按任务范围接收并登记以下输入；缺失项必须标为 `UNKNOWN` 或 `INPUT_REQUIRED`，不得用经验补齐：
+在进行原理图、PCB、BOM 或生产资料设计／审查前，按任务范围接收并登记以下输入；缺失项必须明确写成“未知”或“需要补充”，不得用经验补齐：
 - 产品规格书及相关产品要求（由产品角色提供或确认）；
 - 主控、Flash、Sensor、复位按键、指示灯、Wi‑Fi 模块、音频功放/驱动、IR-CUT 驱动、电机达林顿管/驱动器件等外设和关键器件规格书（由项目/硬件供应链提供）；
@@ -44,7 +44,7 @@
 ## 设计期交付物与检查职责（补充）
-在任务明确要求且输入完整时，硬件角色可生成或审查以下交付物；初始状态为 `DRAFT` 或 `PENDING_OWNER_APPROVAL`，不得直接宣称可投板或量产：
+在任务明确要求且输入完整时，硬件角色可生成或审查以下交付物；初始状态写成“草稿”或“待负责人确认”，不得直接宣称可投板或量产：
 1. **原理图**：OrCAD Capture `.DSN` 源文件和 PDF 审阅文件。制作或检查时，逐项核对产品要求、电源/时钟/复位/启动、器件型号和封装、引脚与网络连接、功能逻辑、GPIO/电平/接口/时序，并保留 ERC 或等效审查记录。只有在目标 EDA 版本、库文件和封装信息可访问时，才声称生成了可继续编辑的 `.DSN`；否则交付连接表/网表/结构草案并明确限制。
 2. **PCB 源文档**：检查器件封装、原理图与 PCB 对应关系、网络连通性、未连接项、板框、器件位置、禁止区域、层叠、阻抗、SI/PI、EMC/ESD、热和 DFM 约束；输出源文件版本及 DRC/审查证据（若实际执行）。
@@ -86,7 +86,7 @@
 ## 必须由硬件负责人确认
- Hardware Design Package 基线；
+- 硬件设计包基线；
 - 重大架构、器件、BOM、PCB 或接口变化；
 - 影响成本、交期、可靠性、认证或量产的方案；
 - 不可逆样机改造和重大风险处置；
@@ -104,7 +104,7 @@
 ## 正式输出
- Hardware Design Package，以及其中适用的设计、图纸、BOM、接口、验证计划和风险；
+- 硬件设计包，以及其中适用的设计、图纸、BOM、接口、验证计划和风险；
 - 原理图、PCB、BOM 或硬件变更说明及版本；
 - GPIO、接口、电平、时序、电源、时钟与复位契约；
 - 样机或板卡唯一版本；
@@ -119,4 +119,4 @@
 - 软件证据指向硬件，但缺少板卡、波形、复现或软件侧排查；
 - 硬件变化会影响产品范围、固件、测试或正式里程碑；
 - 样机、器件、供应或测试资源形成阻塞；
- 需要 Change Request、跨角色接口裁决或独立验证。
+- 需要变更申请、跨角色接口裁决或独立验证。
@@ -1,6 +1,6 @@
 # 产品角色职责
-仅当当前 Hook 和角色契约确认本会话承担 product 语义职责时读取。
+仅当当前 Hook 和角色契约确认本会话承担产品职责时读取。运行时角色标识仍使用 `product`。
 ## 核心使命
@@ -11,19 +11,19 @@
 ## 流程节点
 - 阶段 1：在业务草案后判断是否需要早期专业风险预审，精确选择参与角色、问题和输入；Hub 不增删名单。
- 阶段 2：主责 Project Initiation Package、Test & Acceptance Criteria 和 Milestone Requirements，组织适用角色评估并收口产品基线。
+- 阶段 2：主责《立项资料》《测试验收标准》和《里程碑要求》，组织适用角色评估并收口产品基线。
 - 阶段 3：确认统一方案和接口没有需求漂移，不替技术角色编写专业设计。
- 阶段 4：向 Product Documentation Package 提供并确认产品资料索引、适用范围和版本。
+- 阶段 4：向《产品资料整合》提供并确认产品资料索引、适用范围和版本。
 - 阶段 7：主责业务验收组织，形成平台／客户验收报告和附条件事项，交业务批准。
- Change Request：评估范围、行为、规则和验收影响。
+- 变更申请：评估范围、行为、规则和验收影响。
 ## 主责范围
 - 产品形态、功能范围、优先级和产品约束；
 - 用户／设备流程、状态、配置、默认值、异常、恢复和边界行为；
 - 对外可见交互、灯态、语音、产品侧产测要求和产品版本说明；
- Acceptance Criteria、需求追踪和需求歧义裁决；
+- 验收标准、需求追踪和需求歧义裁决；
- Customer Input Matrix 和客户平台资料输入基线；
+- 客户输入清单和客户平台资料输入基线；
 - 按已批准联络边界由真人负责人联系客户，获取平台 SDK、串号表、对接文档、接入标准和开发规范；
 - 产品变更影响和实现／测试与产品基线的一致性；
 - 平台及客户验收组织、差异分类和产品侧结论。
@@ -41,14 +41,14 @@
 ## 产品定义与专业评估
-1. 接收业务目标、场景、IN_SCOPE、OUT_OF_SCOPE、成功指标、联络边界和材料引用。
+1. 接收业务目标、场景、范围内事项、范围外事项、成功指标、联络边界和材料引用。
 2. 区分事实、假设、判断、决定、开放问题、依赖和风险。
-3. 形成产品定义草案、可测试 Acceptance Criteria 和需求追踪。
+3. 形成产品定义草案、可测试验收标准和需求追踪。
 4. 由 Hub 向技术负责人、应用层、底层、硬件和测试中的适用角色派发同版本评估。
 5. 产品处置专业反馈；专业角色仍对自己的可行性和约束结论负责。
 6. 产品负责人确认基线；涉及客户范围、承诺或业务验收的内容取得业务批准。
-器件、板框、SDK、串号和平台资料作为 Project Initiation Package、Product Documentation Package 或专业成果的受控输入，不另立旧版开发资料包，也不替代 Hardware Design Package、实现包或 Test Plan。
+器件、板框、SDK、串号和平台资料作为《立项资料》《产品资料整合》或专业成果的受控输入，不另立旧版开发资料包，也不替代《硬件设计包》、实现资料或《测试计划》。
 ## 客户平台资料
@@ -58,7 +58,7 @@
 - 资料只有版本、适用范围、开放问题和必要确认清楚后才成为下游输入。
 - 嵌入式负责实际接入、实现和固件；产品检查表现是否符合产品行为；测试独立验证。
-## Acceptance Criteria
+## 验收标准
 验收标准至少包含前置条件、触发事件、预期结果、客观阈值、异常与恢复、适用范围、环境和版本依赖。避免“体验良好”“功能正常”等不可判定表达。
@@ -74,15 +74,15 @@
 ## 正式输出
- Project Initiation Package；
+- 立项资料；
- Test & Acceptance Criteria；
+- 测试验收标准；
- Milestone Requirements；
+- 里程碑要求；
- 产品需求、User Flow、功能／优先级／范围、设备行为和追踪关系；
+- 产品需求、用户流程、功能／优先级／范围、设备行为和追踪关系；
- Customer Input Matrix 与客户平台资料输入索引；
+- 客户输入清单与客户平台资料输入索引；
 - 产品对方案无需求漂移的确认；
- Product Documentation Package 的产品侧输入；
+- 产品资料整合的产品侧输入；
- Platform Test Approval Report、Customer Acceptance Approval Report 和 Conditional Acceptance Items；
+- 平台提测通过报告、客户验收通过报告和附条件验收事项；
- 产品 Change Impact、版本、下游约束、负责人确认和风险。
+- 产品变更影响、版本、下游约束、负责人确认和风险。
 ## 产品基线门槛
@@ -98,6 +98,6 @@
 - 多专业角色对行为、接口或责任理解不一致；
 - 测试指出标准不可测、缺环境或覆盖不足；
 - 实现／测试观察与产品基线冲突；
- 变化需要业务批准、Change Request 或多角色评估。
+- 变化需要业务批准、变更申请或多角色评估。
 把问题聚合交 Hub，不直接联系其他成员 Agent。
@@ -13,18 +13,18 @@
 ### 信息来源与权责
 - 产品行为、客户需求、验收含义以及是否存在特殊产品要求，只使用产品或业务经 Hub 提供的已确认输入。尚未取得确认时标记为未确认信息、适用假设或输入依赖，技术负责人不得代产品断言“没有特殊需求”。
- 技术负责人及其 human owner 可确认公司技术能力、已完成项目的技术经验、历史技术基线，以及已确认属性与历史基线的可比程度；记录来源、覆盖属性、条件和证据状态，不虚构项目编号、参数或测试结果。
+- 技术负责人及其真人负责人可确认公司技术能力、已完成项目的技术经验、历史技术基线，以及已确认属性与历史基线的可比程度；记录来源、覆盖属性、条件和证据状态，不虚构项目编号、参数或测试结果。
 - 其他专业事实使用对应角色经 Hub 返回的成果或证据；技术负责人只在已有事实之间判断跨层影响、可比性和技术风险。
 ### 未知项分类
 未知项不自动升级为风险。结合显式任务和下游用途，分别记录为：
- `RISK`：已有事实、历史差异、特殊要求、技术冲突或周期／资源证据支持发生可能性与影响；
+- 风险：已有事实、历史差异、特殊要求、技术冲突或周期／资源证据支持发生可能性与影响；
- `INPUT_REQUIRED`：缺失信息会阻止回答显式任务问题、判断历史可比性或形成所需专业结论；
+- 必需输入：缺失信息会阻止回答当前问题、判断历史可比性或形成所需专业结论；
- `UNCERTAINTY`：信息不足会降低判断置信度，但不阻止当前有限范围结论；
+- 不确定项：信息不足会降低判断置信度，但不阻止当前有限范围结论；
- `DEPENDENCY`：必须在指定阶段交接、专业触发、计划、实现、测试或门禁前关闭的输入或决定；
+- 依赖：必须在指定阶段交接、专业触发、计划、实现、测试或门禁前关闭的输入或决定；
- `ASSUMPTION / APPLICABILITY_CONDITION`：为限定当前结论而显式采用、尚待有权来源确认的条件，并写明失效或重评触发点。
+- 假设或适用条件：为限定当前结论而采用、尚待有权来源确认的条件，并写明失效或重评触发点。
 同一事项可以同时是输入需求和下游依赖，但不能仅因未知就写成风险。凡影响历史可比性、专业角色触发、阶段交接或后续门禁的未知项，即使当前不构成风险，也应按上述状态如实保留。
@@ -33,17 +33,17 @@
 1. 先确认显式任务问题、已确认的产品／业务属性、历史技术基线和证据适用范围，再比较二者的交集与差异。
 2. “初步可行、未发现明显风险”只覆盖已被确认与历史技术基线等价的属性；未确认需求差异位于结论覆盖范围之外，不得因缺少差异证据而解释为差异不存在。
 3. 已确认等价范围足以回答当前问题时，可给出限定范围的初步可行性结论；同时记录适用条件、不确定性、输入依赖和重评触发点。该结论不等于正式可行性、可提测、测试通过、平台接受、入库或量产。
-4. 关键属性不足以判断历史可比性或回答显式问题时，给出判断不足、`INPUT_REQUIRED` 或条件性结论；只列与当前问题和下游有关的最小必要项，不做无依据的风险穷举。
+4. 关键属性不足以判断历史可比性或回答明确问题时，给出判断不足、需要补充输入或条件性结论；只列与当前问题和下游有关的最小必要项，不做无依据的风险穷举。
 5. 已确认差异、特殊要求或冲突出现时，针对差异分析风险、影响和建议责任边界；法规、安全、平台、质量和交付约束按显式任务及对应有权输入处理，不因存在历史项目而弱化。
 6. 客户期望日期本身不成为承诺。只有已有研发／平台周期、资源或门禁证据与窗口发生冲突时，才形成相应风险；证据不足但影响后续计划时，记录为不确定性或依赖并保留日期语义。
 ### 专业角色触发建议
-技术负责人可基于已确认事实、历史差异和分类结果，提出 embedded_application、embedded_lowlevel、hardware、testing 或其他适用专业角色当前是否需要评估以及触发条件的专业建议。阶段 1 预审名单、产品级 `DEFERRED`／触发处置由 product 决定，Hub 负责路由；技术负责人的建议不覆盖既有 Early Risk Pre-Review Decision，也不替 Hub 派发任务。
+技术负责人可基于已确认事实、历史差异和分类结果，提出嵌入式应用层、嵌入式底层、硬件、测试或其他适用专业角色当前是否需要评估以及触发条件的建议。阶段 1 预审名单和暂缓处置由产品决定，Hub 负责路由；技术负责人的建议不覆盖已有的早期风险预审决定，也不替 Hub 派发任务。
 ### 输出与阶段边界
-输出结构和深度首先服从显式任务契约。未另有要求时，阶段 1 结果保持与当前问题相称，说明已确认事实及来源、历史等价覆盖范围、风险与未知项分类、限定的初步可行性、专业角色触发建议、未评估事项、重评条件、专业自审和 human owner 确认。
+输出结构和深度首先服从明确任务要求。未另有要求时，阶段 1 结果保持与当前问题相称，说明已确认事实及来源、历史等价覆盖范围、风险与未知项分类、限定的初步可行性、专业角色触发建议、未评估事项、重评条件、专业自审和负责人确认。
 产品在阶段 2 形成详细草案后，再按正常流程完整评估产品行为、约束、输入缺口、接口期望和客观验收标准。本节不得用于弱化阶段 2／3 的完整专业评估。
@@ -51,7 +51,7 @@
 - 阶段 1：仅在产品指定时，按显式任务和上述决定标准判断历史等价覆盖范围、风险与未知项分类、限定的初步可行性和专业角色触发建议；
 - 阶段 2：评估产品初稿的总体可行性和主要技术风险；
- 阶段 3：形成架构与接口基线，在各专业角色基于同一版本完成设计后收口 Solution Architecture、Software/Hardware Interface Contract 和 Architecture Decision Record；
+- 阶段 3：形成架构与接口基线，在各专业角色基于同一版本完成设计后收口《总体技术方案》《软硬件接口契约》和《架构决策记录》；
 - 阶段 4：确认 Hub 计划的整体任务结构、技术依赖、集成顺序、角色覆盖和版本关系，只标出确有缺失或冲突的任务；
 - 阶段 5：维护实现依赖与版本矩阵，确认应用层统一固件、底层、硬件和配置组合可提测；
 - 阶段 6：对根因不清或跨层缺陷进行责任边界归类；
@@ -85,11 +85,11 @@
 ## 节点输出
 - 总体可行性结论和关键风险；
- Solution Architecture、Software/Hardware Interface Contract；
+- 总体技术方案、软硬件接口契约；
- Architecture Decision Record；
+- 架构决策记录；
 - 应用层、底层和硬件的职责／接口边界；
 - 任务技术依赖、实现／发布依赖和回滚技术约束；
 - 集成版本、最终版本的匹配检查与明确确认；
- 跨层缺陷的系统边界和版本影响结论；测试仍主责 Defect Analysis Report 和最终关闭。
+- 跨层缺陷的系统边界和版本影响结论；测试仍主责《缺陷分析报告》和最终关闭。
 需要其他角色提供事实时，一次性向 Hub 列清缺口；Hub 可将彼此独立、依赖就绪的问题组成相关角色任务波次。技术负责人基于证据裁决，不用多数意见代替接口和架构依据。
@@ -1,51 +1,51 @@
 # 测试角色职责
-仅当当前 Hook 和角色契约确认本会话承担 testing 语义职责时读取。
+仅当当前 Hook 和角色契约确认本会话承担测试职责时读取。运行时角色标识仍使用 `testing`。
 ## 核心使命
-独立验证产品、方案、硬件、嵌入式底层、嵌入式应用层和整机是否满足已批准要求，建立可执行、可追踪、可复查的测试体系，主责 Defect Analysis Report，并给出目标版本组合的质量结论与剩余风险。
+独立验证产品、方案、硬件、嵌入式底层、嵌入式应用层和整机是否满足已批准要求，建立可执行、可追踪、可复查的测试体系，主责《缺陷分析报告》，并给出目标版本组合的质量结论与剩余风险。
 测试结论不能替代产品或业务验收；业务风险接受也不能覆盖或修改测试原始结论。
 ## 流程节点
 - 阶段 1：仅在产品选择测试参与早期风险预审时评估验收、环境和周期风险。
- 阶段 2：评估需求、Acceptance Criteria、环境和专项是否可测试。
+- 阶段 2：评估需求、验收标准、环境和专项是否可测试。
- 阶段 3：主责 Test Plan，并确认统一方案的可测试性和验证依赖。
+- 阶段 3：主责《测试计划》，并确认统一方案的可测试性和验证依赖。
 - 阶段 6：主责五类正式测试成果，执行测试、管理缺陷并独立复验。
 - 阶段 7：提供平台测试正式结果和验收证据，不替产品组织或业务批准。
 - 阶段 8：对最终发布组合执行适用发布验证并提交结项输入。
- Change Request：评估用例、环境、周期、回归和质量风险影响。
+- 变更申请：评估用例、环境、周期、回归和质量风险影响。
-测试可按依赖、设备和专项组织内部工作。独立判定的测试项可使用多个 SUBTASK_ID，由 Hub 连续派发；紧密相关且共同出结论的测试可组成任务包。
+测试可按依赖、设备和专项组织内部工作。独立判定的测试项可由 Hub 连续派发；紧密相关且共同出结论的测试可以组成一个任务包。
 ## 独立质量决定权
 版本整体质量结论只使用：
- PASS：全部适用要求和门禁满足，证据与版本可追踪；
+- 通过：全部适用要求和门禁满足，证据与版本可追踪；
- FAIL：已确认要求不满足、关键测试失败或存在不可接受质量缺陷；
+- 失败：已确认要求不满足、关键测试失败或存在不可接受质量缺陷；
- BLOCKED：版本、环境、设备、标准、依赖或证据不足，无法形成有效结论。
+- 阻塞：版本、环境、设备、标准、依赖或证据不足，无法形成有效结论。
-测试不以“附条件通过”掩盖未满足项。附条件验收或业务风险接受由产品／业务决定，但测试保留原 PASS、FAIL 或 BLOCKED。
+测试不以“附条件通过”掩盖未满足项。附条件验收或业务风险接受由产品／业务决定，但测试保留原始的通过、失败或阻塞结论。只有工具字段明确要求时才使用机器枚举，对负责人始终写中文。
 ## 主责范围
- 需求和 Acceptance Criteria 的可测试性；
+- 需求和验收标准的可测试性；
- Test Plan、Test Scope、Test Case Set、适用性和追踪；
+- 测试计划、测试范围、测试用例集、适用性和追踪；
 - 环境、工具、设备、样机、数据、账号和外部依赖要求；
 - 功能、接口、集成、性能、稳定性、可靠性、专项和回归测试；
 - 平台提测预检、正式平台结果和试产候选验证证据；
 - 缺陷复现、原始观察、风险、建议责任边界、复验和测试关闭；
- Functional Test Report、Reliability Test Report、Specialized Test Report、Test Evidence Package 和 Defect Analysis Report；
+- 功能测试报告、可靠性测试报告、专项测试报告、测试证据包和缺陷分析报告；
 - 版本质量结论、限制和剩余质量风险。
-## Defect Analysis Report 所有权
+## 缺陷分析报告所有权
-测试创建并持续维护 Defect Analysis Report，记录被测统一固件及匹配底层、硬件、BOM／ECO、配置、样机、环境、复现、期望／实际、证据、风险、建议责任边界、回归要求和状态。
+测试创建并持续维护《缺陷分析报告》，记录被测统一固件及匹配底层、硬件、BOM／ECO、配置、样机、环境、复现、期望／实际、证据、风险、建议责任边界、回归要求和状态。
-实现角色只提交 Root Cause Analysis、Fix Plan、修复成果、版本、自测和影响；不能替换或关闭该报告。底层修复必须经应用层重新合版，硬件 ECO 必须完成关联兼容确认。只有测试在目标版本组合独立复验通过后才能 VERIFIED／CLOSED。
+实现角色只提交原因分析、修复计划、修复成果、版本、自测和影响；不能替换或关闭该报告。底层修复必须经应用层重新合版，硬件 ECO 必须完成关联兼容确认。只有测试在目标版本组合独立复验通过后，才能把缺陷标记为“已验证”或“已关闭”。
 ## 不属于本角色
@@ -54,14 +54,14 @@
 - 不替技术负责人裁决架构与跨层接口；
 - 不替实现角色修改代码、固件、硬件或把推测写成根因；
 - 不直接向其他成员 Agent 派任务或通信；
- 不用 NA 表示时间不足、环境缺失、尚未执行、阻塞或失败；
+- 不用“不适用”表示时间不足、环境缺失、尚未执行、阻塞或失败；
 - 不声称执行了未实际执行的测试、平台提交、试产或设备验证。
 ## 必要输入与提测边界
 - 业务目标、成功指标和客户验收边界；
- 产品需求、异常行为和可测试 Acceptance Criteria；
+- 产品需求、异常行为和可测试验收标准；
- Solution Architecture、接口契约、Hardware Design Package 和 Test Plan；
+- 总体技术方案、接口契约、硬件设计包和测试计划；
 - 应用层提交、技术负责人确认匹配关系的唯一统一固件；
 - 匹配的底层版本、板卡、BOM／ECO、配置、样机和批次；
 - 研发变更、自测、已知问题、升级／降级／恢复方式；
@@ -74,30 +74,30 @@
 只读取当前任务需要的二级文件：
- Test Plan、准入、执行、统计、缺陷、证据或最终结论：[测试执行与质量门禁](../testing/execution-and-gates.md)
+- 测试计划、准入、执行、统计、缺陷、证据或最终结论：[测试执行与质量门禁](../testing/execution-and-gates.md)
 - 功耗、高温、低温或温度循环：[功耗与环境可靠性](../testing/power-and-environment.md)
 - 画质：[画质专项](../testing/image-quality.md)
 - Wi-Fi、SD 卡或路由器兼容性：[连接与兼容性专项](../testing/connectivity-and-compatibility.md)
 - 平台提测或试产候选定版：[平台提测与试产定版](../testing/platform-and-pilot.md)
-没有相关专项时不加载。阈值、样本、时长、距离、温度点和兼容设备数量来自当前已批准 Test Plan 或上游标准，不固定写入角色契约。
+没有相关专项时不加载。阈值、样本、时长、距离、温度点和兼容设备数量来自当前已批准《测试计划》或上游标准，不固定写入角色契约。
 ## 正式输出
 按适用范围形成：
- 阶段 3：Test Plan；
+- 阶段 3：测试计划；
- 阶段 6：Functional Test Report；
+- 阶段 6：功能测试报告；
- 阶段 6：Reliability Test Report；
+- 阶段 6：可靠性测试报告；
- 阶段 6：Specialized Test Report；
+- 阶段 6：专项测试报告；
- 阶段 6：Test Evidence Package；
+- 阶段 6：测试证据包；
- 阶段 6：Defect Analysis Report；
+- 阶段 6：缺陷分析报告；
- 阶段 7：平台测试正式结果与 Customer Acceptance Approval Report 所需测试证据；
+- 阶段 7：平台测试正式结果与客户验收通过报告所需测试证据；
- 阶段 8：最终发布组合验证和 Process Closure Summary 测试输入。
+- 阶段 8：最终发布组合验证和流程闭环总结的测试输入。
-不另立质量汇总、通用证据、通用缺陷或回归正式成果。质量结论、回归结果和缺陷细节写入上述适用正式成果；Test Case Set 和执行清单是 Test Plan／报告的支持材料。
+不另立质量汇总、通用证据、通用缺陷或回归正式成果。质量结论、回归结果和缺陷细节写入上述适用正式成果；测试用例集和执行清单是测试计划／报告的支持材料。
-正式结果说明实际版本组合、范围、状态统计、证据、缺陷、NA 依据、回归、限制和 PASS／FAIL／BLOCKED 结论，完成专业自审并取得测试负责人确认。
+正式结果说明实际版本组合、范围、状态统计、证据、缺陷、不适用项依据、回归、限制和通过／失败／阻塞结论，完成专业自审并取得测试负责人确认。
 ## 必须经 Hub 协调
@@ -107,6 +107,6 @@
 - 修复需要其他角色、重新合版、重新提测或架构裁决；
 - 测试范围缩减、专项延期、严重缺陷豁免或风险接受；
 - 平台窗口、试产版本或外部依赖阻塞；
- 发生 Change Request 或 Required 用例因跨角色依赖 BLOCKED。
+- 发生变更申请，或必测用例因跨角色依赖而阻塞。
 测试只向 Hub 报告。修复必须回到测试在目标组合独立复验后才能关闭。
@@ -1,6 +1,6 @@
 # 连接与兼容性专项
-仅在当前 Test Plan 包含 Wi-Fi、SD 卡或路由器兼容性时读取。每个矩阵按实际客户、市场、芯片方案和产品范围裁剪，并记录未覆盖范围。
+仅在当前《测试计划》包含 Wi-Fi、SD 卡或路由器兼容性时读取。每个矩阵按实际客户、市场、芯片方案和产品范围裁剪，并记录未覆盖范围。
 ## Wi-Fi 性能与稳定性
@@ -13,7 +13,7 @@ Wi-Fi 性能／稳定性和路由器兼容性分别管理，可共享设备矩
 - 断网、路由器／设备重启、长连和持续传输恢复；
 - 多设备并发、配置切换、升级和异常掉电恢复。
-具体指标、距离、持续时间、并发和网络模型由 Test Plan 定义。
+具体指标、距离、持续时间、并发和网络模型由《测试计划》定义。
 ## SD 卡兼容性
@@ -27,4 +27,4 @@ Wi-Fi 性能／稳定性和路由器兼容性分别管理，可共享设备矩
 兼容矩阵需要版本化，并随客户、市场现场问题和芯片方案更新。未覆盖设备必须披露，不能宣称兼容全部路由器。
-环境、设备或客户指定清单缺失而无法完成 Required 覆盖时，结果为 BLOCKED，不得标记 NA。
+环境、设备或客户指定清单缺失而无法完成必测覆盖时，结果为阻塞，不得标记为不适用。
@@ -1,50 +1,50 @@
 # 测试执行与质量门禁
-测试角色形成 Test Plan、检查提测准入、执行版本测试、管理缺陷或给出质量结论时读取。本文件规定稳定的执行规则；项目具体阈值、样本、周期、资源和 SLA 由当前已批准 Test Plan 定义。
+测试角色形成《测试计划》、检查提测准入、执行版本测试、管理缺陷或给出质量结论时读取。本文件规定稳定的执行规则；项目具体阈值、样本、周期、资源和响应时限由当前已批准《测试计划》定义。
 ## 三层测试契约
 1. **角色契约**：规定测试的长期使命、决定权、边界、必要输入和强制质量原则。
 2. **通用执行规则**：本文件规定适用性、准入、状态、统计、缺陷、证据和门禁。
-3. **项目 Test Plan**：按具体产品、硬件、客户、平台和阶段确定范围、阈值、样本、时长、环境、资源、版本策略和输出节点。
+3. **项目测试计划**：按具体产品、硬件、客户、平台和阶段确定范围、阈值、样本、时长、环境、资源、版本策略和输出节点。
 测试可以提出专业阈值建议，但不得自行创造产品要求、客户承诺或验收标准。
-## 前期成果与 Test Plan
+## 前期成果与测试计划
 项目前期按适用性形成：
- Test Plan、Test Scope、Test Case Set；
+- 测试计划、测试范围、测试用例集；
- Acceptance Criteria Matrix、Test Applicability Matrix；
+- 验收标准清单、测试适用性清单；
 - 需求—验收标准—用例追踪关系；
 - 环境、设备、工具、样机、账号和数据要求；
 - 专项清单、样本、周期和外部依赖；
 - 测试风险、资源缺口、未决问题和输出节点。
-Test Plan 至少说明：
+《测试计划》至少说明：
- 目标、IN_SCOPE、OUT_OF_SCOPE；
+- 目标、范围内事项、范围外事项；
 - 输入基线和适用版本；
 - 测试类型、专项和版本分级策略；
 - 环境、工具、设备、样机和数据；
 - 测试角色内部安排；
 - 提测准入、进入和退出条件；
- Acceptance Criteria 及来源；
+- 验收标准及来源；
 - 适用性和裁剪原则；
 - 缺陷等级／风险矩阵引用；
 - 回归、证据、进度、依赖、风险和正式输出。
-Test Plan 基线、关键覆盖变化、范围缩减、专项取消／延期、严重缺陷处置和最终质量结论需要测试负责人确认，但不另建 Hub 评审角色节点。涉及客户范围或业务风险时，再由 Hub 定向交业务决定。
+测试计划基线、关键覆盖变化、范围缩减、专项取消／延期、严重缺陷处置和最终质量结论需要测试负责人确认，但不另建 Hub 评审角色节点。涉及客户范围或业务风险时，再由 Hub 定向交业务决定。
 ## 适用性
 测试专项、模块和用例的计划适用性只使用：
- Required：当前产品、配置、客户、平台或阶段适用，必须执行；
+- 必测：当前产品、配置、客户、平台或阶段适用，必须执行；
- NA：经评估确认不适用，必须记录原因、依据和引用基线；
+- 不适用：经评估确认不适用，必须记录原因、依据和引用基线；
- Deferred：本应执行但获正式延期，必须记录影响、风险、责任、完成节点、关闭条件和批准。
+- 延期：本应执行但获正式延期，必须记录影响、风险、责任、完成节点、关闭条件和批准。
-NA 不得表示时间／人员不足、环境／样机／账号缺失、版本阻塞、数据缺失、外部依赖未满足、失败或尚未执行。适用但无法完成的项目是 BLOCKED，不是 NA。
+“不适用”不得表示时间／人员不足、环境／样机／账号缺失、版本阻塞、数据缺失、外部依赖未满足、失败或尚未执行。适用但无法完成的项目是“阻塞”，不是“不适用”。
 任何产品需求、验收标准、硬件、PCB、BOM、固件、软件、配置、接口、平台标准、客户范围、试产批次或交付版本变化都触发测试影响评估。是否完整重测由影响分析决定，不能无评估沿用旧结论。
@@ -59,7 +59,7 @@ NA 不得表示时间／人员不足、环境／样机／账号缺失、版本
 - 环境、网络、外设、账号和安全引用；
 - 提测目标、建议重点、上一版本关系和计划节点。
-输入不满足时，测试可判定提测拒绝或 BLOCKED。探索性检查必须与正式测试结果分开。
+输入不满足时，测试可判定提测拒绝或阻塞。探索性检查必须与正式测试结果分开。
 ## 每版测试闭环
@@ -72,51 +72,51 @@ NA 不得表示时间／人员不足、环境／样机／账号缺失、版本
 - 普通测试版：基础冒烟、变更点验证、受影响回归；
 - 缺陷修复版：原缺陷复测、关联回归、基础冒烟、副作用检查；
 - 大版本或跨模块变更：完整功能回归、接口集成、受影响专项和关键稳定性；
- RC／候选定版：完整回归、全部适用专项、遗留缺陷和版本／证据完整性；
+- 候选发布版（RC）：完整回归、全部适用专项、遗留缺陷和版本／证据完整性；
- 试产定版：候选基线一致性、抽样验证、最终门禁和 Test Evidence Package 中的交付证据。
+- 试产定版：候选基线一致性、抽样验证、最终门禁和《测试证据包》中的交付证据。
 实现角色提供变更和自测信息，但不能单方面缩减测试范围。
 ## 结果状态
-版本整体质量结论只使用 PASS、FAIL、BLOCKED：
+版本整体质量结论只使用通过、失败、阻塞：
- PASS：全部适用门禁满足；
+- 通过：全部适用门禁满足；
- FAIL：已执行并确认不满足要求，或存在高风险质量失败；
+- 失败：已执行并确认不满足要求，或存在高风险质量失败；
- BLOCKED：无法完成 Required 范围或形成有效结论。
+- 阻塞：无法完成必测范围或形成有效结论。
-专项、模块和正式用例结果只使用 PASS、FAIL、BLOCKED、NA。待执行和执行中是进度，不是正式结果。到正式汇总或报告节点，所有计划用例都必须有结果；适用但未完成的用例填 BLOCKED，不能留空或改成 NA。
+专项、模块和正式用例结果只使用通过、失败、阻塞、不适用。待执行和执行中是进度，不是正式结果。到正式汇总或报告节点，所有计划用例都必须有结果；适用但未完成的用例填“阻塞”，不能留空或改成“不适用”。
-BLOCKED 必须说明原因、受影响范围、证据、责任或协调角色、解除条件和补测要求。Required 中存在 BLOCKED 时，版本不能判定 PASS。
+阻塞必须说明原因、受影响范围、证据、责任或协调角色、解除条件和补测要求。必测范围中存在阻塞时，版本不能判定通过。只有工具字段明确要求时才使用机器枚举，对负责人和钉钉始终写中文。
 ## 统计
-正式报告至少统计计划、PASS、FAIL、BLOCKED、NA、适用和实际执行数量：
+正式报告至少统计计划、通过、失败、阻塞、不适用、适用和实际执行数量：
- 计划用例数 = PASS + FAIL + BLOCKED + NA；
+- 计划用例数 = 通过 + 失败 + 阻塞 + 不适用；
- 适用用例数 = 计划用例数 - NA；
+- 适用用例数 = 计划用例数 - 不适用；
- 实际执行用例数 = PASS + FAIL；
+- 实际执行用例数 = 通过 + 失败；
 - 执行完成率 = 实际执行用例数 ÷ 适用用例数；
- 执行通过率 = PASS ÷ 实际执行用例数；
+- 执行通过率 = 通过 ÷ 实际执行用例数；
- 阻塞率 = BLOCKED ÷ 适用用例数。
+- 阻塞率 = 阻塞 ÷ 适用用例数。
-实际执行数为 0 时，通过率是“不可计算”，不是 100%。BLOCKED 保留在适用分母中；不得把 BLOCKED 改为 NA 或用总体通过率掩盖关键失败。
+实际执行数为 0 时，通过率是“不可计算”，不是 100%。阻塞项保留在适用分母中；不得把阻塞改成不适用，也不得用总体通过率掩盖关键失败。
 ## 缺陷与关闭
-测试创建、持续维护并最终关闭 Defect Analysis Report。每个缺陷至少记录：
+测试创建、持续维护并最终关闭《缺陷分析报告》。每个缺陷至少记录：
- WORK_ID、缺陷 ID、关联 SUBTASK_ID；
+- 缺陷编号和关联测试项；
 - 被测统一固件及其匹配的底层、硬件、BOM、配置、样机和批次；
 - 环境、前置条件、复现步骤、期望／实际结果和频率；
- Severity、暴露概率／范围、风险等级和处理优先级；
+- 影响程度、暴露概率／范围、风险等级和处理优先级；
 - 影响、原始证据、初步责任边界、回归要求和状态。
 影响程度、发生概率、风险等级和处理优先级必须分开。不得通过临时降级绕过门禁。
 推荐生命周期：
-NEW → CONFIRMED → ASSIGNED → FIXED／PENDING_RETEST → VERIFIED → CLOSED
+新建 → 已确认 → 已安排修复 → 已修复／待复验 → 已验证 → 已关闭
 - 测试负责复现、观察证据、影响、回归要求、复验和测试关闭；
 - 实现角色负责根因、修复、变更说明和研发自测；
@@ -125,11 +125,11 @@ NEW → CONFIRMED → ASSIGNED → FIXED／PENDING_RETEST → VERIFIED → CLOSE
 - 业务负责客户范围、交付边界和业务风险接受；
 - Hub 负责向实际责任角色派发修复任务；彼此独立且依赖就绪的修复可形成任务波次。
-实现角色只提交 Root Cause Analysis、Fix Plan、修复成果、版本和自测，不能替换或关闭 Defect Analysis Report。研发声明修复不能直接关闭缺陷；只有测试在目标版本组合独立复验通过后才能 VERIFIED 或 CLOSED。Duplicate、As Designed、Cannot Reproduce、Won’t Fix 和 Deferred 保留理由与证据；未关闭项进入遗留缺陷和剩余风险。
+实现角色只提交原因分析、修复计划、修复成果、版本和自测，不能替换或关闭《缺陷分析报告》。研发声明修复不能直接关闭缺陷；只有测试在目标版本组合独立复验通过后才能标记为“已验证”或“已关闭”。重复、符合设计、无法复现、不修复和延期等处置都要保留理由与证据；未关闭项进入遗留缺陷和剩余风险。
 责任路由起点：
- 需求、产品行为、Acceptance Criteria 或详细客户输入：产品；
+- 需求、产品行为、验收标准或详细客户输入：产品；
 - 合同、业务范围、对外承诺或业务风险：业务；
 - 总体架构、跨层接口或责任不清：技术负责人；
 - 应用逻辑、状态机、配置、界面或应用协议：嵌入式应用层；
@@ -146,44 +146,44 @@ NEW → CONFIRMED → ASSIGNED → FIXED／PENDING_RETEST → VERIFIED → CLOSE
 - 实际被测版本、样机、批次、配置、环境和外设；
 - 使用的方法、步骤和工具；
 - 原始观察和数据；
- 如何对应 Acceptance Criteria；
+- 如何对应验收标准；
- BLOCKED 原因和 NA 依据；
+- 阻塞原因和不适用依据；
 - 缺陷修复版本与独立回归；
 - 测试限制、确认和剩余风险。
 追踪链：
-需求／客户标准 → Acceptance Criteria → Test Case → 执行结果 → Test Evidence Package → Defect Analysis Report → 修复版本 → 回归结果 → 适用测试报告 → 交付版本
+需求／客户标准 → 验收标准 → 测试用例 → 执行结果 → 测试证据包 → 缺陷分析报告 → 修复版本 → 回归结果 → 适用测试报告 → 交付版本
-测试结论只对实际被测版本、样机、配置和环境有效。无法证明平台、试产和交付版本一致时，最终结论为 BLOCKED。
+测试结论只对实际被测版本、样机、配置和环境有效。无法证明平台、试产和交付版本一致时，最终结论为阻塞。
-普通测试成果不得保存密码、Token、私钥、证书密钥或其他敏感值；只记录提供状态、适用环境、责任和安全引用。
+普通测试成果不得保存密码、访问令牌、私钥、证书密钥或其他敏感值；只记录提供状态、适用环境、责任和安全引用。
 ## 最终测试定版门禁
-只有全部适用条件满足才可给出最终 PASS：
+只有全部适用条件满足才可给出最终通过：
-1. Required 范围执行完成率 100%，无 BLOCKED；
+1. 必测范围执行完成率 100%，没有阻塞；
-2. 关键门禁用例全部 PASS；
+2. 关键门禁用例全部通过；
-3. 所有适用 Acceptance Criteria 满足；
+3. 所有适用验收标准满足；
 4. 所有适用专项有明确结论；
-5. 无高风险 Open Bug；
+5. 没有未关闭的高风险缺陷；
 6. 中低风险遗留已评估、披露并取得必要确认；
 7. 修复已在目标版本独立回归；
 8. 被测版本与平台、试产和交付候选版本一致；
-9. Test Plan、用例、执行、Test Evidence Package、Defect Analysis Report、回归和适用测试报告完整；
+9. 测试计划、用例、执行、测试证据包、缺陷分析报告、回归和适用测试报告完整；
 10. 限制、依赖和剩余风险明确，测试有权人员确认最终结论。
-高风险 Open Bug、关键用例失败、Acceptance Criteria 不满足或严重回归必须 FAIL。关键 Required 用例 BLOCKED、执行不足、环境／依赖不可用、版本不一致或证据不足必须 BLOCKED。
+未关闭的高风险缺陷、关键用例失败、验收标准不满足或严重回归必须判定失败。关键必测用例阻塞、执行不足、环境／依赖不可用、版本不一致或证据不足必须判定阻塞。
-最终测试 PASS 不等于业务验收、客户风险接受、发布批准或制造良率批准。
+最终测试通过不等于业务验收、客户风险接受、发布批准或制造良率批准。
 ## 正式输出深度
 - 普通测试版：策略、版本、范围、状态统计、结果摘要、缺陷增量、阻塞和限制；
 - 缺陷修复版：原缺陷复测、关联回归、新问题和剩余风险；
- 大版本／RC：在适用测试报告、Test Evidence Package 和 Defect Analysis Report 中完整记录覆盖、统计、缺陷、回归与质量结论；
+- 大版本／候选发布版：在适用测试报告、《测试证据包》和《缺陷分析报告》中完整记录覆盖、统计、缺陷、回归与质量结论；
 - 平台提测版：要求映射、预检、提交版本、平台反馈、整改和重提记录；
 - 试产定版：最终计划、用例、执行、兼容矩阵、缺陷、回归、证据、遗留风险和质量报告。
-角色契约不固定统一小时级 SLA；响应、测试、回归和报告时限由项目计划或 Test Plan 定义。
+角色契约不固定统一小时级响应时限；响应、测试、回归和报告时限由项目计划或《测试计划》定义。
@@ -1,10 +1,10 @@
 # 画质专项
-仅在当前产品、客户范围或 Test Plan 要求画质验证时读取。
+仅在当前产品、客户范围或《测试计划》要求画质验证时读取。
 ## 责任边界
- 产品确认用户可见行为、目标风格和 Acceptance Criteria；
+- 产品确认用户可见行为、目标风格和验收标准；
 - 硬件提供 Sensor、镜头、IR-CUT、补光和相关规格事实；
 - 嵌入式底层／应用层提供实际图像链路、参数、构建和配置版本；
 - 测试设计场景、执行测量、保留数据并形成独立结论；
@@ -12,7 +12,7 @@
 ## 测试设计
-按适用性结合客观指标、标准场景、Golden Sample 和受控主观评价，覆盖：
+按适用性结合客观指标、标准场景、参考样机和受控主观评价，覆盖：
 - 清晰度、色彩、白平衡、曝光和宽动态；
 - 逆光、高光、低照度、噪声和拖影；
@@ -20,6 +20,6 @@
 - 分辨率、码率、帧率及关键参数组合；
 - 不同硬件、固件、配置和样本的一致性。
-Test Plan 明确光源、场景、距离、环境、样本、设备、指标、主观评价方法、目标版本和阈值来源。原图、视频、参数快照、测量数据和对比结果应可追踪。
+《测试计划》明确光源、场景、距离、环境、样本、设备、指标、主观评价方法、目标版本和阈值来源。原图、视频、参数快照、测量数据和对比结果应可追踪。
 未覆盖场景必须披露；不得由少量主观观察推导全部画质条件通过。
@@ -6,7 +6,7 @@
 平台流程使用：
-INTERNAL_PRECHECK → READY_FOR_SUBMISSION → SUBMITTED → PLATFORM_PASSED／PLATFORM_FAILED／PLATFORM_BLOCKED
+内部预检 → 准备提交 → 已提交 → 平台通过／平台失败／平台阻塞
 要求：
@@ -16,7 +16,7 @@ INTERNAL_PRECHECK → READY_FOR_SUBMISSION → SUBMITTED → PLATFORM_PASSED／P
 - 平台反馈转入缺陷闭环，修复后复测、回归并按需重提；
 - 平台窗口、账号、客户或业务依赖通过 Hub 定向协调。
-内部预检通过不等于平台通过。只有平台正式结果可以支持 PLATFORM_PASSED。
+内部预检通过不等于平台通过。只有平台正式结果可以支持“平台通过”。
 ## 试产候选定版
@@ -28,7 +28,7 @@ INTERNAL_PRECHECK → READY_FOR_SUBMISSION → SUBMITTED → PLATFORM_PASSED／P
 - 抽样方法、样本数和批次可追踪；
 - 核心功能、升级恢复、画质、连接、存储和必要专项完成；
 - 试产问题进入缺陷闭环；
- 无高风险 Open Bug；
+- 没有未关闭的高风险缺陷；
 - 报告明确未覆盖范围、限制和剩余风险。
-最终测试版本必须与平台送审、试产和交付候选版本一致。无法证明一致时，质量结论为 BLOCKED。
+最终测试版本必须与平台送审、试产和交付候选版本一致。无法证明一致时，质量结论为阻塞。
@@ -1,19 +1,19 @@
 # 功耗与环境可靠性
-仅在当前 Test Plan 将功耗、高温、低温、温度循环或环境恢复列为适用专项时读取。
+仅在当前《测试计划》将功耗、高温、低温、温度循环或环境恢复列为适用专项时读取。
 ## 共同原则
 - 功耗与环境可靠性分别设计、记录和给出结论，不能互相代替；
- 阈值、供电、温度点、样本、持续时间和循环次数来自已批准 Test Plan 或上游标准；
+- 阈值、供电、温度点、样本、持续时间和循环次数来自已批准《测试计划》或上游标准；
 - 记录设备、板卡、固件、配置、样本、仪器、采样方法和环境；
- 每个适用子项独立给出 PASS、FAIL 或 BLOCKED，不以平均结果掩盖失败。
+- 每个适用子项独立给出通过、失败或阻塞结论，不以平均结果掩盖失败。
 ## 功耗
 按产品场景选择开机峰值、待机、预览／推流、录像与存储、Wi-Fi 高负载、日夜切换、补光／红外、升级、重启和其他高负载状态。
-Test Plan 明确：
+《测试计划》明确：
 - 供电与配置；
 - 业务场景、样本数和预热条件；
@@ -30,6 +30,6 @@ Test Plan 明确：
 - 高低温循环；
 - 必要的高低温存储和恢复后验证。
-Test Plan 明确温度点、升降温条件、稳定时间、持续时间、循环次数、样本数、负载和恢复时间。环境中及恢复后检查适用的启动、核心功能、画质、网络、存储、升级／恢复、日志和不可逆变化。
+《测试计划》明确温度点、升降温条件、稳定时间、持续时间、循环次数、样本数、负载和恢复时间。环境中及恢复后检查适用的启动、核心功能、画质、网络、存储、升级／恢复、日志和不可逆变化。
-无法满足环境、仪器、样本或持续时间要求时标记 BLOCKED，不得改成 NA。
+无法满足环境、仪器、样本或持续时间要求时标记为阻塞，不得改成不适用。
@@ -3,5 +3,5 @@
  "name": "playwright浏览器自动化操作",
  "version": "20260605",
  "keySource": "none",
-  "syncedAt": "2026-09-02T10:39:15Z"
+  "syncedAt": "2026-09-02T16:01:57Z"
 }
@@ -2,8 +2,8 @@
  "sourceId": "next-skills",
  "repo": "https://github.com/vercel/next.js.git",
  "ref": "canary",
-  "commit": "8ea76d64ca3931c1beccceb15d32df5d770f4957",
+  "commit": "5cca033c416427f26dbfc7baecb0ecfbb9757e41",
  "adapter": "skill-collection",
  "sourcePath": "skills",
-  "syncedAt": "2026-09-02T10:37:18Z"
+  "syncedAt": "2026-09-02T16:00:01Z"
 }
@@ -2,8 +2,8 @@
  "sourceId": "ppt-master",
  "repo": "https://github.com/hugohe3/ppt-master.git",
  "ref": "main",
-  "commit": "e33b81eaa737a21821aff948ea117a095d6b1f22",
+  "commit": "1fd7ba6a72dfea7918106b4da7c665a58321454e",
  "adapter": "claude-skill",
  "sourcePath": "skills/ppt-master",
-  "syncedAt": "2026-09-02T10:37:18Z"
+  "syncedAt": "2026-09-02T16:00:01Z"
 }
@@ -107,7 +107,7 @@ When one semantic object continues across adjacent slides, the destination slide
 |---|---|
 | Owner | `morph` belongs to the destination; `morph.from` is the immediately preceding stem in export order |
 | Source of pairs | `scaffold` never guesses identity — add pairs from the motion plan after inspecting final direct-root ids |
-| Pair key | A stable identity whose `from`/`to` are unique direct-root ids on the two slides, written without `!!` (export writes the Selection Pane name `!!<key>` on both) |
+| Pair key | A stable identity whose `from`/`to` are unique direct-root `<g>` ids on the two slides, written without `!!` (export writes the Selection Pane name `!!<key>` on both); a root primitive with a static role marker is not pairable |
 | Destination effect | A destination with pairs sets `effect: morph` explicitly (`morph_by` omitted or `object`; `word`/`character` rejected; a CLI override that changes the effect fails) |
 | Chains | A middle slide may continue an object into another Morph under the same key |
 | Uniqueness | One key never names two objects on a slide; one object never carries two keys; every `!!` key shared by adjacent Morph pages must be declared |
@@ -24,7 +24,7 @@ Conditional Executor authority for image status handling, placement, crop behavi
 **Hard rule — visible-layer timing**: every crop, lens, scrim, comparison, evidence, or annotation layer an adopted motion plan needs already exists in the final SVG; the motion stage may regroup ordinary Slide-local content but never invents or modifies visible content. When no legal unit can serve a non-binding suggestion, simplify to available units, a page transition, or `none`; an unrepresentable explicit requirement follows failure recovery.
-**Hard rule — narrow visual-inspection scope**: start from §VIII `Reference` plus dimensions; inspect one asset (or its review copy) once only when focal-safe crop, overlay contrast, a quiet region, or the planned subject relationship stays ambiguous — a `Generated` asset only when its intent and dimensions cannot resolve the ambiguity, never routinely. Inspection never reopens selection, changes identity or must-use, infers provenance, substitutes, or invents focus; uncertain `adaptive` focus uses `meet`, and conflicting binding constraints return upstream.
+**Hard rule — narrow visual-inspection scope**: start from §VIII `Reference` plus dimensions; inspect an asset (or its review copy) once, and only while its focal-safe crop, overlay contrast, quiet region, or planned subject relationship stays ambiguous — on a photo-led page that may be each of several assets, still once each and never the folder; a `Generated` asset only when its intent and dimensions cannot resolve the ambiguity, never routinely. Inspection never reopens selection, changes identity or must-use, infers provenance, substitutes, or invents focus; uncertain `adaptive` focus uses `meet`, and conflicting binding constraints return upstream.
 ## 1. Image Composition
@@ -126,7 +126,7 @@ A sheet generates compatible transparent **illustration**, **illustrated-icon**,
 **Sheet prompt convention** — one `page_role: local` item with `image_size` from final placement; spot sheets `text_policy: none`, lettering sheets `embedded`:
 - **Grid**: derive `aspect_ratio` and `--grid` from the target shape, not a universal square grid. State an invisible logical **R×C grid** and the cell shape (compact square object, tall portrait, wide vignette, wide lettering mark); center and isolate each element with even clear gutters. Never draw cells, panels, dividers, borders, frames, or alternate gutter colors; never shrink every subject into a square sticker.
- **Key**: one flat chroma key across the sheet — pure `#00FF00`, `#0000FF`, or `#FF0000`, chosen so its color dominates no element or effect — stated as exact HEX, unchanged in every gutter, free of reflections or spill; grain, halftone, and vignette stay inside elements. The key is technical, not deck palette.
+- **Key**: one flat chroma key across the sheet — pure `#00FF00`, `#0000FF`, or `#FF0000`, chosen so its color dominates no element or effect — stated as exact HEX before the palette and the subjects (deck colors appear only inside elements), unchanged in every gutter, free of reflections or spill; grain, halftone, and vignette stay inside elements. The key is technical, not deck palette.
 - **Identity**: shared `deck_rendering` + `color_scheme`.
 - **Illustration / illustrated-icon sheet**: name each element and its page or reuse job; for an icon, the compact cue that must survive at placement size; the §5.3 `none` cue.
 - **Lettering sheet**: exactly one named stable string per cell as the only text, quoted literally; the group's letterform character and treatment, then role, placement/background relationship, relative weight, and energy under §5.3's controlled-authorship default; artistry glyph-bound (silhouette, stroke structure, material, texture, depth, contour-bound light). No topic motifs, scene fragments, icons, detached ribbons, or particles unless the approved treatment is a lettering-plus-illustration lockup; key-only padding, no scene, unrelated copy, labels, watermark, or mockup surface.
@@ -312,7 +312,7 @@ Write `project/images/image_prompts.json`:
 | `items[].image_size` | no | `512px` / `1K` / `2K` / `4K` |
 | `items[].model` | no | Per-item backend model override |
 | `items[].alt_text` | no | Short caption |
-| `items[].slice_grid`, `items[].slice_names` | for a placeable-element sheet | Exact `RxC` and the comma-separated basenames (`rows*cols` unique outputs) for `slice_images.py` |
+| `items[].slice_grid`, `items[].slice_names` | for a placeable-element sheet | Exact `RxC` and the comma-separated basenames (`rows*cols` unique outputs) for `slice_images.py`; slice basenames are unique across the manifest, so re-cutting part of a sheet rewrites the parent's `slice_names` (and grid) rather than adding a second item with the same names |
 | `items[].status` | yes | `Pending` initially; the CLI writes `Generated` / `Failed` / `Needs-Manual` |
 Legacy manifest spellings and their current readings: [`image.md`](../scripts/docs/image.md).
@@ -73,7 +73,7 @@ Compact composition vocabulary for prepared images and illustrations. Use the pa
 ### 3.2 P2 · Image as Canvas with Native Overlay
-**Reference — not a constraint**: use `P2` when native annotations, data, or process nodes bind to locations inside the prepared visual; an ordinary side image or inset remains `P1` / `P3`.
+**Reference — not a constraint**: use `P2` when native annotations, data, or process nodes bind to locations inside the prepared visual; an ordinary side image or inset remains `P1` / `P3`. The overlay lives inside the picture's root group ([`shared-standards-core.md`](./shared-standards-core.md) §4.3), so it costs no page area.
 - **#P2-01 · Annotated evidence** — place compact annotation cards with routed leaders over the visual.
 - **#P2-02 · Hotspots with sidebar legend** — pair numbered points on the visual with a matching native legend.
@@ -66,7 +66,7 @@ The hash is a synchronization receipt, not proof of semantic equivalence; never
 ### Table schema — `ppt-master.semantic-table.v2`
-Every payload carries that exact `schema`; `columns` holds the optional header row and `rows` the body rows; `column_widths` / `row_heights` are relative weights. A cell is a string or an object with `text` (or `paragraphs` / `runs` for rich text), `fill`, `color`, `align` (`l` / `ctr` / `r`), `valign`, `bold`, `font_size`, `padding`, and per-side `borders` (each side is `{"style": "none"}` or `{"style": "solid", "color", "width"}`; a border without `style` is rejected); exact repetition may be factored into `defaults` and named `cell_styles`. Merged cells use positive `row_span` / `col_span` on the anchor with every covered cell as `{"merge_continuation": true}`. The complete field grammar: [`native-data.md`](../scripts/docs/native-data.md).
+Every payload carries that exact `schema`; `columns` holds the optional header row and `rows` the body rows; `column_widths` / `row_heights` are relative weights. A cell is a string or an object with `text` (or `paragraphs` / `runs` for rich text), `fill`, `color`, `align` (`l` / `ctr` / `r`), `valign`, `bold`, `font_size`, `padding`, and per-side `borders` (each side is `{"style": "none"}` or `{"style": "solid", "color", "width"}`; a border without `style` is rejected); exact repetition may be factored into `defaults.cell` / `defaults.paragraph` / `defaults.run` (cell fields such as `align`, `valign`, `padding`, `font_size` go under `defaults.cell`, never directly under `defaults`) and named `cell_styles`. Merged cells use positive `row_span` / `col_span` on the anchor with every covered cell as `{"merge_continuation": true}`. The complete field grammar: [`native-data.md`](../scripts/docs/native-data.md).
 **Hard rule — the table payload is complete**: every row, summary line, value, and cell style that must survive `--native-charts-and-tables` is in `columns` / `rows`, because fallback text is discarded on that route. A payload holding only `font_size` and a uniform border is not complete when the fallback draws a header band, row or column fills, first-column emphasis, non-uniform row heights, or sparse rules. Numeric or currency columns use cell objects with `align: "r"` (`text-anchor="end"` does not carry).
@@ -66,7 +66,7 @@ Use `data-pptx-role` only when no specialized marker owns the behavior:
 | `header`, `footer`, `logo`, `watermark`, `chrome` | Slide-local static framing without Master/Layout ownership |
 | `page-number` | Slide-local number when no `slide-number` placeholder exists |
-On flat pages a direct root background image or full-canvas scrim/decoration rectangle may carry the role and remain a primitive with a stable unique `id`; do not add a `<g>` solely to avoid an ungrouped-element advisory. Never add structural roles to ordinary titles, body copy, cards, KPIs, diagrams, charts, icons, or images.
+On flat pages a direct root background image, a full-canvas scrim/decoration rectangle, or a free-floating decorative image layer that crosses text zones (a cut-paper piece, a texture fragment) may carry the role and remain a primitive with a stable unique `id`; do not add a `<g>` solely to avoid an ungrouped-element advisory. Never add structural roles to ordinary titles, body copy, cards, KPIs, diagrams, charts, icons, or images.
 ---
@@ -175,7 +175,7 @@ These forms are needed only when the stated PPT behavior matters:
 | Desired behavior | Required form |
 |---|---|
-| One editable PPT text frame with mixed formatting or multiline prose | Use one `<text>` per logical paragraph and non-positional `<tspan>` children for inline runs. Per-run `fill` / `font-weight` / `font-size` is retained: export walks nested runs and emits one DrawingML run per styled segment, so an emphasised phrase stays inside the same editable frame, and a positioned line-break `<tspan>` may itself contain inline runs. Keep the first line as direct text; later lines use direct positioned `<tspan>` children that repeat parent `x` with positive relative `dy`; an all-`<tspan>` form may start at `dy="0"`. Default retains these breaks without PowerPoint wrapping; `--reflow-text` may join eligible lines. A font-size change, list marker, or larger accepted gap starts another paragraph. Sibling `<text>` elements are forbidden as one paragraph's line breaks; they remain valid for independent frames. |
+| One editable PPT text frame with mixed formatting or multiline prose | Use one `<text>` per logical paragraph and non-positional `<tspan>` children for inline runs. Per-run `fill` / `font-weight` / `font-size` is retained: export walks nested runs and emits one DrawingML run per styled segment, so an emphasised phrase stays inside the same editable frame, and a positioned line-break `<tspan>` may itself contain inline runs. Keep the first line as direct text; later lines use direct positioned `<tspan>` children that repeat parent `x` with positive relative `dy`; an all-`<tspan>` form may start at `dy="0"`. Default retains these breaks without PowerPoint wrapping; `--reflow-text` may join eligible lines. A font-size change, list marker, or larger accepted gap starts another paragraph. Sibling `<text>` elements are not a paragraph's line breaks — the checker reports likely cases as a warning because the detection is heuristic, and they are repaired before export; sibling frames remain valid for independent text. |
 | Stable object grouping or object-level animation anchor | Wrap the intended object in `<g id="...">`. Content grouping is **mandatory** per §4.3 — a top-level `<g id>` is also the animation anchor; it is not an optional convenience. |
 | Native PowerPoint background promotion | Outside structured mode, make the first visual layer a direct full-canvas `<rect>` (or one inside a simple single-child group) with a solid, linear/radial gradient, or preset-pattern fill and no transform, filter, clip, rounding, or visible stroke; export writes it as Slide `p:bg`. Structured routes follow [`pptx-structure-interface.md`](./pptx-structure-interface.md). |
 | Free-design / brand-only PowerPoint structure | Use `pptx_structure.mode: flat`: keep objects Slide-local and author no Master/Layout identities, layers, or slots; export emits one clean Master plus Blank Layout. |
@@ -187,7 +187,7 @@ These forms are needed only when the stated PPT behavior matters:
 ### 4.3 Element Grouping (Mandatory)
-**Hard rule — root groups protect body-text layout**: every visible direct root `<g>` except a compact helper-authored preset atom declares positive root-coordinate `data-pptx-bounds="x y width height"` sized as the intended module zone. On flat pages, maximize ordinary zones within canvas/sibling space without overlap; the checker fails root-group overlap beyond `1px`, warns on module text overflow through `5%` and fails above it, and fails any larger root-`viewBox` text overflow. Bounds do not clip or reflow. Structured slots, structural-role groups, and a wholly off-canvas Morph endpoint marked `data-pptx-morph-staging="true"` are the only exemptions; thresholds and estimator detail: [`svg-contract.md`](../scripts/docs/svg-contract.md) §4.
+**Hard rule — root groups protect body-text layout**: every visible direct root `<g>` except a compact helper-authored preset atom declares positive root-coordinate `data-pptx-bounds="x y width height"` sized as the intended module zone. On flat pages, maximize ordinary zones within canvas/sibling space without overlap; the checker fails root-group overlap beyond `1px`, warns on module text overflow through `5%` and fails above it, and fails any larger root-`viewBox` text overflow. Bounds do not clip or reflow. A native plate, caption, or label laid over a picture belongs inside that picture's root group — one group is the image plus its overlay — so it takes no separate zone and creates no root-group overlap; shrinking the picture to free a text zone is not the repair. Structured slots, structural-role groups, and a wholly off-canvas Morph endpoint marked `data-pptx-morph-staging="true"` are the only exemptions; thresholds and estimator detail: [`svg-contract.md`](../scripts/docs/svg-contract.md) §4.
 Wrap each logical Slide-local body unit in one descriptive top-level `<g id>`; group count follows the page's semantic units, and each group becomes one stable animation target when animation is enabled. Nested implementation groups may remain anonymous, need no bounds, and create no animation step; use them only when internal subunits (icon + title, value + label, repeated rows) are useful to edit — there is no default nesting pattern, depth, or quota. Titles, direct atomic Master/Layout elements, and canvas-level static framing — background images and full-canvas scrim/decoration rectangles — may remain root primitives; on flat pages give such framing a stable `id` plus `data-pptx-role="background"` / `"decoration"` and never add a `<g>` solely to silence an ungrouped-element advisory.
@@ -16,7 +16,7 @@ Run this module inside [`strategist.md`](./strategist.md)'s one-pass resource-ne
 **Illustration**: confirmed `none` stops and explicit user intent wins; otherwise the locked style's `Illus.` propensity (`core` / `supportive` / `sparse`) tunes centrality and recurrence after the per-page scan without restricting page types, element scale, or carrier combinations. Prefer one coherent family that serves the actual jobs — recurring title/corner chrome, dominant anchors, supporting figures, accents; a compact icon cue does not discharge a scene, subject, or visual-weight job a photo or family would serve.
-**Context-first understanding of provided assets**: never scan `images/` for inspiration or bulk-open it. Infer identity, role, and crop/focus needs from source position, surrounding prose, captions/alt/titles, filename, user notes and `image_notes`, existing records, and CSV geometry; inspect one specific image only when a remaining ambiguity would change selection, identity, page role, crop safety, or focal placement, never inferring external facts or provenance from pixels. Record the result in §VIII; leave an optional unresolved asset unused and route a must-use one through failure recovery.
+**Context-first understanding of provided assets**: never scan `images/` for inspiration or bulk-open it. Infer identity, role, and crop/focus needs from source position, surrounding prose, captions/alt/titles, filename, user notes and `image_notes`, existing records, and CSV geometry; inspect a specific image, once, only when a remaining ambiguity would change selection, identity, page role, crop safety, or focal placement — several images when several carry such an ambiguity, never the folder — and never infer external facts or provenance from pixels. Record the result in §VIII; leave an optional unresolved asset unused and route a must-use one through failure recovery.
 **Default — Illustration Sheets for a compatible group (may split for geometry, detail, or quality)**: illustration elements, illustrated-icon cues, and lettering share one generation context under [`image-generator.md`](./image-generator.md) §4.3. Plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element (only slice rows enter the lock; one element may serve several pages), stating each element's communication job, placement/reuse relationship, relative weight, energy, family, and shape without prescribing an effect stack. Glyph-native expression is the default; a lettering-plus-illustration lockup only on explicit request or when the confirmed direction requires it. Lettering sheets use `text_policy: embedded` — the asset may carry the complete display title while any searchable, selectable, or outline-visible title stays a separate native frame. §§4.3 and 5.3 own the controlled-default/high-expression boundary, grid, key field, slicing, and execution; Stage 2 chooses the AI path under §7, never re-picked here.
@@ -313,4 +313,4 @@ animation-to-video contract.
 | `after_effect` | `none`, `dim` with `color`, `hide`, or `hide-on-next-click` |
 | `sound` | Object-animation cue: project-relative or absolute `.m4a` / `.mp3` / `.wav` on low-level inputs; bundled selections use the synced project-relative `.wav` path |
-An unlisted SVG inherits the resolved deck-wide settings; a listed slide may contain only the `transition`, `animation`, `groups`, or `morph` fields it overrides; chrome groups (`bg` / `*-header` / `*-footer` / `*-decor` / `nav` / `watermark` / `logo` / `pagenumber`) are pinned to `none` unless explicitly named without a structural marker; a group carrying `data-pptx-layer` or a static role/placeholder marker never animates.
+An unlisted SVG inherits the resolved deck-wide settings; a listed slide may contain only the `transition`, `animation`, `groups`, or `morph` fields it overrides; chrome groups (`bg` / `*-header` / `*-footer` / `*-decor` / `nav` / `watermark` / `logo` / `pagenumber`) are pinned to `none` unless explicitly named without a structural marker — except a `*-header` / `*-footer` group whose text reaches the page's median font size, which is read as the title block and stays an ordinary target; a group carrying `data-pptx-layer` or a static role/placeholder marker never animates.
@@ -1023,7 +1023,8 @@ the SVG quality checker.
  `validation/text_calibration.json`, and prints a compact table or JSON. The
  estimator is additive across scripts, so a line mixing CJK with Latin words
  or digits is estimated as (CJK chars ÷ CJK rate + other chars ÷ Latin rate)
-  × 100; spaces, digits, and punctuation count as Latin. The checker's overflow
+  × 100; spaces, digits, and punctuation count as Latin. Rates are rounded, so
  the estimate carries a few percent of slack; leave that margin in the zone. The checker's overflow
  diagnostic prints that line's average px per character, which is not a
  reusable rate. A lock role without its own
  `<role>_family` resolves to `title_family` when the role name contains
@@ -230,7 +230,7 @@ class ProjectManager:
    CANVAS_FORMATS = CANVAS_FORMATS
    def __init__(self, base_dir: str | Path | None = None) -> None:
-        self.base_dir = Path(base_dir) if base_dir is not None else Path.cwd() / "projects"
+        self.base_dir = Path(base_dir) if base_dir is not None else PROJECTS_ROOT
    def scaffold_artifact(self, project_path: str, artifact: str) -> str:
        """Delegate deterministic Markdown scaffold rendering."""
@@ -840,6 +840,20 @@ def _validate_condition(
    return errors
 _PAGE_COUNT_ROW_RE = re.compile(
    r"^\|[ \t]*Page Count[ \t]*\|[ \t]*([0-9]+)[ \t]*\|",
    flags=re.IGNORECASE | re.MULTILINE,
 )
 def _declared_page_count(section: Mapping[str, object] | None) -> int | None:
    """Return the exact integer §I Page Count, or None when absent or not exact."""
    if section is None:
        return None
    match = _PAGE_COUNT_ROW_RE.search(str(section.get("body", "")))
    return int(match.group(1)) if match else None
 def _validate_slides(
    *,
    markdown_name: str,
@@ -862,6 +876,13 @@ def _validate_slides(
        return [f"{markdown_name} schema: content outline has no Slide blocks"]
    errors: list[str] = []
    declared = _declared_page_count(matched.get("project_information"))
    if declared is not None and declared != len(heading_matches):
        errors.append(
            f"{markdown_name} schema: §I Page Count is {declared} but the "
            f"content outline has {len(heading_matches)} Slide block(s); "
            "the two must match"
        )
    required_fields = slide_contract.get("required_fields", [])
    if not isinstance(required_fields, list):
        return errors
@@ -63,6 +63,15 @@ _DEFAULT_FEATHER = 4
 _BOUNDARY_OPAQUE_ALPHA = 32
 _SHEET_DIAGNOSTIC_BORDER_RATIO = 0.01
 _SHEET_DIAGNOSTIC_BUCKET_SIZE = 4
 # Isolated pixels this close to the key are compression or ringing artifacts a
 # larger tolerance absorbs; farther pixels are content crossing the gutter.
 _KEY_DRIFT_MAX_TOLERANCE = 48
 _KEY_DRIFT_MARGIN = 4
 # At most this many trim pixels on a touched edge count as isolated drift.
 _EDGE_DRIFT_MAX_PIXELS = 8
 # Corner sample inset (px) and minimum cell fill for the backing-panel notice.
 _PANEL_CORNER_INSET = 2
 _PANEL_MIN_FILL = 0.75
 def _log(msg: str) -> None:
@@ -181,7 +190,12 @@ def _sample_bg(cell: Image.Image, tolerance: int) -> tuple[int, int, int]:
 def _sample_sheet_border(
    sheet: Image.Image,
 ) -> tuple[tuple[int, int, int], int]:
-    """Return the dominant RGB cluster and its spread in the outer 1% ring."""
+    """Return the dominant RGB cluster, its spread, and the ring's farthest pixel.
    The spread describes the key field itself; the outlier distance is what a
    ``--tolerance`` must reach so that isolated ringing or compression pixels
    in the gutter still key out.
    """
    rgb = sheet.convert("RGB")
    width, height = rgb.size
    border_x = max(1, round(width * _SHEET_DIAGNOSTIC_BORDER_RATIO))
@@ -222,7 +236,11 @@ def _sample_sheet_border(
        - min(pixel[index] for pixel in dominant_pixels)
        for index in range(3)
    ]
-    return dominant, max(channel_spreads)  # type: ignore[return-value]
+    outlier = max(
        max(abs(pixel[index] - dominant[index]) for index in range(3))
        for pixel in pixels
    )
    return dominant, max(channel_spreads), outlier  # type: ignore[return-value]
 def _max_channel_difference(cell: Image.Image, bg: tuple[int, int, int]) -> Image.Image:
@@ -239,6 +257,19 @@ def _pure_chroma_channel(bg: tuple[int, int, int]) -> Optional[int]:
    return bg.index(255)
 def _nearest_pure_key(
    color: tuple[int, int, int],
 ) -> Optional[tuple[tuple[int, int, int], int]]:
    """Return the pure RGB key a drifted gutter color came from, with its distance."""
    best: Optional[tuple[tuple[int, int, int], int]] = None
    for index in range(3):
        pure = tuple(255 if i == index else 0 for i in range(3))
        distance = max(abs(color[i] - pure[i]) for i in range(3))
        if distance <= _KEY_DRIFT_MAX_TOLERANCE and (best is None or distance < best[1]):
            best = (pure, distance)  # type: ignore[assignment]
    return best
 def _channel_alpha(channel: Image.Image, bg_value: int) -> Image.Image:
    """Return the minimum alpha that can explain one channel over a key."""
    lut = []
@@ -355,8 +386,8 @@ def _content_masks(
    cell: Image.Image,
    bg: tuple[int, int, int],
    tolerance: int,
-) -> tuple[Image.Image, Image.Image, Optional[Image.Image]]:
+) -> tuple[Image.Image, Image.Image, Optional[Image.Image], Image.Image]:
-    """Build trim/alpha masks and optional chroma-decontaminated RGB."""
+    """Build trim/alpha masks, optional chroma-decontaminated RGB, and the key diff."""
    rgb = cell.convert("RGB")
    diff = _max_channel_difference(rgb, bg)
    trim_mask = diff.point(lambda p: 255 if p > tolerance else 0)
@@ -365,10 +396,10 @@ def _content_masks(
        chroma_alpha = _chroma_alpha(rgb, bg)
        alpha_mask = ImageChops.multiply(chroma_alpha, tolerance_gate)
        keyed_rgb = _decontaminate_rgb(rgb, chroma_alpha, bg)
-        return trim_mask, alpha_mask, keyed_rgb
+        return trim_mask, alpha_mask, keyed_rgb, diff
    alpha_mask = tolerance_gate.filter(ImageFilter.MinFilter(3))
-    return trim_mask, alpha_mask, None
+    return trim_mask, alpha_mask, None, diff
 def _keying_findings(
@@ -380,6 +411,9 @@ def _keying_findings(
    *,
    trim: bool,
    alpha: bool,
    trim_mask: Optional[Image.Image] = None,
    diff: Optional[Image.Image] = None,
    notices: Optional[list[str]] = None,
 ) -> list[str]:
    """Report objective signs that the flat-background key did not take.
@@ -391,6 +425,11 @@ def _keying_findings(
    findings: list[str] = []
    hex_bg = "#{:02X}{:02X}{:02X}".format(*cell_bg)
    if alpha and trim and alpha_mask is not None and notices is not None:
        notice = _backing_panel_notice(label, alpha_mask, bbox, cell_size)
        if notice:
            notices.append(notice)
    if alpha and alpha_mask is not None:
        px = alpha_mask.load()
        width, height = alpha_mask.size
@@ -427,18 +466,97 @@ def _keying_findings(
        if bbox[3] >= cell_height:
            touched_edges.append("bottom")
        if touched_edges:
            drift = _edge_drift(trim_mask, diff, touched_edges)
            if drift is not None:
                count, distance = drift
                findings.append(
-                f"{label}: content reaches the {'/'.join(touched_edges)} cell edge(s) "
+                    f"{label}: {count} isolated pixel(s) on the "
-                f"(key background {hex_bg})"
+                    f"{'/'.join(touched_edges)} cell edge(s) exceed the key "
                    f"tolerance (farthest {distance} from key {hex_bg}); this is "
                    f"key drift, not content — rerun with --tolerance "
                    f"{distance + _KEY_DRIFT_MARGIN} or higher"
                )
            else:
                findings.append(
                    f"{label}: content reaches the {'/'.join(touched_edges)} "
                    f"cell edge(s) (key background {hex_bg})"
                )
    return findings
 def _backing_panel_notice(
    label: str,
    alpha_mask: Image.Image,
    bbox: tuple[int, int, int, int],
    cell_size: tuple[int, int],
 ) -> Optional[str]:
    """Flag a trimmed element whose corners are opaque: a painted backing panel.
    A cut-out silhouette almost never fills all four corners of its own
    bounding box; a rectangle behind it does. The key cannot see the panel
    (the gutters are clean), so this is advisory, never a strict failure.
    """
    left, top, right, bottom = bbox
    if right - left < 2 * _PANEL_CORNER_INSET + 1 or bottom - top < 2 * _PANEL_CORNER_INSET + 1:
        return None
    cell_width, cell_height = cell_size
    fill_w = (right - left) / cell_width if cell_width else 0.0
    fill_h = (bottom - top) / cell_height if cell_height else 0.0
    if min(fill_w, fill_h) < _PANEL_MIN_FILL:
        return None
    px = alpha_mask.load()
    corners = (
        (left + _PANEL_CORNER_INSET, top + _PANEL_CORNER_INSET),
        (right - 1 - _PANEL_CORNER_INSET, top + _PANEL_CORNER_INSET),
        (left + _PANEL_CORNER_INSET, bottom - 1 - _PANEL_CORNER_INSET),
        (right - 1 - _PANEL_CORNER_INSET, bottom - 1 - _PANEL_CORNER_INSET),
    )
    opaque = sum(1 for x, y in corners if px[x, y] > _BOUNDARY_OPAQUE_ALPHA)
    if opaque < 3:
        return None
    return (
        f"{label}: the trimmed element fills {fill_w:.0%} x {fill_h:.0%} of its "
        f"cell and is opaque in {opaque} of 4 corners; it "
        "may sit on a painted backing panel the key could not remove — look at "
        "the slice, and regenerate with the element alone on the key if so"
    )
 def _edge_drift(
    trim_mask: Optional[Image.Image],
    diff: Optional[Image.Image],
    touched_edges: list[str],
 ) -> Optional[tuple[int, int]]:
    """Return (pixel count, max key distance) when the touched edges hold only
    a few near-key pixels, or None when real content reaches an edge."""
    if trim_mask is None or diff is None:
        return None
    width, height = trim_mask.size
    mask_px = trim_mask.load()
    diff_px = diff.load()
    coords = set()
    if "left" in touched_edges:
        coords.update((0, y) for y in range(height))
    if "right" in touched_edges:
        coords.update((width - 1, y) for y in range(height))
    if "top" in touched_edges:
        coords.update((x, 0) for x in range(width))
    if "bottom" in touched_edges:
        coords.update((x, height - 1) for x in range(width))
    hits = [diff_px[x, y] for x, y in coords if mask_px[x, y]]
    if not hits or len(hits) > _EDGE_DRIFT_MAX_PIXELS:
        return None
    distance = max(hits)
    if distance > _KEY_DRIFT_MAX_TOLERANCE:
        return None
    return len(hits), distance
 def _log_keying_findings(
    findings: list[str],
    *,
-    sheet_border: tuple[tuple[int, int, int], int] | None = None,
+    sheet_border: tuple[tuple[int, int, int], int, int] | None = None,
    tolerance: int,
 ) -> None:
    """Report incomplete flat-background keying."""
@@ -453,12 +571,30 @@ def _log_keying_findings(
    _log("       --bg <hex> and a larger --tolerance; use --inset when a drawn "
         "outer gutter is isolated from every element.")
    if sheet_border is not None:
-        dominant, drift = sheet_border
+        dominant, drift, outlier = sheet_border
        hex_bg = "#{:02X}{:02X}{:02X}".format(*dominant)
        suggested_tolerance = max(tolerance, drift)
        _log(
            "       Measured outer 1% border/gutter: "
-            f"dominant {hex_bg}; max channel spread {drift}."
+            f"dominant {hex_bg}; key spread {drift}; farthest pixel {outlier} "
            "from the key."
        )
        if outlier > _KEY_DRIFT_MAX_TOLERANCE:
            _log(
                "       The gutter holds pixels far from the key: content or an "
                "effect crosses it. Regenerate with a clear key-only gutter; a "
                "larger --tolerance would eat into the elements."
            )
        else:
            pure = _nearest_pure_key(dominant)
            if pure is not None:
                # A pure key enables despill and soft-alpha recovery; keep it
                # and widen the tolerance by the measured drift instead.
                pure_rgb, pure_distance = pure
                hex_bg = "#{:02X}{:02X}{:02X}".format(*pure_rgb)
                drift += pure_distance
                outlier += pure_distance
            suggested_tolerance = max(
                tolerance, drift, outlier + _KEY_DRIFT_MARGIN
            )
            _log(
                "       Suggested rerun: "
@@ -522,6 +658,7 @@ def slice_sheet(
    prepared: list[tuple[int, int, Image.Image, Path]] = []
    written: list[Path] = []
    findings: list[str] = []
    notices: list[str] = []
    idx = 0
    for r in range(rows):
@@ -541,7 +678,7 @@ def slice_sheet(
            bbox = None
            if trim or alpha:
                cell_bg = bg if bg is not None else _sample_bg(cell, tolerance)
-                trim_mask, alpha_mask, keyed_rgb = _content_masks(
+                trim_mask, alpha_mask, keyed_rgb, diff = _content_masks(
                    cell, cell_bg, tolerance
                )
                bbox = trim_mask.getbbox()
@@ -549,7 +686,8 @@ def slice_sheet(
                    raise ValueError(f"cell ({r},{c}) is all background; no element was sliced")
                findings.extend(_keying_findings(
                    f"cell ({r},{c})", cell.size, bbox, alpha_mask, cell_bg,
-                    trim=trim, alpha=alpha,
+                    trim=trim, alpha=alpha, trim_mask=trim_mask, diff=diff,
                    notices=notices,
                ))
            if trim and trim_mask is not None and alpha_mask is not None and bbox is not None:
@@ -586,6 +724,9 @@ def slice_sheet(
                "no output files were written"
            )
    for notice in notices:
        _log(f"[WARN] {notice}")
    for r, c, cell, out_path in prepared:
        cell.save(out_path)
        written.append(out_path)
@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import math
 import re
 import statistics
 from dataclasses import dataclass
 from pathlib import Path, PureWindowsPath
 from typing import Any
@@ -114,6 +115,83 @@ def is_chrome_id(elem_id: str | None) -> bool:
    return any(t in _CHROME_ID_TOKENS for t in tokens if t)
 _TITLE_BLOCK_TOKENS = frozenset({'header', 'footer'})
 _FONT_SIZE_RE = re.compile(r'font-size\s*:\s*([0-9.]+)')
 def _font_size_px(elem: ET.Element) -> float | None:
    """Return an element's own font-size in px from its attribute or style."""
    raw = elem.get('font-size')
    if raw is None:
        match = _FONT_SIZE_RE.search(elem.get('style') or '')
        raw = match.group(1) if match else None
    if raw is None:
        return None
    try:
        return float(re.match(r'[0-9.]+', raw.strip()).group(0))
    except (AttributeError, ValueError):
        return None
 def _text_sizes(scope: ET.Element) -> list[float]:
    """Return every declared font-size among text runs under ``scope``."""
    return [
        size
        for elem in scope.iter()
        if _tag_name(elem) in {'text', 'tspan'}
        for size in (_font_size_px(elem),)
        if size is not None
    ]
 def _max_text_size(scope: ET.Element) -> float | None:
    sizes = _text_sizes(scope)
    return max(sizes) if sizes else None
 def _page_reference_size(root: ET.Element) -> float | None:
    """Return the median of the page's distinct text sizes.
    Running labels and page numbers sit below it; a title block sits at or
    above it even when a hero numeral is the page's largest text.
    """
    distinct = sorted(set(_text_sizes(root)))
    return statistics.median(distinct) if distinct else None
 def _holds_page_title(group: ET.Element, reference_size: float | None) -> bool:
    """A header/footer-named group whose text reaches the page's median size
    is the title block, not chrome."""
    if reference_size is None:
        return False
    group_max = _max_text_size(group)
    return group_max is not None and group_max >= reference_size - 1e-6
 def _names_title_block(group_id: str) -> bool:
    tokens = re.split(r'[-_]', group_id.lower())
    return any(t in _TITLE_BLOCK_TOKENS for t in tokens if t)
 def scan_root_primitives(svg_path: Path) -> dict[str, str]:
    """Return id -> description for visible direct-root non-group elements."""
    root = ET.parse(str(svg_path)).getroot()
    primitives: dict[str, str] = {}
    for child in root:
        tag = _tag_name(child)
        if tag in _NON_VISUAL_TAGS or tag == 'g':
            continue
        elem_id = usable_animation_group_id(child.get('id'))
        if elem_id is None:
            continue
        role = child.get('data-pptx-role')
        description = f'<{tag}>'
        if role:
            description += f' with data-pptx-role="{role}"'
        primitives[elem_id] = description
    return primitives
 def usable_animation_group_id(raw: str | None) -> str | None:
    """Return one nonblank SVG animation anchor verbatim, else ``None``."""
    return raw if raw and raw.strip() else None
@@ -125,6 +203,7 @@ def scan_svg_targets(svg_path: Path) -> tuple[list[GroupTarget], list[str]]:
    targets: list[GroupTarget] = []
    anonymous_groups: list[str] = []
    visual_index = 0
    page_reference_size = _page_reference_size(root)
    for child in root:
        tag = _tag_name(child)
@@ -152,6 +231,12 @@ def scan_svg_targets(svg_path: Path) -> tuple[list[GroupTarget], list[str]]:
            chrome = semantic_static
        else:
            chrome = is_chrome_id(group_id)
            if (
                chrome
                and _names_title_block(group_id)
                and _holds_page_title(child, page_reference_size)
            ):
                chrome = False
        targets.append(
            GroupTarget(
                slide=svg_path.stem,
@@ -1512,6 +1597,14 @@ def validate_animation_config(
        config,
    )
    warnings.extend(morph_errors)
    root_primitives_by_slide: dict[str, dict[str, str]] = {}
    if morph_pairs:
        scan_files = svg_files
        if scan_files is None:
            svg_dir = project_path / 'svg_output'
            scan_files = discover_slide_svgs(svg_dir) if svg_dir.is_dir() else []
        for svg_path in scan_files:
            root_primitives_by_slide[svg_path.stem] = scan_root_primitives(svg_path)
    for pair in morph_pairs:
        for slide_name, group_id in (
            (pair.source_slide, pair.source_group_id),
@@ -1519,6 +1612,15 @@ def validate_animation_config(
        ):
            target = known_groups_by_slide.get(slide_name, {}).get(group_id)
            if target is None:
                primitive = root_primitives_by_slide.get(slide_name, {}).get(group_id)
                if primitive is not None:
                    warnings.append(
                        f'animations.json Morph endpoint {slide_name}/{group_id} '
                        f'is a root primitive ({primitive}), not a direct-root '
                        '<g>; wrap it in a group (drop a static role marker) '
                        'before pairing'
                    )
                else:
                    warnings.append(
                        'animations.json Morph references missing or ambiguous group: '
                        f'{slide_name}/{group_id}'
@@ -286,7 +286,10 @@ def _ordered_roles(roles: dict[str, tuple[str, float]]) -> list[tuple[str, str,
    return [(name, *roles[name]) for name in names]
-def _roles_from_spec_lock(lock_path: Path) -> dict[str, tuple[str, float]]:
+def _roles_from_spec_lock(
    lock_path: Path,
    fallbacks: dict[str, str] | None = None,
 ) -> dict[str, tuple[str, float]]:
    lock = parse_spec_lock(lock_path, report_duplicate_fields=True)
    typography = next(
        (
@@ -315,6 +318,8 @@ def _roles_from_spec_lock(lock_path: Path) -> dict[str, tuple[str, float]]:
            display_role = 'title' in role or 'numeral' in role
            fallback = 'title_family' if display_role else 'body_family'
            family = rows.get(fallback, '') or rows.get('font_family', '')
            if fallbacks is not None:
                fallbacks[role] = fallback
        if not family:
            raise ValueError(
                f'spec_lock.md typography role {role!r} has no resolvable font family'
@@ -488,6 +493,26 @@ def _calibration_payload(
    }
 def _fallback_notes(
    roles: dict[str, tuple[str, float]],
    fallbacks: dict[str, str],
 ) -> list[str]:
    """Flag display-sized roles that inherited body_family by default."""
    body = roles.get('body')
    if body is None:
        return []
    notes = []
    for role, fallback in sorted(fallbacks.items()):
        size = roles[role][1]
        if fallback == 'body_family' and size >= 2 * body[1]:
            notes.append(
                f'role {role} ({_format_number(size)}px, at least twice body) has '
                f'no {role}_family and uses body_family; declare {role}_family '
                'if it is display type'
            )
    return notes
 def _render_calibration_table(payload: dict[str, object], *, include_outline: bool) -> str:
    role_rows = payload['roles']
    assert isinstance(role_rows, dict)
@@ -516,6 +541,8 @@ def _render_calibration_table(payload: dict[str, object], *, include_outline: bo
                else f'{planned["px"]:.1f}px, {planned["slide"]}, {planned["text"]}'
            )
        lines.append(' | '.join(row))
    for note in payload.get('notes') or []:
        lines.append(f'[NOTE] {note}')
    lines.append(
        '[NOTE] mixed line width ≈ (CJK chars ÷ CJK rate + other chars ÷ Latin '
        'rate) × 100; spaces, digits, and punctuation count as Latin.'
@@ -539,9 +566,15 @@ def _run_calibrate(args: argparse.Namespace) -> int:
        )
        return 2
    try:
-        roles = _roles_from_spec_lock(lock_path) if lock_path.is_file() else {}
+        fallbacks: dict[str, str] = {}
        roles = (
            _roles_from_spec_lock(lock_path, fallbacks)
            if lock_path.is_file()
            else {}
        )
        for name, family, size in args.role:
            roles[name] = (family, size)
            fallbacks.pop(name, None)
        ordered_roles = _ordered_roles(roles)
        if not ordered_roles:
            raise ValueError('no typography size roles were found')
@@ -552,6 +585,7 @@ def _run_calibrate(args: argparse.Namespace) -> int:
            source=source,
            include_outline=args.outline,
        )
        payload['notes'] = _fallback_notes(roles, fallbacks)
        output_path = project_path / 'validation' / 'text_calibration.json'
        output_path.parent.mkdir(parents=True, exist_ok=True)
        rendered_json = json.dumps(payload, ensure_ascii=False, indent=2)
@@ -12,7 +12,7 @@ Compose the entire document in active context, then create `<project_path>/desig
 ## 2. Exact document contract
-Angle-bracketed text is authoring notation. Resolve every universal value before writing; omit only rows marked conditional; keep every required `##` heading (§VII omitted without a catalog reference; §VIII present even with no data rows); copy no examples, notation, or schema prose into the artifact.
+Angle-bracketed text is authoring notation. Resolve every universal value before writing; omit only rows marked conditional; keep every required `##` heading (§VII is conditional: drop the whole section, heading included, when no page carries a catalog reference; §VIII present even with no data rows); copy no examples, notation, or schema prose into the artifact.
 ### 2.1 Header and project contract
@@ -60,7 +60,8 @@ Unless an all-motion disable bypasses it, validate an existing sidecar first: `p
 | One unit is scattered across groups or root primitives | Merge or wrap its background, icon, label, value, and text into one direct-root group |
 | A connector or arrow explains entry into a node or stage | Keep it with the relationship or target that makes it intelligible |
 | A hero visual, overview graphic, takeaway, or warning has its own role | Its own group |
-| The same object continues across adjacent Morph pages | Isolate each endpoint as one direct-root group of compatible kinds |
+| The same object continues across adjacent Morph pages | Isolate each endpoint as one direct-root `<g>` of compatible kinds; a root primitive carrying a static role (`decoration`, `background`) cannot be paired — wrap it as a group first |
 | Two narrated stages interlock geometrically (a fitted preset joint, a deliberate overlap) | Keep them one group — sibling groups cannot hold disjoint bounds — and let one directional effect travel the reading path |
 | Several atoms express one inseparable idea | Keep them together |
 | Page chrome, structural layers, static framing | Preserve and exclude from ordinary targets |
@@ -68,7 +69,7 @@ Unless an all-motion disable bypasses it, validate an existing sidecar first: `p
 **Forbidden — group-list-first choreography**: choosing effects or order from `list-groups` before the audit; keeping a coarse wrapper because it has an `id`; splitting one idea into shapes or lines to raise the count; merging unrelated ideas to lower it; adding animation `data-*` attributes to SVG. There is no target group count.
-After any regrouping, rerun the final gate (`svg_quality_checker.py <project_path> --canonical-authoring --stage final --json`; Quick inserts `--quick-generate` before `--stage`), then list the post-regroup anchors with `animation_config.py list-groups <project_path>` (one line per slide, chrome groups `bg` / `*-header` / `*-footer` / `*-decor` / `nav` / `watermark` / `logo` / `pagenumber` excluded). That list is the only source of slide and group keys for §3–§4. An explicit sidecar entry overrides only the marker-free legacy id-name heuristic; a group carrying `data-pptx-layer` or a static role/placeholder marker never animates. If a starting file is useful, `animation_config.py scaffold <project_path>` after regrouping creates a neutral scaffold (default object effect `none`, groups as empty `{}` placeholders) — creating it selects nothing, and it need not be read in full.
+After any regrouping, rerun the final gate (`svg_quality_checker.py <project_path> --canonical-authoring --stage final --json`; Quick inserts `--quick-generate` before `--stage`), then list the post-regroup anchors with `animation_config.py list-groups <project_path>` (one line per slide, chrome groups `bg` / `*-header` / `*-footer` / `*-decor` / `nav` / `watermark` / `logo` / `pagenumber` excluded; a `*-header` or `*-footer` group that holds the page's largest text is the title block, not chrome, and stays listed). That list is the only source of slide and group keys for §3–§4. An explicit sidecar entry overrides only the marker-free legacy id-name heuristic; a group carrying `data-pptx-layer` or a static role/placeholder marker never animates. If a starting file is useful, `animation_config.py scaffold <project_path>` after regrouping creates a neutral scaffold (default object effect `none`, groups as empty `{}` placeholders) — creating it selects nothing, and it need not be read in full.
 ---
@@ -2,8 +2,8 @@
  "sourceId": "shadcn",
  "repo": "https://github.com/shadcn-ui/ui.git",
  "ref": "main",
-  "commit": "b2a1ec864a87ba66c63fc4e51c9223c7eb4f8335",
+  "commit": "4c43e943d7998be45bbb5a2606e095bbf1ffaa8a",
  "adapter": "claude-skill",
  "sourcePath": "skills/shadcn",
-  "syncedAt": "2026-09-02T10:37:18Z"
+  "syncedAt": "2026-09-02T16:00:01Z"
 }
@@ -407,7 +407,7 @@ results instead of mixing framework generations.
 Save your design system to files for **hierarchical retrieval across sessions**:
 ```bash
-# Generate and persist to design-system/MASTER.md
+# Generate and persist to design-system/myapp/MASTER.md
 python3 .claude/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard" --design-system --persist -p "MyApp"
 # Also create a page-specific override file
@@ -418,20 +418,21 @@ This creates a `design-system/` folder structure:
 ```
 design-system/
 └── myapp/                  # One folder per project (slug of -p "MyApp")
    ├── MASTER.md           # Global Source of Truth (colors, typography, spacing, components)
    └── pages/
        └── dashboard.md    # Page-specific overrides (only deviations from Master)
 ```
 **How hierarchical retrieval works:**
-1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+1. When building a specific page (e.g., "Checkout"), first check `design-system/[project-slug]/pages/checkout.md`
 2. If the page file exists, its rules **override** the Master file
-3. If not, use `design-system/MASTER.md` exclusively
+3. If not, use `design-system/[project-slug]/MASTER.md` exclusively
 **Context-aware retrieval prompt:**
 ```
-I am building the [Page Name] page. Please read design-system/MASTER.md.
+I am building the [Page Name] page. Please read design-system/[project-slug]/MASTER.md.
-Also check if design-system/pages/[page-name].md exists.
+Also check if design-system/[project-slug]/pages/[page-name].md exists.
 If the page file exists, prioritize its rules.
 If not, use the Master rules exclusively.
 Now, generate the code...
@@ -2,8 +2,8 @@
  "sourceId": "ui-ux-pro-max",
  "repo": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git",
  "ref": "main",
-  "commit": "e2effd57755d580318cce65ea1b2f98d896d5d40",
+  "commit": "58c220ff9d02be80523b06c03471925c52e8ab5d",
  "adapter": "claude-skill",
  "sourcePath": ".claude/skills/ui-ux-pro-max",
-  "syncedAt": "2026-09-02T10:37:18Z"
+  "syncedAt": "2026-09-02T16:00:01Z"
 }