@pzy560117/codex-harness 0.1.1 → 0.1.3

package/README.md

@@ -11,6 +11,13 @@ harness verify
 harness run
 ```
 
+如果目标项目准备在 Codex app 中使用 `/goal` 长时间推进，安装完成后优先阅读：
+
+- `docs/codex-harness-engineering/goal-harness-integration-guide.md`
+- `docs/codex-harness-engineering/examples/goal-templates.md`
+
+`/goal` 只作为外层长期目标控制面，不替代 `task.json + codex-loop.ps1 + stop hook` 主链。
+
 ## Release Assets
 
 GitHub Release assets are built from the repository package source with:

package/lib/powershell/find-powershell.js

@@ -1,3 +1,20 @@
+import { spawnSync } from "node:child_process";
+
+function commandExists(command) {
+  const result = spawnSync(command, ["-NoProfile", "-Command", "$PSVersionTable.PSVersion.ToString()"], {
+    stdio: "ignore",
+    windowsHide: true
+  });
+
+  return result.status === 0;
+}
+
 export function findPowerShell() {
+  for (const candidate of ["pwsh", "powershell"]) {
+    if (commandExists(candidate)) {
+      return candidate;
+    }
+  }
+
   return "powershell";
 }

package/package-source/docs/codex-harness-engineering/templates/config/agents/failure-triage.toml

@@ -10,6 +10,9 @@ Before concluding, read `AGENTS.md`, `docs/harness/task-session-strategy.md`, `.
 Read the matching package skill before classifying failures:
 - `skills/build-error-resolver/SKILL.md`
 Stay read-only.
-Return structured output only: finding id, owner, severity, evidence path, likely cause, and next verification step.
+Classify every failure in two steps:
+1. one primary class: `TEST_CODE_ISSUE` / `PRODUCT_BUG` / `REQUIREMENT_CHANGE` / `ENV_OR_DATA_ISSUE` / `FLAKY`
+2. one secondary owner-oriented category from `docs/testing/failure-triage.md`
+Return structured output only: finding id, primary class, secondary category, owner, severity, evidence path, likely cause, and next verification step.
 Do not repair code or edit files.
 """

package/package-source/docs/codex-harness-engineering/templates/config/agents/test-planner.toml

@@ -6,11 +6,12 @@ sandbox_mode = "read-only"
 
 developer_instructions = """
 You are the test planning auxiliary subagent.
-Before concluding, read `AGENTS.md`, `docs/harness/task-session-strategy.md`, `.codex/rules/agents.md`, the relevant product/design/contract truth sources, and the matching package skills:
+Before concluding, read `AGENTS.md`, `docs/harness/task-session-strategy.md`, `.codex/rules/agents.md`, the relevant product/design/contract truth sources, `docs/ai/repo-map.md` or `docs/context/repo-map.md` when present, and the matching package skills:
 - `skills/qa-e2e-planner/SKILL.md`
 - `skills/test-coverage/SKILL.md`
 - `skills/tdd/SKILL.md`
 Stay read-only.
-Return structured output only: test matrix, coverage gaps, evidence paths, seed data needs, and verification commands.
+Prefer starting from repo map / codemap to identify entry points and affected areas before broad file reads.
+Return structured output only: test matrix, coverage gaps, impacted modules, affected tests, evidence paths, seed data needs, whether an `e2e-plan.md` is required, and verification commands.
 Do not edit files.
 """

package/package-source/docs/codex-harness-engineering/templates/config/codex-config.toml

@@ -19,6 +19,8 @@ approval_policy = "on-request"
 # hooks 作为 stop-gate 增强层默认启用；driver 仍是主链路。
 # Windows 继续以 PowerShell driver 为主，hooks 只负责结束前补一轮 reflection / feedback。
 hooks = true
+# goal mode 作为外层长期目标控制面启用；仓库执行仍回到 task.json + driver + stop hook。
+goals = true
 
 [mcp_servers.anysearch]
 # AnySearch 提供可匿名访问的 Streamable HTTP MCP；需要更高额度时在本机设置 ANYSEARCH_API_KEY 后取消下一行注释。

package/package-source/docs/codex-harness-engineering/templates/config/codex-readme.md

@@ -48,6 +48,8 @@
 
 ## Profile 使用
 
+当前项目模板默认启用 `features.goals = true`，这样 Codex app 可以显示 `/goal`。这只是在产品层打开长期目标控制面，不改变 Harness 的主执行协议；仓库推进仍应回到 `task.json + tools/harness/codex-loop.ps1 + stop hook`。
+
 包内 `profiles.*` 是安装后的推荐配置模板，不保证 `codex -C <path> -p <profile>` 在所有调用场景都会自动读取项目 `.codex/config.toml`。
 
 更稳的方式是：

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

@@ -30,9 +30,10 @@ task.json
 | --- | --- |
 | `README.md` | 当前目录总览 |
 | `START-HERE.md` | 首次进入目录时的分流入口 |
-| `mode-matrix.md` | full 模式的职责、状态源、提交责任、trace 责任和验证入口 |
+| `mode-matrix.md` | `user/project/vendor/full` 的职责边界、状态源、持续运行定位和验证入口 |
 | `best-practices.md` | 任务、上下文、权限、测试、阻塞、提交、回归沉淀的最佳实践 |
 | `implementation-flow.md` | 从 当前仓库包根结构出发说明安装、bootstrap、driver、验证、知识归档和同步的整体实现流程 |
+| `goal-harness-integration-guide.md` | 说明如何把 Codex `/goal` 与 Harness driver/stop hook 结合使用，包含推荐用法和提示词模板 |
 | `harness-analysis-and-practice.md` | GitHub 调研后的 Harness 工程分析、当前安装包工程评估和改进路线图 |
 | `harness-quality-model.md` | 定义好的、好用的、完整的 Harness 工程质量模型、成熟度和评分标准 |
 | `harness-improvement-plan.md` | 基于质量模型和源码审计的 Harness 改进计划，说明每项改哪里、怎么改、如何验收 |
@@ -44,6 +45,7 @@ task.json
 | `templates/docs/frontend-quality-rules.md` | 前端审美、动效、响应式、可访问性、性能和证据要求 |
 | `templates/docs/service-dependency-matrix.md` | 多服务、多仓库、契约和外部系统影响面的可选 truth source 维护口径 |
 | `templates/design/frontend-architecture.md` | 前端页面、feature、组件、状态、API、响应式和测试边界模板 |
+| `examples/goal-templates.md` | `/goal` 启动模板库，强调它是外层控制壳而不是替代 `task.json` / spec 的目标定义 |
 | `templates/` | 可复制模板集中目录 |
 | `templates/docs/project-agents-template.md` | 根据不同项目事实生成项目根 `AGENTS.md` / 子目录 `AGENTS.md` / `CLAUDE.md` 组合的通用模板 |
 
@@ -62,7 +64,8 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\docs\codex-harness-enginee
 6. 如果需要把根 `AGENTS.md` 调整为项目专属规则，按 `templates/docs/project-agents-template.md` 扫描项目事实后裁剪生成，不要原样套模板。
 7. 首次接入时，建议先用 `templates/runtime/smoke-task.json` 验证主链路；一旦 spec / plan 确认，就改用 `templates/runtime/project-task-template.json` 生成正式 `task.json` 并切回 driver。
 8. 正式任务队列落盘前，先补齐 `docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/ACCEPTANCE_EXAMPLES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/verify-matrix.md` 等测试左移真相源。
-9. 运行：
+9. 如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，补齐 `docs/testing/e2e-plan.md`，并先从 `docs/ai/repo-map.md` 进入代码结构后再做实现规划。
+10. 运行：
 
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/best-practices.md

@@ -96,6 +96,12 @@ Windows 不应依赖 Codex hooks 作为主链路。Codex hooks 可以作为结
 - 生成 trace。
 - 提交 Git commit。
 
+同理，Codex 官方 `/goal` 更适合作为**外层长期目标控制面**，而不是直接替代当前仓库的 `task.json + codex-loop.ps1 + stop hook` 执行协议。当前 Harness 的推荐分层仍然是：
+
+- `/goal` 负责长期目标保持和人机 steering
+- driver 负责任务、验证、trace 和提交
+- stop hook 负责停止前治理门和 continuation 决策
+
 要明确区分两层职责：
 
 - 内层 `codex exec` 会话只负责当前任务直接要求的代码或文档改动。

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

@@ -0,0 +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 模式文档里。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/global-rules-and-bootstrap.md

@@ -180,6 +180,11 @@ test-data-plan.md
 e2e-plan.md
 ```
 
+其中：
+
+- `failure-triage.md` 应作为失败一级分类和 owner 二级归因入口，至少区分测试代码问题、产品 Bug、需求变更、环境/数据问题和 Flaky。
+- `e2e-plan.md` 不应对所有任务一刀切；它主要用于涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环的高风险任务。
+
 建议同时初始化代码地图，作为大型项目的检索入口：
 
 ```text
@@ -188,6 +193,8 @@ docs/ai/repo-map.md
 
 如果使用本包模板，可从 `templates/context/repo-map.md` 复制后按项目事实裁剪。根 `AGENTS.md` 只需要索引它，不要把整张代码地图复制进入口文件。
 
+进入实现前，优先从 `docs/ai/repo-map.md` 或等价 codemap 进入代码结构，再补局部文件阅读；不要把大型仓库的首次理解建立在全仓盲扫上。
+
 通过 `tools/install/install-agent.ps1` 或 `tools/install/bootstrap-codex-harness.ps1` 安装时，模板会自动初始化：
 
 ```text
@@ -206,6 +213,8 @@ docs/ai/architecture-brief.md
 
 项目配置只放项目特有内容。能在全局复用的项放到 `~/.codex/config.toml`。
 
+如果目标项目准备在 Codex app 中使用 `/goal` 长时间推进，建议保留模板中的 `features.goals = true`。这只是打开 Goal mode 入口，不会替代 Harness 的 `task.json + codex-loop.ps1 + stop hook` 主链。
+
 ### Step 4: 初始化任务
 
 编辑 `task.json`：
@@ -258,6 +267,13 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.p
  powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1 -RunUntilDone
 ```
 
+如果你想把 `/goal` 作为外层 7x24 控制面来用，先读：
+
+- `docs/codex-harness-engineering/goal-harness-integration-guide.md`
+- `docs/codex-harness-engineering/examples/goal-templates.md`
+
+然后再在 Codex app 中设置 `/goal`。不要跳过 `task.json`、driver 或 stop hook，直接让 `/goal` 自由实现。
+
 ## 5. 新环境初始化步骤
 
 这里指新电脑、新 runner、WSL、新 CI 环境。