@pzy560117/codex-harness 0.1.1 → 0.1.3

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/goal-harness-integration-guide.md

@@ -0,0 +1,364 @@
+# `/goal` + Harness 接入指南
+
+## 1. 目标
+
+本文说明如何把 Codex 官方 `/goal` 长期目标模式，与当前 Harness 的 driver-first 执行链结合使用。
+
+目标不是让 `/goal` 替代 Harness，而是让它承担：
+
+- 外层 7x24 持续目标保持
+- 人机协同 steering
+- 长任务 pause / resume / edit
+
+同时继续保留 Harness 的：
+
+- `task.json`
+- `tools/harness/codex-loop.ps1`
+- `test_command`
+- review gate
+- `progress.txt`
+- `traces/*.json`
+- stop hook continuation / block
+
+一句话：
+
+```text
+/goal 在外
+driver + stop hook 在内
+```
+
+## 2. 推荐分层
+
+推荐分层如下：
+
+```text
+Codex Goal Mode
+  -> 维持长期目标
+  -> 接受人工跟进消息修正方向
+  -> 持续要求“推进当前 Harness 任务”
+
+Harness Driver
+  -> 读取 task.json
+  -> 单任务实现
+  -> Stage 1 / test_command / Stage 2
+  -> trace / progress / commit
+
+Stop Hook
+  -> 停止前治理门
+  -> continuation / allow stop
+  -> dirty workspace / governance drift / failed trace gate
+```
+
+这三层的职责不要混：
+
+- `/goal` 不负责直接判断代码是否完成。
+- driver 不负责维护长期目标 UI 状态。
+- stop hook 不负责变更 goal 本身。
+
+## 3. 适用场景
+
+适合使用 `/goal + Harness` 的场景：
+
+- 长时间、跨多个任务推进的工程目标
+- 需要白天人工 occasional steering、夜间自动续跑
+- 希望持续推进，但又不能放弃严格的 review / test / trace / commit 约束
+
+不适合的场景：
+
+- 只跑一个短任务
+- 还没补齐 testing truth source、repo-map、task queue
+- 当前工作区不稳定、频繁 dirty、需求边界模糊
+
+## 4. 安装层建议
+
+### 4.1 `user` 层
+
+更适合放：
+
+- `/goal` 的使用习惯
+- 目标模板
+- 全局 steering 方式
+
+### 4.2 `project` / `full` 层
+
+更适合放：
+
+- `task.json`
+- `tools/harness/codex-loop.ps1`
+- stop hook
+- `docs/testing/*`
+- `docs/ai/repo-map.md`
+
+### 4.3 最终建议
+
+如果你要实际使用两者：
+
+- `/goal` 的“目标文案”放在用户工作流层
+- Harness runtime 和 repo truth source 仍放项目层
+
+## 5. 使用前提
+
+开始前至少满足：
+
+1. `features.goals = true` 已启用，或 `codex features enable goals` 已执行。
+2. 项目已完成 Harness bootstrap。
+3. 已有真实 `task.json`，不是 smoke 占位。
+4. 已有 `docs/ai/repo-map.md` 或等价导航文件。
+5. 已有最少 testing truth source：
+   - `ACCEPTANCE_EXAMPLES.md`
+   - `TRACEABILITY_MATRIX.md`
+   - `TEST_DATA_MATRIX.md`
+   - `verify-matrix.md`
+6. 若目标涉及用户可见高风险路径，已有 `docs/testing/e2e-plan.md`。
+
+如果这些前提不成立，不要直接开 `/goal` 长跑。
+
+## 6. 推荐操作顺序
+
+### Step 1：先收敛计划
+
+先用 `/plan` 或等价流程，把目标收敛成：
+
+- 当前要推进的 feature / release
+- 任务边界
+- 非目标
+- 阻塞条件
+
+### Step 2：确认 Harness 状态
+
+在目标项目里至少确认：
+
+```powershell
+git status --short
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/doctor.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+### Step 3：设置 `/goal`
+
+在 Codex app 中启动 `/goal`，让它以“持续推进 Harness 任务”为目标，而不是“自由发挥写功能”。
+
+### Step 4：目标运行时的固定动作
+
+推荐让 `/goal` 驱动以下固定策略：
+
+1. 优先读取 `AGENTS.md`、`docs/ai/repo-map.md`、`docs/testing/*`。
+2. 优先推进 `task.json` 中下一个 runnable task。
+3. 实际执行通过 `tools/harness/codex-loop.ps1 -RunUntilDone` 完成。
+4. 遇到 stop hook continuation、failed trace、failure-triage 报告时，再决定：
+   - 继续
+   - 暂停
+   - 请求人工输入
+
+### Step 5：暂停 / 恢复 / 编辑
+
+`/goal` 适合做这些动作：
+
+- 暂停夜间运行
+- 修改长期目标的表述
+- 把“实现 feature”改成“先修 release blocker”
+- 清空不再需要的目标
+
+但这些不应直接修改 driver 协议本身。
+
+## 7. 推荐 `/goal` 文案模板
+
+下面这些模板的共同原则是：
+
+- 目标要约束到 Harness 执行方式
+- 不允许绕过 task/test/review/trace
+- 出现阻塞时要求明确输出
+
+### 模板 A：标准持续推进
+
+```text
+持续推进当前项目的 Harness 任务队列，直到 task.json 中没有 runnable task、出现真实人工阻塞，或 stop hook / review / test / trace 明确要求暂停。
+
+强制约束：
+1. 先遵守 AGENTS.md、docs/ai/repo-map.md、docs/harness/*、docs/testing/*。
+2. 通过 tools/harness/codex-loop.ps1 -RunUntilDone 推进任务，不绕过 task.json。
+3. 不跳过 test_command、Stage 1、Stage 2、trace 或 commit gate。
+4. 测试失败时先查看 failure-triage 结果，再决定下一步。
+5. 缺少 truth source、e2e-plan、权限或外部依赖时，明确报告 BLOCKED，不自行猜测。
+```
+
+适用：
+
+- 常规功能开发
+- 多任务串行推进
+
+### 模板 B：夜间长跑
+
+```text
+在无人值守时持续推进当前 Harness 项目，但只允许在 driver 和 stop hook 都认为可以继续时前进。
+
+运行原则：
+1. 优先执行 task.json 中下一个 runnable task。
+2. 任何 dirty workspace、governance drift、failed trace、truth source 缺失都视为暂停信号。
+3. 不要为追求连续运行而弱化测试、跳过 review 或绕过 stop hook。
+4. 每次停下时总结：当前任务、最近证据、failure-triage 结果、是否需要人工。
+```
+
+适用：
+
+- 夜间自动推进
+- 低频人工巡检
+
+### 模板 C：高风险用户可见功能
+
+```text
+持续推进当前高风险用户可见功能，但必须先确认 docs/testing/e2e-plan.md、验收示例、追溯矩阵和 repo-map 已齐备。
+
+额外约束：
+1. 没有 e2e-plan 时不进入实现，先补测试计划。
+2. 先从 docs/ai/repo-map.md 进入代码结构，再做局部文件修改。
+3. 测试失败时先按 TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY 分类。
+4. 不允许用 mock、fixture、local-only adapter 冒充真实交付路径。
+```
+
+适用：
+
+- 前端主流程
+- 权限、路由、状态流转
+- release 前关键路径
+
+### 模板 D：恢复性目标
+
+```text
+恢复并继续当前 Harness 执行链。先判断上次停止是正常 allow stop、stop hook continuation、review 失败、test_command 失败还是真实 BLOCKED。
+
+执行顺序：
+1. 读取最新 progress.txt、latest trace、failure-triage 报告。
+2. 确认当前 runnable task 和最近失败阶段。
+3. 如果 stop hook / driver 允许继续，则继续推进。
+4. 如果仍然 blocked，输出需要人工处理的最小动作，不要空转。
+```
+
+适用：
+
+- 中断恢复
+- 早上接手夜间运行结果
+
+## 8. 推荐跟进消息模板
+
+### 调整优先级
+
+```text
+把长期目标改成：优先清掉当前 release blocker，其次再继续 feature 实现。不要新增新范围。
+```
+
+### 强制保守
+
+```text
+接下来优先保守模式：不要扩展范围，只推进当前 runnable task，测试失败就停并给出 failure-triage 摘要。
+```
+
+### 切回人工确认
+
+```text
+如果下一轮还遇到相同 blocker，不要继续尝试，直接停下并输出需要人工决策的最小问题清单。
+```
+
+## 9. 和 stop hook 的协作规则
+
+推荐固定规则：
+
+1. stop hook 的 continuation / allow stop 结果优先于 `/goal` 的“想继续跑”。
+2. `/goal` 不应覆盖 dirty workspace gate。
+3. `/goal` 不应覆盖 failed trace / governance drift gate。
+4. stop hook 只决定：
+   - 允许继续
+   - 要求继续下一轮
+   - 必须阻塞
+5. `/goal` 只决定：
+   - 目标是否还有效
+   - 人类是否要继续让系统围绕这个目标工作
+
+## 10. 和 failure-triage 的协作规则
+
+当前 driver 已在测试失败时自动生成 `failure-triage` JSON。
+
+因此 `/goal` 运行时建议遵守：
+
+1. 测试失败后先读 triage 报告，不要直接盲修。
+2. 若一级分类是：
+   - `TEST_CODE_ISSUE`：可以优先修测试
+   - `PRODUCT_BUG`：优先修业务实现
+   - `REQUIREMENT_CHANGE`：先回规格/测试真相源
+   - `ENV_OR_DATA_ISSUE`：先修环境、seed、权限
+   - `FLAKY`：先修等待/隔离/时序，不要糊 timeout
+3. 若 triage parse 失败或报告缺失，应降级为人工检查 latest trace/log。
+
+## 11. 反模式
+
+不要这样用：
+
+### 反模式 1：把 `/goal` 当 driver 替代品
+
+错误：
+
+- 直接让 `/goal` 自由实现，不走 `task.json`
+
+问题：
+
+- 失去任务边界
+- 失去 trace / commit gate
+
+### 反模式 2：让 `/goal` 覆盖 stop hook
+
+错误：
+
+- stop hook 明确 blocked，但目标仍要求“继续往前冲”
+
+问题：
+
+- 容易导致脏工作区、无意义重试、证据漂移
+
+### 反模式 3：目标写得太宽
+
+错误：
+
+- “持续把这个项目做完”
+
+更好：
+
+- “持续推进当前 Harness 任务队列，严格遵守 task/review/test/trace/commit gate”
+
+## 12. 推荐最小试点方式
+
+不要一开始就在关键生产仓库全量依赖 `/goal`。
+
+建议试点顺序：
+
+1. 选一个已完成 bootstrap 的 Harness 项目。
+2. 任务规模控制在 2-5 个 runnable task。
+3. 先人工跑一轮 driver，确认链路干净。
+4. 再开 `/goal` 跑一个夜间周期。
+5. 第二天检查：
+   - `progress.txt`
+   - latest trace
+   - failure-triage 报告
+   - stop hook continuation 次数
+6. 只要出现空转或频繁重复 blocker，就先收紧目标文案，再继续试。
+
+## 13. 当前仓库的推荐结论
+
+当前仓库最适合的默认建议是：
+
+- `/goal`：可选、外层、用户级
+- stop hook：内层、治理门
+- driver：主执行链
+
+短期不建议：
+
+- 把 `/goal` 直接接进 driver 主逻辑
+- 让 stop hook 反向控制 goal 状态
+- 再造第二套长期运行状态文件
+
+## 14. 参考
+
+- OpenAI Codex app commands: `https://developers.openai.com/codex/app/commands`
+- OpenAI Codex use cases: `https://developers.openai.com/codex/use-cases`
+- 本仓库分析：`harness-analysis/13-goal-mode-vs-stop-hook-continuation.md`
+- 当前 driver：`tools/harness/codex-loop.ps1`
+- 当前 stop hook：`tools/harness/hook-stop-verify.ps1`

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/implementation-flow.md

@@ -79,12 +79,17 @@ bootstrap baseline
 | Bootstrap | 当前包仓库和目标 Git 仓库 | 根 runtime、`.codex/`、`.agents/`、docs 模板 | `tools\harness\verify.ps1` 通过，工作区有清晰 baseline |
 | Smoke | `tools\harness\templates\smoke-task.json` | `progress.txt`、`traces/*.json`、一次 driver 提交 | driver、trace、progress、commit 链路可用 |
 | 需求收敛 | spec、PRD、访谈、现有代码 | `docs/product/`、`docs/context/`、`docs/design/` | P0/P1 需求有 Requirement IDs 和验收边界 |
-| 测试左移 | 需求、设计、风险 | `docs/testing/*` | 验收示例、追溯矩阵、测试数据、证据路径齐备 |
+| 测试左移 | 需求、设计、风险、repo map / code intelligence 摘要 | `docs/testing/*` | 验收示例、追溯矩阵、测试数据、证据路径齐备；高风险用户可见任务已明确是否需要 `e2e-plan.md` |
 | 任务队列 | `tools\harness\templates\project-task-template.json` | 真实 `task.json` | 无 smoke 占位，依赖、owned paths、test_command 可执行 |
 | 实现执行 | `task.json` 当前未完成任务 | 代码/文档改动、测试输出、trace、commit | Stage 1、test_command、Stage 2 全部通过 |
 | Release | 已完成用户故事 | affected tests、P0/P1 回归、视觉/契约证据 | fresh evidence 可追溯 |
 | Archive | trace、progress、review、failure triage | `docs/knowledge/*`、候选报告 | 可复用经验归档，不越权提升规则 |
 
+补充约束：
+
+- 进入高风险前端或用户可见业务流实现前，先从 `docs/ai/repo-map.md` 或等价导航文件识别入口、调用链和受影响测试。
+- 失败归因先走 `failure-triage.md` 的一级分类，再决定修测试、修业务、更新规格还是处理环境。
+
 ## 5. Driver 单任务执行流程
 
 `tools\harness\codex-loop.ps1` 每次只处理一个 `passes: false` 且依赖已满足的任务。核心流程是：
@@ -185,6 +190,13 @@ INIT-001
 
 `tools\harness\verify.ps1` 是包级 sanity check，默认至少运行 `git diff --check`，并检查 package freshness、hook 配置兼容性、PowerShell 语法和过时引用。具体项目的业务验证仍由每个 task 的 `test_command` 决定。
 
+当 `task.test_command` 失败时，driver 现在会自动追加一轮只读 `failure-triage`：
+
+- 输入任务 ID、Requirement IDs、验收标准、testing truth source、测试日志和原始测试输出。
+- 先做一级分类：`TEST_CODE_ISSUE`、`PRODUCT_BUG`、`REQUIREMENT_CHANGE`、`ENV_OR_DATA_ISSUE`、`FLAKY`。
+- 输出结构化 JSON 报告到当前 task trace 目录。
+- 把 triage 报告路径写入 trace 和 `progress.txt` 备注，便于后续 repair queue 或人工接管。
+
 ## 8.1 Stop Hook 治理自迭代
 
 Stop hook 是每轮会话结束前的治理入口，不只检查是否还有 runnable task。当前模板链路是：

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/implementation-guide.md

@@ -12,12 +12,14 @@
 4. 补齐 `docs/product/`、`docs/design/`、`docs/context/dev-plan.md`。
 5. 在生成真实 `task.json` 之前，先补齐 `docs/testing/ACCEPTANCE_CRITERIA.md`、`ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md`、`TEST_STRATEGY.md`、`TEST_DATA_MATRIX.md`、`RISK_BASED_TEST_PLAN.md`、`REGRESSION_PLAN.md`、`EVIDENCE_PROTOCOL.md`、`test-matrix.md`、`verify-matrix.md`。
 6. 用 `tools/harness/templates/project-task-template.json` 生成真实 `task.json`。
-7. 运行 `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`tools/harness/codex-loop.ps1 -RunUntilDone`。
+7. 如需在 Codex app 中启用长期目标模式，确认 `.codex/config.toml` 已开启 `features.goals = true`，并先阅读 `docs/codex-harness-engineering/goal-harness-integration-guide.md` 和 `docs/codex-harness-engineering/examples/goal-templates.md`。
+8. 运行 `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`tools/harness/codex-loop.ps1 -RunUntilDone`。
 
 ## 原则
 
 - 不在未提交的混合改动上启动 driver。
 - 不保留额外执行工作区和外部 worker 说明。
 - 正式任务队列建立前，先让 testing truth source 成为实现前 gate。
+- `/goal` 只作为外层长期目标控制面，不替代 `task.json + codex-loop.ps1 + stop hook`。
 - Stage 17 只做 fresh evidence、affected tests 和回归确认，不承担第一次补测试范围。
 - 所有完成声明都必须回到 `progress.txt`、`traces/` 和验证命令。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/mode-matrix.md

@@ -2,33 +2,56 @@
 
 ## 1. Summary
 
-当前安装包只保留 `full` 模式。SpecKit 的 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们服务于 `task.json + tools/harness/codex-loop.ps1` 的 driver-first 主链路，不再提供独立轻量 stop hook 安装形态。
+当前安装体系同时保留 `user`、`project`、`vendor`、`full` 四种模式，但它们暴露的是不同层能力，不应混成一个概念：
 
-| 字段 | full |
+| 模式 | 主要定位 |
 | --- | --- |
-| 适用场景 | 长期业务项目、需求收敛、实现、验证和归档都走同一套 driver 闭环 |
-| 状态源 | `task.json` |
-| 执行入口 | `tools/harness/codex-loop.ps1` |
-| 提交责任 | driver |
-| trace 责任 | driver 写 `traces/*.json` |
-| 验证入口 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` |
-| 禁区 | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 |
+| `user` | 用户级共享能力层，更适合全局技能、规则和类似 `/goal` 的外层长期目标控制习惯 |
+| `project` | 项目根 runtime + truth source，适合 driver-first、stop hook、trace、verify 闭环 |
+| `vendor` | 离线 / 隔离环境下的完整 package 镜像复制 |
+| `full` | `project` runtime + 完整 `.agents/` package assets，适合长期驻留的完整 Harness 项目 |
+
+其中：
+
+- **外层目标控制** 更适合放在 `user` 层使用。
+- **仓库级持续执行与治理** 更适合放在 `project` / `full` 层使用。
+
+| 字段 | user | project | vendor | full |
+| --- | --- | --- | --- | --- |
+| 适用场景 | 全局规则、共享技能、外层长期目标控制 | 目标项目最小 driver-first 闭环 | 离线 / 隔离复制完整包 | 长期业务项目的完整 Harness 工程 |
+| 状态源 | 用户环境 | `task.json` | 以复制的 package 为主 | `task.json` |
+| 执行入口 | 用户级 Codex / CLI / App | `tools/harness/codex-loop.ps1` | 按目标环境决定 | `tools/harness/codex-loop.ps1` |
+| 提交责任 | 不负责项目提交 | driver | 不默认承担项目提交 | driver |
+| trace 责任 | 无项目级 trace 保证 | driver 写 `traces/*.json` | 取决于目标环境 | driver 写 `traces/*.json` |
+| 验证入口 | 用户自定义 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` | 取决于目标环境 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` |
+| 持续运行定位 | 可承载 `/goal` 这类外层长期目标控制 | stop hook + driver continuation | 取决于复制后的目标环境 | 同时具备 `project` 执行面和 `.agents/` 能力包 |
+| 禁区 | 不应假装拥有项目级 gate | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 | 不应误当作项目执行协议本身 | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 |
 
 ## 2. Installation Outputs
 
 | 模式 | 必备安装产物 |
 | --- | --- |
-| full | `AGENTS.md`、`tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`tools/install/env-check.ps1`、`task.json`、`.codex/*`、`docs/harness/*`、`docs/testing/*`、`.codex/rules/*`、`.agents/workflows/*`、`.agents/.specify/*`、`.agents/skills/*` |
+| user | 共享 package assets、全局规则/技能入口，不要求目标项目先具备完整 runtime |
+| project | `AGENTS.md`、`tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`task.json`、`.codex/*`、`docs/harness/*`、`docs/testing/*`、`docs/ai/*` |
+| vendor | `.agents/` 下的完整 package 镜像、模板和 skills/workflows |
+| full | `project` runtime 产物 + `.agents/workflows/*`、`.agents/.specify/*`、`.agents/skills/*` 等完整能力包 |
 
 ## 3. Ownership Rules
 
-| 字段 | full |
+| 字段 | project / full |
 | --- | --- |
 | 当前任务边界 | `task.json` 当前 task 的 `owned_paths`、`dependencies`、`test_command` |
 | 提交者 | `tools/harness/codex-loop.ps1` 或任务收尾流程 |
 | 失败记录 | `progress.txt` + `traces/*.json` |
 | 允许的运行产物 | `task.json`、`progress.txt`、`traces/`、显式 `non_blocking_dirty_paths` |
 
+`user` 和 `vendor` 模式本身不应宣称拥有上述项目级 ownership gate；它们更多提供共享控制面或分发面。
+
 ## 4. SpecKit Usage
 
 SpecKit 仍用于生成或完善 `spec.md`、`plan.md`、testing truth sources 和任务拆解输入。方案确认后，应把结果转成 `tools/harness/templates/project-task-template.json` / `task.json`，再交给 `tools/harness/codex-loop.ps1` 执行。
+
+如果未来要把 Codex `/goal` 纳入长期运行体验，推荐分层是：
+
+- `user` 层承载 `/goal` 这类长期目标控制习惯
+- `project` / `full` 层承载 driver-first 的仓库执行协议

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/README.md

@@ -1057,6 +1057,13 @@ Codex macOS 应用：
 | api-design | REST API 设计模式 |
 | verification-loop | 构建、测试、代码检查、类型检查、安全 |
 
+### Harness / Codex 项目补充
+
+如果你把 ECC / Codex 用在带 `AGENTS.md`、`docs/ai/repo-map.md`、`docs/testing/*` 的工程中，建议额外遵守两条：
+
+1. 涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环时，先从 `docs/ai/repo-map.md` 或等价代码地图进入代码结构，再进入具体实现。
+2. 这类高风险任务在进入实现或 E2E 代码生成前，先补齐 `docs/testing/e2e-plan.md`；测试失败后先做 `TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY` 一级分类，再决定修复路径。
+
 ### 关键限制
 
 Codex **尚未提供与 Claude 风格同等的钩子执行功能**。ECC 在该平台上的强制执行是通过 `AGENTS.md`、可选的 `model_instructions_file` 覆盖以及沙箱/批准设置以指令方式实现的。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/e2e.md

@@ -29,11 +29,14 @@ description: 使用 Playwright 生成并运行端到端测试。创建测试旅
 e2e-runner 代理将：
 
 1. **分析用户流程**并识别测试场景
-2. **使用页面对象模型模式生成 Playwright 测试**
-3. **跨多个浏览器（Chrome、Firefox、Safari）运行测试**
-4. **捕获失败**，包括截图、视频和跟踪
-5. **生成包含结果和工件的报告**
-6. **识别不稳定测试**并推荐修复方法
+2. **优先从 `docs/ai/repo-map.md` 或等价代码地图进入代码结构**，再补局部页面、接口和测试入口
+3. **使用页面对象模型模式生成 Playwright 测试**
+4. **跨多个浏览器（Chrome、Firefox、Safari）运行测试**
+5. **捕获失败**，包括截图、视频和跟踪
+6. **生成包含结果和工件的报告**
+7. **识别不稳定测试**并推荐修复方法
+
+如果仓库已经采用 Harness testing truth sources，建议先补齐 `docs/testing/e2e-plan.md`，再让 `/e2e` 落测试代码。对于只读研究阶段，应先通过 `repo-map`、验收示例、追溯矩阵和验证矩阵确定范围，而不是直接全仓扫描。
 
 ## 使用示例
 
@@ -254,6 +257,18 @@ WARNING:  FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
 隔离建议: 在修复前标记为 test.fixme()
 ```
 
+## 失败处理顺序
+
+不要在失败后第一时间弱化断言或跳过测试。先分类：
+
+1. `TEST_CODE_ISSUE`
+2. `PRODUCT_BUG`
+3. `REQUIREMENT_CHANGE`
+4. `ENV_OR_DATA_ISSUE`
+5. `FLAKY`
+
+然后再进入 owner 级归因和修复动作。对于 Harness 项目，建议把分类结果同步到 `docs/testing/failure-triage.md`。
+
 ## 浏览器配置
 
 默认情况下，测试在多个浏览器上运行：

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/harness-surface-sync/references/stale-patterns.md

@@ -48,6 +48,9 @@ Common stale surfaces:
 - `test-planner` described only as “test matrix”
 - `test-runner` described only as “reports”
 - no mention of acceptance examples, traceability, affected tests, or fresh evidence in config/role docs
+- high-risk user-visible tasks described with no mention of `e2e-plan.md`
+- code-intelligence / impact-analysis wording that does not mention `repo-map.md`, codemap, or equivalent AI navigation entry
+- failure-triage wording that jumps straight to owner without a primary failure class such as test issue / product bug / requirement change / env-data issue / flaky
 
 ## Recommended First Scan
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/qa-e2e-planner/SKILL.md

@@ -16,13 +16,14 @@ description: 专门扫描前端工程，生成零幻觉、元素级的端到端
 严格按照 **"扫描 -> 计划 -> 审核 -> 生成任务"** 的顺序执行，不得越级跳步：
 
 1. **深度扫描组件 (Mock & DOM 提取)**
+   - 若项目存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类 codemap，先阅读导航文件定位前端入口、路由、状态源和测试相关目录，再进入具体组件；禁止上来就全仓盲扫。
    - 必须通过底层文件 API (`find_by_name` / `list_dir` / `view_file`) 全面读取当前正在开发或测试的 Vue/React 视图组件文件。
    - 提取 `<template>` 中所有的交互式控件，例如：`<button>`、`<input>`、`<select>` 等。
    - 通过 `grep_search` 或深度读取，检索代码中 `mock`、`MockStateWrapper` 等硬编码虚拟数据的痕迹。
 
 2. **导出标准化测试大纲 (e2e-plan.md)**
    - 根据收集到的待测点与排雷点，调用模板 `.agents/.specify/templates/e2e-plan-template.md`。
-   - 分章节输出：**Mock 排雷清单**、**各页面元素级断言**（即测试用例）、**CRUD 闭环业务流**。
+   - 分章节输出：**代码入口与影响面**、**Mock 排雷清单**、**各页面元素级断言**（即测试用例）、**CRUD 闭环业务流**。
    - ⚠️ **输出路径强制规范**：必须使用 `write_to_file` 将文件写入**项目根目录**（即与 `frontend/`、`backend/` 同级），路径为 `<项目根路径>/e2e-plan.md`。**绝对禁止**将此文件写入 artifact 目录（`~/.gemini/...`）。
    - **注意**：大纲生成完毕后必须立即挂起操作。
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/qa-e2e-runner/SKILL.md

@@ -14,7 +14,8 @@ description: 根据 e2e-plan.md 纯粹地唤起并调度 browser_subagent 进行
 ## 工作流 (Workflow)
 
 1. **装载测试计划**
-   - 强行切入到 `e2e-plan.md`。解读其中的所有的元素和交互基准，特别是 **10 维度断言** 和 **CRUD 全生命周期测试流水线**。
+   - 若项目存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类 codemap，先读取导航文件确认页面入口、路由、状态源和关联测试目录，再切入 `e2e-plan.md`。
+   - 解读 `e2e-plan.md` 中的所有元素和交互基准，特别是 **代码入口与影响面**、**10 维度断言** 和 **CRUD 全生命周期测试流水线**。
 
 2. **执行自动化测试闭环**
    - 唤起执行测试的主程序 (通过 `browser_subagent` 或者关联测试框架驱动如 Playwright/Cypress，取决于本地支持)。
@@ -23,4 +24,4 @@ description: 根据 e2e-plan.md 纯粹地唤起并调度 browser_subagent 进行
 
 3. **收录与报告输出**
    - 构建 `qa-e2e-report.md` 测试报告文件，对比原计划中的每一个勾选项标记 Pass 或是 Fail。
-   - 如果发生阻断错误（Fail），提供详尽的终端输出日志摘录，或页面元素截图证据供研发人员回溯修复。
+   - 如果发生阻断错误（Fail），先按 `TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY` 做一级分类，再提供详尽的终端输出日志摘录或页面元素截图证据供研发人员回溯修复。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/qa-mock-cleaner/SKILL.md

@@ -14,7 +14,8 @@ description: 专门依据 e2e-plan.md 执行前端 Mock 数据依赖的扫除行
 ## 工作流 (Workflow)
 
 1. **获取排雷计划**
-   - 读取目标路径中的 `e2e-plan.md` 文件的 "Mock 依赖排雷清单" 章节。
+   - 若项目存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类 codemap，先读取导航文件定位页面入口、Mock 所在目录和真实接口边界。
+   - 读取目标路径中的 `e2e-plan.md` 文件的 "代码入口与影响面"、"Mock 依赖排雷清单" 章节。
    - 精准定位被指出的那些 `.vue` 页面文件或 `src/mock/` 目录下的拦截文件。
 
 2. **精细化剥离与真实接口替换**

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/speckit-e2e-tasks/SKILL.md

@@ -19,13 +19,14 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 1. **Setup & Component Discovery**:
    - 阅读目标特性目录的 `tasks.md`（或 `plan.md`），获取目前的 Task ID 增长规律（如 `<!-- id: X0 -->` 系列）以及涉及的页面。
+   - 若项目存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类 codemap，先读取导航文件锁定前端入口、页面目录、状态源和测试相关目录，禁止无边界全仓扫描。
    - **强制遍历指令:** 必须使用 `find_by_name` 或 `list_dir` 锁定 `frontend/src/pages/`、`views/` 等目录下具体的 `.vue` 页面文件列表。
    - 必须基于上述页面采用 `grep_search` 或深度读取源码，搜索 `mock` 关键字、组件属性写死数组等，精准生成无幻觉的 “Mock依赖排雷清单”。
 
 2. **Element Deep Extraction & Generate Standardized e2e-plan.md**:
    - 调用并克隆参考模板 `.agents/.specify/templates/e2e-plan-template.md`。
    - **强制源码解构:** 严禁自由联想。必须通过 `view_file` 彻底读取所有相关 `.vue` 文件的 `<template>` 结构。精准提取出所有的 `<button>`、`<input>`、`el-select/a-select` 等交互控件，以及 `v-if`/`v-show` 所定义的动态状态(加载屏、空态、报错视图)。
-   - 将这些确凿的交互元素清单对应填入模板的 **“2.元素级扫描”** 和 **“3. CRUD 闭环”** 中，并强制与 [D1-D10] 维度进行绑定映射。
+   - 将这些确凿的交互元素清单对应填入模板的 **“代码入口与影响面”**、**“2.元素级扫描”** 和 **“3. CRUD 闭环”** 中，并强制与 [D1-D10] 维度进行绑定映射。
    - 将最终结构化分析的结果保存至对应的特性目录 (例如 `specs/xxx/e2e-plan.md`)。
 
 3. **Append Tasks using Strict `Speckit Tasks` Format (CRITICAL)**:
@@ -50,4 +51,4 @@ You **MUST** consider the user input before proceeding (if not empty).
 ```
 
 4. **Report to User**:
-   - 通知用户该特性的 E2E 大纲及其配套的 tasks 生成完毕。提醒使用者若计划无误即可使用 `/speckit.implement` 执行排雷，最后再调用 `/browser-e2e-testing` 运行测例。
+   - 通知用户该特性的 E2E 大纲及其配套的 tasks 生成完毕。提醒使用者若计划无误即可使用 `/speckit.implement` 执行排雷，最后再调用 `/browser-e2e-testing` 运行测例；测试失败后先按 `TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY` 做一级归因。

package/package-source/docs/codex-harness-engineering/templates/package-assets/workflows/speckit.e2e-testing.md

@@ -14,16 +14,18 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 This workflow analyzes the current frontend interface, meticulously examines code for mocked data, and generates a robust E2E test plan (`e2e-plan.md`) along with standard OpenSpec tasks in `tasks.md`. By generating E2E test cases during the OpenSpec Planning phase (Test-Left), you ensure that:
 1. **Zero-Mock Assurance**: No frontend interfaces rely on fake or mocked data; everything connects to real backend APIs.
-2. **Exhaustive Coverage**: Every single interactive UI element (buttons, inputs, dropdowns) is mapped out and verified.
-3. **CRUD Reliability**: Core business entities seamlessly undergo Create, Read, Update, and Delete testing sequences without breakage.
+2. **Code-Intelligence First**: Start from `docs/ai/repo-map.md` or equivalent codemap when present, so page discovery and impact analysis are bounded by known entry points.
+3. **Exhaustive Coverage**: Every single interactive UI element (buttons, inputs, dropdowns) is mapped out and verified.
+4. **CRUD Reliability**: Core business entities seamlessly undergo Create, Read, Update, and Delete testing sequences without breakage.
 
 ## Outline
 
-1. **Context & Mock Extraction**: Read the frontend views (`src/pages`, `src/views`) identified by the feature spec. Rigorously check for the presence of mocked data or hardcoded dependencies. Flag these for mandatory cleanup.
+1. **Context & Mock Extraction**: Read `docs/ai/repo-map.md` or equivalent codemap when present, then inspect the frontend views (`src/pages`, `src/views`) identified by the feature spec. Rigorously check for mocked data or hardcoded dependencies. Flag these for mandatory cleanup.
 2. **Element Traversal Analysis**: Iterate across all extracted interactive UI elements. Generate dedicated natural language `browser-subagent` commands to test bounds and interactions.
 3. **CRUD Sequence Design**: Construct a cohesive execution sequence connecting Create -> Read -> Update -> Delete scenarios to validate the full business lifecycle.
-4. **Plan Output (`e2e-plan.md`)**: Produce an `e2e-plan.md` detailing the exhaustive test cases structured around the 10 dimensions of E2E verification.
+4. **Plan Output (`e2e-plan.md`)**: Produce an `e2e-plan.md` detailing code entry points, impact scope, exhaustive test cases, and the 10 dimensions of E2E verification.
 5. **Task Population (`tasks.md`)**: Append testing tasks into your `tasks.md`. Include an explicit task to clean up mock references, and a task to execute the E2E suites.
+6. **Failure Handling**: If later execution fails, classify the failure first as `TEST_CODE_ISSUE`, `PRODUCT_BUG`, `REQUIREMENT_CHANGE`, `ENV_OR_DATA_ISSUE`, or `FLAKY` before selecting the repair path.
 
 ## Task Format Rules