@pzy560117/codex-harness 0.1.3 → 0.1.5

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

@@ -1,380 +1,380 @@
-# `/goal` 目标启动模板库
-
-## 1. 先说结论
-
-这里不是“自由目标文案库”，而是 **`/goal` 启动模板库**。
-
-原因很简单：
-
-- 真正定义“做什么”的，不是 `/goal`。
-- 真正定义“怎么拆任务”的，不是 `/goal`。
-- 真正定义“能不能完成”的，也不是 `/goal`。
-
-在当前 Harness 体系里，这三件事分别由下面几层承担：
-
-| 层 | 负责什么 |
-| --- | --- |
-| spec / PRD / design / testing truth source | 定义目标、范围、验收、风险、非目标 |
-| `task.json` | 定义可执行任务队列、依赖、owned paths、验证命令 |
-| `/goal` | 只负责外层长期目标保持、持续推进和人机 steering |
-
-所以这里的模板，更准确的名字应该理解成：
-
-- **goal launch profiles**
-- **goal wrappers**
-- **goal control prompts**
-
-而不是“随便写一个长期目标让它自己跑”。
-
-## 2. `/goal` 和 spec / task.json 的区别
-
-### 2.1 spec / truth source 解决什么问题
-
-spec、设计、测试真相源回答的是：
-
-- 为什么要做
-- 做到什么算完成
-- 不做什么
-- 哪些路径高风险
-- 哪些证据必须存在
-
-### 2.2 `task.json` 解决什么问题
-
-`task.json` 回答的是：
-
-- 先做哪个任务
-- 哪些任务有依赖
-- 哪个任务接管哪些路径
-- 每个任务要跑什么验证命令
-
-### 2.3 `/goal` 解决什么问题
-
-`/goal` 回答的是：
-
-- 在长时间运行里，系统持续朝哪个方向推进
-- 用户暂停、恢复、修改目标时，外层控制面怎么表达
-- 遇到 stop hook / failed trace / triage 结果时，是继续、保守、还是停下等人
-
-所以它本质上是：
-
-```text
-持续运行控制模板
-```
-
-不是：
-
-```text
-需求模板
-```
-
-也不是：
-
-```text
-任务模板
-```
-
-## 3. 使用前提
-
-任何 `/goal` 模板启用前，都要先确认下面这些已经存在：
-
-### 最小前提
-
-1. `task.json` 已经是真实任务队列，不是 smoke 占位。
-2. 已有 `docs/ai/repo-map.md` 或等价导航文件。
-3. 已有基本 testing truth source：
-   - `ACCEPTANCE_EXAMPLES.md`
-   - `TRACEABILITY_MATRIX.md`
-   - `TEST_DATA_MATRIX.md`
-   - `verify-matrix.md`
-
-### 高风险用户可见任务额外前提
-
-4. 已有 `docs/testing/e2e-plan.md`
-5. 已明确 `failure-triage.md`
-
-### 运行前检查
-
-6. `tools/harness/doctor.ps1` 通过
-7. `tools/harness/verify.ps1` 通过
-8. 工作区不是未解释的脏状态
-
-如果这些前提不成立，不要直接开 `/goal`。
-
-## 4. 模板字段说明
-
-下面每个模板都建议显式包含 6 类信息：
-
-### A. 目标对象
-
-- 当前 feature / release / recovery scope
-
-### B. 依赖的真实真相源
-
-- `AGENTS.md`
-- `docs/ai/repo-map.md`
-- `docs/testing/*`
-- `task.json`
-
-### C. 执行动作
-
-- 通过 `tools/harness/codex-loop.ps1 -RunUntilDone` 推进
-
-### D. 停止条件
-
-- 没有 runnable task
-- stop hook block
-- failed trace
-- 人工 blocker
-
-### E. 禁止事项
-
-- 不绕过 `task.json`
-- 不绕过 `test_command`
-- 不绕过 review / trace / commit gate
-
-### F. 失败处理
-
-- 优先读取 `failure-triage` 结果
-
-## 5. 模板 01：标准持续推进
-
-### 适用场景
-
-- 已有明确 spec
-- 已有真实任务队列
-- 需要连续推进多个任务
-
-### 启动模板
-
-```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，不自行猜测。
-```
-
-### 适合的跟进消息
-
-```text
-继续按当前任务队列推进，不新增范围。优先完成已经 runnable 的任务。
-```
-
-## 6. 模板 02：夜间长跑
-
-### 适用场景
-
-- 白天人工确认过状态
-- 夜间希望继续推进
-- 更关注稳态而不是速度
-
-### 启动模板
-
-```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 结果、是否需要人工。
-```
-
-### 适合的跟进消息
-
-```text
-进入保守夜间模式：如果同一 blocker 连续出现，不要反复重试，直接停下并报告。
-```
-
-## 7. 模板 03：高风险用户可见功能
-
-### 适用场景
-
-- 路由
-- 表单
-- 权限
-- 状态流转
-- 关键 UI 主流程
-
-### 启动模板
-
-```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 冒充真实交付路径。
-```
-
-### 适合的跟进消息
-
-```text
-先确认 e2e-plan 和影响面，不要为了前进速度绕过用户可见路径的测试计划。
-```
-
-## 8. 模板 04：恢复性目标
-
-### 适用场景
-
-- 上一轮 stop hook 强制继续
-- 早上接手夜间运行
-- 测试刚失败，需要恢复执行链
-
-### 启动模板
-
-```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，输出需要人工处理的最小动作，不要空转。
-```
-
-### 适合的跟进消息
-
-```text
-先恢复上下文，不要直接重跑实现；先解释最近一次失败和当前是否真的可继续。
-```
-
-## 9. 模板 05：Release 收口
-
-### 适用场景
-
-- 多个故事已完成
-- 进入 P0/P1 回归
-- 需要收口而不是再发散实现
-
-### 启动模板
-
-```text
-持续推进当前 release 收口，但不新增新功能范围。目标是完成当前 task.json 中与 release 相关的 runnable task，并输出 fresh evidence。
-
-约束：
-1. 优先处理 P0/P1 回归、契约验证、e2e/视觉证据和 failure-triage。
-2. 不新增新的 feature 实现任务，除非任务队列本身已经声明。
-3. 如果发现问题，优先归因到现有 story 或 release blocker，不要模糊扩写需求。
-4. 没有 fresh evidence 就不要声称 release 完成。
-```
-
-### 适合的跟进消息
-
-```text
-收口优先，不再扩 scope。失败项先归因到现有 blocker，再决定是否需要 repair。
-```
-
-## 10. 模板 06：治理修复
-
-### 适用场景
-
-- stop hook 被 governance drift 卡住
-- rules / prompts / docs / mirrors 漂移
-- 需要先修 Harness 面再继续业务开发
-
-### 启动模板
-
-```text
-当前目标不是继续业务功能，而是先修复 Harness 治理面，使 driver 和 stop hook 能重新进入稳定运行状态。
-
-约束：
-1. 优先读取 AGENTS.md、docs/harness/governance-auto-repair.md、docs/harness/rule-governance.md、.codex/rules/agents.md。
-2. 只修与当前治理失败直接相关的 runtime/docs/template/package-assets 面。
-3. 业务实现不是当前目标，除非治理修复明确要求一起同步。
-4. 修复完成后重新运行 verify / doctor，再决定是否恢复原目标。
-```
-
-### 适合的跟进消息
-
-```text
-优先恢复治理面，不继续业务功能。只处理当前 stop hook / verify 报出的直接问题。
-```
-
-## 11. 模板 07：人工旁路保守模式
-
-### 适用场景
-
-- 人工希望介入更多
-- 不希望系统自由选择太多 repair 动作
-- 高风险上线前夕
-
-### 启动模板
-
-```text
-持续推进当前 Harness 项目，但进入人工旁路保守模式。
-
-规则：
-1. 只推进 task.json 中已经 runnable 的任务。
-2. 遇到同一 blocker 或 triage 分类不清时，立即停下请求人工确认。
-3. 不自行扩大范围，不自行改写目标，不自行新增 repair 分支。
-4. 每轮仅报告：当前任务、最近验证、failure-triage 分类、是否建议继续。
-```
-
-### 适合的跟进消息
-
-```text
-进入人工旁路模式：遇到需要策略判断的地方，不要自己选，直接停下问我。
-```
-
-## 12. 这些模板和 spec / task.json 的区别
-
-这是最容易混淆的一点：
-
-### spec / truth source 是“内容层”
-
-定义：
-
-- 业务目标
-- 验收
-- 约束
-- 风险
-
-### `task.json` 是“执行层”
-
-定义：
-
-- 任务顺序
-- 依赖
-- owned paths
-- test_command
-
-### `/goal` 模板是“控制层”
-
-定义：
-
-- 如何持续推进
-- 什么时候停
-- 什么时候保守
-- 遇到失败怎么先归因
-
-所以这里的模板库价值不在“重复写需求”，而在：
-
-- 减少使用 `/goal` 时的外层控制失误
-- 保证 `/goal` 不压过 Harness driver
-
-## 13. 推荐命名
-
-如果后续继续扩充，建议把这一类文案统一叫：
-
-- `goal launch profiles`
-- `goal control templates`
-
-不要叫：
-
-- feature goal specs
-- long-running task specs
-
-因为它们不是在定义业务目标本身。
-
-## 14. 推荐下一步
-
-如果后面还要继续完善，最值得补的不是“更多空泛模板”，而是：
-
-1. 基于真实 Harness 场景补更多 launch profiles。
-2. 补一个“如何从 stop hook / failed trace 自动挑选合适 goal 模板”的决策表。
-3. 如果未来 `user` 安装层正式支持 `/goal`，再把这套模板库明确挂到 user 模式文档里。
+# `/goal` 目标启动模板库
+
+## 1. 先说结论
+
+这里不是“自由目标文案库”，而是 **`/goal` 启动模板库**。
+
+原因很简单：
+
+- 真正定义“做什么”的，不是 `/goal`。
+- 真正定义“怎么拆任务”的，不是 `/goal`。
+- 真正定义“能不能完成”的，也不是 `/goal`。
+
+在当前 Harness 体系里，这三件事分别由下面几层承担：
+
+| 层 | 负责什么 |
+| --- | --- |
+| spec / PRD / design / testing truth source | 定义目标、范围、验收、风险、非目标 |
+| `task.json` | 定义可执行任务队列、依赖、owned paths、验证命令 |
+| `/goal` | 只负责外层长期目标保持、持续推进和人机 steering |
+
+所以这里的模板，更准确的名字应该理解成：
+
+- **goal launch profiles**
+- **goal wrappers**
+- **goal control prompts**
+
+而不是“随便写一个长期目标让它自己跑”。
+
+## 2. `/goal` 和 spec / task.json 的区别
+
+### 2.1 spec / truth source 解决什么问题
+
+spec、设计、测试真相源回答的是：
+
+- 为什么要做
+- 做到什么算完成
+- 不做什么
+- 哪些路径高风险
+- 哪些证据必须存在
+
+### 2.2 `task.json` 解决什么问题
+
+`task.json` 回答的是：
+
+- 先做哪个任务
+- 哪些任务有依赖
+- 哪个任务接管哪些路径
+- 每个任务要跑什么验证命令
+
+### 2.3 `/goal` 解决什么问题
+
+`/goal` 回答的是：
+
+- 在长时间运行里，系统持续朝哪个方向推进
+- 用户暂停、恢复、修改目标时，外层控制面怎么表达
+- 遇到 stop hook / failed trace / triage 结果时，是继续、保守、还是停下等人
+
+所以它本质上是：
+
+```text
+持续运行控制模板
+```
+
+不是：
+
+```text
+需求模板
+```
+
+也不是：
+
+```text
+任务模板
+```
+
+## 3. 使用前提
+
+任何 `/goal` 模板启用前，都要先确认下面这些已经存在：
+
+### 最小前提
+
+1. `task.json` 已经是真实任务队列，不是 smoke 占位。
+2. 已有 `docs/ai/repo-map.md` 或等价导航文件。
+3. 已有基本 testing truth source：
+   - `ACCEPTANCE_EXAMPLES.md`
+   - `TRACEABILITY_MATRIX.md`
+   - `TEST_DATA_MATRIX.md`
+   - `verify-matrix.md`
+
+### 高风险用户可见任务额外前提
+
+4. 已有 `docs/testing/e2e-plan.md`
+5. 已明确 `failure-triage.md`
+
+### 运行前检查
+
+6. `tools/harness/doctor.ps1` 通过
+7. `tools/harness/verify.ps1` 通过
+8. 工作区不是未解释的脏状态
+
+如果这些前提不成立，不要直接开 `/goal`。
+
+## 4. 模板字段说明
+
+下面每个模板都建议显式包含 6 类信息：
+
+### A. 目标对象
+
+- 当前 feature / release / recovery scope
+
+### B. 依赖的真实真相源
+
+- `AGENTS.md`
+- `docs/ai/repo-map.md`
+- `docs/testing/*`
+- `task.json`
+
+### C. 执行动作
+
+- 通过 `tools/harness/codex-loop.ps1 -RunUntilDone` 推进
+
+### D. 停止条件
+
+- 没有 runnable task
+- stop hook block
+- failed trace
+- 人工 blocker
+
+### E. 禁止事项
+
+- 不绕过 `task.json`
+- 不绕过 `test_command`
+- 不绕过 review / trace / commit gate
+
+### F. 失败处理
+
+- 优先读取 `failure-triage` 结果
+
+## 5. 模板 01：标准持续推进
+
+### 适用场景
+
+- 已有明确 spec
+- 已有真实任务队列
+- 需要连续推进多个任务
+
+### 启动模板
+
+```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，不自行猜测。
+```
+
+### 适合的跟进消息
+
+```text
+继续按当前任务队列推进，不新增范围。优先完成已经 runnable 的任务。
+```
+
+## 6. 模板 02：夜间长跑
+
+### 适用场景
+
+- 白天人工确认过状态
+- 夜间希望继续推进
+- 更关注稳态而不是速度
+
+### 启动模板
+
+```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 结果、是否需要人工。
+```
+
+### 适合的跟进消息
+
+```text
+进入保守夜间模式：如果同一 blocker 连续出现，不要反复重试，直接停下并报告。
+```
+
+## 7. 模板 03：高风险用户可见功能
+
+### 适用场景
+
+- 路由
+- 表单
+- 权限
+- 状态流转
+- 关键 UI 主流程
+
+### 启动模板
+
+```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 冒充真实交付路径。
+```
+
+### 适合的跟进消息
+
+```text
+先确认 e2e-plan 和影响面，不要为了前进速度绕过用户可见路径的测试计划。
+```
+
+## 8. 模板 04：恢复性目标
+
+### 适用场景
+
+- 上一轮 stop hook 强制继续
+- 早上接手夜间运行
+- 测试刚失败，需要恢复执行链
+
+### 启动模板
+
+```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，输出需要人工处理的最小动作，不要空转。
+```
+
+### 适合的跟进消息
+
+```text
+先恢复上下文，不要直接重跑实现；先解释最近一次失败和当前是否真的可继续。
+```
+
+## 9. 模板 05：Release 收口
+
+### 适用场景
+
+- 多个故事已完成
+- 进入 P0/P1 回归
+- 需要收口而不是再发散实现
+
+### 启动模板
+
+```text
+持续推进当前 release 收口，但不新增新功能范围。目标是完成当前 task.json 中与 release 相关的 runnable task，并输出 fresh evidence。
+
+约束：
+1. 优先处理 P0/P1 回归、契约验证、e2e/视觉证据和 failure-triage。
+2. 不新增新的 feature 实现任务，除非任务队列本身已经声明。
+3. 如果发现问题，优先归因到现有 story 或 release blocker，不要模糊扩写需求。
+4. 没有 fresh evidence 就不要声称 release 完成。
+```
+
+### 适合的跟进消息
+
+```text
+收口优先，不再扩 scope。失败项先归因到现有 blocker，再决定是否需要 repair。
+```
+
+## 10. 模板 06：治理修复
+
+### 适用场景
+
+- stop hook 被 governance drift 卡住
+- rules / prompts / docs / mirrors 漂移
+- 需要先修 Harness 面再继续业务开发
+
+### 启动模板
+
+```text
+当前目标不是继续业务功能，而是先修复 Harness 治理面，使 driver 和 stop hook 能重新进入稳定运行状态。
+
+约束：
+1. 优先读取 AGENTS.md、docs/harness/governance-auto-repair.md、docs/harness/rule-governance.md、.codex/rules/agents.md。
+2. 只修与当前治理失败直接相关的 runtime/docs/template/package-assets 面。
+3. 业务实现不是当前目标，除非治理修复明确要求一起同步。
+4. 修复完成后重新运行 verify / doctor，再决定是否恢复原目标。
+```
+
+### 适合的跟进消息
+
+```text
+优先恢复治理面，不继续业务功能。只处理当前 stop hook / verify 报出的直接问题。
+```
+
+## 11. 模板 07：人工旁路保守模式
+
+### 适用场景
+
+- 人工希望介入更多
+- 不希望系统自由选择太多 repair 动作
+- 高风险上线前夕
+
+### 启动模板
+
+```text
+持续推进当前 Harness 项目，但进入人工旁路保守模式。
+
+规则：
+1. 只推进 task.json 中已经 runnable 的任务。
+2. 遇到同一 blocker 或 triage 分类不清时，立即停下请求人工确认。
+3. 不自行扩大范围，不自行改写目标，不自行新增 repair 分支。
+4. 每轮仅报告：当前任务、最近验证、failure-triage 分类、是否建议继续。
+```
+
+### 适合的跟进消息
+
+```text
+进入人工旁路模式：遇到需要策略判断的地方，不要自己选，直接停下问我。
+```
+
+## 12. 这些模板和 spec / task.json 的区别
+
+这是最容易混淆的一点：
+
+### spec / truth source 是“内容层”
+
+定义：
+
+- 业务目标
+- 验收
+- 约束
+- 风险
+
+### `task.json` 是“执行层”
+
+定义：
+
+- 任务顺序
+- 依赖
+- owned paths
+- test_command
+
+### `/goal` 模板是“控制层”
+
+定义：
+
+- 如何持续推进
+- 什么时候停
+- 什么时候保守
+- 遇到失败怎么先归因
+
+所以这里的模板库价值不在“重复写需求”，而在：
+
+- 减少使用 `/goal` 时的外层控制失误
+- 保证 `/goal` 不压过 Harness driver
+
+## 13. 推荐命名
+
+如果后续继续扩充，建议把这一类文案统一叫：
+
+- `goal launch profiles`
+- `goal control templates`
+
+不要叫：
+
+- feature goal specs
+- long-running task specs
+
+因为它们不是在定义业务目标本身。
+
+## 14. 推荐下一步
+
+如果后面还要继续完善，最值得补的不是“更多空泛模板”，而是：
+
+1. 基于真实 Harness 场景补更多 launch profiles。
+2. 补一个“如何从 stop hook / failed trace 自动挑选合适 goal 模板”的决策表。
+3. 如果未来 `user` 安装层正式支持 `/goal`，再把这套模板库明确挂到 user 模式文档里。