feat: add Hermes role profiles and context firewall

README.md

@@ -97,7 +97,7 @@ node packages/cli/scripts/release-preflight.js verify-packed-cli
 新包发布后，可固定安装本次测试版：
 
 ```bash
-npm install -g research-trellis@0.7.0-beta.0
+npm install -g research-trellis@0.7.1-beta.0
 research-trellis --version
 ```
 
@@ -107,7 +107,7 @@ research-trellis --version
 
 ```bash
 npm uninstall -g trellis-hermes
-npm install -g research-trellis@0.7.0-beta.0
+npm install -g research-trellis@0.7.1-beta.0
 research-trellis --version
 ```
 
@@ -197,7 +197,17 @@ node /path/to/research-trellis/packages/cli/bin/trellis.js update
 
 详见[中文手册：Lean Research Closure](docs/manual/17-lean-research-closure.md)。
 
-### 6. 预检不是形式检查
+### 6. 五角色与轻量模式
+
+五个正式 `Hermes`（科研工作流）角色现在是 `planner`（规划代理）、`researcher`（检索代理）、`coder`（编码代理）、`runner`（运行代理）和 `reviewer`（复核代理）。角色决定权限，`Profile`（模式）决定本次关注点；正式模板目前只提供给 `Claude Code`（Claude 代码工具）和 `Codex`（代码代理平台）。
+
+### 7. Agent Context Firewall
+
+每次正式角色派发先生成绑定 `hermes_revision`（Hermes 修订号）的结构化文件，正文最多 2000 字符、引用最多 3 个。`Claude Code`（Claude 代码工具）钩子只接收 `job_id`（工作编号）并替换长提示；`Codex native`（Codex 原生）仅为建议性，`Codex strict`（Codex 严格模式）使用结构化输出参数执行。
+
+返回必须包含 `uncertainties`（不确定项），长日志、完整差异和搜索过程不会进入主上下文。原始跟踪保存在 `.trellis/.runtime/`（本地运行目录），成功或失败都会机械更新下一动作，但不会仅凭聊天关闭任务。
+
+### 8. 预检不是形式检查
 
 `hermes:preflight`（Hermes 预检）会检查模板文件、Python 编译、Hermes hook、门禁文档、沙箱配置、模板测试、类型检查和构建。
 

docs/hermes_deployment_preflight.md

@@ -14,8 +14,8 @@ pnpm --filter research-trellis hermes:preflight -- --quick
 2. 发布前补跑完整验证：
 
 ```bash
-pnpm --filter research-trellis exec vitest run test/templates/hermes-runtime.test.ts test/templates/trellis.test.ts test/templates/claude.test.ts test/templates/codex.test.ts test/templates/shared-hooks.test.ts
-PYTHONPYCACHEPREFIX=/tmp/research-trellis-pycache python3 -m py_compile packages/cli/src/templates/trellis/scripts/hermes/*.py packages/cli/src/templates/shared-hooks/hermes-runtime-guard.py
+pnpm --filter research-trellis exec vitest run test/scripts/agent-context-firewall.integration.test.ts test/scripts/closure.integration.test.ts test/templates/hermes-runtime.test.ts test/templates/hermes-roles.test.ts test/templates/trellis.test.ts test/templates/claude.test.ts test/templates/codex.test.ts test/templates/shared-hooks.test.ts
+PYTHONPYCACHEPREFIX=/tmp/research-trellis-pycache python3 -m py_compile packages/cli/src/templates/trellis/scripts/common/*.py packages/cli/src/templates/trellis/scripts/hermes/*.py packages/cli/src/templates/shared-hooks/*.py
 pnpm --filter research-trellis typecheck
 pnpm --filter research-trellis build
 ```
@@ -24,6 +24,9 @@ pnpm --filter research-trellis build
 
 ## 安全 Gate
 
+- 正式上下文防火墙只支持 `Claude Code`（Claude 代码工具）和 `Codex`（代码代理平台）。Claude 的 `Agent`（代理）工具必须启用项目钩子；Codex 原生代理仅是建议性入口，需要强制控制时必须使用 `dispatch.py run --platform codex --mode strict`（Codex 严格派发）。
+- `TRELLIS_HOOKS=0`（关闭钩子）或 `TRELLIS_DISABLE_HOOKS=1`（禁用钩子）会覆盖心跳判断。`lean`（轻量）模式会显示强警告；`standard`（标准）模式要求新鲜钩子或严格执行心跳；`publication`（发表）模式缺少该硬门禁时必须拒绝派发和关闭。
+- Claude Agent 调用只传 `job_id`（工作编号），不允许异步调用。Codex 严格包装使用 `codex exec --output-schema --json -o`（结构化执行）并把原始跟踪保存在 `.trellis/.runtime/hermes-traces/`（本地跟踪目录）；发布包和聊天只使用校验后的净化结果。
 - `Bash` 写入守卫是最佳努力，不是完整 shell 沙箱。hook 会解析常见重定向和 `tee` 写入；遇到写入语义但无法明确解析目标时必须 `fail closed`。
 - `runner.py` 必须按任务 `experiment.yaml` 的 `allowed_commands` 执行命令白名单；未匹配命令直接失败。`allowed_commands` is not a strong command sandbox（不是强命令沙箱）；如果允许 `python3`，仍能执行任意 Python 行为。需要更强控制时，应使用更严格 exact match（精确匹配）或外部 OS 级隔离。
 - `sandbox.required=true` 且 `mode=none` 必须拒绝运行；`mode=none` 只是本地执行，不是隔离环境。`container` 当前只提供 `Docker`（容器运行时）薄切片：通过 `docker run --rm`（一次性容器执行命令）挂载仓库，并在容器工作目录执行已通过白名单的命令；这仍是 `not an OS sandbox`（不是操作系统沙箱），也不是 `production ready`（生产就绪）的强隔离。`external` 当前仍只做可用性检查，不能声称已经提供 `OS sandbox`（操作系统沙箱）。
@@ -38,6 +41,7 @@ pnpm --filter research-trellis build
 - Bash gate 失败：改用受 Hermes runner 管理的命令，或把写入文件纳入任务卡 `allowed_files`。
 - 命令不在 `allowed_commands`：更新任务级 `experiment.yaml`，不要绕过 runner。
 - approval 失败：由外部 human/root 流程补写完整 approval 记录，agent 不能自行生成批准。
+- 防火墙状态异常：运行 `python3 ./.trellis/scripts/hermes/dispatch.py status --task <task>`（派发状态），确认平台、环境变量和最新心跳；不能用手工改写心跳文件绕过 `standard`（标准）或 `publication`（发表）门禁。
 
 ## 已知边界
 

docs/hermes_role_profile_migration.md

@@ -0,0 +1,55 @@
+# Hermes 五角色迁移说明
+
+## 变化
+
+正式角色收敛为 `planner`（规划代理）、`researcher`（检索代理）、`coder`（编码代理）、`runner`（运行代理）和 `reviewer`（复核代理）。
+
+`Role`（角色）决定权限、工具、输出契约和独立性要求；`Profile`（模式）决定本次工作的关注点。模式不会生成新的角色文档或平台代理模板。
+
+正式五角色模板只提供给 `Claude Code`（Claude 代码工具）和 `Codex`（代码代理平台）。其他平台继续保留原版通用代理和兼容行为。
+
+## 旧名称
+
+| 旧名称 | 规范化结果 |
+| --- | --- |
+| `scientist`（科学家） | `planner:research_design`（规划代理的研究设计模式） |
+| `builder`（构建代理） | `coder:implementation`（编码代理的实现模式） |
+| `literature`（文献代理） | `researcher:literature`（检索代理的文献模式） |
+| `research/scout`（检索侦察代理） | 根据目标选择检索代理模式，默认 `codebase`（代码库） |
+| `evaluator`（评估代理） | `reviewer:evidence`（复核代理的证据模式） |
+| `claim-reviewer`（主张审查代理） | `reviewer:claim`（复核代理的主张模式） |
+| `analyst`（分析代理） | 根据目标选择规划或复核模式，无法判断时使用 `planner:root_cause`（规划代理的根因模式） |
+
+旧任务卡读取时会给出弃用提示，但不会重写追加式历史。新任务卡写入时只保存正式角色和合法模式。
+
+`evidence-curator`（证据整理代理）不再允许新派发。产物路径、哈希、运行清单和引用检查由 `evidence.py`（证据工具）确定性完成，证据质量判断由 `reviewer:evidence`（证据复核模式）完成。
+
+## 派发上下文
+
+`v0.7.1`（当前版本）开始，主代理先生成 validated dispatch（已验证派发），其中只保留：
+
+1. `job_id`（工作编号）和 `hermes_revision`（Hermes 修订号）；
+2. 当前角色与模式；
+3. 当前工作包或任务级空绑定；
+4. 有界目标；
+5. 最多 3 个直接引用。
+
+完整需求、设计、历史报告、事件、账本和全部规范只在当前检查确实需要时读取。
+
+## 测量
+
+| 项目 | 改造前 | 改造后 | 变化 |
+| --- | ---: | ---: | ---: |
+| 角色文档 | 8 个 / 9673 字符 | 6 个 / 6819 字符 | 字符减少 29.5% |
+| `Claude Code`（Claude 代码工具）正式 Hermes 模板 | 7 个 / 9873 字符 | 5 个 / 3865 字符 | 字符减少 60.9% |
+| 两平台正式 Hermes 模板合计 | 7 个 / 9873 字符 | 10 个 / 8904 字符 | 新增 Codex 支持后仍减少 9.8% |
+| 单个正式模板平均长度 | 1410 字符 | 890 字符 | 减少 36.9% |
+
+派发正文测试限制在 2000 字符内。`Claude Code`（Claude 代码工具）只向 `Agent`（代理）传 `job_id`（工作编号），`Codex native`（Codex 原生）仅为建议性，`Codex strict`（Codex 严格模式）由统一 CLI 包装器执行。
+
+## 兼容边界
+
+- 原版任务、原版通用代理和非 closure 任务行为不变。
+- 已有 closure 任务缺少修订号时按 0 读取，下一次语义写入会补齐并递增。
+- 旧角色模板不再随新安装分发；已安装的旧别名只在 Hermes closure 任务中映射到正式角色和模式。
+- 证据、产物、主张、批准和任务事件的现有语义不变。

docs/hermes_trellis_research_transformation_plan.md

@@ -199,7 +199,7 @@ ledger、local service queue、audit ledger、evaluation quality gate。这里
 - 新增 `report.md`（报告）
 - 新增或模板化 `compare.jsonl`（对比记录）
 - 新增 aggregate/compare/report 命令
-- 扩展 reviewer/evaluator 角色模板
+- 使用 `reviewer:evidence`（证据复核模式）扩展证据审查
 
 交付物：
 
@@ -211,7 +211,7 @@ ledger、local service queue、audit ledger、evaluation quality gate。这里
 验收标准：
 
 - 报告中的每个核心结论都能回链到 claim 和 evidence。
-- evaluator 不能修改源码、metric、split、baseline。
+- `reviewer:evidence`（证据复核模式）不能修改源码、指标、切分或基线。
 - reviewer 只读 diff、record、evidence 和任务说明，不继承 coder 长对话。
 
 主要风险：
@@ -220,7 +220,7 @@ ledger、local service queue、audit ledger、evaluation quality gate。这里
 
 ### P5：多代理科研协作层
 
-目标：把 coder、runner、evaluator、reviewer、literature 的协作固定成可复用模式。
+目标：把 `planner`（规划代理）、`researcher`（检索代理）、`coder`（编码代理）、`runner`（运行代理）和 `reviewer`（复核代理）的协作固定成可复用模式。
 
 要改的范围：
 
@@ -231,7 +231,7 @@ ledger、local service queue、audit ledger、evaluation quality gate。这里
 
 交付物：
 
-- 角色模板：scientist、coder、runner、evaluator、reviewer、literature。
+- 角色模板：一个公共契约和五个正式角色；具体工作由 `Profile`（模式）表达。
 - 默认 `maker/checker`（写作者/审查者）分离。
 - 同一 worktree 默认只有一个 active writer。
 - 子代理任务卡强制包含 allowed_files、forbidden_files、timeout_at、heartbeat_interval、record_uri。
@@ -240,7 +240,7 @@ ledger、local service queue、audit ledger、evaluation quality gate。这里
 
 - 没有 `task_card` 的子代理结果不被接受。
 - coder 的输出必须经过 runner 和 reviewer 才能进入 review 状态。
-- reviewer/evaluator 的记录不能替代 human approval。
+- 任何复核记录都不能替代人工批准。
 
 主要风险：
 
@@ -303,13 +303,13 @@ P4 已完成：
 
 P5 已完成：
 
-- [x] 角色模板覆盖 scientist、coder、runner、evaluator、reviewer、literature、evidence-curator、claim-reviewer。
+- [x] 角色模板收敛为 planner、researcher、coder、runner、reviewer；证据整理改为确定性工具。
 - [x] bundled skill 和 Claude Hermes agents 已加入多代理科研协作入口。
 - [x] `task_card` 强制包含 allowed_files、forbidden_files、timeout_at、heartbeat_interval、record_uri 等边界字段。
 - [x] 没有 `task_card` 的结果记录会被拒收。
 - [x] 同一 worktree 只允许一个未完成 coder/runner active writer。
 - [x] coder 进入 review/claim_ready 前必须经过 runner 和 reviewer 记录。
-- [x] reviewer/evaluator 记录不能替代 `human/root` approval。
+- [x] reviewer 记录不能替代 `human/root` approval。
 
 P6 部署前安全 gate：
 
@@ -325,6 +325,15 @@ P6 部署前安全 gate：
 - [x] Hermes hook guard 已覆盖 `Edit`、`Write`、`MultiEdit` 和 `apply_patch`。
 - [x] `MultiEdit` 会从当前 `tool_input`（工具输入）递归提取目标路径并按任务卡权限拦截。
 
+P7 Agent Context Firewall：
+
+- [x] 新增统一 `dispatch.py`（派发命令），支持创建、校验、显示、运行、列表、应用和状态查询。
+- [x] 派发绑定单调 `hermes_revision`（Hermes 修订号）、当前工作包、五角色模式和最多 3 个引用。
+- [x] Claude Agent 钩子只接受 `job_id`（工作编号），拒绝异步，并在结束时校验和净化结果。
+- [x] Codex native（Codex 原生）明确为建议性；strict（严格）复用结构化执行参数，不增加 SDK、数据库或服务。
+- [x] 原始跟踪只写入忽略发布的 `.trellis/.runtime/`（本地运行目录）；主上下文只接收净化摘要。
+- [x] `lean`（轻量）、`standard`（标准）和 `publication`（发表）按钩子或严格模式心跳执行不同门禁。
+
 最终验证记录：
 
 - [x] `pnpm --filter research-trellis exec vitest run test/templates/hermes-runtime.test.ts test/templates/trellis.test.ts test/templates/claude.test.ts test/templates/codex.test.ts test/templates/shared-hooks.test.ts`：5 个文件、135 个测试通过。

docs/manual/01-overview.md

@@ -11,7 +11,7 @@
 ## 前置条件
 
 - 能管理目标项目中的文件和提交。
-- 接受当前版本为 `0.7.0-beta.0`（测试版）。
+- 接受当前版本为 `0.7.1-beta.0`（测试版）。
 - 不把它当作安全隔离工具或自动科研结论系统。
 
 ## 操作步骤
@@ -45,7 +45,7 @@
 ## 验证记录
 
 - 日期：2026-07-15。
-- 版本：`0.7.0-beta.0`（测试版）。
+- 版本：`0.7.1-beta.0`（测试版）。
 - 更名前基准提交：`9f7dc8497b4782878d6fa7ac3b63eba5bde507df`。
 - 命令：`rg -n "AGPL|Hermes|未实现" README.md docs/manual/appendix-f-feature-status.md`（静态核对）。
 - 结果：项目定位、上游归属、实验性与未实现边界已对齐。

docs/manual/02-installation.md

@@ -28,22 +28,22 @@ git --version
 新包发布后，推荐固定安装本手册对应的测试版：
 
 ```bash
-npm install --global research-trellis@0.7.0-beta.0
+npm install --global research-trellis@0.7.1-beta.0
 research-trellis --version
 research-trellis --help
 ```
 
 如不希望全局安装，可临时执行：
 
 ```bash
-npm exec --yes --package research-trellis@0.7.0-beta.0 -- research-trellis --version
+npm exec --yes --package research-trellis@0.7.1-beta.0 -- research-trellis --version
 ```
 
 已经安装旧包时，先卸载旧名称，再安装新包：
 
 ```bash
 npm uninstall --global trellis-hermes
-npm install --global research-trellis@0.7.0-beta.0
+npm install --global research-trellis@0.7.1-beta.0
 research-trellis --version
 ```
 
@@ -62,7 +62,7 @@ node packages/cli/bin/trellis.js --version
 
 ## 预期结果
 
-版本命令输出 `0.7.0-beta.0`，帮助中能看到 `init`（初始化）、`update`（更新）、`workflow`（工作流）、`channel`（协作频道）和 `mem`（会话记忆）等命令。
+版本命令输出 `0.7.1-beta.0`，帮助中能看到 `init`（初始化）、`update`（更新）、`workflow`（工作流）、`channel`（协作频道）和 `mem`（会话记忆）等命令。
 
 ## 失败恢复
 
@@ -74,10 +74,10 @@ node packages/cli/bin/trellis.js --version
 ## 验证记录
 
 - 日期：2026-07-15。
-- 版本：`0.7.0-beta.0`（测试版）。
+- 版本：`0.7.1-beta.0`（测试版）。
 - 更名前基准提交：`9f7dc8497b4782878d6fa7ac3b63eba5bde507df`。
 - 命令：`node -p "require('./packages/cli/package.json').version"`（包版本核对）。
-- 结果：源码包版本为 `0.7.0-beta.0`（测试版），运行时要求与包配置一致。
+- 结果：源码包版本为 `0.7.1-beta.0`（测试版），运行时要求与包配置一致。
 - 未验证项：本轮未重新进行全局安装，也未实时查询 `npm`（Node 包平台）标签。
 
 ## 来源

docs/manual/03-first-research-task.md

@@ -23,7 +23,7 @@ git status --short
 research-trellis init -y -u "$USER" --codex --no-monorepo
 ```
 
-2. 检查生成结果和启动任务：
+2. 检查生成结果和启动任务。空仓库先处理 `00-bootstrap-guidelines`（项目启动任务）：完成一次研究合同讨论，填写 `.trellis/project/` 中的三份项目资料，再创建下面的首个任务。已有项目先读取 `PROJECT_INDEX.md`（事实索引）列出的原始资料，不把索引当作自动摘要。
 
 ```bash
 python3 ./.trellis/scripts/task.py list
@@ -95,7 +95,7 @@ python3 ./.trellis/scripts/closure.py close --task "$TASK"
 ## 验证记录
 
 - 日期：2026-07-15。
-- 版本：`0.7.0-beta.0`（测试版）。
+- 版本：`0.7.1-beta.0`（测试版）。
 - 更名前基准提交：`9f7dc8497b4782878d6fa7ac3b63eba5bde507df`。
 - 命令：`rg -n "experiment.py|task.py start|--codex" packages/cli/src packages/cli/test`（实现与测试核对）。
 - 结果：初始化、任务创建、实验校验和启动步骤与当前入口一致。

docs/manual/04-how-it-works.md

@@ -62,7 +62,7 @@
 ## 验证记录
 
 - 日期：2026-07-15。
-- 版本：`0.7.0-beta.0`（测试版）。
+- 版本：`0.7.1-beta.0`（测试版）。
 - 更名前基准提交：`9f7dc8497b4782878d6fa7ac3b63eba5bde507df`。
 - 命令：`rg -n "state_machine|approval-gate|task.py" packages/cli/src/templates`（协议与实现核对）。
 - 结果：任务生命周期有实现支持；科研状态文件已准确标为协议模板。