helloagents 3.0.8-beta.1 → 3.0.10-beta.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "helloagents",
       "description": "Quality-driven orchestration kernel for AI CLIs: intelligent routing, quality verification, safety guards, and notifications",
-      "version": "3.0.8-beta.1",
+      "version": "3.0.10-beta.1",
       "source": "./",
       "author": {
         "name": "HelloWind",

package/.claude-plugin/plugin.json

@@ -1,8 +1,11 @@
 {
   "name": "helloagents",
-  "version": "3.0.8-beta.1",
+  "version": "3.0.10-beta.1",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
-  "author": "HelloWind",
+  "author": {
+    "name": "HelloWind",
+    "email": "hellowind777@gmail.com"
+  },
   "license": "Apache-2.0",
   "keywords": [
     "orchestration",
@@ -12,10 +15,7 @@
     "notification",
     "safety"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hellowind777/helloagents.git"
-  },
+  "repository": "https://github.com/hellowind777/helloagents",
   "skills": "./skills",
   "hooks": "./hooks/hooks-claude.json"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.8-beta.1",
+  "version": "3.0.10-beta.1",
   "description": "HelloAGENTS — Quality-driven orchestration kernel for AI CLIs with intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/README.md

@@ -8,7 +8,7 @@
 
 **Quality-driven workflow framework for AI coding CLIs — 14 auto-activated skills, process discipline, and checklist-based quality checks.**
 
-[![Version](https://img.shields.io/badge/version-3.0.8-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.10-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,7 +95,7 @@ HelloAGENTS fixes that. It's a workflow layer that sits on top of your AI CLI an
 
 If the last version you used seriously was `v2.3.8`, this is not a minor update. The current line is a full product-line reset.
 
-| Dimension | v2.3.8 | Local `v3.0.8` |
+| Dimension | v2.3.8 | Local `v3.0.10` |
 |-----------|--------|----------------|
 | **Implementation base** | Python package plus mixed scripts/rules | Pure Node.js + Markdown runtime built around `cli.mjs`, `bootstrap*.md`, `skills/`, and `scripts/` |
 | **Product shape** | More like a multi-CLI management tool plus prompt protocol bundle | More like a quality workflow framework for AI CLIs, centered on routing, checks, verification, and resumable execution |
@@ -108,7 +108,7 @@ If the last version you used seriously was `v2.3.8`, this is not a minor update.
 | **KB storage** | Project-local only | Project-local by default, plus `project_store_mode=repo-shared` for sharing stable KB/plan assets across git worktrees |
 | **Codex integration** | Earlier compatibility layers and legacy paths | Standby = injected rules + local links; global = native local-plugin chain with less noise and drift |
 
-In one sentence: `v2.3.8` was closer to "workflow glue for multiple CLIs"; `v3.0.8` is a workflow framework that unifies quality rules, plan files, verification records, and installation lifecycle into one operating model.
+In one sentence: `v2.3.8` was closer to "workflow glue for multiple CLIs"; `v3.0.10` is a workflow framework that unifies quality rules, plan files, verification records, and installation lifecycle into one operating model.
 
 ## ✨ Core Features
 
@@ -304,12 +304,12 @@ HelloAGENTS touches different files depending on mode. The write/cleanup rules a
 |-----|------------------------|----------------|
 | Claude Code | Native plugin install (manual CLI command) | Managed by Claude's plugin system |
 | Gemini CLI | Native extension install (manual CLI command) | Managed by Gemini's extension system |
-| Codex CLI | Native local-plugin chain (automatic) | `~/.agents/plugins/marketplace.json`, `~/plugins/helloagents/`, `~/.codex/plugins/cache/local-plugins/helloagents/local/`, `~/.codex/config.toml` |
+| Codex CLI | Native local-plugin chain (automatic) | `~/.agents/plugins/marketplace.json`, `~/plugins/helloagents/`, `~/.codex/plugins/cache/local-plugins/helloagents/local/`, `~/.codex/config.toml`, `~/.codex/helloagents -> ~/plugins/helloagents` |
 
 ### Update / reinstall / branch-switch behavior
 
 - **Standby mode** keeps scripts, skills, templates, and hooks on `~/.claude/helloagents`, `~/.gemini/helloagents`, and `~/.codex/helloagents` symlinks, so linked package files reflect local changes immediately. The injected rules files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`) are still snapshots and must be refreshed after bootstrap or branch changes.
-- **Codex global mode** uses copied runtime files. Re-running `helloagents --global` refreshes both `~/plugins/helloagents/` and the Codex cache copy.
+- **Codex global mode** uses copied runtime files and keeps `~/.codex/helloagents -> ~/plugins/helloagents` as the stable read-root fallback expected by bootstrap routing. Re-running `helloagents --global` refreshes both `~/plugins/helloagents/` and the Codex cache copy.
 - Re-running the current mode command is supported intentionally: `helloagents --standby` and `helloagents --global` both act as **switch-or-refresh** commands.
 - For deterministic manual cleanup, run `helloagents cleanup` before `npm uninstall -g helloagents`.
 - `npm uninstall -g helloagents` removes the package; `~/.helloagents/helloagents.json` is intentionally preserved.
@@ -499,9 +499,9 @@ After every task, Ralph Loop auto-runs your project's verification commands:
 
 `~wiki` creates or syncs the project knowledge base only. `~init` is the fuller bootstrap: it also writes project-level rule files (`AGENTS.md`, `CLAUDE.md`, `.gemini/GEMINI.md`), refreshes host-native project skill links, and appends the related ignore rules. In standby mode, the presence of the local `.helloagents/` is what promotes the current project into the full project workflow; project-level rule files are optional.
 
-By default, KB and plan files live in the project's local `.helloagents/`. If `project_store_mode = "repo-shared"`, the local `.helloagents/` directory keeps only the activation signal, `STATE.md`, and runtime files such as `.ralph-*`, while `context.md`, `guidelines.md`, `DESIGN.md`, `verify.yaml`, `modules/`, `plans/`, and `archive/` move to `~/.helloagents/projects/<repo-key>/` so multiple worktrees of the same git repo can share stable project memory.
+By default, KB and plan files live in the project's local `.helloagents/`. The state file uses the path provided by `state_path`. When the host exposes a stable conversation/session identifier, HelloAGENTS writes it to `.helloagents/sessions/<branch>/<session>/STATE.md`; otherwise it uses the branch default path at `.helloagents/sessions/<branch>/default/STATE.md`. If `project_store_mode = "repo-shared"`, the local `.helloagents/` directory keeps the activation signal, session-scoped `STATE.md`, and runtime files such as `.ralph-*`, while `context.md`, `guidelines.md`, `DESIGN.md`, `verify.yaml`, `modules/`, `plans/`, and `archive/` move to `~/.helloagents/projects/<repo-key>/` so multiple worktrees of the same git repo can share stable project memory.
 
-`STATE.md` is a project-level recovery snapshot, not a universal memory file for every interaction. It is created and continuously updated for long-running project workflows such as `~wiki`, `~init`, `~plan`, `~build`, `~auto`, `~prd`, and `~loop`; updated when already present for verification/review style tasks; and intentionally not created for one-off read-only interactions such as `~help`.
+`STATE.md` is the current state file resolved from `state_path`, not a universal memory file for every interaction. Its branch + session layout prevents concurrent conversations on the same repo from fighting over one shared file. It is created and continuously updated for long-running project workflows such as `~wiki`, `~init`, `~plan`, `~build`, `~auto`, `~prd`, and `~loop`; updated when already present for verification/review style tasks; and intentionally not created for one-off read-only interactions such as `~help`.
 
 | File | Purpose |
 |------|---------|
@@ -718,10 +718,19 @@ Subagents may skip workflow packaging such as routing, interaction flow, and out
 
 ## 📈 Version History
 
-### v3.0.8 (current)
+### v3.0.10 (current)
+
+**Fixes and verification since `v3.0.9beta`:**
+- 🔧 Codex managed `notify` entries now carry an explicit marker, so cleanup can distinguish HelloAGENTS config from user-owned `notify` commands that also use `codex-notify`
+- 🔧 Codex cleanup now preserves multiline user `notify` arrays and restores them without corrupting surrounding TOML sections
+- 🔧 `notify_level=0` now suppresses warning and confirmation notifications as well as completion notifications, keeping the documented "off" behavior consistent
+- 🔧 Restored `hello-ui` guidance after confirming OpenAI's public skill guidance recommends keeping `SKILL.md` under about 500 lines rather than enforcing a 200-line limit
+- 🧪 Added regressions for Codex `notify` preservation, multiline TOML handling, and notification-level gating
+
+### v3.0.9
 
 **Fixes and verification:**
-- 🔧 Claude Code / Gemini CLI `stop` delivery gating now prioritizes structured `turn-state` instead of inferring completion from natural-language text, so ordinary waiting turns no longer get misclassified as finished delivery
+- 🔧 Claude Code / Gemini CLI `stop` delivery gating now only accepts structured `turn-state` for completion, so ordinary waiting turns no longer get misclassified as finished delivery
 - 🔧 Codex cleanup now preserves user-owned post-install replacements for `model_instructions_file`, `notify`, and non-managed `codex_hooks` instead of restoring stale pre-install values over them
 - 🧪 Added lifecycle/runtime regressions for structured `stop` gating and Codex config preservation after post-install user edits
 

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **质量驱动的 AI 编码 CLI 工作流框架 — 14 个自动激活技能、流程纪律、检查清单把关。**
 
-[![Version](https://img.shields.io/badge/version-3.0.8-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.10-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)
@@ -36,7 +36,7 @@
 - [🆚 相比 v2.3.8 的变化](#-相比-v238-的变化)
 - [✨ 核心特性](#-核心特性)
 - [🚀 快速开始](#-快速开始)
-- [🔄 安装链路与文件写入](#-安装链路与文件写入)
+- [🔄 安装流程与文件写入](#-安装流程与文件写入)
 - [📖 命令](#-命令)
 - [🔧 配置](#-配置)
 - [⚙️ 工作原理](#️-工作原理)
@@ -95,7 +95,7 @@ HelloAGENTS 就是为了解决这个问题。它是一个编排层，装在你
 
 如果你上一次认真使用 HelloAGENTS 还是 `v2.3.8`，这一代的变化不是“增量补丁”，而是整条产品线重构。
 
-| 维度 | v2.3.8 | 本地 `v3.0.8` |
+| 维度 | v2.3.8 | 本地 `v3.0.10` |
 |------|--------|---------------|
 | **底层实现** | Python 包 + 大量脚本/规则混合 | 纯 Node.js + Markdown 运行时，围绕 `cli.mjs`、`bootstrap*.md`、`skills/`、`scripts/` 重建 |
 | **目标定位** | 更像多 CLI 管理工具 + 提示协议集合 | 更像 AI CLI 的质量工作流框架，重点是路由、把关、验证和可恢复执行 |
@@ -106,9 +106,9 @@ HelloAGENTS 就是为了解决这个问题。它是一个编排层，装在你
 | **质量模型** | 规则较分散，更多依赖自然语言约束 | 14 个自动激活技能 + 检查清单把关 + Ralph Loop + 结构化证据 |
 | **项目状态** | 知识库更多是附属能力 | `.helloagents/` 成为项目激活边界，`STATE.md` / 方案包 / `DESIGN.md` / `contract.json` 组成主流程的主要判断依据 |
 | **知识库存储** | 默认项目本地 | 默认项目本地，同时新增 `project_store_mode=repo-shared`，支持同一 git 仓库多个 worktree 共享稳定知识和方案资产 |
-| **Codex 集成** | 早期依赖更多兼容层和旧链路 | 标准模式使用注入规则 + 本地链接；全局模式使用原生本地插件链路，减少噪音与漂移 |
+| **Codex 集成** | 早期依赖更多兼容层和旧流程 | 标准模式使用注入规则 + 本地链接；全局模式使用原生本地插件，减少噪音与漂移 |
 
-一句话概括：`v2.3.8` 更像“给多个 CLI 加一层工作流外壳”，`v3.0.8` 更像“把质量协议、计划产物、验证证据和安装生命周期统一成一套真正可运转的工作流框架”。
+一句话概括：`v2.3.8` 更像“给多个 CLI 加一层工作流外壳”，`v3.0.10` 更像“把质量规则、计划产物、验证证据和安装生命周期统一成一套真正可运转的工作流框架”。
 
 ## ✨ 核心特性
 
@@ -217,7 +217,7 @@ helloagents install --all --standby
 |------|----------|------|
 | 先安装包，不立即改宿主 | `npm install -g helloagents` | 仅安装命令与 `~/.helloagents/helloagents.json` |
 | 默认保持轻量 | `helloagents install --all --standby` | **标准模式**：显式为目标 CLI 注入精简规则 |
-| 所有项目启用完整规则 | `helloagents install --all --global` 或 `helloagents --global` | 切到 **全局模式**：Claude/Gemini 走原生插件/扩展，Codex 自动安装原生本地插件链路 |
+| 所有项目启用完整规则 | `helloagents install --all --global` 或 `helloagents --global` | 切到 **全局模式**：Claude/Gemini 走原生插件/扩展，Codex 自动安装原生本地插件 |
 | 本地切分支/改文件后重新同步 | `helloagents update codex`、`helloagents install --all --standby`、`helloagents --global` | 按目标或当前模式刷新已注入/已复制的文件 |
 
 ### 2.1）按单个 CLI 管理
@@ -233,7 +233,7 @@ helloagents uninstall gemini
 - 支持的目标：`claude`、`gemini`、`codex`
 - 省略 `--standby` / `--global` 时：优先沿用该 CLI 已记录或已检测到的模式；如果没有历史记录，则回退到 `standby`
 - `install` / `update` 只处理目标 CLI；用 `--all` 可显式批量处理全部目标
-- Claude Code / Gemini CLI 在 `global` 模式下仍需手动执行原生插件/扩展安装或卸载命令；Codex CLI 仍由 HelloAGENTS 自动处理本地插件链路
+- Claude Code / Gemini CLI 在 `global` 模式下仍需手动执行原生插件/扩展安装或卸载命令；Codex CLI 仍由 HelloAGENTS 自动处理本地插件安装
 
 如需所有项目启用完整规则，切换到全局模式：
 
@@ -251,7 +251,7 @@ helloagents --global
 gemini extensions install https://github.com/hellowind777/helloagents
 ```
 
-Codex CLI 无需手动执行插件命令。`helloagents --global` 会自动走原生本地插件链路，写入：
+Codex CLI 无需手动执行插件命令。`helloagents --global` 会自动安装原生本地插件，写入：
 - `~/.agents/plugins/marketplace.json`
 - `~/plugins/helloagents/`
 - `~/.codex/plugins/cache/local-plugins/helloagents/local/`
@@ -286,7 +286,7 @@ Codex CLI 无需手动执行插件命令。`helloagents --global` 会自动走
 ~plan "重构支付模块"
 ```
 
-## 🔄 安装链路与文件写入
+## 🔄 安装流程与文件写入
 
 HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都是可预期的。
 
@@ -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 中的副本。
+- **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,8 +323,8 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 | 命令 | 说明 |
 |------|------|
 | `~idea` | 轻量点子探索 — 比较方向与方案，不写文件 |
-| `~auto` | 自动编排 — 自动选择主路径并持续衔接到实现 / 验证 / 收尾，并优先复用现有活跃方案包 |
-| `~plan` | 结构化规划 — 需求澄清 + 方案收敛 + 计划包 |
+| `~auto` | 自动执行 — 自动选择主路径并持续推进到实现 / 验证 / 收尾，并优先复用现有活跃方案包 |
+| `~plan` | 结构化规划 — 需求澄清 + 方案确认 + 计划包 |
 | `~build` | 执行实现 — 基于当前需求或现有计划包完成实现 |
 | `~prd` | 完整 PRD — 13 维度头脑风暴式探索，生成产品需求文档 |
 | `~loop` | 自主迭代优化 — 设定目标和指标，AI 循环改进直到达标 |
@@ -440,7 +440,7 @@ helloagents --standby
 - `T0` — 只读探索、点子比较、方向发散
 - `T1` — 低风险小改动、明确实现、显式验证
 - `T2` — 多文件功能、新项目、需要结构化产物的任务
-- `T3` — 高风险或不可逆链路，如认证、安全、支付、数据库、生产发布
+- `T3` — 高风险或不可逆操作，如认证、安全、支付、数据库、生产发布
 
 **路由规则：**
 - 点子探索 / 比较方向 → `~idea`
@@ -464,7 +464,7 @@ 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，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。
+标准模式会把规则注入到 `~/.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` 作为运行时判断依据。
 
@@ -482,10 +482,10 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 | `~plan` | 仅做交互式规划，生成计划包 | 想先审查方案再编码 |
 | `~build` | 从当前需求或现有计划包执行实现 | 需求已明确，想直接开始做 |
 | `~verify` | 审查与验证工作流 | 想先看审查结果、跑检查并修复 |
-| `~auto` | 在以上模式之间自动编排并一路推进 | 需求明确，想要端到端交付 |
+| `~auto` | 在以上模式之间自动选择并一路推进 | 需求明确，想要端到端交付 |
 | `~prd` | 13 维度 PRD 生成 | 需要完整的产品需求文档 |
 
-典型模式：先 `~idea` 比较方向，再 `~plan` 收敛方案，然后 `~build` 实现，最后 `~verify` 验证。或者直接 `~auto` 一步到位。如果项目里已经有活跃方案包，`~auto` 应先复用这条现有链路，而不是无故重新脑暴或重新规划。涉及 UI 时，决策优先级固定为：`plan.md` / PRD 中的 UI 决策 → `DESIGN.md` → 通用 UI 规则。
+典型模式：先 `~idea` 比较方向，再 `~plan` 确认方案，然后 `~build` 实现，最后 `~verify` 验证。或者直接 `~auto` 一步到位。如果项目里已经有活跃方案包，`~auto` 应先复用现有计划，而不是无故重新脑暴或重新规划。涉及 UI 时，决策优先级固定为：`plan.md` / PRD 中的 UI 决策 → `DESIGN.md` → 通用 UI 规则。
 
 ### 质量验证（Ralph Loop）
 
@@ -499,9 +499,9 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 
 `~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` 这类一次性只读交互则不会创建。
 
 | 文件 | 用途 |
 |------|------|
@@ -541,8 +541,8 @@ npm test
 测试覆盖：
 - 标准/全局模式的安装、重装、刷新、卸载、模式切换
 - Claude / Gemini / Codex 配置文件的合并、恢复、清理行为
-- Codex 本地插件在本地切分支或文件更新后的刷新链路
-- 运行时 inject / route / guard / Ralph Loop 链路
+- Codex 本地插件在本地切分支或文件更新后的刷新流程
+- 运行时 inject / route / guard / Ralph Loop 流程
 - `~/.codex/` 已不存在时，Codex 全局产物的清理行为
 
 ## ❓ FAQ
@@ -550,7 +550,7 @@ npm test
 <details>
 <summary><strong>Q：这是 CLI 工具还是 prompt 框架？</strong></summary>
 
-**A：** 两者都是。CLI（`cli.mjs`）负责安装、模式切换和 CLI 配置。实际工作流来自 `bootstrap.md` / `bootstrap-lite.md` 规则、质量技能，以及按宿主选择的运行时辅助链路。Claude/Gemini 会使用 `notify.mjs`、`guard.mjs`、`ralph-loop.mjs` 等 hooks；Codex 默认走规则文件驱动，尽量保持 TUI 安静。可以理解为：交付系统 + 智能质量协议。
+**A：** 两者都是。CLI（`cli.mjs`）负责安装、模式切换和 CLI 配置。实际工作流来自 `bootstrap.md` / `bootstrap-lite.md` 规则、质量技能，以及按宿主选择的运行时辅助流程。Claude/Gemini 会使用 `notify.mjs`、`guard.mjs`、`ralph-loop.mjs` 等 hooks；Codex 默认走规则文件驱动，尽量保持 TUI 安静。可以理解为：交付系统 + 智能质量协议。
 </details>
 
 <details>
@@ -718,21 +718,30 @@ npm test
 
 ## 📈 版本历史
 
-### v3.0.8（当前版本）
+### v3.0.10（当前版本）
+
+**相对 `v3.0.9beta` 的修复与验证：**
+- 🔧 Codex 受管 `notify` 配置现在带有明确标记，清理时可区分 HelloAGENTS 写入和用户自定义的 `codex-notify`
+- 🔧 Codex 清理流程现在会保留用户的多行 `notify` 数组，并正确恢复周围 TOML 配置
+- 🔧 `notify_level=0` 现在同时关闭完成、警告和确认通知，和文档中的“关闭”含义保持一致
+- 🔧 恢复 `hello-ui` 的完整指导；已确认 OpenAI 公开 skill 建议是主 `SKILL.md` 尽量控制在约 500 行以内，而不是按 200 行硬限制精简
+- 🧪 新增 Codex `notify` 保留、多行 TOML 处理和通知等级门控的回归测试
+
+### v3.0.9
 
 **修复与验证：**
-- 🔧 Claude Code / Gemini CLI 的 `stop` 交付门控现在优先读取结构化 `turn-state`，不再先从自然语言文本反推“是否完成交付”，普通等待态不再被误判为已完成
-- 🔧 Codex 清理链路现在会保留安装后用户自行改写的 `model_instructions_file`、`notify` 与非托管 `codex_hooks`，不再被安装前旧备份回写覆盖
+- 🔧 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-*` 证据成为流程判断依据，而不是附属文档
-- ✨ 安装模型重构为标准模式 / 全局模式双轨；Codex 改为原生本地插件链路，Claude/Gemini 保留各自宿主原生能力
+- ✨ 安装模型重构为标准模式 / 全局模式双轨；Codex 改为原生本地插件，Claude/Gemini 保留各自宿主原生能力
 - ✨ 新增 `project_store_mode=repo-shared`，让同一 git 仓库的多个 worktree 可以共享稳定知识库和方案包，而本地 `.helloagents/` 继续保留激活和运行态隔离
 
 ### v3.0.4
@@ -761,8 +770,8 @@ npm test
 ### v3.0.1
 
 **修复与验证：**
-- 🔧 收敛并加强 `STATE.md` 恢复规则：关键决策变更即更新，长流程一旦失真立即重写，宿主明确进入压缩/恢复前置阶段前必须先确认已同步
-- 🔧 修复 Codex 本地插件链路清理后的空 `~/.agents/plugins/marketplace.json` 残留
+- 🔧 明确并加强 `STATE.md` 恢复规则：关键决策变更即更新，长流程一旦失真立即重写，宿主明确进入压缩/恢复前置阶段前必须先确认已同步
+- 🔧 修复 Codex 本地插件清理后的空 `~/.agents/plugins/marketplace.json` 残留
 - 🔧 修复并验证单 CLI `update` 在记录模式过期时仍会优先复用本地已检测模式，符合 `helloagents update <cli>` 的预期行为
 - 🔧 明确标准模式下“链接文件立即同步、注入后的规则文件需显式刷新”的分支 / bootstrap 刷新语义
 - 🧪 新增标准模式规则文件刷新、模式自动复用、Codex 空 marketplace 清理，以及与版本号无关的 npm pack 生命周期测试
@@ -783,11 +792,11 @@ npm test
 - ✨ `~verify` 命令：自动检测并运行所有验证命令
 - ✨ Guard 系统（`guard.mjs`）：L1 拦截破坏性命令 + L2 安全模式建议
 - ✨ 标准/全局模式：`install_mode` 配置项支持按项目或全局激活
-- ✨ 流状态管理（`STATE.md`）：用于压缩/恢复衔接的恢复快照（≤70 行）
+- ✨ 流状态管理（`STATE.md`）：用于压缩/恢复时继续工作的恢复快照（≤70 行）
 - ✨ 设计系统生成（`DESIGN.md`）：作为项目级 UI 契约自动创建
 - ✨ 计划包系统：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`
-- ✨ 可选 advisor 契约与证据：仅在 T3 / UI / 高风险链路启用，通过 `contract.json` + `.helloagents/.ralph-advisor.json` 落地
-- ✨ 可选视觉验收证据：仅在 UI 契约明确要求时启用，通过 `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

package/bootstrap-lite.md

@@ -172,10 +172,10 @@
 - `T0` — 只读分析、创意探索、方案比较 → 自然响应或 `~idea`
 - `T1` — 低风险小改动、明确实现、显式验证 → 直接执行或 `~build` / `~verify`
 - `T2` — 多文件功能、新项目、需要结构化产物 → `~plan` 或 `~auto`
-- `T3` — 高风险或不可逆链路（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
+- `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
 
 ## 完成约束
-- 未激活项目且未进入方案包 / `contract.json` / 证据链路时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
+- 未激活项目且未进入方案包 / `contract.json` / 证据文件时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
 - 当前项目已激活，或已存在方案包 / `contract.json` / 证据文件时，以完整流程、对应 skill 与运行时交付约束为准，不得降级为本节
 - 只读分析、创意探索、方案比较、中间进度和阻塞汇报不适用本节
 
@@ -193,13 +193,14 @@
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
 - `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
-- `STATE.md`、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- `state_path` 指向的状态文件、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- `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/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
 按上文 `~command` 路由中的相同技能根目录规则确定；确定根目录后读取其中的 `templates/`。
 
 ### 流程状态（不受 kb_create_mode 控制，始终可写）
-- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一判断依据；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
+- 状态文件（`state_path`）— ≤70 行，用来记录“上次做到哪里”。判断当前任务时，当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于状态文件
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
   - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入统一执行流程/已激活项目的连续任务
@@ -207,14 +208,14 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
   - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
   - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
   更新规则：
-  - 属于“强制创建并持续更新”范围且文件不存在时，按 templates/STATE.md 创建
-  - 每次更新是重写，不是追加。STATE.md 永远反映“此刻”的状态，不是历史
+  - 属于“强制创建并持续更新”范围且状态文件不存在时，按 templates/STATE.md 创建
+  - 每次更新是重写，不是追加。状态文件只记录当前状态，不记录历史
   - 更新时机：任务开始、关键决策落定、子任务完成、遇到/解除阻塞、任务完成
-  - 长流程中 STATE.md 过时就立即重写，不等任务结束
-  - 恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续；否则按当前消息、活跃方案包与代码事实重建主线，并立即重写 STATE.md
-  - `.helloagents/` 里只有 `STATE.md` 时，它只是恢复锚点，不是项目规则或自动授权
-  - 若宿主进入压缩/恢复前置阶段，且当前任务属于 STATE.md 适用范围，必须先确认 STATE.md 已同步到最新
-  - 自检：如果现在上下文被压缩，下一轮能否凭 STATE.md 找回进度？不能 → 该更新了
+  - 长流程中状态文件过时就立即重写，不等任务结束
+  - 恢复时先看当前用户消息；如果仍是同一任务，再参考状态文件；否则按当前消息、活跃方案包与代码事实重新判断任务，并立即重写状态文件
+  - 当前项目只有状态文件时，它只是恢复参考，不是项目规则或自动授权
+  - 若宿主进入压缩/恢复前置阶段，且当前任务属于状态文件适用范围，必须先确认状态文件已同步到最新
+  - 自检：如果现在上下文被压缩，下一轮能否凭状态文件找回进度？不能 → 该更新了
   - “关键上下文”只保留恢复所需的信息，已不再相关的决策和变更移除
 - DESIGN.md — 项目级稳定 UI 契约（仅 UI 项目），`~plan` / `~auto` / `~prd` 创建或更新；不存在且当前任务涉及 UI → 按 templates/DESIGN.md 创建；不替代单次需求的 `plan.md`
 - plans/{feature}/ — 活跃方案包。`~plan` / `~auto` 生成：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`；`~prd` 生成：`prd/` 目录（多维度文档）+ `tasks.md` + `decisions.md` + `contract.json`
@@ -222,7 +223,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 - archive/YYYY-MM/ — 已归档的方案包（整个 plans/{feature}/ 目录移入）
 - archive/_index.md — 归档索引
 
-### 知识沉淀（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
+### 知识记录（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -241,17 +242,17 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. `.helloagents/STATE.md`（恢复快照，只用于补齐最近进度）
-4. 其他知识沉淀与历史归档
+3. 当前状态文件（`state_path`，只用于补齐最近进度）
+4. 其他知识记录与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取项目本地 `.helloagents/STATE.md`
+- Tier 1 始终读取当前 `state_path`
 - Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
-Tier 1 — 恢复当前链路时优先读取：
-- .helloagents/STATE.md → 恢复快照（先确认当前消息仍是同一任务，再用它找回最近进度）
+Tier 1 — 恢复当前任务时优先读取：
+- 当前状态文件（`state_path`）→ 先确认当前消息仍是同一任务，再用它找回最近进度
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引

package/bootstrap.md

@@ -176,14 +176,14 @@
   - `T0` — 只读分析、创意探索、方案比较 → 自然响应或 `~idea`
   - `T1` — 低风险小改动、明确实现、显式验证 → 直接执行或 `~build` / `~verify`
   - `T2` — 多文件功能、新项目、需要结构化产物 → `~plan` 或 `~auto`
-  - `T3` — 高风险或不可逆链路（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`，必要时单独确认
+  - `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`，必要时单独确认
 - 创意探索 / 方案比较 → `~idea`
 - 明确实现 / 小范围修复 → `~build`
 - 为指定模块编写测试 → `~test`
 - 结构化规划 / 新功能 / 新项目 → `~plan`
 - 完整产品规格 → `~prd`
 - 审查 / 执行验证 → `~verify`
-- 不确定或希望端到端自动推进时由 `~auto` 自动编排
+- 不确定或希望端到端自动推进时使用 `~auto`
 
 当前项目只要已建立 `.helloagents/`（例如执行过 `~wiki`、`~init`，或已进入项目级连续流程），就按项目级完整流程执行。
 
@@ -209,9 +209,9 @@ 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` 是方案包的机器契约，至少明确 `verifyMode`、`reviewerFocus`、`testerFocus`；只有在 T3 / UI / 高风险流程确有收益时，才额外声明 `advisor`；进入验证或最终交付前，优先消费它而不是从自然语言描述里回推验证路径
 - 涉及 UI 时，设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） → 通用 UI 规则
-- `~idea` 在输出比较与推荐后结束，不进入实现，也不创建 `.helloagents/`、`STATE.md` 或方案包
+- `~idea` 在输出比较与推荐后结束，不进入实现，也不创建 `.helloagents/`、状态文件或方案包
 
 ### 4. BUILD — 实现
 进入实现时，读取 PLAN 阶段标记的技能 SKILL.md（按上方 hello-* 技能查找路径读取 `skills/{技能名}/SKILL.md`），按其规范执行。
@@ -233,10 +233,10 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 非编码任务（文档 / 方案 / 审查等）：
 - 收集已激活技能的交付检查清单，逐项确认通过
 
-### 6. CONSOLIDATE — 状态、沉淀与归档
+### 6. CONSOLIDATE — 状态、资料与归档
 所有任务：
 - 有方案包且准备报告完成 → 优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录“需求覆盖”和“交付清单”；每项写明 `PASS` / `BLOCKED` 与简要摘要，再进入最终交付
-- `STATE.md` 维护：按上文“流程状态”中的适用边界执行。属于“强制创建并持续更新”范围时，重写 `.helloagents/STATE.md`（“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
+- 状态文件维护：按上文“流程状态”中的适用范围执行。属于“强制创建并持续更新”范围时，重写 `state_path` 指向的文件（“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
 - 有方案包且任务已完成 → 将整个 `plans/{feature}/` 目录归档到 `.helloagents/archive/YYYY-MM/`，并更新 `archive/_index.md`。清理临时文件（`loop-results.tsv`、`.ralph-breaker.json`、`.ralph-verify.json`、`.ralph-review.json`、`.ralph-closeout.json`）
 - 按 `kb_create_mode` 同步知识库（0=关闭 / 1=已激活项目或全局模式中编码自动 / 2=已激活项目或全局模式中始终）：
   - `.helloagents/` 不存在则按 templates/ 创建知识库文件（`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`modules/`）
@@ -262,13 +262,14 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
 - `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
-- `STATE.md`、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- `state_path` 指向的状态文件、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- `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/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
 按上文相同的技能根目录规则确定；确定根目录后读取其中的 `templates/`。
 
 ### 流程状态（不受 kb_create_mode 控制，始终可写）
-- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一判断依据；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
+- 状态文件（`state_path`）— ≤70 行，用来记录“上次做到哪里”。判断当前任务时，当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于状态文件
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
   - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入统一执行流程/已激活项目的连续任务
@@ -276,14 +277,14 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
   - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
   - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
   更新规则：
-  - 属于“强制创建并持续更新”范围且文件不存在时，按 templates/STATE.md 创建
-  - 每次更新是重写，不是追加。STATE.md 永远反映“此刻”的状态，不是历史
+  - 属于“强制创建并持续更新”范围且状态文件不存在时，按 templates/STATE.md 创建
+  - 每次更新是重写，不是追加。状态文件只记录当前状态，不记录历史
   - 更新时机：任务开始、关键决策落定、子任务完成、遇到/解除阻塞、任务完成
-  - 长流程中 STATE.md 过时就立即重写，不等任务结束
-  - 恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续；否则按当前消息、活跃方案包与代码事实重建主线，并立即重写 STATE.md
-  - `.helloagents/` 里只有 `STATE.md` 时，它只是恢复锚点，不是项目规则或自动授权
-  - 若宿主进入压缩/恢复前置阶段，且当前任务属于 STATE.md 适用范围，必须先确认 STATE.md 已同步到最新
-  - 自检：如果现在上下文被压缩，下一轮能否凭 STATE.md 找回进度？不能 → 该更新了
+  - 长流程中状态文件过时就立即重写，不等任务结束
+  - 恢复时先看当前用户消息；如果仍是同一任务，再参考状态文件；否则按当前消息、活跃方案包与代码事实重新判断任务，并立即重写状态文件
+  - 当前项目只有状态文件时，它只是恢复参考，不是项目规则或自动授权
+  - 若宿主进入压缩/恢复前置阶段，且当前任务属于状态文件适用范围，必须先确认状态文件已同步到最新
+  - 自检：如果现在上下文被压缩，下一轮能否凭状态文件找回进度？不能 → 该更新了
   - “关键上下文”只保留恢复所需的信息，已不再相关的决策和变更移除
 - DESIGN.md — 项目级稳定 UI 契约（仅 UI 项目），`~plan` / `~auto` / `~prd` 创建或更新；不存在且当前任务涉及 UI → 按 templates/DESIGN.md 创建；不替代单次需求的 `plan.md`
 - plans/{feature}/ — 活跃方案包。`~plan` / `~auto` 生成：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`；`~prd` 生成：`prd/` 目录（多维度文档）+ `tasks.md` + `decisions.md` + `contract.json`
@@ -291,7 +292,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 - archive/YYYY-MM/ — 已归档的方案包（整个 plans/{feature}/ 目录移入）
 - archive/_index.md — 归档索引
 
-### 知识沉淀（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
+### 知识记录（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -310,17 +311,17 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. `.helloagents/STATE.md`（恢复快照，只用于补齐最近进度）
-4. 其他知识沉淀与历史归档
+3. 当前状态文件（`state_path`，只用于补齐最近进度）
+4. 其他知识记录与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取项目本地 `.helloagents/STATE.md`
+- Tier 1 始终读取当前 `state_path`
 - Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
-Tier 1 — 恢复当前链路时优先读取：
-- .helloagents/STATE.md → 恢复快照（先确认当前消息仍是同一任务，再用它找回最近进度）
+Tier 1 — 恢复当前任务时优先读取：
+- 当前状态文件（`state_path`）→ 先确认当前消息仍是同一任务，再用它找回最近进度
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.8-beta.1",
+  "version": "3.0.10-beta.1",
   "description": "Quality-driven orchestration kernel for AI CLIs",
   "contextFileName": "bootstrap.md",
   "author": "HelloWind",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.8-beta.1",
+  "version": "3.0.10-beta.1",
   "type": "module",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": "HelloWind",

package/scripts/capability-registry.mjs

@@ -8,9 +8,9 @@ function getPrimaryPlan(snapshot) {
   return snapshot.activePlans[0] || snapshot.plans[0] || null
 }
 
-export function selectCapabilities({ cwd, skillName = '' }) {
-  const snapshot = getWorkflowSnapshot(cwd)
-  const recommendation = getWorkflowRecommendation(cwd)
+export function selectCapabilities({ cwd, skillName = '', options = {} }) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
+  const recommendation = getWorkflowRecommendation(cwd, options)
   const plan = getPrimaryPlan(snapshot)
   const advisorRequirement = getAdvisorRequirement(plan?.contract)
   const visualRequirement = getVisualValidationRequirement(plan?.contract)
@@ -52,8 +52,8 @@ export function selectCapabilities({ cwd, skillName = '' }) {
   return capabilities
 }
 
-export function buildCapabilityHint({ cwd, skillName = '' }) {
-  const capabilities = selectCapabilities({ cwd, skillName })
+export function buildCapabilityHint({ cwd, skillName = '', options = {} }) {
+  const capabilities = selectCapabilities({ cwd, skillName, options })
   if (capabilities.length === 0) return ''
   return `按需能力：${capabilities.map((entry) => `${entry.id}=${entry.description}`).join(' ')}`
 }