helloagents 3.0.7 → 3.0.9-beta.1

package/skills/commands/help/SKILL.md

@@ -12,13 +12,13 @@ Trigger: ~help
 | 命令 | 说明 |
 |------|------|
 | ~idea | 轻量点子探索与方向比较 |
-| ~auto | 自动选路：在脑暴 / 规划 / 执行 / 验证 / PRD 间选择合适路径 |
+| ~auto | 自动编排：自动选主路径并持续衔接到执行 / 验证 / 收尾，除非命中真实阻塞 |
 | ~plan | 结构化规划：需求澄清 + 方案收敛 + 方案包 |
 | ~build | 执行实现：按需求或方案包完成实现与验证 |
 | ~prd | 完整 PRD：头脑风暴式逐维度挖掘，生成现代产品需求文档 |
 | ~loop | 自主迭代优化：设定目标和指标，循环修改-验证-保留/回滚 |
 | ~wiki | 仅创建/同步项目知识库（`.helloagents/`） |
-| ~init | 完整初始化项目：知识库 + 项目级载体配置 |
+| ~init | 完整初始化项目：知识库 + 项目级规则文件配置 |
 | ~test | 为指定模块或最近变更编写完整测试 |
 | ~verify | 验证总入口：审查 + 运行验证命令 + 修复循环 |
 | ~commit | 规范化提交 + 知识库同步 |
@@ -32,7 +32,7 @@ Trigger: ~help
 
 ### 自动激活技能
 以下技能仅在全局模式或已激活项目中自动激活（例如执行过 `~wiki`、`~init`，或已处于项目级连续流程）。
-纯标准模式未激活项目不会自动触发这些深层技能；但涉及 UI 的任务仍受 UI 质量内核约束。
+纯标准模式未激活项目不会自动触发这些深层技能；但涉及 UI 的任务仍受 UI 质量基线约束。
 
 编码时：hello-ui, hello-api, hello-data, hello-security, hello-errors, hello-perf, hello-arch, hello-test
 特定场景：hello-debug, hello-subagent, hello-write, hello-review

package/skills/commands/idea/SKILL.md

@@ -11,7 +11,7 @@ Trigger: ~idea [description]
 ## 铁律
 - 只讨论，不编写实现代码，不创建项目文件，不执行实现操作
 - 不创建 `.helloagents/`
-- 不创建或更新 `.helloagents/STATE.md`、知识库文件、方案包或项目根载体
+- 不创建或更新 `.helloagents/STATE.md`；若当前项目存储给出 `state_path`，同样禁止更新该当前 `STATE.md`、知识库文件、方案包或项目级规则文件
 - 不生成方案包
 - 不执行会改变工作区或外部状态的命令
 - 不默认使用子代理
@@ -45,7 +45,7 @@ Trigger: ~idea [description]
   - 想形成结构化方案 → `~plan`
   - 想直接进入实现 → `~build`
   - 需要重型产品规格 → `~prd`
-  - 想让 AI 自动选路径 → `~auto`
+  - 想让 AI 自动编排完整链路 → `~auto`
 - 如果用户在 `~idea` 过程中转而明确要求写文件、改代码、创建知识库或执行命令，不在 `~idea` 内偷偷落地；改为按最合适的升级路径继续
 
 ## 输出要求

package/skills/commands/init/SKILL.md

@@ -1,22 +1,25 @@
 ---
 name: ~init
-description: 初始化项目知识库和配置（~init 命令）
+description: 初始化项目知识库与项目级规则文件（~init 命令）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~init
 
 ~init 是用户显式命令，创建完整知识库，不受 kb_create_mode 限制。
-执行 `~init` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 规则按当前已加载 bootstrap 执行；本命令额外负责项目根载体和项目级 `skills/helloagents` 链接。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：项目本地 `.helloagents/` 继续承担激活目录与 `STATE.md`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前会话注入的项目知识/方案目录写入。
+执行 `~init` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 规则按当前已加载 bootstrap 执行；本命令额外负责项目级规则文件和各宿主项目级原生 skills 链接。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活目录与 `STATE.md`；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录写入。
 
 ## 流程
 
 ### 阶段 1：环境搭建（必做）
 
-1. 创建 `.helloagents/` 目录 + `STATE.md`（按 templates/STATE.md 格式，初始“主线目标”写当前初始化链路，初始状态为空闲）
-2. 定位插件根目录：优先读取当前会话中注入的“当前 HelloAGENTS 包根目录”；若上下文未提供，再根据当前已加载载体和规则反推，禁止猜测其他目录
-3. 创建 `skills/helloagents` symlink → `{插件根目录}/`
+1. 创建 `.helloagents/` 目录 + 当前 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`；按 templates/STATE.md 格式，初始“主线目标”写当前初始化链路，初始状态为空闲）
+2. 定位插件根目录：优先读取当前上下文中已注入的“当前 HelloAGENTS 包根目录”；若上下文未提供，再根据当前已加载的规则文件反推，禁止猜测其他目录
+3. 刷新各宿主项目级原生 skills 链接（删除旧的重建）：
+   - `.claude/skills/helloagents` symlink → `{插件根目录}/`
+   - `.gemini/skills/helloagents` symlink → `{插件根目录}/`
+   - `.codex/skills/helloagents` symlink → `{插件根目录}/`
 4. 读取 `{插件根目录}/bootstrap.md`，用 `<!-- HELLOAGENTS_START -->` / `<!-- HELLOAGENTS_END -->` 标记包裹后写入：
    - `AGENTS.md`（项目根目录，Codex 读取）
    - `CLAUDE.md`（项目根目录，Claude Code 读取）
@@ -25,7 +28,9 @@ Trigger: ~init
 5. 追加 `.gitignore`（如果对应行不存在）：
    ```
    .helloagents/
-   skills/helloagents
+   .claude/skills/helloagents
+   .gemini/skills/helloagents
+   .codex/skills/helloagents
    AGENTS.md
    CLAUDE.md
    .gemini/GEMINI.md
@@ -58,6 +63,6 @@ commands:
 重复执行 ~init 是安全的：
 - 已存在的 .helloagents/ 文件不覆盖
 - `STATE.md` 只作为当前初始化链路的恢复快照；后续进入其他主线任务时必须按新主线重写
-- symlink 刷新（删除旧的重建）
+- 各宿主项目级原生 skills 链接会刷新（删除旧的重建）
 - AGENTS.md/CLAUDE.md/GEMINI.md 中标记内容替换更新
 - .gitignore 只追加缺失行

package/skills/commands/loop/SKILL.md

@@ -19,12 +19,12 @@ Trigger: ~loop <目标描述> [--iterations N] [--metric "命令"] [--direction
 ## 初始化
 
 1. 确认 git 工作区干净（有未提交变更则先提醒用户处理）
-2. 确保 `.helloagents/` 目录和 `.helloagents/STATE.md` 存在；目录不存在时先创建，`STATE.md` 不存在时按 `templates/STATE.md` 创建。这是 `~loop` 的强制恢复快照，不受 `kb_create_mode` 控制；“主线目标”固定写本次优化目标，避免被旧任务主线污染
+2. 确保 `.helloagents/` 目录和当前会话的 `STATE.md` 存在；优先使用当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`；文件不存在时按 `templates/STATE.md` 创建。这是 `~loop` 的强制恢复快照，不受 `kb_create_mode` 控制；“主线目标”固定写本次优化目标，避免被旧任务主线污染
 3. 运行指标命令获取基线值，记录到 results log
 4. 如有守卫命令，运行确认基线通过
 5. 创建 `.helloagents/loop-results.tsv`，并确保 .gitignore 包含该文件
 6. 根据优化目标标记可能需要的 hello-* 质量技能（如性能优化标记 hello-perf，UI 优化标记 hello-ui）
-7. 重写 `.helloagents/STATE.md`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
+7. 重写当前会话的 `STATE.md`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
 
 results log 格式：
 ```
@@ -77,7 +77,7 @@ iteration	commit	metric	delta	guard	status	description
 ### Phase 7: Log
 - 追加一行到 results log
 - status: baseline / keep / discard / crash / no-op
-- 重写 `.helloagents/STATE.md`：保持主线目标=当前优化目标，并记录当前轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
+- 重写当前会话的 `STATE.md`：保持主线目标=当前优化目标，并记录当前迭代轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
 
 ### Phase 8: Repeat
 - 如果 iterations > 0 且 current_iteration >= max_iterations → 输出总结并停止
@@ -90,7 +90,7 @@ iteration	commit	metric	delta	guard	status	description
 - 总迭代次数 / 保留次数 / 丢弃次数
 - 最有效的 3 个改进
 - results log 路径
-- 重写 `.helloagents/STATE.md`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
+- 重写当前会话的 `STATE.md`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
 
 ## 安全规则
 - 使用 `git revert`（保留历史）而非 `git reset --hard`（丢失历史）

package/skills/commands/plan/SKILL.md

@@ -6,23 +6,24 @@ policy:
 ---
 Trigger: ~plan [description]
 
-`~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案落盘；默认停在“形成可执行方案”，只有用户明确授权继续时才衔接执行。
+`~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案落盘；直接显式执行 `~plan` 时，默认停在“形成可执行方案”，只有用户明确授权继续时才衔接执行。
 执行 `~plan` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充 `~plan` 的需求澄清、方案收敛、方案包写入与执行衔接要求。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前会话注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何实现文件、或执行任何实现操作
 - 需求澄清阶段不读取实现类技能（hello-ui / hello-test / hello-verify 等），需求明确后再按需读取
-- 方案必须收敛为可执行 artifact，不停留在泛化建议
-- 涉及 UI 时，当前方案包中的 UI 决策优先于逻辑 `.helloagents/DESIGN.md`；逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析）优先于通用 UI 规则
+- 方案必须收敛为可执行产物，不停留在泛化建议
+- 若当前链路来自 `~auto`，则“开始执行”视为已包含在 `~auto` 授权内；方案包落地后默认继续衔接执行，只有命中阻塞判定时才停下
+- 涉及 UI 时，当前方案包中的 UI 决策优先于 `.helloagents/DESIGN.md`；`.helloagents/DESIGN.md`（按当前项目存储模式解析）优先于通用 UI 规则
 
 ## 流程
 
 ### 1. 上下文收集与需求澄清准备
 
 已有项目：
-- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
-- 在需求澄清前，至少确认逻辑 `.helloagents/context.md`、逻辑 `.helloagents/guidelines.md`；涉及 UI 时，如存在逻辑 `.helloagents/DESIGN.md`，一并读取现有设计契约
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用（若当前项目存储给出 `state_path`，则优先读取该当前会话的 `STATE.md`），再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 在需求澄清前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`（按当前项目存储模式解析）；涉及 UI 时，如存在 `.helloagents/DESIGN.md`（按当前项目存储模式解析），一并读取现有设计契约
 - 只扫描与当前需求直接相关的代码文件，用于形成假设和识别约束
 
 全新项目（无 `.helloagents/` 目录）：
@@ -58,7 +59,7 @@ Trigger: ~plan [description]
 涉及 UI 的方案：
 - 读取 `hello-ui` SKILL.md
 - 将视觉、交互、设计系统要求纳入方案
-- 区分“本次 feature 的 UI 决策”和“项目级稳定设计契约”：前者写入 `plan.md`，后者同步到逻辑 `.helloagents/DESIGN.md`
+- 区分“本次 feature 的 UI 决策”和“项目级稳定设计契约”：前者写入 `plan.md`，后者同步到 `.helloagents/DESIGN.md`（按当前项目存储模式解析）
 
 ### 4. 方案细化
 
@@ -73,7 +74,7 @@ Trigger: ~plan [description]
 
 将确认的方案写入本地项目：
 - 按当前已加载 bootstrap 的 `.helloagents/` 与流程状态规则，确保最小项目状态已建立
-- 创建逻辑 `.helloagents/plans/YYYYMMDDHHMM_{feature}/`
+- 创建 `.helloagents/plans/YYYYMMDDHHMM_{feature}/`（按当前项目存储模式解析）
 - 按模板写入：
   - `requirements.md`
   - `plan.md`
@@ -83,9 +84,9 @@ Trigger: ~plan [description]
 - 只有在 UI 方向确需前置收敛时，才额外写 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason` 与 `ui.styleAdvisor.focus`；它复用 `.helloagents/.ralph-advisor.json`，不是默认常驻步骤
 - 只有在 UI 验收确有收益时，才额外写 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens` 与 `ui.visualValidation.states`；不要把视觉验收扩成所有 UI 任务的固定步骤
 - 只有在 `T3`、非 UI 的高风险审查或确需额外跨模型建议时，才写 `advisor.required`、`advisor.reason`、`advisor.focus` 与 `advisor.preferredSources`；不要把 advisor 变成默认常驻流程
-- 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要让 gate / validator 再从 `plan.md` prose 里猜验证主路径
-- 涉及 UI 的项目：生成或更新逻辑 `.helloagents/DESIGN.md`；若原文件不存在，先按模板建立最小设计契约，再写入已确认的稳定设计决策
-- 重写 `.helloagents/STATE.md`，其中“主线目标”写当前规划链路真正要完成的目标，不把旧任务残留为当前主线
+- 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要让后续检查脚本再从 `plan.md` 的自然语言说明里猜验证主路径
+- 涉及 UI 的项目：生成或更新 `.helloagents/DESIGN.md`（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再写入已确认的稳定设计决策
+- 重写当前会话的 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`），其中“主线目标”写当前规划链路真正要完成的目标，不把旧任务残留为当前主线
 
 知识库完整创建与归档按当前已加载 bootstrap 的后续规则执行。
 
@@ -97,6 +98,7 @@ Trigger: ~plan [description]
 - 暂不执行，保留方案 → 更新 `STATE.md`；“主线目标”写当前已确认方案要解决的问题，下一步写为“方案已确认；执行需用户明确启动”
 
 如果用户已明确表示继续执行，则视为授权成立，可直接衔接执行。
+如果当前链路来自 `~auto`，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 `~build`，不再追加一次“是否开始执行”的询问。
 
 ## 方案包要求
 

package/skills/commands/prd/SKILL.md

@@ -8,14 +8,15 @@ Trigger: ~prd [description]
 
 执行 `~prd` 时，不读取 `~plan` 的 command skill；只有当前流程明确需要时，才继续读取对应的 hello-* 技能。
 执行 `~prd` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充规格探索、PRD 落盘与执行衔接要求。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前会话注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
 - 每个维度的选项必须体现当前前沿水准。若当前已加载 bootstrap 含审美/体验规则则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅。
 - 用户说"跳过"某维度 → 跳过，不生成该文件。不强迫用户讨论不关心的维度。
 - 大项目检测：涉及多个独立子系统时，先帮用户分解为子项目，每个子项目走独立的 ~prd 循环。
-- 涉及 UI 时，`prd/03-ui-design.md` 负责沉淀本次产品/功能的 UI 决策；项目级稳定设计契约同步写入逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析）
+- 若当前链路来自 `~auto`，则 PRD / 任务 / 契约落地后默认继续衔接后续执行；只有真实阻塞时才停在规格阶段。
+- 涉及 UI 时，`prd/03-ui-design.md` 负责沉淀本次产品/功能的 UI 决策；项目级稳定设计契约同步写入 `.helloagents/DESIGN.md`（按当前项目存储模式解析）
 
 ## PRD 维度清单
 
@@ -57,7 +58,7 @@ Trigger: ~prd [description]
 ### 1. 上下文收集
 
 已有项目：
-- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用（若当前项目存储给出 `state_path`，则优先读取该当前会话的 `STATE.md`），再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
 - 在进入维度探索前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`，并只扫描与当前产品范围直接相关的代码和配置
 
 全新项目（无 .helloagents/ 目录）：
@@ -97,14 +98,14 @@ c. AI 总结该维度的决策结果，进入下一个维度
 
 将讨论结果写入本地项目：
 - 按当前已加载 bootstrap 的 `.helloagents/` 与流程状态规则，确保最小项目状态已建立；这是方案包写入的前置操作，不受 kb_create_mode 开关控制
-- 创建逻辑 `.helloagents/plans/YYYYMMDDHHMM_{feature}/prd/`
+- 创建 `.helloagents/plans/YYYYMMDDHHMM_{feature}/prd/`（按当前项目存储模式解析）
 - 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
 - 生成 tasks.md（每个任务包含具体文件路径、预期变更、完成标准、验证方式；任务独立可验证；依赖顺序明确）
 - 生成 decisions.md（贯穿全程的决策日志）
 - 生成 `contract.json`（至少包含 `verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时补 `ui.required`、`ui.designContract`、`ui.sourcePriority`；仅在确需前置审美收敛时再补 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason`、`ui.styleAdvisor.focus`；仅在确需视觉验收时再补 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens`、`ui.visualValidation.states`；仅在确需独立 advisor 时，再补 `advisor.required`、`advisor.reason`、`advisor.focus`、`advisor.preferredSources`）
-- 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在 prose 里
-- 涉及 UI 的项目：生成或更新逻辑 `.helloagents/DESIGN.md`；若原文件不存在，先按模板建立最小设计契约，再同步已确认的稳定 UI 决策
-- 重写 `.helloagents/STATE.md`，其中“主线目标”写当前 PRD 链路真正要完成的产品 / 功能目标，不延续无关旧主线
+- 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在自然语言说明里
+- 涉及 UI 的项目：生成或更新 `.helloagents/DESIGN.md`（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再同步已确认的稳定 UI 决策
+- 重写当前会话的 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`），其中“主线目标”写当前 PRD 链路真正要完成的产品 / 功能目标，不延续无关旧主线
 
 输出 PRD 完整度摘要：已覆盖 N/13 个维度，建议后续补充的维度（如有）。
 
@@ -116,6 +117,7 @@ c. AI 总结该维度的决策结果，进入下一个维度
 - 暂不执行，保留方案 → 重写 `STATE.md`（“主线目标”保持当前 PRD 目标，下一步设为“方案已确认；执行需用户明确启动”）
 
 如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 `~plan` 收敛实现方案。
+如果当前链路来自 `~auto`，且 PRD 已收敛到可执行任务、也未命中阻塞判定，则默认继续进入 `~build`，必要时先补一轮轻量 `~plan`，不再额外询问一次“是否开始执行”。
 
 ### 6. 执行衔接
 
@@ -137,7 +139,7 @@ plans/YYYYMMDDHHMM_{feature}/
 │   ├── 01-user-stories.md  # 仅用户未跳过的维度
 │   ├── 02-functional.md
 │   └── ...
-├── contract.json           # 机器可消费的验证 / 审查 contract
+├── contract.json           # 机器可消费的验证 / 审查契约
 ├── tasks.md                # 任务分解
 └── decisions.md            # 决策日志
 ```

package/skills/commands/verify/SKILL.md

@@ -9,27 +9,27 @@ Trigger: ~verify [scope]
 ## 流程
 
 0. 先对齐当前工作流状态：
-   - 若当前上下文已注入“当前工作流约束”或“当前建议下一命令”，先服从它
+   - 若当前上下文中已注入“当前工作流约束”或“当前建议下一命令”，先服从它
    - 即使命令通过，也不能越过当前方案包边界：不完整方案包不能视为可信交付记录，未闭合方案包不能被整体报告为已完成
    - 当推荐路径已进入 `~verify` / 收尾时，优先把本命令用于审查、验真和交付收尾
    - 若当前存在活跃方案包，先读取 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`，把它们当作本轮验证契约；不要只看命令结果
    - 若 `contract.json` 声明 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，则本轮还必须补齐 `.helloagents/.ralph-advisor.json`；advisor / style advisor 都是可选能力，不是默认常驻步骤
    - 若 `contract.json` 声明 `ui.visualValidation.required=true`，则本轮还必须补齐 `.helloagents/.ralph-visual.json`；视觉验收优先用截图/浏览器工具，没有工具时才降级为结构化代码级自检
 1. 先决定验证分流：
-   - 若当前上下文已注入“验证分流”，先按该分流执行
-   - 用户显式使用 `~review` 时，即使当前轮没有注入分流，也按审查优先起步
+   - 若当前上下文中已注入“验证分流”，先按该分流执行
+   - 用户显式使用 `~review` 时，即使本轮没有注入分流，也按审查优先起步
    - 若没有注入分流、也不是 `~review`，默认先做全量验证；执行中一旦发现高风险链路、关键权限/配置/迁移/发布边界或明显未覆盖的风险点，立即补做 `hello-review`
 2. 审查优先模式：
    - 获取变更范围：无参数默认未提交变更；`staged` 代表暂存区；指定文件/目录则只审查对应范围
    - 按 hello-* 技能查找路径读取 `hello-review` SKILL.md，执行逐文件审查
    - 高风险链路除显式范围外，还要主动补查相关配置、迁移、权限、部署或安全边界文件，不能只盯住单个功能文件
-   - 审查结论确定后，立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`；用结构化字段记录 `outcome`、`conclusion`、`findings`、`fileReferences`，不要让 gate 再从自然语言消息里猜结论
+   - 审查结论确定后，立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`；用结构化字段记录 `outcome`、`conclusion`、`findings`、`fileReferences`，不要让后续检查脚本再从自然语言消息里猜结论
 3. 全量验证模式或审查后继续验证：
    - 读取 `hello-verify` SKILL.md
    - 按其“验证命令来源”优先级检测命令
    - 逐个运行所有检测到的命令
    - 收集每个命令的输出和退出码
-   - 对照当前 contract 逐项核对：requirements 是否覆盖、tasks 中每项“完成标准”是否满足、`plan.md` 中风险与设计约束是否被验证、`contract.json` 中声明的 `verifyMode` / reviewer / tester 关注边界是否已被覆盖
+   - 对照当前契约逐项核对：requirements 是否覆盖、tasks 中每项“完成标准”是否满足、`plan.md` 中风险与设计约束是否被验证、`contract.json` 中声明的 `verifyMode` / reviewer / tester 关注边界是否已被覆盖
    - 若 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，在进入收尾前调用 `scripts/advisor-state.mjs write` 写 `.helloagents/.ralph-advisor.json`；记录触发原因、focus、consultedSources、结论与建议，禁止只在自然语言里留一段 advisor 意见
    - 若 `ui.visualValidation.required=true`，在进入收尾前调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`；记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status`、`summary`、`findings` 与 `recommendations`
 4. 汇总报告：

package/skills/commands/wiki/SKILL.md

@@ -1,31 +1,29 @@
 ---
 name: ~wiki
-description: 初始化或同步项目知识库（仅 `.helloagents/`，不写项目根载体）
+description: 初始化或同步项目知识库（仅 `.helloagents/`）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~wiki
 
-`~wiki` 是用户显式命令，用于只创建、补全或同步项目知识库，不创建项目根 `AGENTS.md` / `CLAUDE.md` / `.gemini/GEMINI.md`，也不创建项目级 `skills/helloagents` symlink。适用于标准模式下希望保留项目目录为“非载体项目”，但仍希望当前项目拥有 `.helloagents/` 激活目录、`STATE.md` 和知识沉淀文件的场景。
+`~wiki` 是用户显式命令，仅创建、补全或同步项目知识库。
 
 `~wiki` 是显式知识库命令，不受 `kb_create_mode` 限制。
-执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 重写规则按当前已加载 bootstrap 执行；本命令只补充“只写知识库、不写项目根载体”的边界。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 保持项目本地；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`DESIGN.md`、`modules/` 改按当前会话注入的项目知识目录写入。
+执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 重写规则按当前已加载 bootstrap 执行；不写入项目级规则文件，也不创建项目级原生 skills 链接。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`DESIGN.md`、`modules/` 改按当前上下文中已注入的项目知识目录写入。
 
 ## 流程
 
 ### 阶段 1：基础准备（必做）
 
-1. 创建 `.helloagents/` 目录 + `STATE.md`（按 templates/STATE.md 格式）；初始“主线目标”只写当前知识库初始化 / 同步目标，不把它写成长期项目总目标
+1. 创建 `.helloagents/` 目录 + 当前 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`；按 templates/STATE.md 格式）；初始“主线目标”只写当前知识库初始化 / 同步目标，不把它写成长期项目总目标
 2. 追加 `.gitignore`（如果对应行不存在）：
    ```
    .helloagents/
    ```
 3. 明确不执行以下操作：
-   - 不创建或更新项目根 `AGENTS.md`
-   - 不创建或更新项目根 `CLAUDE.md`
-   - 不创建或更新 `.gemini/GEMINI.md`
-   - 不创建项目级 `skills/helloagents` symlink
+   - 不创建或更新项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）
+   - 不创建项目级原生 skills 链接
 
 ### 阶段 2：知识库创建或补全（条件性）
 
@@ -33,7 +31,7 @@ Trigger: ~wiki
 - 有代码文件 → 执行完整知识库创建/补全（下方流程）
 - 空项目 → 保留 `.helloagents/` 和 `STATE.md`，告知用户“项目为空，其余知识文件将在后续开发或首次编码任务中补全”
 
-知识库创建/补全流程（逻辑写入 `.helloagents/`；`project_store_mode=repo-shared` 时实际落在共享知识目录）：
+知识库创建/补全流程（统一写入 `.helloagents/` 对应的项目级存储路径；`project_store_mode=repo-shared` 时实际落在共享知识目录）：
 1. 按 templates/ 目录的模板格式，分析项目代码库后创建或补全：
    - context.md — 按 templates/context.md 格式，填入项目概述、技术栈、架构、目录结构、模块链接
    - guidelines.md — 按 templates/guidelines.md 格式，从现有代码推断编码约定
@@ -56,4 +54,4 @@ commands:
 - `STATE.md` 按当前任务状态重写，不追加历史；它只记录当前知识库链路的恢复快照，不承担项目主线的唯一记忆
 - 知识库文件缺失时补全，已存在时按模板增量更新
 - `.gitignore` 只追加缺失行
-- 永不写入项目根载体文件，也不创建项目级 `skills/helloagents` symlink
+- 永不写入项目级规则文件，也不创建任何项目级原生 skills 链接

package/skills/hello-review/SKILL.md

@@ -32,7 +32,7 @@ description: 审查代码变更、检查 PR、review 代码质量，或用户要
 - 审查结束时必须单独给出一行“审查结论：...”
 - 若发现阻塞问题，结论中明确写出存在问题，并在正文中为每个问题附文件定位
 - 若未发现阻塞问题，明确写“审查结论：未发现阻塞问题。”
-- 若当前项目已激活，且本轮审查结果需要进入 gate / closeout，审查结论确定后立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`
+- 若当前项目已激活，且本轮审查结果需要进入后续交付检查或收尾，审查结论确定后立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`
 - `.ralph-review.json` 必须使用结构化字段记录：`outcome`（`clean` / `findings`）、`conclusion`、`findings`、`fileReferences`
 - 不要依赖“审查结论：...”这行让运行时再从自然语言里猜机器结论；这行只服务于人类阅读
 

package/skills/hello-subagent/SKILL.md

@@ -4,13 +4,13 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 ---
 
 子代理编排必须遵循以下规范。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 和 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，方案包、`verify.yaml` 与 `DESIGN.md` 按当前会话注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 和 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，方案包、`verify.yaml` 与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 编码前
 先确定任务是否适合子代理（独立性高、边界清晰、可验证）。
 
 ## 派遣规范
-- 每个子代理获得：tasks.md 中的对应任务 + 方案包中的相关约束（~plan: requirements.md + plan.md；~prd: prd/ 中的相关维度文件 + decisions.md）+ 验证命令；涉及 UI 时，再附逻辑 `.helloagents/DESIGN.md` 或其中相关片段
+- 每个子代理获得：tasks.md 中的对应任务 + 方案包中的相关约束（~plan: requirements.md + plan.md；~prd: prd/ 中的相关维度文件 + decisions.md）+ 验证命令；涉及 UI 时，再附 `.helloagents/DESIGN.md`（按当前项目存储模式解析）或其中相关片段
 - 新鲜上下文：不继承主会话历史，避免上下文污染
 - 提示开头标记 [子代理任务]，让子代理跳过 bootstrap 加载
 - 单一职责：一个子代理只做一件事
@@ -20,6 +20,7 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 - 使用子代理时，主代理作为控制器跟踪进度
 - 主代理只有在本轮最终收尾时才可使用 HelloAGENTS 外层输出格式。
 - 团队协作中的进度与状态汇报都属于中间输出，不得包装 HelloAGENTS 外层输出格式。
+- 子代理不得调用 `scripts/turn-state.mjs write` 代替主代理写完成态或等待态；turn-state 只由主代理在本轮最终收尾前写入
 - 子代理完成后执行双阶段审查：
   1. 需求符合性审查：变更是否符合方案包需求和 tasks.md 的要求？有无多做或少做？
   2. 代码质量审查：运行验证命令，审查代码质量

package/skills/hello-ui/SKILL.md

@@ -1,28 +1,28 @@
 ---
 name: hello-ui
-description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 内核之上补充项目契约消费、设计系统映射与视觉验证。
+description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约消费、设计系统映射与视觉验证。
 ---
 
-本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量内核负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和深度 UI 任务中，补充更强的契约执行、实现映射与视觉验收。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`.ralph-*.json` 等运行态证据保持项目本地；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前会话注入的项目知识/方案目录解析。
+本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和深度 UI 任务中，补充更强的契约执行、实现映射与视觉验收。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`.ralph-*.json` 等运行态证据保持项目本地；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 适用边界
 已进入显式 UI 规划/实现/验证路径，或当前项目已激活且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
-标准模式未激活项目中的普通 UI 请求，仍只受当前 bootstrap 的 UI 内核约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
+标准模式未激活项目中的普通 UI 请求，仍只受当前 bootstrap 的 UI 质量基线约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
 
 ## 设计契约优先级
 进入 UI 相关的规划、实现、验证时，按以下顺序做设计决策：
 1. 当前活跃方案包 `plan.md` 或 PRD 中已确认的 UI 决策
-2. 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析）
+2. `.helloagents/DESIGN.md`（按当前项目存储模式解析）
 3. 本 skill 的通用规则
-缺少上层 artifact 时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。
+缺少上层产物时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。
 
 ## 深层职责
 - 消费上游契约：把 `plan.md` / PRD / `DESIGN.md` 中已确认的 UI 决策视为强约束，而不是建议
-- 消费可选 UI contract：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 留下设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 留下视觉验收证据
+- 消费可选 UI 契约：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 留下设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 留下视觉验收证据
 - 映射到代码结构：明确 token 放在哪里、组件边界如何划分、状态组件如何组织、动效与主题如何落地
 - 做视觉验收闭环：优先使用截图/浏览器工具做桌面与移动端检查；没有工具时也要完成结构化视觉自检
-- 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回逻辑 `.helloagents/DESIGN.md`，不要把一次性页面细节全部写成项目级契约
+- 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回 `.helloagents/DESIGN.md`（按当前项目存储模式解析），不要把一次性页面细节全部写成项目级契约
 
 ## 深层设计 brief（编码前必须落定）
 
@@ -31,15 +31,15 @@ description: 已进入显式 UI 工作流、已激活项目的视觉变更、设
 1. 目的：这个界面解决什么问题？谁在用？什么场景？什么平台？
 2. 美学方向：选择一个鲜明的方向并坚持到底。不从固定列表中选，而是根据项目的受众、场景和情感目标，创造一个忠于上下文的独特风格。问自己：这个产品的用户期待什么情绪？什么视觉语言能传达这种情绪？
 3. 记忆点：用户看到这个设计会记住的一个特征是什么？
-4. 差异化：每次设计必须不同。在明暗主题、字体、美学方向间变换，不收敛到常见选择。
+4. 差异化：当任务明确要求探索，或缺少现成设计约束时，主动避免滑入常见默认风格；差异化必须服务产品语义、品牌边界与可用性，不为变化而变化。
 5. 设计 token：尽早建立变量/token 体系——背景色/表面色/主色/弱化色/强调色 + 展示/标题/正文/说明文字的字体角色。Web 用 CSS 变量，桌面/移动端用平台对应的主题系统。
 6. 约束定义：为当前项目定义具体约束（如最多几个区块、几种字体、几个强调色、首屏的 CTA 数量），约束释放创意。
 7. 真实内容：使用真实文案、产品信息、项目上下文，不使用 Lorem ipsum 或泛化占位符。真实内容帮助做出更贴合上下文的设计决策。
 
 执行顺序要求：
-- 已激活项目且存在逻辑 `.helloagents/DESIGN.md` 时，进入真实 UI 任务先读取它，再展开方案或实现
+- 已激活项目且存在 `.helloagents/DESIGN.md`（按当前项目存储模式解析）时，进入真实 UI 任务先读取它，再展开方案或实现
 - 已通过方案包或 PRD 确认设计方向的，按确认方向执行，并以 `plan.md` / PRD 中的 UI 决策为最高优先级
-- 已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在时，先按 `templates/DESIGN.md` 创建最小设计契约（至少覆盖产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项），再继续大规模实现
+- 已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但 `.helloagents/DESIGN.md`（按当前项目存储模式解析）不存在时，先按 `templates/DESIGN.md` 创建最小设计契约（至少覆盖产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项），再继续大规模实现
 - 未经方案包且无 `DESIGN.md` 的任务，基于以上规则，结合任务需求和项目上下文做出设计决策并执行
 
 ## 实现映射（进入编码前必须明确）
@@ -218,8 +218,8 @@ Hero 区域：
 1. 截图渲染结果（桌面 + 移动端视口）
 2. 对照设计原则审查截图：构图是否完整？品牌感是否到位？配色是否一致？
 3. 发现问题 → 修复 → 再截图验证
-4. 若当前 contract 要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
+4. 若当前契约要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
 5. 确认截图与设计意图一致后才能报告完成
 
 无浏览器工具时，仔细审查生成的代码，确认样式、布局、动效的实现与设计意图一致。
-若当前 contract 要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，并明确标记所用 tooling 与已检查的 screens / states。
+若当前契约要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，并明确标记所用 tooling 与已检查的 screens / states。

package/skills/hello-verify/SKILL.md

@@ -4,7 +4,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 ---
 
 声称完成之前，必须有验证证据。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`.ralph-review.json`、`.ralph-visual.json`、`.ralph-closeout.json` 等交付证据保持项目本地；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前会话注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`.ralph-review.json`、`.ralph-visual.json`、`.ralph-closeout.json` 等交付证据保持项目本地；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 
@@ -65,7 +65,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 - package.json 中的 lint/test/typecheck 脚本
 - pyproject.toml 中的 ruff/mypy/pytest
 
-## 交付检查清单门控
+## 交付检查清单把关
 
 验证命令全部通过后，还需要：
 这些标记只用于交付检查清单、验收记录和验证结果，不用于普通说明、方案解释或进度汇报。
@@ -75,7 +75,8 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 4. 有未通过项 → 修复 → 重新运行验证循环
 5. 若当前存在方案包并准备最终收尾，优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录 `requirementsCoverage` 与 `deliveryChecklist` 两项结论；两项都必须包含 `status`（`PASS` / `BLOCKED`）和 `summary`
 6. 若当前方案包要求 `review-first`，必须先确认 `.helloagents/.ralph-review.json` 已通过 `scripts/review-state.mjs write` 写成最新结构化证据；不要把审查自然语言消息直接当成交付证据
-7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认 `.helloagents/.ralph-visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉 evidence，不得把本轮视为 UI 可交付
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认 `.helloagents/.ralph-visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉验收证据，不得把本轮视为 UI 可交付
+8. 准备以本轮最终收尾消息报告完成时，先调用 `scripts/turn-state.mjs write` 写 `kind=complete`、`role=main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，不要让运行时从自然语言消息里猜状态
 
 ## 需求追踪验证
 
@@ -85,8 +86,8 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 3. 确认非目标章节列出的内容确实没有被实现（防止范围蔓延）
 4. 若 tasks.md 中定义了“完成标准”，逐项确认每个任务的完成标准确实成立，不能只因为代码存在或命令通过就视为完成
 5. 若存在 `contract.json`，逐项确认其中的 `verifyMode`、reviewer / tester 关注边界都已被本轮验证覆盖
-6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认 `.helloagents/.ralph-advisor.json` 已存在且结论为 clean；若没有 advisor artifact，不得把本轮视为可交付
-7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认 `.helloagents/.ralph-visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有 visual artifact，不得把本轮视为 UI 可交付
+6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认 `.helloagents/.ralph-advisor.json` 已存在且结论为 clean；若没有 advisor 证据，不得把本轮视为可交付
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认 `.helloagents/.ralph-visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有视觉验收证据，不得把本轮视为 UI 可交付
 8. 发现遗漏 → 补充实现 → 重新验证
 
 ## 反代理目标漂移 (APGD)

package/skills/helloagents/SKILL.md

@@ -5,10 +5,11 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 
 # HelloAGENTS
 
-主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在当前轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
+主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在本轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
+主代理在本轮最终收尾前，如要报告“已完成 / 等待输入 / 本轮阻塞”，必须先调用 `scripts/turn-state.mjs write` 写机器可读的 turn-state；不要让运行时再从自然语言或图标反推状态。子代理不得写 turn-state。
 
-`.helloagents/` 在所有 skill 中都先视为逻辑项目空间：项目本地 `.helloagents/` 继续承担激活信号、`STATE.md` 与 `.ralph-*.json` 等运行态文件；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 改按当前会话注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定它们一定物理存在于工作树内。
+`.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活信号、`STATE.md` 与 `.ralph-*.json` 等运行态文件；若当前上下文中的“当前项目存储”给出 `state_path`，本轮读写恢复快照一律使用该路径（可能是会话级 `sessions/{branch}/{session}/STATE.md`），不要强行回写旧的 `.helloagents/STATE.md`；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
 
 ## 三重质量保障
 
@@ -22,23 +23,23 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 ### 流程纪律（执行时）
 - 执行 command skill 时，公共阶段边界以当前已加载 bootstrap 为准；command skill 只补充该命令的专属动作和边界
 - 统一执行流程的六个阶段（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）不可跳过
-- 所有 UI 任务先受当前 bootstrap 的 UI 质量内核约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） → `hello-ui` 深层规则
-- 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付门控优先按它执行，不再从自然语言总结里回推
+- 所有 UI 任务先受当前 bootstrap 的 UI 质量基线约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → `hello-ui` 深层规则
+- 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付检查优先按它执行，不再从自然语言总结里回推
 - 因阻塞判定而必须等待用户输入时，遵循当前 bootstrap 的等待输入规则，不得把等待输入包装成完成态
 - ~plan 的需求澄清与方案收敛不可跳过，不可一个问题就出方案
 - ~prd 的维度探索不可跳过，每个激活维度必须经过讨论或用户明确跳过
 - ~auto 的复杂度判断不可省略
 - hello-verify 的验证铁律：没有运行验证 = 不能说完成
 
-### 检查清单门控（完成时）
-任务完成后，必须执行以下门控流程（详见 hello-verify）：
+### 检查清单把关（完成时）
+任务完成后，必须执行以下检查流程（详见 hello-verify）：
 1. 运行验证命令（lint/test/build）→ 循环直到通过
 2. 收集所有已激活技能的交付检查清单
 3. 逐项验证。仅在交付检查清单、验收记录和验证结果中使用 [√] / [-] 标记，并附带证据；普通说明、方案解释、状态汇报不用这些标记
 4. 有未通过项 → 修复后重新检查
 5. 全部通过 → 才能报告完成
 
-未经门控就报告完成 = 违反 HelloAGENTS 核心规则。
+未经过完整检查就报告完成 = 违反 HelloAGENTS 核心规则。
 
 ## 技能加载规则（渐进式披露）
 
@@ -63,14 +64,18 @@ Layer 3 — 资源文件（技能内引用时读取）：
 
 读取其他技能时，按以下路径查找，找到即停，不自行猜测或遍历其他路径。
 
+路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录
+先确定当前技能根目录：
+- 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
+- 若当前上下文未注入，则将当前宿主 home 目录下的 `helloagents/` 链接作为 `{HELLOAGENTS_READ_ROOT}`
+- 已激活项目或全局模式下，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
+
 ### hello-* 技能
-1. `{CWD}/skills/helloagents/skills/{技能名}/SKILL.md`
-2. 当前已加载 HelloAGENTS 包根目录下的 `skills/{技能名}/SKILL.md`
+读取 `{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.md`
 
 ### ~command 命令技能
-1. `{CWD}/skills/helloagents/skills/commands/{name}/SKILL.md`
-2. 当前已加载 HelloAGENTS 包根目录下的 `skills/commands/{name}/SKILL.md`
-命中路径后立即停止，不要重复读取同一命令 skill。
+若当前上下文已解析出具体命令技能文件路径，直接使用它；否则读取 `{HELLOAGENTS_READ_ROOT}/skills/commands/{name}/SKILL.md`
+确定路径后立即停止，不要重复读取同一命令 skill。
 
 ## 技能索引（仅元数据）