helloagents 3.0.33 → 3.0.37

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.33-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.37-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)
@@ -78,9 +78,9 @@ HelloAGENTS 叠加在 Claude Code、Gemini CLI 和 Codex CLI 之上，帮助模
 
 ## 核心功能
 
-### 1）14 个按任务使用的质量技能
+### 1）14 个内置工作流技能
 
-HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时读取，因此简单任务不会被额外流程拖慢，复杂任务则会得到更完整的检查。
+HelloAGENTS 内置 14 个技能。技能只在当前阶段需要时读取，因此简单任务不会被额外流程拖慢，复杂任务则会得到更完整的检查。
 
 | 技能 | 关注点 |
 |------|--------|
@@ -88,19 +88,19 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 | `hello-api` | API 设计、校验、错误格式、兼容性 |
 | `hello-security` | 认证、密钥、权限、注入风险 |
 | `hello-test` | TDD、覆盖率、边界用例、测试结构 |
-| `hello-verify` | 审查、命令验证、交付证据、收尾 |
+| `qa-review` | 统一质量审查、命令验证、阻断修复、交付证据、收尾 |
+| `helloagents` | 命令路由、工作流阶段规则、项目知识和状态协调 |
 | `hello-errors` | 错误处理、日志、重试和恢复 |
 | `hello-perf` | 性能、缓存、查询和渲染风险 |
 | `hello-data` | 数据库、迁移、事务、索引 |
 | `hello-arch` | 架构、边界、代码体积、可维护性 |
 | `hello-debug` | 问题诊断和卡住时的升级处理 |
 | `hello-subagent` | 子代理分工和结果整合 |
-| `hello-review` | 代码审查和结构化问题记录 |
 | `hello-write` | 文档、报告和文字交付 |
 | `hello-reflect` | 可复用经验和知识更新 |
 
 所有 UI 任务都会先受共享的 UI 质量基线约束。
-在全局模式、已初始化项目或明确的 UI 工作流里，`hello-ui` 会在该基线之上补充设计契约执行、设计系统映射与视觉验收。
+在宿主全局模式、已初始化项目或明确的 UI 工作流里，`hello-ui` 会在该基线之上补充设计契约执行、设计系统映射与视觉验收。
 当需要视觉证据时，HelloAGENTS 会写入当前会话的 `artifacts/visual.json`。
 
 ### 2）面向不同工作方式的命令
@@ -114,12 +114,10 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 | `~plan` | 需求、方案、任务拆分和方案包 |
 | `~build` | 按当前请求或现有方案实现 |
 | `~prd` | 通过逐维度讨论生成现代产品需求文档 |
-| `~loop` | 设置指标和守卫命令，循环改进、保留或回滚 |
-| `~wiki` | 只创建或同步项目知识库 |
-| `~init` | 同 `~wiki` |
-| `~global` | 初始化项目级全局模式 |
+| `~loop` | 长任务入口；在 Codex 中优先走 `/goal -> ~auto -> ~qa` |
+| `~init` | 初始化项目工作流并同步项目知识库 |
 | `~test` | 为指定模块或最近变更编写测试 |
-| `~verify` | 审查、运行验证命令、修复失败并收尾 |
+| `~qa` | 运行统一质量闭环：审查、验证命令、修复失败并收尾 |
 | `~commit` | 生成规范化提交信息并同步知识库 |
 | `~clean` | 归档已完成方案，清理临时运行文件 |
 | `~help` | 显示命令和当前设置 |
@@ -128,7 +126,7 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 
 - `~do` → `~build`
 - `~design` → `~plan`
-- `~review` → `~verify` 的审查优先模式
+- `~review` → `~qa`
 
 ### 3）项目知识库
 
@@ -147,9 +145,7 @@ HelloAGENTS 可以在 `.helloagents/` 下创建和维护项目知识库。
 | `plans/<feature>/` | 活跃方案包 |
 | `archive/` | 已归档方案包 |
 
-`~wiki` 和 `~init` 只创建或更新知识库。
-
-`~global` 做得更多：创建或更新知识库、写入项目级全局模式标记，并刷新各宿主项目级 HelloAGENTS 包根链接。
+`~init` 用来初始化项目工作流：写入项目级 full carrier 标记、准备项目状态，并创建或更新知识库。
 
 ### 4）结构化方案包
 
@@ -180,7 +176,7 @@ HelloAGENTS 可以在 `.helloagents/` 下创建和维护项目知识库。
 
 `contract.json` 会影响验证范围、reviewer/tester 关注点、可选 advisor 检查和可选视觉验收。
 
-`tasks.md` 还会保留 Codex `/goal` 执行入口。长程 Codex 任务应使用这个已拆分入口，不要把原始产品文档直接交给 `/goal`。HelloAGENTS 保持 `/goal` 的 Codex 原生定位，只把它作为续跑和预算控制；方案文件、任务边界、验证与收尾仍由 HelloAGENTS 负责。
+`tasks.md` 还会保留 Codex `/goal` 执行入口。长程 Codex 任务应使用这个已拆分入口，不要把原始产品文档直接交给 `/goal`。默认链路是 `/goal -> ~auto -> ~qa`：`/goal` 负责长程续跑，`~auto` 负责执行 AFK 任务，`~qa` 负责最终质量闭环与收尾前验收。
 
 ### 5）状态与恢复
 
@@ -193,24 +189,30 @@ HelloAGENTS 现在只从 `state_path` 解析当前状态文件：
 
 `<workspace>` 是当前 Git 分支、detached HEAD 的 `detached-<sha>`，或非 Git 项目的 `workspace`。`.helloagents/sessions/active.json` 只记录当前活跃会话索引。
 
-`STATE.md` 只记录当前工作流做到哪里，不承担所有对话的统一记忆。
+对于项目本地会话目录，HelloAGENTS 现在只使用稳定宿主标识，如 `sessionId`、`conversationId`、`threadId` 或 `HELLOAGENTS_NOTIFY_SESSION_ID`。它不再使用 `WT_SESSION`、`TERM_SESSION_ID`、`WINDOWID` 这类终端或窗口标识去额外生成项目会话目录。
+
+`STATE.md` 只记录当前工作流做到哪里，不承担所有对话的统一记忆。Codex `/goal` 也不替代 `state_path`、`turn-state` 或本地证据文件；它只负责 Codex 侧的长程续跑。
 
 ### 6）验证与交付证据
 
 HelloAGENTS 不把“命令通过”和“任务完成”简单画等号。交付还可能要求需求覆盖、任务清单、审查证据、advisor 证据和视觉证据。
 
-运行态证据文件包括：
+运行态现在尽量收敛，只保留真正有用的文件：
 
-- `.helloagents/sessions/<workspace>/<session>/capsule.json`
-- `.helloagents/sessions/<workspace>/<session>/events.jsonl`
+- `.helloagents/sessions/<workspace>/<session>/STATE.md`
 - `.helloagents/sessions/active.json`
-- `.helloagents/sessions/<workspace>/<session>/artifacts/review.json`
+- `.helloagents/sessions/<workspace>/<session>/artifacts/qa-review.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/advisor.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/visual.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/closeout.json`
-- `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
+- 仅用于 Codex 原生收尾去重的 `~/.codex/.helloagents/notify-state.json`
+
+`turn-state`、路由上下文和 artifact 索引都写进 `STATE.md` 的元数据，不再单独生成 `capsule.json`。`events.jsonl` 改为可选 trace 输出，默认不写。
+项目本地 `STATE.md` 现在会更晚创建；旧版残留的项目根 `.helloagents/artifacts/*.log` 也会自动清理，不再继续充当第二套历史系统。
+
+标准运行态证据和临时运行态现在默认 72 小时过期。只有工作流明确需要的长程 Codex goal 链路，才继续保留 720 小时上限。
 
-交付门控、守卫和循环提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终回复还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
+交付门控、守卫和 QA gate 提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终回复还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
 这个外层格式现在只保留给直接面向最终用户的终局交付。中间汇报、委派任务结果和子代理回复都保持自然输出；子代理结束钩子也会拦截错误的外层收尾格式。
 
 ### 7）更安全的安装、更新、清理和诊断
@@ -221,8 +223,8 @@ CLI 显式管理宿主文件：
 - `update` 刷新指定目标或全部目标
 - `cleanup` 删除受管注入和链接
 - `uninstall` 在移除包前执行对应清理
-- `doctor` 检查规则文件、链接、hooks、配置项、插件根目录、缓存副本和版本漂移
-- 单 CLI 模式记录只会在宿主安装成功后写入，避免原生全局安装失败后留下错误模式记录
+- `doctor` 检查规则文件、链接、hooks、配置项、插件根目录、缓存副本和版本漂移；对 Codex 还会在可用时附带原生 `codex doctor` 结果
+- 单 CLI 模式记录只会在宿主安装成功后写入；如果原生全局清理失败，也会继续保留 `global` 记录，而不是悄悄叠加 standby
 
 ## 快速开始
 
@@ -266,20 +268,14 @@ helloagents install --all --global
 ~help
 ```
 
-应能看到 14 个对话命令和当前设置。
+应能看到可用对话命令和当前设置。
 
 ### 4）创建项目知识
 
-只创建知识库：
-
-```text
-~wiki
-```
-
-初始化项目级全局模式：
+初始化项目工作流：
 
 ```text
-~global
+~init
 ```
 
 ## CLI 管理
@@ -313,7 +309,7 @@ helloagents codex goals enable
 
 ### npm 和一键脚本入口
 
-当你不想依赖更新过程中的 `helloagents` 可执行文件时，用 npm 或一键脚本。`HELLOAGENTS=目标[:模式]` 中，目标支持 `all`、`claude`、`gemini`、`codex`；模式支持 `standby`、`global`。用于安装时，省略模式按 `standby` 处理；用于更新、清理、卸载和切换分支时，省略模式会原样下传，让 HelloAGENTS 先复用该 CLI 已记录或检测到的模式。
+当你不想依赖更新过程中的 `helloagents` 可执行文件时，用 npm 或一键脚本。`HELLOAGENTS=目标[:模式]` 中，目标支持 `all`、`claude`、`gemini`、`codex`；模式支持 `standby`、`global`。用于安装时，省略模式按 `standby` 处理；用于更新、清理、卸载和切换分支时，省略模式会原样下传，让 HelloAGENTS 先复用该 CLI 已记录或检测到的模式。如果未提供 `HELLOAGENTS`，一键安装脚本现在会保持“只装包/只升级包”的默认语义，不会自动部署任何宿主 CLI。若要安装自定义 tarball 或包规格，用 `HELLOAGENTS_PACKAGE`，不要写 `HELLOAGENTS_BRANCH`。对于已经装好的包，如需确保宿主一定刷新，优先在包命令后显式执行一次 `npm explore -g helloagents -- npm run sync-hosts -- ...`。
 
 宿主配置使用稳定的 `helloagents-js` 入口和运行根目录 `~/.helloagents/helloagents`，Node 全局包路径变化不会破坏受管 hooks 或 Codex `notify`。Codex hooks 使用独立 `~/.codex/hooks.json`，不把大段配置写入 `config.toml`；Codex 全局插件根目录和插件缓存也会回链到这个稳定运行根目录。
 
@@ -328,11 +324,13 @@ HELLOAGENTS=codex npm install -g helloagents
 # 安装到 Codex，全局模式
 HELLOAGENTS=codex:global npm install -g helloagents
 
-# 更新并同步 Claude，标准模式
-HELLOAGENTS=claude:standby npm update -g helloagents
+# 先更新包，再刷新 Claude，标准模式
+npm update -g helloagents
+npm explore -g helloagents -- npm run sync-hosts -- claude --standby
 
-# 切换到 beta 分支并同步全部 CLI，标准模式
-HELLOAGENTS=all:standby npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
+# 先切到 beta 分支，再刷新全部 CLI，标准模式
+npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
+npm explore -g helloagents -- npm run sync-hosts -- --all --standby
 
 # 卸载包前清理 Gemini 集成
 npm explore -g helloagents -- npm run uninstall -- gemini --standby
@@ -348,11 +346,13 @@ $env:HELLOAGENTS="codex"; npm install -g helloagents
 # 安装到 Codex，全局模式
 $env:HELLOAGENTS="codex:global"; npm install -g helloagents
 
-# 更新并同步 Claude，标准模式
-$env:HELLOAGENTS="claude:standby"; npm update -g helloagents
+# 先更新包，再刷新 Claude，标准模式
+npm update -g helloagents
+npm explore -g helloagents -- npm run sync-hosts -- claude --standby
 
-# 切换到 beta 分支并同步全部 CLI，标准模式
-$env:HELLOAGENTS="all:standby"; npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
+# 先切到 beta 分支，再刷新全部 CLI，标准模式
+npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
+npm explore -g helloagents -- npm run sync-hosts -- --all --standby
 
 # 卸载包前清理 Gemini 集成
 npm explore -g helloagents -- npm run uninstall -- gemini --standby
@@ -365,9 +365,11 @@ npm uninstall -g helloagents
 npm explore -g helloagents -- npm run deploy:global
 npm explore -g helloagents -- npm run sync-hosts -- --all --standby
 npm explore -g helloagents -- npm run cleanup-hosts -- codex --standby
-npm explore -g helloagents -- npm run uninstall -- --all --standby
+npm explore -g helloagents -- npm run uninstall -- --all
 ```
 
+首次安装仍然可以直接用 `HELLOAGENTS=目标[:模式]`。但对于更新、切换分支或强制重同步已安装包，以上显式 `npm run sync-hosts` 路径更确定。
+
 #### 一键脚本
 
 macOS / Linux：
@@ -408,7 +410,7 @@ $env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https:/
 $env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
 ```
 
-PowerShell 包装脚本现在会传递与 `install.sh` 相同的 npm 参数，因此安装、更新、清理、卸载和 `switch-branch` 走的是同一条生命周期链路。
+Shell 和 PowerShell 一键脚本现在都会先解析一次 `HELLOAGENTS`；未指定目标时保持普通包安装/升级语义；在更新、切分支和卸载前清掉生命周期环境变量，然后只走一条显式同步或清理链路。
 
 ### 分支切换
 
@@ -425,7 +427,7 @@ helloagents branch beta --all --standby
 ```bash
 npm install -g https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
 npm update -g helloagents
-npm explore -g helloagents -- npm run uninstall -- --all --standby
+npm explore -g helloagents -- npm run uninstall -- --all
 npm uninstall -g helloagents
 ```
 
@@ -445,16 +447,18 @@ npm uninstall -g helloagents
 | Gemini CLI | 原生扩展安装 | 由 Gemini 扩展系统管理 |
 | Codex CLI | 原生本地插件流程 | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/ -> ~/.helloagents/helloagents`、`~/.codex/plugins/cache/local-plugins/helloagents/local/ -> ~/.helloagents/helloagents`、`~/.codex/config.toml`、`~/.codex/hooks.json`、`~/.codex/helloagents -> ~/.helloagents/helloagents` |
 
-全局模式下，HelloAGENTS 会自动尝试宿主原生命令。若宿主命令不可用，再手动执行：
+全局模式下，HelloAGENTS 会自动尝试宿主原生命令。对 Claude Code，marketplace 应使用 Git URL 添加，这样插件安装阶段会继续走 HTTPS，不会落回 SSH-only clone。若宿主命令不可用，再手动执行：
 
 ```text
-/plugin marketplace add hellowind777/helloagents
+/plugin marketplace add https://github.com/hellowind777/helloagents.git
 /plugin install helloagents@helloagents
-gemini extensions install https://github.com/hellowind777/helloagents
+helloagents install gemini --global
 ```
 
 Claude Code 会自动尝试等价的 `claude plugin marketplace add ...` 和 `claude plugin install ...` 命令。marketplace 名称和插件名称都是 `helloagents`，所以安装目标是 `helloagents@helloagents`。全局安装后需要重启宿主 CLI。
 
+当你把 Claude 或 Gemini 从全局模式切回标准模式时，HelloAGENTS 会先移除原生插件或扩展。如果这一步失败，会继续把该宿主记录为 `global`，而不是静默叠加 standby。
+
 Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 
 ## 对话命令
@@ -468,17 +472,16 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 | 先审查方案再实现 | `~plan "refactor payment module"` |
 | 按明确请求或活跃方案实现 | `~build "finish task 2 in the plan"` |
 | 生成完整产品需求文档 | `~prd "modern dashboard for operations team"` |
-| 按指标迭代优化 | `~loop "reduce bundle size" --metric "npm run size" --direction lower` |
-| 只创建或刷新项目知识 | `~wiki` / `~init` |
-| 初始化项目级全局模式 | `~global` |
-| 验证当前工作 | `~verify` |
+| 用 `/goal -> ~auto -> ~qa` 跑一个长程 Codex 任务 | `~loop "finish the auth refactor"` |
+| 初始化或刷新项目工作流 | `~init` |
+| 验证当前工作 | `~qa` |
 | 生成提交信息并同步知识库 | `~commit` |
 
-### 知识库与项目级全局模式
+### 项目初始化与宿主全局部署
 
-标准模式下，未初始化的项目只获得轻量规则和显式 `~command` 入口。执行 `~global` 后，项目级规则文件会写入 `<!-- HELLOAGENTS_PROFILE: full -->`，项目才进入项目级全局模式。
+标准模式下，未初始化的项目只获得轻量规则和显式 `~command` 入口。执行 `~init` 后，项目级规则文件会写入 `<!-- HELLOAGENTS_PROFILE: full -->`，项目才进入已初始化状态。
 
-全局模式下，HelloAGENTS 默认启用完整规则。
+全局模式下，HelloAGENTS 会在宿主层默认启用完整规则。
 
 ## 项目知识库
 
@@ -507,11 +510,8 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 运行态文件仍保留在当前项目本地：
 
 - `state_path`
-- `.helloagents/sessions/<workspace>/<session>/capsule.json`
-- `.helloagents/sessions/<workspace>/<session>/events.jsonl`
 - `.helloagents/sessions/active.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/*.json`
-- `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
 
 ### 项目本地存储之外的临时会话
 
@@ -521,7 +521,7 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 ~/.helloagents/runtime/<scope-key>/
 ```
 
-这里仅保存短期的 `capsule.json`、`events.jsonl` 和 `artifacts/`，不作为项目知识库。过期临时会话会按 TTL 清理。
+这里仅保存短期的 `STATE.md` 和 `artifacts/`。`events.jsonl` 只有在启用 trace 时才会写入，不作为默认运行态文件。它也不属于项目知识库。过期临时会话会按 TTL 清理。
 
 一旦任务会创建或修改本地文件，或会在当前项目留下本地输出，HelloAGENTS 就会自动创建项目本地 `.helloagents/sessions/.../STATE.md`，而不是只停留在用户级临时运行态。
 
@@ -529,11 +529,10 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 
 | 命令或配置 | 行为 |
 |------------|------|
-| `~wiki` / `~init` | 只创建或同步知识库 |
-| `~global` | 创建知识库，同时写入项目级全局模式标记和包根链接 |
+| `~init` | 初始化项目工作流并同步知识库 |
 | `kb_create_mode = 0` | 关闭自动知识更新 |
 | `kb_create_mode = 1` | 仅在知识库已存在时自动同步 |
-| `kb_create_mode = 2` | 编码任务在知识库已存在或全局模式下自动创建或同步 |
+| `kb_create_mode = 2` | 编码任务在知识库已存在或当前项目已初始化时自动创建或同步 |
 
 ## 工作流与交付
 
@@ -542,7 +541,7 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 结构化任务使用以下阶段：
 
 ```text
-ROUTE / TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
+ROUTE / TIER → SPEC → PLAN → BUILD → QA → CONSOLIDATE
 ```
 
 | 阶段 | 用途 |
@@ -551,7 +550,7 @@ ROUTE / TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
 | `SPEC` | 明确目标、约束和完成标准 |
 | `PLAN` | 准备方案文件并选择需要的技能 |
 | `BUILD` | 实现并做局部检查 |
-| `VERIFY` | 审查、运行命令、核对契约和证据 |
+| `QA` | 审查、运行命令、核对契约和证据 |
 | `CONSOLIDATE` | 更新状态、知识库和收尾证据 |
 
 ### 任务分层
@@ -619,7 +618,7 @@ UI 任务遵循以下优先级：
 | `output_language` | `""` | 默认跟随用户语言 |
 | `output_format` | `true` | 仅主代理直接面向最终用户的终局交付使用 HelloAGENTS 格式；中间输出、委派结果和子代理输出保持自然 |
 | `notify_level` | `0` | `0` 关闭，`1` 桌面通知，`2` 声音，`3` 两者 |
-| `ralph_loop_enabled` | `true` | 显式 `~verify` / `~loop` 或收尾要求时运行验证 |
+| `ralph_loop_enabled` | `true` | 显式 `~qa` / `~loop` 或收尾要求时运行 QA stop gate |
 | `guard_enabled` | `true` | 拦截危险命令 |
 | `kb_create_mode` | `1` | `0` 关闭，`1` 自动同步已有知识库，`2` 编码任务自动创建或同步知识库 |
 | `project_store_mode` | `"local"` | `local` 或 `repo-shared` |
@@ -638,6 +637,7 @@ UI 任务遵循以下优先级：
 - 标准模式在 `~/.claude/settings.json` 中写入受管 hooks 和权限
 - 标准模式创建 `~/.claude/helloagents -> ~/.helloagents/helloagents`
 - 全局模式使用 Claude Code 插件系统
+- 从全局模式切回标准模式前会先移除原生插件；如果失败，HelloAGENTS 会继续把 Claude 记录为 `global`
 
 ### Gemini CLI
 
@@ -645,6 +645,7 @@ UI 任务遵循以下优先级：
 - 标准模式在 `~/.gemini/settings.json` 中写入受管 hooks
 - 标准模式创建 `~/.gemini/helloagents -> ~/.helloagents/helloagents`
 - 全局模式使用 Gemini 扩展系统
+- 从全局模式切回标准模式前会先移除原生扩展；如果失败，HelloAGENTS 会继续把 Gemini 记录为 `global`
 
 ### Codex CLI
 
@@ -659,10 +660,12 @@ Codex 默认走规则文件驱动。
 - 这些 hook trust 状态是基于当前机器 `~/.codex/hooks.json` 真实绝对路径生成的本机状态；它不同于 `model_instructions_file = "~/.codex/AGENTS.md"` 这类可移植配置，应在每台机器上重新生成
 - 标准模式创建 `~/.codex/helloagents -> ~/.helloagents/helloagents`
 - 全局模式安装原生本地插件流程，但仍把 `~/.helloagents/helloagents` 作为唯一受管运行时源；插件根目录、插件缓存和 `~/.codex/helloagents` 都会回链到它
+- 如果你主要看重 Codex app / 插件发现链路，优先使用 `global`；如果你主要看重更轻量、更显式的项目工作流，保留 `standby`
 - 清理时只删除 HelloAGENTS 自己写入的 hook trust 条目和旧式受管 notify 残留，不影响用户已有的 hook 状态
 - Codex hooks 只做静默运行态同步和 Stop 门禁，不通过 hook 注入 HelloAGENTS 规则或路由说明
 - Codex 收尾会对 Stop hook 和原生 `codex-notify` 去重，避免同一轮重复通知；受管 Stop hook 生效时，client 为空的委派子任务完成事件也会保持静默
 - `/goal` 保持 Codex 原生能力；需要长程执行时，用 `helloagents codex goals enable` 显式启用
+- 按当前 OpenAI 文档，`/goal` 仍属于实验特性，Codex app 支持也仍在预览阶段。因此 HelloAGENTS 把它当作可选的 Codex 原生加速能力，而不是必需运行时依赖
 - 感知 goal 的命令从 `tasks.md`、`contract.json` 和 `state_path` 恢复；不会自动创建 goal，也不会在 HelloAGENTS 验证和收尾前标记完成
 
 ## 验证
@@ -676,8 +679,8 @@ npm test
 当前测试覆盖：
 
 - 安装、更新、清理、卸载、分支切换和模式切换
-- shell 与 PowerShell 一键脚本分发链路，以及包装脚本在安装、更新、清理、卸载和分支切换中的模式传递规则
-- Claude、Gemini、Codex 的宿主集成行为
+- shell 与 PowerShell 一键脚本分发链路，以及包装脚本在安装、更新、清理、卸载和分支切换中的环境清理与模式传递规则
+- Claude、Gemini、Codex 的宿主集成行为，包括全局切回标准模式的清理和原生清理失败时的模式保留
 - Codex 受管 `model_instructions_file`、`notify`、`hooks.json`、hook trust 状态、本地插件、marketplace 和缓存行为
 - Windows 下 Codex 旧式受管 notify 变体的清理，以及受管 notify 恢复规则
 - Codex `/goal` 功能开关、长程路由上下文和 goal 感知命令契约
@@ -702,17 +705,18 @@ npm test
 - `skills/` 定义任务类型相关行为
 - `scripts/` 提供选路、Guard、通知、验证、状态和证据等运行时辅助能力
 
-### 应该用 `~wiki`、`~init` 还是 `~global`？
+### 应该用 `~init` 还是 `--global`？
 
-只想创建项目知识库，用 `~wiki` 或 `~init`。
+在仓库里初始化当前项目工作流并同步项目知识，用 `~init`。
 
-还想初始化项目级全局模式，用 `~global`。
+想在宿主层对支持的 CLI 做全局部署，用 `helloagents --global`。
 
 ### standby 和 global 有什么区别？
 
-`standby` 更轻量、更显式。它只把规则部署到指定 CLI，项目级全局模式由 `~global` 触发。
+`standby` 更轻量、更显式。它只把规则部署到指定 CLI，项目是否进入完整工作流由 `~init` 决定。
 
-`global` 默认更广泛地启用完整规则。Claude 和 Gemini 使用原生插件 / 扩展；Codex 使用本地插件路径。
+`global` 会在宿主层更广泛地启用完整规则。Claude 和 Gemini 使用原生插件 / 扩展；Codex 使用本地插件路径。
+如果你主要看重 Codex app / 插件发现链路，用 `global`。如果你主要看重更轻量、更显式的项目工作流，继续用 `standby`。
 
 ### Codex hooks 会显示注入内容吗？
 
@@ -727,7 +731,7 @@ npm test
 
 ### `npm uninstall -g helloagents` 会删除项目知识库吗？
 
-不会。卸载包前运行 `npm explore -g helloagents -- npm run uninstall -- --all --standby`，会清理宿主集成和稳定运行副本。项目 `.helloagents/` 文件和 `~/.helloagents/helloagents.json` 会保留，除非你手动删除。
+不会。卸载包前运行 `npm explore -g helloagents -- npm run uninstall -- --all`，HelloAGENTS 会按各 CLI 已记录或检测到的模式清理宿主集成和稳定运行副本。项目 `.helloagents/` 文件和 `~/.helloagents/helloagents.json` 会保留，除非你手动删除。
 
 ## 故障排除
 

package/bootstrap-lite.md

@@ -193,9 +193,9 @@
 ## 工作流与完成判定
 ### 任务分层（Delivery Tier）
 - `T0` — 只读分析、创意探索、方案比较 → 自然响应或 `~idea`
-- `T1` — 低风险小改动、明确实现、显式验证、单文件或局部改动 → 直接执行或 `~build` / `~verify`
+- `T1` — 低风险小改动、明确实现、显式质量闭环、单文件或局部改动 → 直接执行或 `~build` / `~qa`
 - `T2` — 新项目、从零构建、3+ 文件新功能、架构级变更或需要结构化产物 → `~plan` 或 `~auto`
-- `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
+- `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~qa`
 
 ### 完成判定
 - 当前项目未初始化，且未进入方案包 / `contract.json` / 证据文件时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
@@ -205,7 +205,7 @@
 - 本地版本检查点：非只读任务完成验证且产生工作区变更时，若 `auto_commit_enabled=true`，最终回复前自动执行本地提交；若 `auto_commit_enabled=false`，跳过这一步。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。显式 `~commit` 不受这个开关影响。不自动远程 `git push`，除非用户明确要求
 
 ### 命令路由
-- `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~verify` 的兼容别名
+- `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~qa` 的兼容别名
 - `~test` — 为指定模块或最近变更编写测试
 - 路径定义：`{HELLOAGENTS_READ_ROOT}` = 当前对话已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
 - `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。若当前上下文已解析出具体命令技能文件路径，直接使用它；否则先确定当前技能根目录：
@@ -221,7 +221,7 @@
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 - `.helloagents/` 表示项目本地存储路径，负责知识、方案、状态与运行态；它不再作为项目是否已初始化的判定信号
-- `state_path` 指向的状态文件、当前会话 `capsule.json`、`events.jsonl`、`artifacts/*.json`、`artifacts/loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/`
+- `state_path` 指向的状态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/STATE.md`；当前会话的 `turn-state`、路由上下文和 artifact 索引写入这个文件的元数据，`artifacts/*.json` 仅在需要结构化证据时按需生成，`events.jsonl` 仅在显式 trace 模式下写入
 - `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{workspace}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{workspace}/default/STATE.md`
 - `{workspace}` 为当前 Git 分支、`detached-{sha}` 或非 Git 项目的 `workspace`；`.helloagents/sessions/active.json` 只记录当前活跃会话索引，避免同一会话被拆成多个目录
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
@@ -232,9 +232,9 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本会
 - 状态文件（`state_path`）— ≤70 行，用来记录“上次做到哪里”。判断当前任务时，当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于状态文件
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
-  - 强制创建并持续更新：`~wiki`、`~init`、`~global`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及任何会创建/修改本地文件、会在当前工作区留下实际输出或操作记录的非只读任务
+  - 强制创建并持续更新：`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及任何会创建/修改本地文件、会在当前工作区留下实际输出或操作记录的非只读任务
   - 强制更新，不要求首次创建：`~clean`，主代理汇总子代理结果后
-  - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
+  - 已有则更新：`~qa`、`~test`、`~commit`
   - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
   更新规则：
   - 属于“强制创建并持续更新”范围且状态文件不存在时，按 templates/STATE.md 创建
@@ -253,7 +253,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本会
 - archive/_index.md — 归档索引
 
 ### 知识记录（受 `kb_create_mode` 控制）
-- 0=关闭；1=知识库已存在时自动同步；2=编码任务在知识库已存在或全局模式下自动创建或同步
+- 0=关闭；1=知识库已存在时自动同步；2=编码任务在知识库已存在或当前项目已初始化时自动创建或同步
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -261,10 +261,8 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本会
 - modules/*.md — 模块文档和经验
 
 ### 临时文件（`~clean` 时清理）
-- artifacts/loop-results.tsv — 当前会话的 ~loop 迭代记录
-- artifacts/loop-breaker.json — 当前会话的 hello-verify 断路器状态，仅在 `~loop` 或自动验证触发时写入
-- artifacts/verify.json — 当前会话最近一次成功验证的证据快照
-- artifacts/review.json — 当前会话最近一次成功审查的证据快照
+- artifacts/loop-breaker.json — 当前会话的 QA gate 断路器状态，仅在收尾 QA gate 连续失败时写入
+- artifacts/qa-review.json — 当前会话最近一次成功 qa-review 的证据快照
 - artifacts/closeout.json — 当前会话最近一次成功收尾的交付证据快照
 
 ### 主线判断依据

package/bootstrap.md

@@ -193,9 +193,9 @@
 ## 工作流与完成判定
 ### 任务分层（Delivery Tier）
 - `T0` — 只读分析、创意探索、方案比较 → 自然响应或 `~idea`
-- `T1` — 低风险小改动、明确实现、显式验证、单文件或局部改动 → 直接执行或 `~build` / `~verify`
+- `T1` — 低风险小改动、明确实现、显式质量闭环、单文件或局部改动 → 直接执行或 `~build` / `~qa`
 - `T2` — 新项目、从零构建、3+ 文件新功能、架构级变更或需要结构化产物 → `~plan` 或 `~auto`
-- `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
+- `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~qa`
 
 ### 统一执行流程
 
@@ -206,10 +206,10 @@
 - 为指定模块编写测试 → `~test`
 - 结构化规划 / 新功能 / 新项目 → `~plan`
 - 完整产品规格 → `~prd`
-- 审查 / 执行验证 → `~verify`
+- 审查 / 验真 / 交付前质量闭环 → `~qa`
 - 不确定或希望端到端自动推进时使用 `~auto`
 
-当前项目只要已初始化（例如执行过 `~global`，或当前项目级规则文件已包含 `<!-- HELLOAGENTS_PROFILE: full -->`），就按项目级完整流程执行。
+当前项目只要已初始化（当前项目级规则文件已包含 `<!-- HELLOAGENTS_PROFILE: full -->`，通常由 `~init` 建立），就按项目级完整流程执行。
 
 #### 2. SPEC — 澄清目标与验收
 根据任务需要，按需读取项目上下文（知识库文件和项目文件），明确：
@@ -227,7 +227,7 @@
 - 若当前上下文未注入，则使用稳定运行根目录 `~/.helloagents/helloagents`
 - 宿主固定链接（Codex `~/.codex/helloagents`、Claude `~/.claude/helloagents`、Gemini `~/.gemini/helloagents`）只作为兼容别名，不作为优先探测路径
 - 仍无法确定时，明确说明缺少 HelloAGENTS 读取根目录；不要递归扫描 `$HOME`、`Downloads`、项目目录或旧版本目录
-- 全局模式或已初始化项目时，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
+- 宿主全局模式或已初始化项目时，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
 路径确定一次即可，不预读、不扫描整个目录，也不重复探测同一路径。
 hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.md`
 包内脚本优先使用稳定命令入口；涉及 turn-state 时按“收尾状态信号”执行。
@@ -236,7 +236,7 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 - `~plan` 生成 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`
 - `~prd` 生成 PRD 维度文档、`tasks.md`、`decisions.md`
 - `~build` 读取现有方案包并做定位，不重复发明方案
-- `contract.json` 是方案包的机器契约，至少明确 `verifyMode`、`reviewerFocus`、`testerFocus`；只有在 T3 / UI / 高风险流程确有收益时，才额外声明 `advisor`；进入验证或最终交付前，优先消费它而不是从自然语言描述里回推验证路径
+- `contract.json` 是方案包的机器契约，至少明确 `qaMode`、`qaFocus`；只有在 T3 / UI / 高风险流程确有收益时，才额外声明 `advisor`；进入质量闭环或最终交付前，优先消费它而不是从自然语言描述里回推执行路径
 - 涉及 UI 时，设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） → 已读取的 `hello-ui` 规则；同时所有 UI 任务都必须满足 UI 质量基线
 - `~idea` 在输出比较与推荐后结束，不进入实现，也不创建 `.helloagents/`、状态文件或方案包
 
@@ -251,10 +251,10 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 
 遇到符合“阻塞判定”且无法自行解除的问题（依赖缺失、关键指令不清、验证反复失败等）时才停下；能继续定位或修复时继续推进。
 
-#### 5. VERIFY — 审查与验证
+#### 5. QA — 质量闭环
 编码任务：
-- 读取 `skills/hello-verify/SKILL.md`，执行完整验证循环 → 失败则修复 → 循环直到通过
-- 审查优先或显式使用 `~review` 时，先读取 `skills/hello-review/SKILL.md` 做范围审查；审查完成后调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`，再进入验证
+- 读取 `skills/qa-review/SKILL.md`，执行完整质量闭环 → 失败则修复 → 循环直到通过
+- 完成质量闭环后调用 `scripts/qa-review-state.mjs write` 写当前会话 `artifacts/qa-review.json`
 - 通过后收集已读取技能的交付检查清单，逐项附带证据确认，并确认用户目标已达成
 
 非编码任务（文档 / 方案 / 审查等）：
@@ -264,25 +264,25 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 所有任务：
 - 有方案包且准备报告完成 → 优先调用 `scripts/closeout-state.mjs write` 写当前会话 `artifacts/closeout.json`，记录“需求覆盖”和“交付清单”；每项写明 `PASS` / `BLOCKED` 与简要摘要，再进入最终交付
 - 状态文件维护：按上文“流程状态”中的适用范围执行。属于“强制创建并持续更新”范围时，重写 `state_path` 指向的文件（“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
-- 有方案包且任务已完成 → 将整个 `plans/{feature}/` 目录归档到 `.helloagents/archive/YYYY-MM/`，并更新 `archive/_index.md`。清理当前会话临时文件（`artifacts/loop-results.tsv`、`capsule.json`、`events.jsonl`、`artifacts/loop-breaker.json`、`artifacts/verify.json`、`artifacts/review.json`、`artifacts/closeout.json`）
-- 按 `kb_create_mode` 同步知识库（0=关闭 / 1=知识库已存在时自动同步，未创建则不自动补建 / 2=编码任务在知识库已存在或全局模式下自动创建或同步）：
+- 有方案包且任务已完成 → 将整个 `plans/{feature}/` 目录归档到 `.helloagents/archive/YYYY-MM/`，并更新 `archive/_index.md`。清理当前会话临时文件（可选 `events.jsonl`、`artifacts/loop-breaker.json`、`artifacts/qa-review.json`、`artifacts/closeout.json`）；`STATE.md` 作为唯一主状态保留
+- 按 `kb_create_mode` 同步知识库（0=关闭 / 1=知识库已存在时自动同步，未创建则不自动补建 / 2=编码任务在知识库已存在或当前项目已初始化时自动创建或同步）：
   - `0` → 跳过
   - `1` → 仅在知识库已存在时按模板增量同步；未创建则不自动补建
-  - `2` → 仅在编码任务中生效；知识库已存在时按模板增量同步；若知识库不存在但当前项目已处于全局模式，则按 templates/ 创建或补全 `context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`modules/`
+  - `2` → 仅在编码任务中生效；知识库已存在时按模板增量同步；若知识库不存在但当前项目已初始化，则按 templates/ 创建或补全 `context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`modules/`
   - 已存在但不完整（缺少上述核心文件）→ 按 templates/ 补全缺失文件，不覆盖已有文件
   - 已存在且完整则按模板格式更新 `CHANGELOG.md`、相关 `modules/*.md`、增量经验 delta 追加
 - 符合条件时触发 `hello-reflect`（详见 `hello-reflect` SKILL.md）
 - 本地版本检查点：非只读任务完成验证且产生工作区变更时，若 `auto_commit_enabled=true`，最终回复前自动执行本地提交；若 `auto_commit_enabled=false`，跳过这一步。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。显式 `~commit` 不受这个开关影响。不自动远程 `git push`，除非用户明确要求
 
 ### 完成判定
-- 未进入 VERIFY / CONSOLIDATE 的路径，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
-- 已激活 `hello-*` 技能或存在方案包 / `contract.json` / 证据文件时，以对应 skill、方案包契约与 VERIFY / CONSOLIDATE 为准，不得降级为本节
+- 未进入 QA / CONSOLIDATE 的路径，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
+- 已激活 `hello-*` 技能或存在方案包 / `contract.json` / 证据文件时，以对应 skill、方案包契约与 QA / CONSOLIDATE 为准，不得降级为本节
 - 只读分析、创意探索、方案比较、中间进度和阻塞汇报不适用本节
 - Codex `/goal` 只作为外层长程续跑与预算控制；HelloAGENTS 仍负责方案、执行、验证和收尾。若 active goal 的目标已全部完成，先完成 HelloAGENTS 验证、收尾检查与本地版本检查点，再调用 `update_goal` 标记 complete；不得因预算接近耗尽、单轮结束或准备停下而标记 complete
 
 ### 命令路由
 - 默认按上文“统一执行流程中的 ROUTE / TIER”选路；除显式 `~command` 外，不另起独立路由规则
-- `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~verify` 的兼容别名
+- `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~qa` 的兼容别名
 - `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。若当前上下文已解析出具体命令技能文件路径，直接使用它；否则按上文相同的技能根目录规则确定，确定根目录后读取其中的 `skills/commands/{name}/SKILL.md`。不要额外探测项目目录里的 HelloAGENTS skills 路径，也不要扫描整个目录或对同一命令重复探测多个路径。
 
 ## 项目存储与上下文
@@ -290,7 +290,7 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 - `.helloagents/` 表示项目本地存储路径，负责知识、方案、状态与运行态；它不再作为项目是否已初始化的判定信号
-- `state_path` 指向的状态文件、当前会话 `capsule.json`、`events.jsonl`、`artifacts/*.json`、`artifacts/loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/`
+- `state_path` 指向的状态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/STATE.md`；当前会话的 `turn-state`、路由上下文和 artifact 索引写入这个文件的元数据，`artifacts/*.json` 仅在需要结构化证据时按需生成，`events.jsonl` 仅在显式 trace 模式下写入
 - `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{workspace}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{workspace}/default/STATE.md`
 - `{workspace}` 为当前 Git 分支、`detached-{sha}` 或非 Git 项目的 `workspace`；`.helloagents/sessions/active.json` 只记录当前活跃会话索引，避免同一会话被拆成多个目录
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
@@ -301,9 +301,9 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本会
 - 状态文件（`state_path`）— ≤70 行，用来记录“上次做到哪里”。判断当前任务时，当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于状态文件
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
-  - 强制创建并持续更新：`~wiki`、`~init`、`~global`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入工作流阶段、已初始化项目的连续任务，或任何会创建/修改本地文件、会在当前工作区留下实际输出或操作记录的非只读任务
+  - 强制创建并持续更新：`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入工作流阶段、已初始化项目的连续任务，或任何会创建/修改本地文件、会在当前工作区留下实际输出或操作记录的非只读任务
   - 强制更新，不要求首次创建：`~clean`，主代理汇总子代理结果后
-  - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
+  - 已有则更新：`~qa`、`~test`、`~commit`
   - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
   更新规则：
   - 属于“强制创建并持续更新”范围且状态文件不存在时，按 templates/STATE.md 创建
@@ -322,7 +322,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本会
 - archive/_index.md — 归档索引
 
 ### 知识记录（受 `kb_create_mode` 控制）
-- 0=关闭；1=知识库已存在时自动同步；2=编码任务在知识库已存在或全局模式下自动创建或同步
+- 0=关闭；1=知识库已存在时自动同步；2=编码任务在知识库已存在或当前项目已初始化时自动创建或同步
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -330,10 +330,8 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本会
 - modules/*.md — 模块文档和经验
 
 ### 临时文件（`~clean` 时清理）
-- artifacts/loop-results.tsv — 当前会话的 ~loop 迭代记录
-- artifacts/loop-breaker.json — 当前会话的 hello-verify 断路器状态，仅在 `~loop` 或自动验证触发时写入
-- artifacts/verify.json — 当前会话最近一次成功验证的证据快照
-- artifacts/review.json — 当前会话最近一次成功审查的证据快照
+- artifacts/loop-breaker.json — 当前会话的 QA gate 断路器状态，仅在收尾 QA gate 连续失败时写入
+- artifacts/qa-review.json — 当前会话最近一次成功 qa-review 的证据快照
 - artifacts/closeout.json — 当前会话最近一次成功收尾的交付证据快照
 
 ### 主线判断依据