helloagents 3.0.7 → 3.0.9-beta.1

package/README_CN.md

@@ -6,9 +6,9 @@
 
 <div align="center">
 
-**质量驱动的 AI 编码 CLI 编排内核 — 14 个自动激活技能、流程纪律、检查清单门控。**
+**质量驱动的 AI 编码 CLI 工作流框架 — 14 个自动激活技能、流程纪律、检查清单把关。**
 
-[![Version](https://img.shields.io/badge/version-3.0.7-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.9-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -95,20 +95,20 @@ HelloAGENTS 就是为了解决这个问题。它是一个编排层，装在你
 
 如果你上一次认真使用 HelloAGENTS 还是 `v2.3.8`，这一代的变化不是“增量补丁”，而是整条产品线重构。
 
-| 维度 | v2.3.8 | 本地 `v3.0.7` |
+| 维度 | v2.3.8 | 本地 `v3.0.9` |
 |------|--------|---------------|
 | **底层实现** | Python 包 + 大量脚本/规则混合 | 纯 Node.js + Markdown 运行时，围绕 `cli.mjs`、`bootstrap*.md`、`skills/`、`scripts/` 重建 |
-| **目标定位** | 更像多 CLI 管理工具 + 提示协议集合 | 更像 AI CLI 的质量编排内核，重点是路由、门控、验证和可恢复执行 |
+| **目标定位** | 更像多 CLI 管理工具 + 提示协议集合 | 更像 AI CLI 的质量工作流框架，重点是路由、把关、验证和可恢复执行 |
 | **安装方式** | pip / uv / npx / 一键脚本并行存在 | npm 为主；安装包后再显式部署到 Claude / Gemini / Codex |
 | **CLI 支持策略** | 6 个目标，能力差异很大 | 聚焦 3 个主战场：Claude Code、Gemini CLI、Codex CLI |
-| **工作流模型** | R0/R1/R2 三层路由 + 老式 design/develop 语义 | ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE 六阶段内核 |
-| **命令体系** | 15 个命令，含 `~exec` / `~rollback` / `~rlm` / `~validatekb` | 12 个聚焦命令：`~idea` / `~plan` / `~build` / `~verify` / `~prd` / `~loop` / `~wiki` 等 |
-| **质量模型** | 规则较分散，更多依赖自然语言约束 | 14 个自动激活技能 + 检查清单门控 + Ralph Loop + 结构化 evidence |
-| **项目状态** | 知识库更多是附属能力 | `.helloagents/` 成为项目激活边界，`STATE.md` / 方案包 / `DESIGN.md` / `contract.json` 组成主流程事实链 |
+| **工作流模型** | R0/R1/R2 三层路由 + 老式 design/develop 语义 | ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE 六阶段主流程 |
+| **命令体系** | 15 个命令，含 `~exec` / `~rollback` / `~rlm` / `~validatekb` | 13 个聚焦命令：`~idea` / `~plan` / `~build` / `~verify` / `~prd` / `~loop` / `~wiki` / `~help` 等 |
+| **质量模型** | 规则较分散，更多依赖自然语言约束 | 14 个自动激活技能 + 检查清单把关 + Ralph Loop + 结构化证据 |
+| **项目状态** | 知识库更多是附属能力 | `.helloagents/` 成为项目激活边界，`STATE.md` / 方案包 / `DESIGN.md` / `contract.json` 组成主流程的主要判断依据 |
 | **知识库存储** | 默认项目本地 | 默认项目本地，同时新增 `project_store_mode=repo-shared`，支持同一 git 仓库多个 worktree 共享稳定知识和方案资产 |
 | **Codex 集成** | 早期依赖更多兼容层和旧链路 | 标准模式使用注入规则 + 本地链接；全局模式使用原生本地插件链路，减少噪音与漂移 |
 
-一句话概括：`v2.3.8` 更像“给多个 CLI 加一层工作流外壳”，`v3.0.7` 更像“把质量协议、计划工件、验证证据和安装生命周期统一成一套真正可运转的编排内核”。
+一句话概括：`v2.3.8` 更像“给多个 CLI 加一层工作流外壳”，`v3.0.9` 更像“把质量协议、计划产物、验证证据和安装生命周期统一成一套真正可运转的工作流框架”。
 
 ## ✨ 核心特性
 
@@ -132,7 +132,7 @@ HelloAGENTS 通过三重机制协同保障质量：
 <td width="50%" valign="top">
 <img src="./readme_images/03-feature-icon-workflow.svg" width="48" align="left">
 
-**📋 检查清单门控**
+**📋 检查清单把关**
 
 编码完成后，HelloAGENTS 收集所有已激活技能的交付检查清单，逐项验证通过才能报告完成。
 
@@ -156,7 +156,7 @@ L1 拦截破坏性命令（`rm -rf /`、`git push --force`、`DROP DATABASE`）
 
 **⚡ 结构化工作流**
 
-简单任务保持快速。复杂任务走“路由前置”的内核工作流：ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE，并通过显式命令通道拆分脑暴、规划、实现与验证。
+简单任务保持快速。复杂任务走“先选路再执行”的主流程：ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE，并通过显式命令通道拆分脑暴、规划、实现与验证。
 
 **你的收益：** 按需投入 — 简单任务保持快速，复杂任务获得完整流程。
 
@@ -166,11 +166,11 @@ L1 拦截破坏性命令（`rm -rf /`、`git push --force`、`DROP DATABASE`）
 <td width="50%" valign="top">
 <img src="./readme_images/02-feature-icon-installer.svg" width="48" align="left">
 
-**🧠 结构化计划工件**
+**🧠 结构化计划产物**
 
-复杂任务不再只靠一段自然语言方案，而是落成 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`、`STATE.md`、`DESIGN.md` 等可追踪工件。
+复杂任务不再只靠一段自然语言方案，而是落成 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`、`STATE.md`、`DESIGN.md` 等可追踪产物。
 
-**你的收益：** 路由、实现、验证、收尾都围绕同一组事实源推进，不容易中途漂移。
+**你的收益：** 路由、实现、验证、收尾都围绕同一组判断依据推进，不容易中途漂移。
 
 </td>
 <td width="50%" valign="top">
@@ -304,12 +304,12 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 |-----|---------|----------|
 | Claude Code | 原生插件安装（手动命令） | 由 Claude 插件系统管理 |
 | Gemini CLI | 原生扩展安装（手动命令） | 由 Gemini 扩展系统管理 |
-| Codex CLI | 原生本地插件链路（自动） | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml` |
+| Codex CLI | 原生本地插件链路（自动） | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml`、`~/.codex/helloagents -> ~/plugins/helloagents` |
 
 ### 更新 / 重装 / 切分支行为
 
-- **标准模式** 通过 `~/.claude/helloagents`、`~/.gemini/helloagents`、`~/.codex/helloagents` 这三个符号链接保持脚本、技能、模板和 hooks 与包根目录同步，相关链接文件会立即反映本地变化；但 `CLAUDE.md`、`GEMINI.md`、`AGENTS.md` 这类注入载体仍是快照，bootstrap 或分支变化后需要显式刷新。
-- **Codex 全局模式** 使用复制后的运行时文件。重新执行 `helloagents --global` 会刷新 `~/plugins/helloagents/` 和 Codex cache 中的副本。
+- **标准模式** 通过 `~/.claude/helloagents`、`~/.gemini/helloagents`、`~/.codex/helloagents` 这三个符号链接保持脚本、技能、模板和 hooks 与包根目录同步，相关链接文件会立即反映本地变化；但 `CLAUDE.md`、`GEMINI.md`、`AGENTS.md` 这类注入后的规则文件仍是快照，bootstrap 或分支变化后需要显式刷新。
+- **Codex 全局模式** 使用复制后的运行时文件，并维护 `~/.codex/helloagents -> ~/plugins/helloagents` 作为 bootstrap 路由期望的稳定读取根目录。重新执行 `helloagents --global` 会刷新 `~/plugins/helloagents/` 和 Codex cache 中的副本。
 - 重新执行当前模式命令是被支持的：`helloagents --standby` 和 `helloagents --global` 都是 **切换或刷新** 命令。
 - 如需确定性的手动清理，先执行 `helloagents cleanup`，再执行 `npm uninstall -g helloagents`。
 - `npm uninstall -g helloagents` 会移除包本身；`~/.helloagents/helloagents.json` 会被有意保留。
@@ -323,7 +323,7 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 | 命令 | 说明 |
 |------|------|
 | `~idea` | 轻量点子探索 — 比较方向与方案，不写文件 |
-| `~auto` | 自动选路 — 在脑暴 / 规划 / 实现 / 验证 / PRD 间选择合适路径，并优先复用现有活跃方案包 |
+| `~auto` | 自动编排 — 自动选择主路径并持续衔接到实现 / 验证 / 收尾，并优先复用现有活跃方案包 |
 | `~plan` | 结构化规划 — 需求澄清 + 方案收敛 + 计划包 |
 | `~build` | 执行实现 — 基于当前需求或现有计划包完成实现 |
 | `~prd` | 完整 PRD — 13 维度头脑风暴式探索，生成产品需求文档 |
@@ -341,7 +341,7 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 | 命令 | 说明 |
 |------|------|
 | `~wiki` | 仅创建/同步项目知识库（`.helloagents/`） |
-| `~init` | 完整初始化项目：知识库 + 项目级载体文件 |
+| `~init` | 完整初始化项目：知识库 + 项目级规则文件 |
 | `~commit` | 生成规范化提交信息 + 知识库同步 |
 | `~clean` | 归档已完成方案，清理临时文件 |
 | `~help` | 显示所有命令和当前配置 |
@@ -425,13 +425,13 @@ helloagents --standby
 
 ## ⚙️ 工作原理
 
-**简单说：** HelloAGENTS 根据任务类型、风险等级和项目状态选择执行深度。标准模式下，未激活项目只保留轻量规则：安全、完成约束、压缩版质量下限，以及显式 `~command` 通道；一旦项目通过 `.helloagents/` 激活，或启用全局模式，就切换到完整内核工作流，显式经过脑暴、规划、实现、验证与收尾阶段。
+**简单说：** HelloAGENTS 根据任务类型、风险等级和项目状态选择执行深度。标准模式下，未激活项目只保留轻量规则：安全、完成约束、压缩版质量下限，以及显式 `~command` 通道；一旦项目通过 `.helloagents/` 激活，或启用全局模式，就切换到完整主流程，显式经过脑暴、规划、实现、验证与收尾阶段。
 
-**六阶段内核：**
+**六阶段主流程：**
 
 1. **ROUTE / TIER** — 判断当前任务应进入 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 还是 `~auto`
 2. **SPEC** — 明确目标、约束与成功标准
-3. **PLAN** — 标记所需质量技能，并准备 `requirements.md`、`plan.md`、`tasks.md` 等 artifact
+3. **PLAN** — 标记所需质量技能，并准备 `requirements.md`、`plan.md`、`tasks.md` 等结构化产物
 4. **BUILD** — 实现，TDD（写测试 → 写代码 → 重构），每步后增量验证
 5. **VERIFY** — 运行 Ralph Loop，需要时先审查 diff，再收集交付检查清单
 6. **CONSOLIDATE** — 更新 `STATE.md`、同步知识库、归档计划包
@@ -439,7 +439,7 @@ helloagents --standby
 **Delivery Tier：**
 - `T0` — 只读探索、点子比较、方向发散
 - `T1` — 低风险小改动、明确实现、显式验证
-- `T2` — 多文件功能、新项目、需要结构化 artifact 的任务
+- `T2` — 多文件功能、新项目、需要结构化产物的任务
 - `T3` — 高风险或不可逆链路，如认证、安全、支付、数据库、生产发布
 
 **路由规则：**
@@ -449,7 +449,7 @@ helloagents --standby
 - 审查 / 验证类任务 → `~verify`
 
 **按任务类型生效的质量规则与技能：**
-- UI / 前端 / 视觉交互任务始终先遵循当前 bootstrap 载体中的共享 UI 内核
+- UI / 前端 / 视觉交互任务始终先遵循当前 bootstrap 文件中的 UI 质量基线
 - 在已激活项目、全局模式或显式 UI 工作流命令中，`hello-ui` 会进一步补充设计契约执行、设计系统映射与视觉验收
 - 只有当 UI `contract.json` 显式要求更强 UI 保障时，HelloAGENTS 才会在保持默认路径轻量的前提下，额外引入 `.helloagents/.ralph-advisor.json` 和 `.helloagents/.ralph-visual.json`
 - 涉及 API？→ `hello-api` 激活（REST 规范、校验、错误格式）
@@ -461,12 +461,12 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 
 | 模式 | 安装方式 | 规则 | 技能 | 适用场景 |
 |------|---------|------|------|----------|
-| **标准模式** (默认) | `helloagents install <target> --standby` 或 `helloagents install --all --standby` | `bootstrap-lite.md`（含压缩版质量下限、共享 UI 内核、安全规则与完成约束的精简规则） | `~command` 按需使用；激活前 UI 任务仍受共享 UI 内核约束，出现 `.helloagents/` 后切换到完整流程 | 按需使用，不影响其他项目 |
+| **标准模式** (默认) | `helloagents install <target> --standby` 或 `helloagents install --all --standby` | `bootstrap-lite.md`（含压缩版质量下限、UI 质量基线、安全规则与完成约束的精简规则） | `~command` 按需使用；激活前 UI 任务仍受 UI 质量基线约束，出现 `.helloagents/` 后切换到完整流程 | 按需使用，不影响其他项目 |
 | **全局模式** | Claude/Gemini 手动装插件；Codex 自动装原生本地插件 | `bootstrap.md`（完整规则） | 14 个技能自动激活 | 全面使用 HelloAGENTS |
 
-标准模式会把规则注入到 `~/.claude/CLAUDE.md`、`~/.gemini/GEMINI.md`、`~/.codex/AGENTS.md`；其中 Codex 在 `~/.codex/config.toml` 中保留 `developer_instructions` 作为受管兜底，使 home `AGENTS.md` 继续作为主基线。HelloAGENTS 在受管安装 Codex 时会临时移除已有的 `model_instructions_file`，因为该配置会遮蔽 `AGENTS.md` 链路；执行清理时会恢复用户原值。每个 CLI 还会创建 `helloagents` 包根目录符号链接。Claude Code 和 Gemini 仍使用 hooks，因为宿主可以较安静地承载这类注入；Codex 默认**不启用** HelloAGENTS hooks：最新 pre 源码里 hook 生命周期会在 TUI 中可见显示，且 `suppressOutput` 不能作为真正的静默注入通道，所以 Codex 改为依赖注入后的规则文件，以及本地符号链接 / 原生本地插件目录结构。全局模式下，Claude Code 通过 `.claude-plugin/plugin.json` 中声明的 hooks 工作，Gemini 通过 `contextFileName=bootstrap.md` 和扩展 hooks 工作；Codex 仍使用原生本地插件安装链路（marketplace + 本地插件目录 + cache + `config.toml` 插件启用段），并同步维护 `~/.codex/AGENTS.md` 这层 home 基线，但不启用插件 hooks。
+标准模式会把规则注入到 `~/.claude/CLAUDE.md`、`~/.gemini/GEMINI.md`、`~/.codex/AGENTS.md`；对于 Codex，HelloAGENTS 还会在 `~/.codex/config.toml` 中写入一条受管的 `model_instructions_file`，指向同步后的 `~/.codex/AGENTS.md`，让同一份 home carrier 同时成为 Codex 的 base instructions override。执行清理时会恢复用户原来的 `model_instructions_file`。每个 CLI 还会创建 `helloagents` 包根目录符号链接。Claude Code 和 Gemini 仍使用 hooks，因为宿主可以较安静地承载这类注入；Codex 默认**不启用** HelloAGENTS hooks：最新 pre 源码里 hook 生命周期会在 TUI 中可见显示，且 `suppressOutput` 不能作为真正的静默注入通道，所以 Codex 改为依赖注入后的规则文件，以及本地符号链接 / 原生本地插件目录结构。全局模式下，Claude Code 通过 `.claude-plugin/plugin.json` 中声明的 hooks 工作，Gemini 通过 `contextFileName=bootstrap.md` 和扩展 hooks 工作；Codex 仍使用原生本地插件安装链路（marketplace + 本地插件目录 + cache + `config.toml` 插件启用段），并继续使用同一份 `~/.codex/AGENTS.md` home 基线，但不启用插件 hooks。
 
-在标准模式下，`.helloagents/` 就是项目激活边界。激活前，lite 载体**不会**运行完整六阶段内核，也不会启用语义自动选路；它只保留轻量执行规则、显式 `~command` 入口，以及最低质量/完成门槛。项目一旦存在 `.helloagents/`，当前项目就切换到完整项目流程，并以 `bootstrap.md` 作为运行时事实源。
+在标准模式下，`.helloagents/` 就是项目激活边界。激活前，lite 规则**不会**进入完整六阶段主流程，也不会启用语义自动选路；它只保留轻量执行规则、显式 `~command` 入口，以及最低质量/完成门槛。项目一旦存在 `.helloagents/`，当前项目就切换到完整项目流程，并以 `bootstrap.md` 作为运行时判断依据。
 
 整套切换可用：`helloagents --global` 或 `helloagents --standby`
 
@@ -482,7 +482,7 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 | `~plan` | 仅做交互式规划，生成计划包 | 想先审查方案再编码 |
 | `~build` | 从当前需求或现有计划包执行实现 | 需求已明确，想直接开始做 |
 | `~verify` | 审查与验证工作流 | 想先看审查结果、跑检查并修复 |
-| `~auto` | 在以上模式之间自动选路 | 需求明确，想要端到端交付 |
+| `~auto` | 在以上模式之间自动编排并一路推进 | 需求明确，想要端到端交付 |
 | `~prd` | 13 维度 PRD 生成 | 需要完整的产品需求文档 |
 
 典型模式：先 `~idea` 比较方向，再 `~plan` 收敛方案，然后 `~build` 实现，最后 `~verify` 验证。或者直接 `~auto` 一步到位。如果项目里已经有活跃方案包，`~auto` 应先复用这条现有链路，而不是无故重新脑暴或重新规划。涉及 UI 时，决策优先级固定为：`plan.md` / PRD 中的 UI 决策 → `DESIGN.md` → 通用 UI 规则。
@@ -493,15 +493,15 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 - 优先级：逻辑 `.helloagents/verify.yaml`（`project_store_mode=repo-shared` 时解析到共享知识目录）→ `package.json` scripts → 自动检测
 - 全部通过？→ 收集技能检查清单 → 验证 → 完成
 - 有失败？→ 反思 → 修复 → 重跑（3 次连续失败后触发熔断）
-- 若当前活跃方案包仍有未完成任务、缺少必需 artifact，或残留模板占位内容，交付也会被额外门控阻止
+- 若当前活跃方案包仍有未完成任务、缺少必需结构化产物，或残留模板占位内容，交付也会被额外把关拦下
 
 ### 知识库（`.helloagents/`）
 
-`~wiki` 只创建或同步项目知识库。`~init` 是更完整的项目初始化：它还会写入项目级载体文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）、刷新项目 `skills/helloagents` 链接，并补齐相关忽略项。在标准模式下，真正让当前项目进入完整项目流程的是项目本地 `.helloagents/` 的存在，项目级载体文件只是 `~init` 的附加能力。
+`~wiki` 只创建或同步项目知识库。`~init` 是更完整的项目初始化：它还会写入项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）、刷新各宿主项目级原生 skills 链接，并补齐相关忽略项。在标准模式下，真正让当前项目进入完整项目流程的是项目本地 `.helloagents/` 的存在，项目级规则文件只是 `~init` 的附加能力。
 
-默认情况下，知识库和方案包都写在项目本地 `.helloagents/`。若 `project_store_mode = "repo-shared"`，本地 `.helloagents/` 仅保留激活信号、`STATE.md` 与 `.ralph-*` 等运行态文件；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 会改写到 `~/.helloagents/projects/<repo-key>/`，从而在同一 git 仓库的多个 worktree 间共享稳定资料。
+默认情况下，知识库和方案包都写在项目本地 `.helloagents/`。当前恢复快照现在只认一个权威路径：`state_path`。当宿主能提供稳定的会话标识时，HelloAGENTS 会把它写到 `.helloagents/sessions/<branch>/<session>/STATE.md`；否则写到分支默认槽位 `.helloagents/sessions/<branch>/default/STATE.md`。若 `project_store_mode = "repo-shared"`，本地 `.helloagents/` 仅保留激活信号、会话级 `STATE.md` 与 `.ralph-*` 等运行态文件；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 会改写到 `~/.helloagents/projects/<repo-key>/`，从而在同一 git 仓库的多个 worktree 间共享稳定资料。
 
-`STATE.md` 是项目级恢复快照，不是所有交互的统一记忆文件。它会在 `~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop` 这类项目级连续流程中创建并持续更新；在验证/审查类任务中仅在文件已存在时更新；对 `~help` 这类一次性只读交互则不会创建。
+`STATE.md` 是由 `state_path` 解析出的当前恢复快照，不是所有交互的统一记忆文件。按“分支 + 会话 / 默认槽位”存储后，同仓库并发对话不再争用同一个文件。它会在 `~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop` 这类项目级连续流程中创建并持续更新；在验证/审查类任务中仅在文件已存在时更新；对 `~help` 这类一次性只读交互则不会创建。
 
 | 文件 | 用途 |
 |------|------|
@@ -560,7 +560,7 @@ npm test
 - Python 包 → 纯 Node.js/Markdown 架构
 - 15 个命令 → 12 个命令 + 14 个自动激活质量技能
 - 6 个 CLI 目标 → 3 个（Claude Code + Codex CLI + Gemini CLI）
-- 新增：检查清单门控、Guard 系统、~prd、~loop、~verify、设计系统生成
+- 新增：检查清单把关、Guard 系统、~prd、~loop、~verify、设计系统生成
 - 详见[版本历史](#-版本历史)。
 </details>
 
@@ -578,7 +578,7 @@ npm test
 - **hello-api**：API 设计（REST、校验、错误格式、限流）
 - **hello-security**：安全（认证、输入校验、XSS/CSRF、密钥管理）
 - **hello-test**：测试（TDD 流程、边界用例、AAA 模式）
-- **hello-verify**：验证门控（Ralph Loop、熔断器）
+- **hello-verify**：验证把关（Ralph Loop、熔断器）
 - **hello-errors**：错误处理（结构化错误、日志、恢复策略）
 - **hello-perf**：性能（N+1、缓存、代码分割、虚拟滚动）
 - **hello-data**：数据库（迁移、事务、索引、完整性）
@@ -664,7 +664,7 @@ npm test
 - 验证安装：`npm list -g helloagents`
 - Claude Code：检查 `~/.claude/CLAUDE.md` 是否包含 HelloAGENTS 标记
 - Gemini CLI：检查 `~/.gemini/GEMINI.md` 是否包含 HelloAGENTS 标记
-- Codex CLI：检查 `~/.codex/AGENTS.md` 是否包含 HelloAGENTS 标记，`~/.codex/config.toml` 是否仍保留 HelloAGENTS 的 `developer_instructions` 与 `notify`，并确认不存在意外重新出现的 `model_instructions_file` 遮蔽受管基线
+- Codex CLI：检查 `~/.codex/AGENTS.md` 是否包含 HelloAGENTS 标记，`~/.codex/config.toml` 是否保留指向 `~/.codex/AGENTS.md` 的 `model_instructions_file` 与 `notify`
 - 重启你的 CLI
 
 ---
@@ -718,28 +718,35 @@ npm test
 
 ## 📈 版本历史
 
-### v3.0.7（当前版本）
+### v3.0.9（当前版本）
+
+**修复与验证：**
+- 🔧 Claude Code / Gemini CLI 的 `stop` 交付门控现在优先读取结构化 `turn-state`，不再先从自然语言文本反推“是否完成交付”，普通等待态不再被误判为已完成
+- 🔧 Codex 清理链路现在会保留安装后用户自行改写的 `model_instructions_file`、`notify` 与非托管 `codex_hooks`，不再被安装前旧备份回写覆盖
+- 🧪 新增运行时 / 生命周期回归，覆盖 `stop` 的结构化完成态门控，以及安装后用户改写 Codex 配置时的 cleanup 保留行为
+
+### v3.0.7
 
 **相对 `v2.3.8` 的当前主线结果：**
-- ✨ 从 Python 包全面重写为 Node.js/Markdown 编排内核，安装、运行时注入、技能、规则与验证链路全部重建
-- ✨ 把旧的多层路由 / design-develop 流程，统一收敛成 ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE 六阶段内核
+- ✨ 从 Python 包全面重写为 Node.js/Markdown 工作流框架，安装、运行时注入、技能、规则与验证链路全部重建
+- ✨ 把旧的多层路由 / design-develop 流程，统一收敛成 ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE 六阶段主流程
 - ✨ 从旧命令集切换到 `~idea` / `~plan` / `~build` / `~verify` / `~prd` / `~loop` / `~wiki` 等更聚焦的命令体系，并引入 14 个自动激活质量技能
-- ✨ 项目工件体系成型：`STATE.md`、`DESIGN.md`、`requirements.md`、`plan.md`、`tasks.md`、`contract.json`、`.ralph-*` 证据成为流程事实源，而不是附属文档
+- ✨ 项目产物体系成型：`STATE.md`、`DESIGN.md`、`requirements.md`、`plan.md`、`tasks.md`、`contract.json`、`.ralph-*` 证据成为流程判断依据，而不是附属文档
 - ✨ 安装模型重构为标准模式 / 全局模式双轨；Codex 改为原生本地插件链路，Claude/Gemini 保留各自宿主原生能力
 - ✨ 新增 `project_store_mode=repo-shared`，让同一 git 仓库的多个 worktree 可以共享稳定知识库和方案包，而本地 `.helloagents/` 继续保留激活和运行态隔离
 
 ### v3.0.4
 
 **标准待机与运行时边界：**
-- 🔧 相对 `v3.0.3`，进一步明确激活边界：完整六阶段内核保留在 `bootstrap.md`，`bootstrap-lite.md` 作为项目激活前的待机载体
+- 🔧 相对 `v3.0.3`，进一步明确激活边界：完整六阶段主流程保留在 `bootstrap.md`，`bootstrap-lite.md` 作为项目激活前的待机规则文件
 - ✨ 固化标准模式、未激活项目的压缩版质量下限，让轻量模式仍能维持现代技术基线、性能基线和 UI 质量要求
-- 🔧 统一精修 bootstrap 的运行时术语与规则表述，在不改变既有门控模型的前提下提升准确性和专业性
+- 🔧 统一精修 bootstrap 的运行时术语与规则表述，在不改变既有把关模型的前提下提升准确性和专业性
 
 ### v3.0.3
 
 **流程与知识库激活：**
-- ✨ 新增 `~wiki`，用于只创建或同步 `.helloagents/`，不写项目级载体文件
-- 🔧 明确标准模式下的激活边界：`.helloagents/` 才是项目进入完整流程的实际信号；项目级载体文件仍属于 `~init` 的职责
+- ✨ 新增 `~wiki`，用于只创建或同步 `.helloagents/`，不写项目级规则文件
+- 🔧 明确标准模式下的激活边界：`.helloagents/` 才是项目进入完整流程的实际信号；项目级规则文件仍属于 `~init` 的职责
 - 🔧 统一修正 bootstrap、帮助文本和 README 中 `kb_create_mode` 的表述，使其只描述已激活项目或全局模式下的同步时机
 - 🧪 新增 `~wiki` 路由覆盖，并持续验证标准模式下基于 `.helloagents/` 的激活行为
 
@@ -747,18 +754,18 @@ npm test
 
 **修复与验证：**
 - 🔧 移除误回流到 Codex 标准/全局安装产物 `AGENTS.md` 中的静态运行时上下文前缀
-- 🔧 复查 Claude / Gemini 标准模式与全局模式静态载体，确认本来就不存在同类已废弃运行时规则块
-- 🔧 同步修正文档中关于 Codex `developer_instructions` 加载路径和无 hooks 运行方式的表述
-- 🧪 新增回归断言，确保 Codex 标准/全局载体中不再出现被移除的运行时上下文前缀
+- 🔧 复查 Claude / Gemini 标准模式与全局模式静态规则文件，确认本来就不存在同类已废弃运行时规则块
+- 🔧 同步修正文档中关于 Codex `model_instructions_file -> ~/.codex/AGENTS.md` 和无 hooks 运行方式的表述
+- 🧪 新增回归断言，确保 Codex 标准/全局规则文件中不再出现被移除的运行时上下文前缀
 
 ### v3.0.1
 
 **修复与验证：**
 - 🔧 收敛并加强 `STATE.md` 恢复规则：关键决策变更即更新，长流程一旦失真立即重写，宿主明确进入压缩/恢复前置阶段前必须先确认已同步
-- 🔧 修复 Codex 本地插件链路清理后的空 `~/.agents/plugins/marketplace.json` 残留，并在配置恢复时忽略被污染的旧 `developer_instructions` 备份
+- 🔧 修复 Codex 本地插件链路清理后的空 `~/.agents/plugins/marketplace.json` 残留
 - 🔧 修复并验证单 CLI `update` 在记录模式过期时仍会优先复用本地已检测模式，符合 `helloagents update <cli>` 的预期行为
-- 🔧 明确标准模式下“链接文件立即同步、注入载体需显式刷新”的分支/ bootstrap 刷新语义
-- 🧪 新增标准模式载体刷新、模式自动复用、Codex 空 marketplace 清理、Codex 污染备份恢复，以及与版本号无关的 npm pack 生命周期测试
+- 🔧 明确标准模式下“链接文件立即同步、注入后的规则文件需显式刷新”的分支 / bootstrap 刷新语义
+- 🧪 新增标准模式规则文件刷新、模式自动复用、Codex 空 marketplace 清理，以及与版本号无关的 npm pack 生命周期测试
 
 ### v3.0.0 🎉
 
@@ -770,7 +777,7 @@ npm test
 **新功能：**
 - ✨ 14 个自动激活质量技能：hello-ui、hello-api、hello-security、hello-test、hello-verify、hello-errors、hello-perf、hello-data、hello-arch、hello-debug、hello-subagent、hello-review、hello-write、hello-reflect
 - ✨ 3 个支持的 CLI：Claude Code（插件/marketplace）、Gemini CLI（扩展）、Codex CLI（npm）
-- ✨ 检查清单门控：所有已激活技能必须通过交付检查清单才能完成任务
+- ✨ 检查清单把关：所有已激活技能必须通过交付检查清单才能完成任务
 - ✨ `~prd` 命令：13 维度头脑风暴式 PRD 框架
 - ✨ `~loop` 命令：自主迭代优化，带指标追踪和 git 回滚
 - ✨ `~verify` 命令：自动检测并运行所有验证命令
@@ -779,11 +786,11 @@ npm test
 - ✨ 流状态管理（`STATE.md`）：用于压缩/恢复衔接的恢复快照（≤70 行）
 - ✨ 设计系统生成（`DESIGN.md`）：作为项目级 UI 契约自动创建
 - ✨ 计划包系统：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`
-- ✨ 可选 advisor contract / evidence：仅在 T3 / UI / 高风险链路启用，通过 `contract.json` + `.helloagents/.ralph-advisor.json` 落地
-- ✨ 可选视觉验收 evidence：仅在 UI contract 明确要求时启用，通过 `contract.json` + `.helloagents/.ralph-visual.json` 落地
+- ✨ 可选 advisor 契约与证据：仅在 T3 / UI / 高风险链路启用，通过 `contract.json` + `.helloagents/.ralph-advisor.json` 落地
+- ✨ 可选视觉验收证据：仅在 UI 契约明确要求时启用，通过 `contract.json` + `.helloagents/.ralph-visual.json` 落地
 
 **架构：**
-- 📦 路由前置的六阶段内核：ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
+- 📦 先选路再执行的六阶段主流程：ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
 - 📦 简化配置：8 个小写键，合理默认值
 - 📦 双模式安装：标准模式（非插件，显式部署）/ 全局模式（插件/扩展）
 - 📦 模块化脚本架构：`cli-utils.mjs`（共享工具）、`notify-ui.mjs`（跨平台声音/桌面通知）、`guard.mjs`（安全防护）、`ralph-loop.mjs`（质量验证）

package/bootstrap-lite.md

@@ -10,7 +10,7 @@
 在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
 
 ## 编码原则
-- 代码是唯一事实源，文档与代码不一致时以代码为准
+- 代码是唯一判断依据，文档与代码不一致时以代码为准
 - 代码体积控制：
   - 预警阈值（超过后必须评估是否拆分）：文件/类 300 行，函数/方法 40 行
   - 强制拆分阈值（超过后必须在完成功能后按职责拆分）：文件/类 400 行，函数/方法 60 行
@@ -46,17 +46,17 @@
 - 不确定的技术选型主动查阅最新文档和社区最佳实践，不依赖旧版本知识
 - 项目已有技术栈、设计系统或方案包时必须遵循既有决策
 
-### UI 质量内核（涉及视觉/交互任务时，全阶段生效）
-任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下内核；适用于标准模式、标准模式+已激活项目与全局模式。
+### UI 质量基线（涉及视觉/交互任务时，全阶段生效）
+任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式、标准模式+已激活项目与全局模式。
 纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节；项目已有更高优先级的 UI 契约时，只用本节兜底，不得覆盖上层决策。
 
-- 先形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；禁止直接套用泛化风格标签或模型默认审美
-- 先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；已有品牌语言或既有界面模式时保持一致
-- 优先使用真实内容与真实信息层级，不使用 Lorem ipsum、泛化营销套话或无意义占位图；内容必须服务产品语义
+- 先判断本次视觉变更是延续既有风格、演进式优化还是探索性方案，再形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；不得直接滑入泛化风格标签或模型默认审美
+- 已有项目优先复用现有组件、token、品牌资产、内容语气与交互模式；先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；缺少关键设计上下文时明确说明，不凭空发明视觉语言
+- 使用真实内容与真实信息层级，不使用 Lorem ipsum、泛化营销套话或无意义占位图；不为撑满页面编造统计、图标、区块或伪功能；缺少素材时使用明确占位或请求补充，不低质量仿制
 - 结构必须有清晰层级与节奏：每个区块只承担一个核心职责；主界面或首屏形成完整构图；默认克制卡片、徽章、分隔线和装饰元素的滥用
 - 交互必须覆盖关键状态：加载、空、错误、成功、禁用、危险态；动效只服务于引导、反馈和层级切换，不做无意义噪音
 - 可用性必须同步达标：响应式/自适应、可访问性、可见焦点、键盘可达、触控/点击目标、减弱动效偏好，不能在视觉升级时牺牲可用性
-- 若宿主已有浏览器或截图能力，优先做视觉验证；否则至少基于代码与结构做一次明确的视觉自检，确认实现与设计意图一致
+- 若宿主已有浏览器或截图能力，尽早检查关键视口与交互状态；否则至少基于代码与结构做一次明确的视觉自检，确认实现与设计意图一致
 
 仅保留以下必要反模式下限：
 - 默认紫白渐变、白底卡片堆砌、Inter/Roboto/Arial 等默认字体栈、emoji 当图标、纯色平背景
@@ -89,8 +89,16 @@
 - 不允许吞掉错误：捕获的异常必须处理或上报，不能空 catch 后继续
 
 ## 输出格式
-当 helloagents.json 的 output_format 为 true 时，只有主代理在本轮最后一条、且确认**不再继续调用工具/不再继续执行**的**收尾消息**才使用以下格式。若某个 skill 在当前轮明确要求输出停顿、确认或总结，也必须同时满足“该条消息就是本轮收尾消息”这一条件。子代理在任何场景下都不得使用该格式。
-当 output_format 为 false 时，所有回复保持自然输出，不适用以上格式。
+适用条件：
+- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理仅可在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
+- 若某个 skill 在本轮明确要求输出停顿、确认或总结，也仅当该消息同时是**本轮最终收尾消息**时，才可使用输出格式。
+
+排除条件：
+- 当 `output_format` 为 `false` 时，所有回复保持自然输出，不得使用输出格式。
+- 以下内容一律视为中间输出，必须自然输出，不得使用输出格式：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报，以及任何发出后仍会继续调用工具或继续执行的回复。
+- 子代理在任何场景下都不得使用输出格式。
+
+输出格式：
 
 {图标}【HelloAGENTS】- {状态描述}
 {空一行}
@@ -98,11 +106,19 @@
 {空一行}
 🔄 下一步: {下一步状态或动作}
 
-图标: 💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
+图标：💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
+
+使用约束：
+- 状态图标与收尾内容必须一致。等待用户输入、确认、授权或补充信息时，只能使用 `❓等待输入`；仅在本轮执行已完成且不再等待用户输入时，才能使用 `✅完成`。
+- `🔄 下一步` 必须填写当前最合适的下一步动作。若存在自然后续动作，直接给出明确引导；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成，等待您的下一步指示。”
+- 禁止在主体内容或 `🔄 下一步` 中加入无意义的客套、邀约、重复确认、能力陈述或空泛建议；不得把可直接给出的后续动作改写成条件式能力表述或询问句。
 
-以下内容一律视为中间输出，必须自然输出，禁止使用顶部信息栏和底部操作栏：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报、以及任何发出后仍会继续调用工具或继续执行的回复。
-状态图标与收尾内容必须一致：等待用户输入时只能使用 `❓等待输入`；仅在本轮执行已完成且不再等待用户输入时才能使用 `✅完成`。
-“🔄 下一步”填写当前最合适的下一步动作；若当前任务已完成但仍有自然后续动作，直接给出明确引导；仅在确无合理后续时，填写“当前任务已完成，等待您的下一步指示。”之类内容。禁止无意义的客套、邀约、重复确认、能力陈述、重复确认、空泛建议，或把可直接给出的后续动作改写成条件式能力表述或询问句。
+### 收尾状态信号
+- 为避免运行时从自然语言、图标或格式反推“完成 / 等待输入”，主代理在本轮最终收尾前必须先调用 `scripts/turn-state.mjs write`
+- 本轮已完成且不再等待用户输入 → 写 `kind=complete`、`role=main`
+- 因阻塞判定等待用户输入、确认、授权或补充信息 → 写 `kind=waiting`、`role=main`
+- 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`
+- 子代理不得写 turn-state；子代理结束只直接返回结果，不为主代理代写完成态
 
 ## 交互规则
 
@@ -139,7 +155,7 @@
 以下情况才构成中途停下并请求用户输入的正当理由：
 - 需求存在影响执行结果的真实歧义
 - 缺少继续执行所必需的信息、文件、路径或凭据
-- 将产生外部副作用，但当前轮尚未获得对应授权
+- 将产生外部副作用，但本轮尚未获得对应授权
 - 操作属于高风险或不可逆，按安全规则必须确认
 除上述情况外，默认继续执行，不以“建议下一步”替代实际推进。
 
@@ -166,23 +182,25 @@
 ## 路由
 - `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~verify` 的兼容别名
 - `~test` — 为指定模块或最近变更编写测试
-- `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。优先使用当前会话已注入的”当前 HelloAGENTS 读取根目录”或已解析出的具体命令技能文件路径；仅在需要执行具体命令时读取对应 SKILL.md，不扫描整个 `skills/helloagents/` 目录，也不对同一命令重复探测多个路径。查找路径（按优先级，找到即停）：
-  1. {CWD}/skills/helloagents/skills/commands/{name}/SKILL.md
-  2. 当前已加载 HelloAGENTS 包根目录下的 skills/commands/{name}/SKILL.md
+- 路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录
+- `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。若当前上下文已解析出具体命令技能文件路径，直接使用它；否则先确定当前技能根目录：
+  - 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
+  - 若当前上下文未注入，则将当前宿主 home 目录下的 `helloagents/` 链接作为 `{HELLOAGENTS_READ_ROOT}`
+  确定根目录后读取其中的 `skills/commands/{name}/SKILL.md`；标准模式下即使项目目录存在本地 HelloAGENTS skills，也不要读取项目路径。不要扫描整个目录，也不要对同一命令重复探测多个路径。
 
 ## .helloagents/ 目录
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
-- `.helloagents/` 是逻辑项目空间，也是 standby 模式的激活信号
+- `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
 - `STATE.md`、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
-- 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前会话注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定它们一定物理位于工作树内
+- 当前 `STATE.md` 只认当前项目存储中的 `state_path`；支持会话标识时，它会落在 `.helloagents/sessions/{branch}/{session}/STATE.md`，未提供稳定会话标识时则落到 `.helloagents/sessions/{branch}/default/STATE.md`
+- 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
-1. {CWD}/skills/helloagents/templates/
-2. 当前已加载 HelloAGENTS 包根目录下的 templates/
+按上文 `~command` 路由中的相同技能根目录规则确定；确定根目录后读取其中的 `templates/`。
 
 ### 流程状态（不受 kb_create_mode 控制，始终可写）
-- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一事实源；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
+- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一判断依据；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
   - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入统一执行流程/已激活项目的连续任务
@@ -221,20 +239,20 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 
 ## 项目上下文
 
-主线事实源优先级：
+主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. `.helloagents/STATE.md`（恢复快照，只用于补齐最近进度）
+3. 当前 `STATE.md`（始终取当前项目存储中的 `state_path`；恢复快照，只用于补齐最近进度）
 4. 其他知识沉淀与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取项目本地 `.helloagents/STATE.md`
-- Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认是逻辑别名；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
+- Tier 1 的 `STATE.md` 始终读取当前项目存储中的 `state_path`
+- Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
 Tier 1 — 恢复当前链路时优先读取：
-- .helloagents/STATE.md → 恢复快照（先确认当前消息仍是同一任务，再用它找回最近进度）
+- 当前 `STATE.md` → 恢复快照（始终取当前项目存储中的 `state_path`；先确认当前消息仍是同一任务，再用它找回最近进度）
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引
@@ -248,7 +266,7 @@ Tier 3 — 深入特定模块时读取：
 - .helloagents/archive/ → 历史方案归档
 
 ### 项目文件
-根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目根 AGENTS.md / CLAUDE.md / .gemini/GEMINI.md 等提示词文件当作普通项目文件重复读取。
+根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）当作普通项目文件重复读取。
 
 ## 状态符号
 任务状态: [ ] 待办 | [√] 完成 | [X] 取消 | [-] 跳过