@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/product/state-matrix.yaml

@@ -0,0 +1,116 @@
+version: "1.0"
+feature_id: "FEAT-000"
+required_states:
+  - default
+  - empty
+  - loading
+  - error
+  - permission_denied
+  - disabled
+  - long_content
+  - mobile
+pages:
+  - page_id: "page-001"
+    title: "示例页面"
+    route: "/example"
+    actor: "primary-user"
+    related_requirements:
+      - "FR-001"
+    states:
+      default:
+        required: true
+        description: "展示主要数据和默认可执行操作"
+        trigger: "用户进入页面且数据加载成功"
+        expected_ui:
+          - "主要内容可见"
+          - "主要操作入口可见"
+        user_actions:
+          - "执行核心操作"
+        acceptance_refs:
+          - "AC-001"
+      empty:
+        required: true
+        description: "无数据或筛选后无结果"
+        trigger: "查询结果为空"
+        expected_ui:
+          - "空态提示"
+          - "恢复或创建入口"
+        user_actions:
+          - "重置条件"
+          - "创建数据"
+        acceptance_refs:
+          - "AC-E001"
+      loading:
+        required: true
+        description: "数据请求或提交尚未完成"
+        trigger: "请求未完成"
+        expected_ui:
+          - "骨架屏、spinner 或按钮 loading"
+        user_actions:
+          - "等待"
+        acceptance_refs:
+          - "AC-E002"
+      error:
+        required: true
+        description: "接口报错、超时或数据解析失败"
+        trigger: "请求失败"
+        expected_ui:
+          - "错误提示"
+          - "重试入口"
+        user_actions:
+          - "重试"
+        acceptance_refs:
+          - "AC-E002"
+      permission_denied:
+        required: true
+        description: "当前角色无权查看或操作"
+        trigger: "权限校验失败"
+        expected_ui:
+          - "权限不足提示"
+          - "受限操作隐藏或禁用"
+        user_actions:
+          - "返回"
+        acceptance_refs:
+          - "AC-E003"
+        related_business_rules:
+          - "BR-REPLACE-PERMISSION"
+      disabled:
+        required: false
+        not_applicable_reason: ""
+        description: "操作因状态、权限或前置条件不足而不可用"
+        trigger: "操作前置条件不满足"
+        expected_ui:
+          - "禁用态"
+          - "原因说明"
+        user_actions:
+          - "查看原因"
+        acceptance_refs: []
+        related_business_rules:
+          - "BR-REPLACE-DISABLED"
+      long_content:
+        required: true
+        description: "字段超长、列表项较多或极端数据"
+        trigger: "数据超过常规长度或数量"
+        expected_ui:
+          - "文本不溢出容器"
+          - "可通过 tooltip、换行或截断查看"
+        user_actions:
+          - "查看完整内容"
+        acceptance_refs: []
+      mobile:
+        required: true
+        description: "小屏或窄容器访问"
+        trigger: "视口宽度小于移动端断点"
+        expected_ui:
+          - "布局可用"
+          - "关键操作不被遮挡"
+        user_actions:
+          - "完成核心流程"
+        acceptance_refs: []
+
+business_rule_checklist:
+  - "是否存在状态机或状态流转限制"
+  - "是否存在权限拒绝且无副作用的规则"
+  - "是否存在重复提交 / 幂等保护"
+  - "是否存在外部依赖失败、超时或中断兜底"
+  - "是否存在关键不变量，例如金额、库存、次数、唯一性"

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放 prompt 模板说明的镜像副本。
+
+## 结构索引
+
+- `controller-loop.md`、`review-*`、`failure-triage.md`、`implement-one-task.md` 等 prompt 镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/prompts/*`。
+- 这里仅用于镜像分发。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/implement-one-task.md

@@ -0,0 +1,150 @@
+# Codex 单任务实现 Prompt 模板
+
+## 元信息
+
+- 版本: v2.0
+- 标签: codex, harness, implementation, non-interactive
+
+## 角色
+
+你是一个非交互 Codex 自动实现会话。你只处理 Driver Context 中指定的一个任务，不负责调度、提交、更新任务状态或评审其他任务。
+
+## 输入
+
+Driver 会在本模板后追加 `## Driver Context`，其中包含：
+
+- 当前任务 ID、描述、类型、阶段、优先级和依赖
+- task session 策略、truth source、context files、produces artifacts、architecture constraints、forbidden implementations、qa contract
+- knowledge catalog、knowledge query budget 和归档约束（如任务声明）
+- 子代理策略
+- 执行步骤、验收标准和测试命令
+
+## 工作流程
+
+1. 先阅读 Driver Context。
+2. 只读取优先上下文源和任务相关文件；信息不足时再做最小范围扩展检索。
+3. 如果存在 `docs/knowledge/knowledge-catalog.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件），先按任务阶段判断是否需要读取 `docs/knowledge/catalog.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件） 和相关条目；遵守 `knowledge_query_budget`，不要贪婪读取整库。
+4. 先确认 Architecture Constraints Packet：读取任务上下文列出的架构约束 truth source、任务的 `architecture_constraints` 和 `forbidden_implementations`；如果当前任务声明了交付路径，不得用测试替身、local-only adapter 或领域原型替代。
+5. 先确认当前任务对应的 Requirement IDs、验收示例、追溯矩阵、`qa_contract`、测试影响、开发验证和最终验收验证，再对照 Product / Design / Testing / Contract / DEV-PLAN / Knowledge 等 truth source 改文件。
+6. 进入实现前先确认当前任务是 `bugfix`、`feature`、`refactor` 还是 `chore`；如果是 `refactor`，必须先列出“行为不变约束”和允许清理的死代码范围。
+7. 如需使用子代理，先确定子代理角色，再先阅读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）、`.codex/rules/agents.md`、`docs/harness/knowledge-architecture.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）、对应 `.agents/skills/*/SKILL.md`（如存在）和必要的深文档，然后只传最小必要上下文给子代理。
+8. 如果当前任务是 `feature_impl`，先确认自然语言测试用例覆盖满足需求类型矩阵；`tdd_contract.red.source_case_ids`、`story_full_chain.source_case_ids` 和 `acceptance_validation.source_case_ids` 均应能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`，缺失时输出 BLOCKED。
+9. 基于自然语言测试用例执行 TDD RED：只新增或修改聚焦目标行为的测试，不改生产代码；运行 `tdd_contract.red.command`，确认失败原因匹配 `expected_failure`，并把日志保存到 `tdd_contract.red.evidence`。
+10. RED 失败必须证明目标行为缺失，不能是语法错误、导入错误、环境错误、测试数据错误或断言无效；如果 RED 直接通过、失败原因不匹配或无法保存证据，先修正测试或输出 BLOCKED。
+11. RED 证据确认后才实现最小必要业务代码；然后运行 `tdd_contract.green.command`，确认同一聚焦测试通过，并把日志保存到 `tdd_contract.green.evidence`。
+12. GREEN 后才允许重构；重构后运行 `tdd_contract.refactor_guard.command`，并把日志保存到 `tdd_contract.refactor_guard.evidence`。如任务声明 coverage 命令且不是 `not-applicable`，同步运行并记录结果。
+13. 如果 `tdd_contract.policy` 是 `exempted` 或 `not_applicable`，必须在最终回答列明豁免依据和替代证据；不要把“测试后补”伪装成 TDD。
+14. 对非 TDD 任务或 TDD 完成后，按任务步骤实现最小必要改动，并同步更新相关测试、证据路径或测试文档。
+15. 编码过程中运行任务声明的开发验证，例如 affected tests、单元 / 组件、局部 API、契约、类型检查或 lint，并记录 `development_validation` 证据。
+16. 实现完成后、最终回答前，必须从用户、业务闭环或发布候选视角重新运行任务声明的最终验收验证，并记录 `acceptance_validation` fresh evidence；不得把编码中途的小测试直接当作验收证据。
+17. 重构或清理任务结束前，额外检查无用变量、无用函数、无用组件、无用类型、无用 import、临时代码和过期注释是否已按声明范围处理；不能越权删除未确认的兼容逻辑。
+18. 自检是否满足验收标准、测试影响、架构约束、知识引用、forbidden path 约束、自然语言用例来源、TDD 证据、开发验证和最终验收验证。
+19. 在最终回答中给出 Requirement IDs、修改摘要、涉及文件、自然语言用例来源、TDD RED/GREEN/REFACTOR 证据、验证命令、证据路径、开发验证结果、最终验收验证结果、knowledge references、knowledge outputs 和剩余风险。
+
+## 强制边界
+
+- 不要处理 `task.json` 中其他任务。
+- 不要删除或改写任务描述。
+- 不要修改 `task.json`、`progress.txt`、`traces/`、`tools/harness/templates/smoke-task.json`。
+- 不要修改 `docs/harness/trace.schema.json`，除非当前任务明确把它列入 owned paths 且任务目标就是 harness/runtime schema 改造。
+- 不要执行 `git add`、`git commit`、`git push`、`git reset`、`git checkout`。
+- 不要修改与当前任务无关的文件。
+- 不要在没有验收示例或追溯矩阵支撑时自行猜测 P0/P1 业务规则。
+- 不要在缺少 `qa_contract`、测试意图、Oracle、证据路径、开发验证和最终验收验证声明时开始 `feature_impl`；先输出 BLOCKED 或补齐前置测试 truth source。
+- 不要在 P0/P1 需求缺少 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 自然语言用例覆盖时开始 `feature_impl`。
+- 不要在自然语言用例未声明需求类型、最少用例数、已写用例数和风险加量理由时开始 `feature_impl`。
+- 不要在 `tdd_contract.red.source_case_ids` 无法回溯到自然语言测试用例时开始 TDD RED。
+- 不要让非 TDD 自然语言用例停留在设计文档里；必须映射到故事验收、回归、release 验证或 verify-matrix。
+- 不要在 `qa_contract.tdd_contract.policy=required` 且缺少 RED 命令、预期失败、测试文件或证据路径时开始 `feature_impl`；先输出 BLOCKED 或补齐 TDD 合同。
+- 不要在 RED 失败证据产生前修改生产代码；如果已经写了生产代码但没有 RED 证据，必须回到测试先行的最小行为闭环，不能把事后测试声称为 TDD。
+- 不要把语法错误、导入错误、环境错误、测试数据错误、mock 行为或无效断言当作 RED 成功；RED 必须因目标行为缺失而失败。
+- 不要在 RED 直接通过、GREEN 未复跑同一聚焦命令、重构后未复跑 guard 命令时声称完成 TDD。
+- 不要只运行单元测试、小范围 smoke、局部 affected tests、静态检查或 `git diff --check` 后声称 `feature_impl` 完成；每个实现任务必须在代码写完后运行任务声明的用户故事验收链路，除非 `qa_contract.exemptions` 明确写出豁免和替代证据。
+- 不要把编码过程中的开发验证、旧日志或子任务局部测试简单相加当作最终验收验证。
+- 不要在没有跨故事整链路、P0/P1 回归、发布候选验收和失败态证据的情况下声称 `release` 完成。
+- 不要在没有任务声明的架构约束 truth source 或等价约束说明时开始需要架构门禁的 `feature_impl`；如果任务缺少约束但明显涉及交付形态、公开入口、数据边界、异步边界或外部系统，输出 BLOCKED。
+- 不要把测试替身、mock、fixture、local-only adapter 或纯领域原型作为声明交付路径完成，除非任务 `architecture_constraints` 明确允许。
+- 不要违反任务 `forbidden_implementations`；如发现当前任务验收与 forbidden implementation 冲突，输出 BLOCKED。
+- 如果子代理策略是 `off`，不要主动使用子代理。
+- 如果子代理策略不是 `off`，只有在存在两个以上独立子问题时才可使用，并且只消费结构化结论。
+- 如果本轮是 stop hook 强制继续后的续跑，子代理启用前必须先重读对应 docs / rules / skills；只有明确授权的 writer 角色可以写它们被分配的路径，其余子代理保持只读。
+- 测试失败时不能声称任务完成，不能把任何状态标记为通过。
+
+## UI 任务额外规则
+
+如果任务涉及前端页面、组件、布局、交互状态或视觉还原：
+
+- 必须确认是否存在 `docs/design/ai-image-brief.md`、`ui-image-review.md`、`image-to-frontend-spec.md`、`visual-parity-review.md`。
+- 必须在真实浏览器中验证页面，截图保存到 `artifacts/visual-review/` 或任务指定目录。
+- 最终回答必须写明截图路径和视觉差异处理情况。
+- 如果无法启动浏览器或无法截图，输出 BLOCKED，而不是跳过视觉验证。
+
+## BLOCKED 格式
+
+```text
+BLOCKED - 需要人工介入
+
+当前任务: <task-id> <task-description>
+
+已完成的工作:
+- ...
+
+阻塞原因:
+- ...
+
+需要人工操作:
+1. ...
+
+解除阻塞后请运行:
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1
+```
+
+## 输出格式
+
+```markdown
+## Requirement IDs
+- ...
+
+## Summary
+- ...
+
+## Files Changed
+- `path`: ...
+
+## Validation
+- `command`: PASS / FAIL / NOT_RUN - evidence
+
+## Evidence
+- `path`: what it proves
+
+## TDD Evidence
+- policy: required / exempted / not_applicable
+- source cases: `TC-...` from `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`
+- red: PASS / FAIL / NOT_RUN - `command` - `evidence` - expected failure matched: yes/no
+- green: PASS / FAIL / NOT_RUN - `command` - `evidence`
+- refactor guard: PASS / FAIL / NOT_RUN - `command` - `evidence`
+- coverage: PASS / FAIL / NOT_RUN / NOT_APPLICABLE - `command` - `evidence`
+
+## Architecture Constraints
+- `constraint`: PASS / FAIL / NOT_APPLICABLE - evidence
+
+## Full Chain Validation
+- development checks: PASS / FAIL / NOT_RUN - evidence
+- acceptance chain: PASS / FAIL / NOT_RUN - evidence
+- release candidate impact: PASS / FAIL / NOT_RUN - evidence
+- exemptions: none / `path-or-reason`
+
+## Knowledge References
+- `id`: title - used_in - `path`
+
+## Knowledge Outputs
+- `id-or-suggested-id`: type - title - action(created/updated/suggested/archived) - `path-or-target`
+
+## Visual Evidence
+- reference: `path-or-none`
+- screenshot: `path-or-none`
+- parity report: `path-or-none`
+
+## Remaining Risks
+- ...
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/repair-one-finding.md

@@ -0,0 +1,70 @@
+# Repair One Finding Prompt
+
+## 元信息
+
+- 版本: v1.0
+- 标签: codex, harness, repair, retry
+
+## 角色
+
+你是 repair worker。你只修复一个 finding，不扩展范围，不顺手重构。
+
+## 输入
+
+- finding id、severity、owner、evidence、recommended fix
+- 原任务描述和验收标准
+- 原 worker handoff
+- 允许修改的 owned paths
+- retest command
+
+如果下面引用的 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+
+## 修复流程
+
+1. 读取 finding 和 evidence。
+2. 读取原任务 truth source 和相关 `docs/knowledge/` 条目，确认修复不偏离需求且不重复踩已知坑。
+3. 只改 finding 指向的最小文件范围。
+4. 修复后运行 retest command 或任务指定测试。
+5. 如果是 UI finding，重新生成浏览器截图并更新 visual evidence 路径。
+6. 输出修复摘要和复验证据。
+7. 如果修复形成新的可复用经验，输出 `Knowledge Outputs` 建议，不要直接升级全局规则。
+
+## 禁止事项
+
+- 不要修复其他 finding。
+- 不要修改 task/progress/trace 状态文件。
+- 不要改测试来掩盖真实失败，除非 finding 明确指出测试错误。
+- 不要扩大 owned paths。
+- 不要提交 Git。
+- 不要把单点修复顺手扩展成结构性重构或死代码清理任务。
+
+## 输出格式
+
+```markdown
+## Repair Result
+
+- Finding ID: `<finding-id>`
+- Verdict: FIXED / BLOCKED / NOT_REPRODUCED
+
+## Files Changed
+
+- `path`: ...
+
+## Evidence
+
+- Before: `path-or-log`
+- After: `path-or-log`
+- Retest: `command` -> PASS / FAIL
+
+## Knowledge References
+
+- `id-or-none`: title - used_in - `path`
+
+## Knowledge Outputs
+
+- `suggested-id-or-none`: type - title - target path
+
+## Notes
+
+- ...
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/spec/11-security-design.md

@@ -0,0 +1,43 @@
+# 11 安全设计规格
+
+## 职责
+
+定义认证、授权、输入校验、密钥处理、外部服务和威胁模型。
+
+## 安全边界
+
+| 边界 | 当前决策 | 说明 |
+| --- | --- | --- |
+| authentication | TBD | TBD |
+| authorization | TBD | TBD |
+| secret_management | env | 不写入仓库 |
+| input_validation | TBD | TBD |
+
+至少补齐：
+
+- 后端权限校验入口，不能只写前端隐藏按钮
+- 资源所有权 / 租户隔离 / 角色边界
+- 输入校验范围：类型、长度、枚举、金额、日期、文件、特殊字符
+- 敏感信息返回、日志、trace、审计中的脱敏策略
+- 登录、注册、验证码、支付、领取、上传、搜索等高风险入口的限流 / 风控策略
+
+## STRIDE 摘要
+
+| 类型 | 风险 | 缓解 | 验证 |
+| --- | --- | --- | --- |
+| Spoofing | TBD | TBD | 13 |
+
+## LLM / 外部服务注意事项
+
+- 不记录密钥、cookie、token。
+- 不把敏感输入写入 trace。
+- 外部调用必须有失败态证据。
+
+## 安全控制清单
+
+| 控制项 | 最低要求 | 验证方式 |
+| --- | --- | --- |
+| 权限校验 | 服务端强制校验角色、资源权限、本人 / 本租户 | API / integration / e2e |
+| 输入校验 | schema / validator 覆盖类型、长度、枚举、金额、日期、文件 | unit / api |
+| 敏感信息脱敏 | token、密码、手机号、身份证、密钥、堆栈不直接返回给用户或写入 trace | response + log review |
+| 防刷 / 风控 | 登录、注册、验证码、支付、上传等入口有频率限制或幂等控制 | integration / security test |

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放 `spec/*` 模板文档的镜像副本。
+
+## 结构索引
+
+- `01..14`：默认规格链镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/spec/*`。
+- 如果默认安装主线依赖 `docs/spec/*`，这里更不能被误当成第一源。

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放测试模板文档的镜像副本。
+
+## 结构索引
+
+- `ACCEPTANCE_*`、`TRACEABILITY_MATRIX.md`、`TEST_STRATEGY.md`、`verify-matrix.md`、`test-report.md` 等测试模板镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/testing/*`。
+- 这里默认不作为测试模板第一真相源。

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

@@ -0,0 +1,54 @@
+# 证据协议
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 必需证据
+
+- 执行过的命令
+- 退出码 / 结论
+- 适用时的截图或日志路径
+- 关联的 Requirement ID
+- 关联的测试文件
+
+## 测试证据包
+
+每个 P0/P1 测试用例或高风险回归至少应能回溯到下面证据:
+
+| 证据 | 适用场景 | 说明 |
+| --- | --- | --- |
+| natural_language_test_case | PRD 完成后、实现前 | 每条 P0/P1 需求的自然语言测试用例，包含 Requirement ID、PRD 来源、步骤、Oracle、数据、证据路径和 TDD RED 预期失败 |
+| tdd_red_log | `feature_impl`、bugfix、重构 | 测试先写且按预期失败；失败原因必须是目标行为缺失，而不是语法、导入、环境或测试数据错误 |
+| tdd_green_log | `feature_impl`、bugfix、重构 | 最小实现后复跑同一 focused test 并通过 |
+| tdd_refactor_log | `feature_impl`、bugfix、重构 | 重构后 affected tests、coverage、lint、类型检查或等价 guard 仍通过 |
+| request_response | API、E2E | 请求、响应、状态码、错误码、Trace ID |
+| db_snapshot_before_after | 写接口、状态流转、批处理 | 操作前后关键表 diff 和 unexpected diff 检查 |
+| cache_observation | 缓存、权限、多租户 | key、TTL、hit/miss、失效结果 |
+| state_source_snapshot | URL、store、form、本地状态 | 证明同一业务条件只有一个主状态来源 |
+| event_log | 队列、事件、Webhook | 事件类型、payload、消费次数、失败重试 |
+| audit_log | 权限、删除、资金、审批 | actor、action、object、result |
+| request_trace_sample | API、服务、网关 | 请求 ID、用户 ID、接口路径、耗时、错误原因 |
+| alert_evidence | 监控、告警、失败态 | 告警规则、阈值、通知通道、触发结果 |
+| validation_failure_sample | 输入校验、文件上传、非法枚举 | 无效输入、错误码、错误字段、无副作用结果 |
+| redaction_check | 响应、日志、trace、审计 | 敏感字段已脱敏或未落盘 |
+| rate_limit_observation | 登录、注册、验证码、支付、上传、搜索 | 限流命中、验证码、幂等、告警或拒绝结果 |
+| screenshot_video_har | UI、E2E、视觉 | 截图、视频、HAR 或 Playwright trace |
+| coverage_or_trace | 白盒、集成、跨服务 | coverage 命中、日志命中或链路 trace |
+| failure_repro | 失败用例 | seed、账号、curl、初始状态、实际结果、疑似位置 |
+
+## 无副作用证据
+
+权限拒绝、非法状态流转、校验失败和重放攻击类用例必须证明没有产生业务副作用:
+
+- 目标业务数据未变化。
+- 不产生成功事件或重复事件。
+- 不写入错误缓存。
+- 不泄露目标资源敏感字段。
+- 必要时记录拒绝审计。
+
+## 新鲜度规则
+
+- 证据必须来自当前变更集。
+- 如复用了过期截图或日志，必须明确说明。
+- 最终 verify 只应汇总能够回溯到当前任务的证据。