@pzy560117/codex-harness 0.1.3 → 0.1.4

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

@@ -1,364 +0,0 @@
-# `/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

@@ -1,288 +0,0 @@
-# Agent Implementation Flow
-
-本文从 当前安装包源码仓库的真实文件结构出发，说明当前 Codex Harness Agent 的整体实现流程。它不是新的流程规范，而是对现有安装、模板、driver、验证、知识归档和同步机制的结构化说明。
-
-## 1. 包的职责边界
-
-当前仓库本身就是一个可分发的 driver-first 能力包，核心职责是把目标项目初始化成可重复执行的 Codex Harness 项目。
-
-| 层级 | 主要文件 | 职责 |
-| --- | --- | --- |
-| 安装入口 | `tools/install/install-agent-here.ps1`、`tools/install/install-agent.ps1` | 把当前仓库的安装资产投影到目标项目，并触发 bootstrap |
-| 项目 runtime | `tools\harness\codex-loop.ps1`、`tools\harness\verify.ps1`、`tools\install\env-check.ps1`、`docs\harness\trace.schema.json` | 在目标项目根目录执行任务、验证、trace 和提交 |
-| 项目规则 | `AGENTS.md`、`rules/*.rules`、`rules/*.md` | `.rules` 约束命令执行策略；Markdown rules 约束主控会话、driver、子代理和项目规则边界 |
-| Codex 配置 | `.codex/config.toml`、`.codex/agents/*.toml`、`.codex/prompts/*.md` | 定义模型、角色、prompt、hook 和 task run profile |
-| Harness 文档 | `docs/harness/*.md` | 解释架构、任务策略、知识、回归、sandbox、trace 和新项目使用方式 |
-| 测试左移 | `docs/testing/*.md` | 在实现前固定验收、示例、追溯、测试数据、风险、证据和回归计划 |
-| 任务模板 | `tools\harness\templates\project-task-template.json`、`tools\harness\templates\smoke-task.json` | 提供正式任务队列和安装 smoke 的起点 |
-| 扩展能力 | `.agents/skills/`、`.agents/workflows/`、`.agents/.specify/` | 提供 SpecKit、skills、规则分发和工程辅助能力 |
-| 分发镜像 | `docs/codex-harness-engineering/templates/`、`templates/package-assets/` | 保存安装复制源和 package 自描述文档 |
-
-当前仓库默认使用 thin project 安装语义，并保留显式 legacy full 兼容入口。SpecKit 仍随包安装，但它只服务于 spec、plan 和 tasks 输入生成；方案确认后必须回到 `task.json + tools\harness\codex-loop.ps1`。
-
-## 2. 从包到项目的安装流程
-
-安装的实际链路如下：
-
-```text
-tools/install/install-agent-here.ps1
-  -> tools/install/install-agent.ps1 -ProjectRoot <target>
-  -> 复制 package-assets 到 <target>/.agents/
-  -> 调用 <target>/tools\install\bootstrap-codex-harness.ps1
-  -> bootstrap 把 runtime/docs/testing/.codex 模板落到项目根
-  -> 可选 InitSmoke / baseline commit
-```
-
-关键点：
-
-- `install-agent-here.ps1` 只负责推断目标项目根，并转调 `tools/install/install-agent.ps1`。
-- `tools/install/install-agent.ps1` 会拒绝在已有 `.agents/` 上静默覆盖，除非显式传入 `-Force`。
-- 如果目标目录不是 Git 仓库，只有传入 `-InitGitIfNeeded` 才会初始化 Git。
-- 安装前工作区不干净时，不会自动 baseline commit，避免把无关改动混入安装提交。
-- 自更新场景下，如果脚本从已安装的 `.agents/` 内运行，会先复制到临时目录，避免边复制边删除源目录。
-
-## 3. Bootstrap 落盘流程
-
-`tools\install\bootstrap-codex-harness.ps1` 是安装后真正把目标项目变成 Harness 项目的脚本。
-
-它负责落盘：
-
-- 根入口：`AGENTS.md`、`tools\harness\codex-loop.ps1`、`tools\harness\verify.ps1`、`tools\install\env-check.ps1`、`docs\harness\trace.schema.json`
-- Codex 配置：`.codex/config.toml`、`.codex/hooks.json`、`.codex/task-run-profile.json`、`.codex/agents/`、`.codex/prompts/`
-- 任务入口：`task.json`、`tools\harness\templates\smoke-task.json`、`tools\harness\templates\project-task-template.json`
-- Harness 文档：`docs/harness/*`
-- Testing truth sources：`docs/testing/*`
-- 服务拓扑 truth source：`.service-matrix/dependencies.yaml`，用于多服务、多仓库、契约或外部系统影响面。
-- Knowledge 初始索引：`docs/knowledge/knowledge-catalog.md`、`docs/knowledge/catalog.md`
-- hook 脚本：`tools/harness/hook-stop-verify.ps1`
-
-`task.json` 已存在时，bootstrap 不会盲目覆盖；它只确保 `runtime.driver` 存在。正式任务队列应从 `tools\harness\templates\project-task-template.json` 裁剪生成，而不是长期使用 smoke 或示例任务。
-
-## 4. 新项目实施流程
-
-目标项目安装后，推荐实施顺序是：
-
-```text
-bootstrap baseline
-  -> smoke task
-  -> product/design/context/testing truth sources
-  -> tools\harness\templates\project-task-template.json -> task.json
-  -> tools\harness\codex-loop.ps1 -RunUntilDone
-  -> release verify
-  -> archive knowledge
-```
-
-每一步的职责：
-
-| 阶段 | 输入 | 输出 | 通过条件 |
-| --- | --- | --- | --- |
-| 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 和验收边界 |
-| 测试左移 | 需求、设计、风险、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` 且依赖已满足的任务。核心流程是：
-
-```text
-读取 task.json
-  -> 选择下一个可执行任务
-  -> 合并 runtime / task-run-profile / task execution policy
-  -> 检查 truth sources
-  -> 创建 task_session_id 和 traces/<task-id>-<session>/
-  -> codex exec 实现阶段
-  -> Stage 1 需求/设计一致性审查
-  -> 运行 task.test_command
-  -> Stage 2 代码质量/测试风险审查
-  -> commit path ownership gate
-  -> task.passes=true
-  -> 写 progress.txt 和 trace
-  -> state compaction 归档旧任务和旧进度
-  -> git commit
-```
-
-失败时的处理：
-
-- truth source 缺失：不进入实现，写 `progress.txt` 和 failed trace。
-- Codex 实现失败或输出 BLOCKED：不跑后续 gate。
-- Stage 1 失败：先修需求、设计、状态或范围偏差。
-- `test_command` 失败：禁止标记 `passes=true`。
-- Stage 2 失败：先修代码质量、测试缺口或维护性风险。
-- commit path ownership gate 失败：说明改动超出 `owned_paths` 或 runtime allowlist，需要拆任务或修正任务边界。
-
-## 6. Task.json 的实现契约
-
-`task.json` 是 driver 的唯一任务状态源。正式任务至少应明确：
-
-- `id`、`description`、`priority`、`dependencies`
-- `passes: false`
-- `task_kind`、`phase`、`gate_profile`
-- `required_truth_sources`
-- `handoff_contract.scope`、`non_goals`、`entrypoints`、`inputs_outputs`、`failure_policy`、`rollback_strategy`、`state_surface`、`writeback_targets`
-- `context_files`
-- `owned_paths`
-- `requirement_ids`
-- `test_command`
-- `acceptance`
-- `execution.mode: single`
-
-`tools\harness\templates\project-task-template.json` 目前按 full 链路组织为：
-
-```text
-INIT-001
-  -> ANALYSIS-001
-  -> DESIGN-001
-  -> PLAN-001
-  -> US1/US2/US3
-  -> RELEASE-001
-  -> ARCHIVE-001
-```
-
-模板只是交接骨架。真实项目必须替换占位的 feature slug、用户故事、Requirement IDs、owned paths、context files 和验证命令。
-
-## 6.1 状态文件压缩与归档
-
-`task.json` 和 `progress.txt` 不能无限增长。driver 模板内置 `runtime.state_compaction`，在成功任务写入 trace 后、`git add` 前自动执行：
-
-- `task.json` 只保留 active queue、未完成任务和最近 `completed_task_retention` 个已完成任务。
-- 旧的已完成任务体写入 `archive/tasks/<task-id>-<timestamp>.json`，完整索引写入 `archive/tasks/index.json`。
-- `task.json.runtime.state_archive.completed_task_ids` 保留归档完成任务 ID，使后续任务依赖仍能判定通过。
-- `progress.txt` 超过 `progress_max_lines` 后只保留最近窗口，旧内容轮转到 `progress/archive/progress-*.log`。
-- 完整审计链路由 `traces/`、`archive/tasks/`、`progress/archive/` 和 Git commit 共同承担。
-
-这条规则的目的不是隐藏历史，而是避免实现会话和子代理反复读取、改写大状态文件时误删任务、错改 `passes` 或把旧失败当成当前状态。AI 只能按需读取近期摘要和相关 trace；不得手工整理 `task.json` / `progress.txt` 来“优化上下文”。
-
-## 7. Prompt、角色与子代理
-
-执行时，driver 通过 `.codex/prompts/implement-one-task.md` 生成单任务实现 prompt，并把当前 task、truth source、owned paths、test command、知识读取要求注入给 Codex。
-
-子代理不是独立状态机，而是单任务实现阶段的受控加速能力：
-
-- 只读角色适合探索、研究、审查、失败归因和测试规划。
-- writer 角色适合明确授权的文档、前端、后端、测试和 harness 文件写入。
-- 实现阶段可以在当前 task `owned_paths` 内使用子代理并行推进，例如前后端分层、测试与实现分离、文档与代码分离、复杂调研与编码分离。
-- 企业级任务可以把 Stage 2 拆成设计一致性、复杂度、并发与状态、错误处理、安全、契约一致性、追溯性和辅助检查等只读 review 维度；这些维度只产出 findings，不产生第二套状态源。
-- 使用 writer 子代理前必须声明 ownership split：允许修改、禁止修改、验收输出和验证命令；多个 writer 不得同时写同一路径。
-- 主控会话需要更新 `task.json`、`AGENTS.md`、`.codex/*`、`.codex/rules/*`、`docs/harness/*` 或 prompt 时，应委派匹配 writer。
-- 子代理启动前必须读取 `AGENTS.md`、`docs/harness/task-session-strategy.md`、`.codex/rules/agents.md` 和相关 skill。
-
-这套设计的目标是提高实现速度，同时避免主控会话和子代理同时伪造 driver 状态。子代理不得修改 `task.json`、`progress.txt`、`traces/` 或 Git 状态；所有完成状态仍回到 `tools\harness\codex-loop.ps1` 的验证、trace 和 Git commit。
-
-## 8. 验证与证据链
-
-当前包把完成定义压到三类证据上：
-
-| 证据 | 文件或命令 | 用途 |
-| --- | --- | --- |
-| 命令证据 | `task.test_command`、`tools\harness\verify.ps1`、`git diff --check` | 判断当前任务是否真的通过 |
-| 过程证据 | `progress.txt`、`traces/*.json`、task session log | 记录失败阶段、命令退出码、review verdict 和文件改动 |
-| 需求证据 | `docs/testing/*`、Requirement IDs、acceptance examples | 证明实现范围和测试覆盖不是事后猜测 |
-
-`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。当前模板链路是：
-
-```text
-Stop hook
-  -> tools/harness/hook-stop-verify.ps1
-  -> git diff --check
-  -> scripts/harness/harness-governance-check.ps1 -WriteExperience
-  -> task/progress/trace gate
-  -> continuation JSON 或 allow stop
-```
-
-`harness-governance-check.ps1` 负责检查：
-
-- `AGENTS.md`、`.codex/`、`docs/harness/`、`docs/codex-harness-engineering/` 是否有 merge marker。
-- `.codex/hooks.json` 是否引用缺失的 `tools/harness/hook-stop-verify.ps1`。
-- `.codex/rules/` 是否缺少官方 `*.rules` 执行策略。
-- `.codex/config.toml` 是否保留无实体 fallback。
-- 最新 trace 是否失败，失败原因应沉淀到哪个治理或测试文档。
-
-失败经验不会直接升级为硬规则。Stop hook 只把 failed trace 摘要去重写入 `docs/harness/governance-auto-repair.md`，并在 continuation JSON 中要求下一轮先读：
-
-- `AGENTS.md`
-- `docs/harness/governance-auto-repair.md`
-- `docs/harness/rule-governance.md`
-- `.codex/rules/agents.md`
-
-后续由 `harness-writer` 或 driver 修复对应路径。只有经过复验且可复用的经验，才允许提升到 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或测试文档。
-
-## 9. 知识闭环
-
-知识系统不是独立产品，而是 driver 执行后的归档层：
-
-```text
-实现任务读取 docs/knowledge/
-  -> 最终输出 knowledge_references / knowledge_outputs
-  -> trace 保留 knowledge_references / knowledge_outputs / archive_summary
-  -> ARCHIVE-001 更新 docs/knowledge/
-  -> knowledge lint 检查索引、冲突、重复、衰减
-  -> 可选 team knowledge sync 输出跨项目候选
-```
-
-约束：
-
-- `draft` 知识只能辅助判断，不作为强阻塞依据。
-- 单次任务经验不得直接升级为 `AGENTS.md` 规则。
-- `verified -> proven` 需要多任务/多项目证据或 maintainer 审批。
-- 团队知识库不可用时，只输出候选报告，不阻塞本地 driver。
-
-## 10. Agent 包自身同步流程
-
-当前仓库本身就是可推送的包根。同步由 `refresh-agent-package.ps1` 和 `.ai-sync.yml` 管理。
-
-典型同步方向：
-
-```text
-root runtime/docs/testing/.codex
-  -> docs/codex-harness-engineering/templates/runtime + docs/*
-  -> agent package-assets
-  -> .agents template mirrors
-```
-
-新增或修改内容时应先判断 canonical：
-
-- runtime 和 driver truth source：优先改 root。
-- human-facing package docs：优先改 `docs/codex-harness-engineering/*.md`。
-- active skills：优先改 `.agents/skills/<name>`，再同步到 package-assets。
-- template package assets：优先改 `docs/codex-harness-engineering/templates/...`，再同步 `.agents/...`。
-
-完成后至少运行：
-
-```powershell
-git diff --check
-powershell -NoProfile -ExecutionPolicy Bypass -Command "& .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot .\agent -CheckOnly -Surface @('docs','runtime','package-assets')"
-```
-
-如果改了 JSON 或 PowerShell，还要分别做 JSON parse 和 PowerShell parser 检查。
-
-## 11. 关键不变量
-
-- `task.json` 是任务状态源；不在聊天里伪造任务完成。
-- `tools\harness\codex-loop.ps1` 是自动执行入口；不要引入第二套 runtime 状态机。
-- driver 每次只处理一个可执行任务。
-- `execution.mode` 当前只支持 `single`。
-- 测试范围必须前置到 `docs/testing/*`，release 阶段只确认 fresh evidence 和回归。
-- 业务代码、文档、`task.json`、`progress.txt`、trace 和 commit 必须形成同一条证据链。
-- 归档沉淀知识，但不重新定义需求范围。
-- 当前仓库可以直接远程推送；如果没有远程，就只做本地提交。

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

@@ -1,25 +0,0 @@
-# 实施指南
-
-## 目标
-
-把当前包接入新项目，并跑通单工作区的 driver-first 闭环。
-
-## 步骤
-
-1. 运行 `tools/install/bootstrap-codex-harness.ps1`。
-2. 提交 bootstrap 基线，确保 Git 工作区干净。
-3. 先用 `tools/harness/templates/smoke-task.json` 做首次自检，确认 driver、trace、progress 和验证入口正常。
-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. 如需在 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/` 和验证命令。