@pzy560117/codex-harness 0.1.0 → 0.1.2

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

@@ -0,0 +1,20 @@
+# 回归计划
+
+**功能 / 发布版本**:
+**最后更新**:
+**负责人**:
+
+## 受影响测试
+
+-
+
+## P0 回归集合
+
+-
+
+## 发布证据
+
+- verify 摘要:
+- 契约验证:
+- e2e smoke:
+- 视觉一致性:

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

@@ -0,0 +1,16 @@
+# 基于风险的测试计划
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+| 风险 ID | 需求 / 区域 | 高风险原因 | 测试重点 | 必需 Oracle | 负责人 | 证据路径 |
+| --- | --- | --- | --- | --- | --- | --- |
+| RISK-001 | | | | | | |
+
+## 规则
+
+- P0 主流程应在实现前识别阻塞性风险。
+- 安全、权限、支付、数据一致性和迁移路径需要明确的负向覆盖。
+- 权限、资金、删除、跨租户、状态机、幂等、并发和外部回调默认按高风险处理。
+- 高风险项必须说明成功态、失败态和无副作用证据。

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

@@ -0,0 +1,30 @@
+# 测试数据矩阵
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+| 场景 / Req ID | Data ID | 数据类型 | 初始化方式 | 重置方式 | 边界 / 负向用例 | 隔离策略 | 负责人 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-001 | seed-default-001 | normal | | | | | |
+| PKG-LAYER-P6-READINESS | readiness-thin-clean | normal | `tools/harness/tests/test-install-modes.ps1` 创建临时 git repo，并运行 `tools/install/install-agent.ps1 -Scope project` 生成 thin 输出。 | 每次 smoke 使用新的 `%TEMP%\codex-install-smoke-*` 根目录；测试结束允许系统临时目录清理。 | 无负向；期望 `Readiness gate: PASS`、`ProjectShape: thin-project`、`FixCommand: none`。 | 每个 fixture 使用唯一 temp 路径和独立 git repo，不复用用户真实项目。 | harness |
+| PKG-LAYER-P6-READINESS | readiness-missing-user-package | negative | 基于 thin clean fixture，临时改写 `.codex-harness/state/config.json` 的 `packageRoot` 指向项目内不存在目录。 | 断言后写回原始 config 内容；fixture 位于独立 temp repo。 | 用户级 package 缺失；期望 `Readiness gate: WARN`、`ProjectShape: thin-project-missing-user-package` 和 `-Scope user` 修复命令。 | 只改 temp fixture 的 config，不触碰真实 `%USERPROFILE%\.codex\packages`。 | harness |
+| PKG-LAYER-P6-READINESS | readiness-legacy-residue | negative | 基于 thin clean fixture，手动创建 `.agents/` 和 `docs/testing/` 作为 legacy residue。 | 不删除 residue，由 temp repo 生命周期隔离；doctor 必须保持只读。 | legacy/vendor 残留；期望 `Readiness gate: WARN`、`ProjectShape: thin-project-with-legacy-residue` 和 `-MigratePlan` 修复命令。 | residue 只写入 temp repo；不对真实项目递归删除。 | harness |
+| PKG-LAYER-P6-READINESS | readiness-vendor-lock | compatibility | `tools/harness/tests/test-install-modes.ps1` 创建临时 git repo，并运行 `tools/install/install-agent.ps1 -Scope vendor` 生成完整 `.agents/` 和 vendor lock。 | 每次 smoke 使用新的 temp repo；不复用前一场景。 | vendor 兼容路径；期望 `Readiness gate: PASS`、`ProjectShape: vendor-project` 和显式 `-Scope vendor` 修复命令。 | vendor fixture 独立于 thin fixture，避免 lock/config 交叉污染。 | harness |
+| PKG-LAYER-P6-READINESS | readiness-no-config | negative | `New-TempGitRepo` 创建空临时 git repo，不运行安装器，不创建 `.codex-harness/`。 | 空 repo 仅用于本次断言；测试结束由 temp 根目录隔离。 | 未安装项目；期望 doctor exit 非 0、`Readiness gate: FAIL`、`ProjectShape: not-installed` 和 `-Scope project` 初始化命令。 | 独立 temp repo；doctor 不得自动创建 `.codex-harness/`、`.codex/` 或 `.agents/`。 | harness |
+| PKG-LAYER-P7-DEFAULT-THIN | p7-default-thin-install | normal | `New-TempGitRepo` 创建空临时 git repo，运行默认 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -InitSmoke`。 | 每次 smoke 使用新的 temp repo；不复用 scope/vendor/full fixture。 | 默认输出必须为 thin；禁止 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/`、`docs/requirement-prep-kit/`。 | 独立 temp repo；默认安装不触碰真实业务项目。 | harness |
+| PKG-LAYER-P7-DEFAULT-THIN | p7-legacy-full-install | compatibility | `New-TempGitRepo` 创建空临时 git repo，运行 `-Mode full -InitSmoke`。 | temp repo 生命周期隔离；不删除 legacy 输出。 | 显式 full 必须保留 `.agents/`、legacy docs 和 readiness legacy warning。 | 与默认 thin fixture 分离，避免 full 输出污染 thin 断言。 | harness |
+| PKG-LAYER-P7-DEFAULT-THIN | p7-scope-project-install | normal | `New-TempGitRepo` 创建空临时 git repo，运行 `-Scope project -InitSmoke`。 | 每次 smoke 使用新的 temp repo；不复用默认 fixture。 | `-Scope project` 输出必须等价 thin，禁止 legacy/vendor 目录。 | 独立 temp repo；用户级 package 只写入临时解析路径。 | harness |
+| PKG-LAYER-P7-DEFAULT-THIN | p7-scope-vendor-install | compatibility | `New-TempGitRepo` 创建空临时 git repo，运行 `-Scope vendor`。 | 每次 smoke 使用新的 temp repo。 | vendor-only 输出必须存在 `.agents/` 和 vendor lock，且不得输出 project runtime/spec docs。 | 独立 vendor fixture；不与 legacy full fixture共用。 | harness |
+| PKG-LAYER-P7-DEFAULT-THIN | p7-scope-user-install | normal | 将 `USERPROFILE` 指向临时项目目录后运行 `-Scope user`。 | 断言结束恢复原始 `USERPROFILE`；临时目录隔离。 | 只安装用户级 package、skills/workflows 和 user lock；不得创建 project runtime。 | 不触碰真实 `%USERPROFILE%`；所有用户级输出在 temp profile 内。 | harness |
+| PKG-LAYER-P7-DEFAULT-THIN | p7-install-plan-profiles | negative | 分别创建 `default-plan`、`scope-project-plan`、`legacy-project-plan` 空临时 repo，运行默认 `-Plan`、`-Scope project -Plan`、`-Mode project -Plan`。 | plan 命令必须只读；fixture 可直接丢弃。 | thin plan 禁止 legacy docs；legacy `-Mode project -Plan` 必须显式保留 legacy docs。 | plan fixture 独立，不创建 `.agents/` 或 `.codex-harness/`。 | harness |
+| PKG-LAYER-P8-CLI-ALIAS | p8-install-user-wrapper | normal | 将 `USERPROFILE` 指向 temp profile，运行 `tools/install/install-user.ps1`，由 wrapper 转发到同目录 `tools/install/install-agent.ps1 -Scope user`。 | 断言结束恢复原始 `USERPROFILE`；temp profile 生命周期隔离。 | wrapper 必须输出 `AliasScope: user` 并生成用户级 package lock；不得写入业务项目 runtime、`.codex-harness/` 或 `.agents/`。 | 不触碰真实 `%USERPROFILE%`；用户级输出全部在 temp profile 内。 | harness |
+| PKG-LAYER-P8-CLI-ALIAS | p8-init-project-wrapper | normal | `New-TempGitRepo` 创建空临时 git repo，运行 `tools/install/init-project.ps1 -ProjectRoot <fixture> -InitSmoke -SkipBaselineCommit`，由 wrapper 转发到 `tools/install/install-agent.ps1 -Scope project`。 | 每次 smoke 使用新的 temp repo；不复用默认 thin、vendor 或 legacy full fixture。 | wrapper 必须输出 `AliasScope: project`，生成 thin required paths，并禁止 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/`、`docs/requirement-prep-kit/`。 | 独立 temp repo；项目输出与 `-Scope project` fixture 对比，不污染真实业务项目。 | harness |
+| PKG-LAYER-P8-CLI-ALIAS | p8-wrapper-no-double-implementation | negative | 读取 `tools/install/install-user.ps1`、`tools/install/init-project.ps1` 及 package template wrapper 源码，检查只定位同目录 `tools/install/install-agent.ps1` 并转发参数。 | 只读源码检查，无需重置；若 refresh 同步后 wrapper 不一致，由 package CheckOnly 捕获。 | wrapper 不得复制 `tools/install/install-agent.ps1` 大段安装逻辑，不得绕过 manifest、lock、doctor 或 scope 语义。 | 只读检查 root/agent/template 三个 surface；不执行破坏性文件操作。 | harness |
+
+## 规则
+
+- 每个 P0/P1 场景都应标明所需的 seed 或 fixture 数据。
+- 负向和权限场景不应依赖临时手工准备。
+- 破坏性场景必须定义重置或隔离策略。
+- 并发、幂等、跨租户和历史数据场景必须使用独立 namespace、tenant、事务回滚或可清理 seed。

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

@@ -0,0 +1,97 @@
+# 测试策略
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 测试层级
+
+- 单元:
+- 组件:
+- API / 契约:
+- 集成:
+- E2E:
+- 视觉:
+
+## 开发验证与验收验证分层
+
+Harness 把实现过程中的快速反馈和交付前的完整验收拆成两个独立闸门:
+
+| 闸门 | 目的 | 典型验证 | 完成条件 |
+| --- | --- | --- | --- |
+| 自然语言测试用例 | 把 PRD 每条需求转成可审查、可追溯、可转脚本的测试用例 | `NATURAL_LANGUAGE_TEST_CASES.md`、需求类型覆盖矩阵、Gherkin/步骤化用例、Oracle、测试数据、证据路径、TDD RED 预期失败 | 每条需求都要分类；P0/P1 按需求类型满足最小用例数；P2 需写用例或豁免原因；TDD 候选用例可被 `tdd_contract.red.source_case_ids` 引用 |
+| TDD RED | 在生产代码变更前证明新增或变更行为当前缺失 | 聚焦单元、组件、契约或 API 测试；必须先失败且失败原因匹配预期 | 作为 `tdd_contract.red` 证据进入任务；失败原因不是目标行为缺失时不得进入实现 |
+| TDD GREEN / REFACTOR | 用最小实现让同一聚焦测试通过，并在重构后保持相关验证绿色 | 同一 focused test、affected tests、coverage、lint 或类型检查 | 作为 `tdd_contract.green` 和 `tdd_contract.refactor_guard` 证据进入任务；不能替代最终验收 |
+| 开发验证 | 支撑编码过程中的快速反馈，证明局部改动没有破坏直接相关行为 | 单元、组件、局部 API、契约检查、affected tests、静态检查、类型检查、lint | 作为实现过程证据进入 `development_validation`，但不能单独声明任务完成 |
+| 验收验证 | 从用户、业务闭环或发布候选视角证明当前交付可被验收 | 用户故事完整链路、跨故事主流程、真实入口 E2E、数据副作用、失败态、P0/P1 回归、视觉/可访问性确认 | 作为完成前 fresh evidence 进入 `acceptance_validation`，缺失时任务必须 BLOCKED 或有 owner 批准的 exemption |
+
+开发验证通过只说明局部实现可继续推进，不等于用户验收通过。PRD 完成后、进入实现前必须先生成自然语言测试用例；每个 `feature_impl` 默认要求 TDD：从自然语言用例选择 TDD 候选，先写聚焦测试并确认 RED 失败，再写最小实现确认 GREEN，通过后才允许重构。每个 `feature_impl` 完成前必须在代码写完后重新运行故事级验收链路；每个 `release` 完成前必须运行发布候选级跨故事验收链路。验收验证不得直接复用编码中途的旧日志，除非证据协议明确证明其仍是当前变更集的 fresh evidence。
+
+## 自然语言用例规模规则
+
+自然语言测试用例不是每条需求固定写 1 条，而是先判定需求类型，再按 `NATURAL_LANGUAGE_TEST_CASES.md` 的覆盖矩阵取最小用例数。基础原则:
+
+- P0 需求默认不少于 5 条，P1 需求默认不少于 3 条，P2 可为 1-2 条并说明不进入 TDD 候选的原因。
+- 低于默认数量必须写明豁免原因、替代证据和 owner 批准人。
+- 只读查询至少覆盖正常、空数据和无权限；列表类还要覆盖筛选、分页、排序或组合条件。
+- 新增、编辑、删除等写操作至少覆盖成功副作用、输入失败、权限失败无副作用、非法状态或并发冲突。
+- 权限、状态机、异步链路、外部系统、金额库存、文件处理和安全需求必须按风险路径加量，不能只写 happy path。
+- 一个需求跨多个类型时，按风险最高类型取基准，再补齐其他类型的必需路径。
+- TESTCASE 阶段必须在覆盖检查表中写明“需求类型、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数、加量理由”，不足时不得进入 `feature_impl`。
+- 非 TDD 自然语言用例必须映射到 `story_full_chain`、`acceptance_validation`、回归或 `verify-matrix`，不能因为不适合作为 RED 种子就从验收链路消失。
+
+## QA Harness 最小闭环
+
+测试设计按下面顺序推进，不允许直接从需求跳到测试脚本:
+
+1. 资料输入: 读取需求、代码、API 契约、UI、数据模型、权限规则和历史缺陷。
+2. 风险建模: 输出业务实体、状态、角色权限、接口、数据副作用和外部依赖风险。
+3. 自然语言用例: 按 PRD / Requirement ID 识别需求类型和风险因子，按覆盖矩阵写出目标、来源、前置条件、动作、预期结果、Oracle、测试数据、证据路径和 TDD RED 预期失败。
+4. 测试意图: 将自然语言用例映射到测试层级、风险、数据和可执行验证命令。
+5. Oracle 审查: 通过后才生成或修改测试脚本。
+6. TDD RED: `feature_impl` 从 `NATURAL_LANGUAGE_TEST_CASES.md` 的 TDD 候选用例生成聚焦测试，运行 `tdd_contract.red.command`，确认失败原因匹配目标行为缺失并记录证据。
+7. TDD GREEN: 写最小实现后运行 `tdd_contract.green.command`，确认同一聚焦测试通过。
+8. TDD REFACTOR: 重构后运行 `tdd_contract.refactor_guard.command` 和必要覆盖率命令，确认相关验证仍通过。
+9. 开发验证: 编码过程中运行 affected tests、局部契约、类型检查、lint 或单元 / 组件测试，记录 `development_validation` 证据。
+10. 验收验证: 代码写完后从用户、业务闭环或发布候选视角运行完整链路，记录 `acceptance_validation` fresh evidence。
+11. 证据归档: 把命令、退出码、日志、截图、DB diff、事件、Trace 等写入证据路径。
+12. 失败归因: 区分产品缺陷、测试缺陷、环境问题和数据问题。
+13. 回归沉淀: 真实缺陷修复后补充回归用例或知识候选。
+
+## Oracle 优先规则
+
+每个测试用例必须在写脚本前定义至少一个业务 Oracle。写接口、状态流转、权限和数据一致性场景通常需要多个 Oracle 组合:
+
+| Oracle 类型 | 适用场景 | 最小要求 |
+| --- | --- | --- |
+| 返回值 | API、服务、UI 动作 | 状态码、错误码、关键字段和业务语义 |
+| Schema / Contract | API、事件、文件 | 字段类型、必填、枚举、版本兼容 |
+| 数据库副作用 | POST / PUT / PATCH / DELETE、批处理 | before / after diff、目标字段变化、非目标字段不变 |
+| 缓存 | 读写缓存、权限缓存、多租户 | key 维度、TTL、失效、跨用户隔离 |
+| 事件 / 队列 | 异步链路、Webhook、消息消费 | event type、payload、重试、幂等、DLQ |
+| 审计 | 登录、权限、资金、删除、审批 | actor、action、object、result、time |
+| 权限 | 水平越权、垂直越权、字段级权限 | 允许 / 拒绝符合权限矩阵，拒绝时无副作用 |
+| 状态机 | 订单、审批、发布、退款等状态流转 | 合法转移成功，非法转移失败且无污染 |
+| 不变量 | 金额、库存、次数、唯一性 | 余额 / 库存不为负，总额守恒，唯一业务结果 |
+| Trace / 证据 | E2E、集成、跨服务 | 命中预期链路、日志或 coverage 可证明目标路径 |
+
+## 假测试拦截规则
+
+Stage 2 必须拦截下列测试:
+
+- 只断言 `200`、`truthy`、元素存在或 snapshot，没有业务断言。
+- 写操作没有 DB、缓存、事件、审计、文件或通知等副作用断言。
+- 权限失败只断言 `403`，没有验证目标数据未变化、响应未泄露和缓存未污染。
+- mock 了当前被测 service、权限判断、状态机、数据库写入或核心业务路径。
+- 没有绑定 Requirement ID、代码分支、API 契约、安全风险、状态机转移或历史缺陷来源。
+- 没有执行证据，或证据不是当前变更集产生的 fresh evidence。
+- 测试名称覆盖多个路径，但实际只跑 happy path。
+
+## 阻塞性失败
+
+-
+
+## Fresh Evidence 策略
+
+- Stage 17 只确认 fresh evidence 和回归状态。
+- 缺少验收示例或需求追溯属于实现前缺口，不是 Stage 17 的任务。

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

@@ -0,0 +1,22 @@
+# 需求追溯矩阵
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+| Req ID | 业务规则 | 页面 / 组件 | 状态 | API / 契约 | 数据 / 副作用 | Oracle | 测试层级 | 测试文件 / 计划 | 证据路径 | 风险 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-001 | | | 默认 | | | response + db | unit / component / api / e2e | | | P0 |
+| PKG-LAYER-P5-MIGRATE-APPLY | `-MigrateApply` 必须 plan-first、默认 dry-run、`-Confirm` 后只采纳 hash 一致 vendor 文件；drift/unknown/manual-review 阻断写入。 | CLI / PowerShell installer | legacy full / drift / unknown / missing / manual-review / thin no-op | `docs/agent-package-redesign/migration-plan.md`, `docs/harness/install-manifest-governance.md` | `.codex-harness/locks/package.lock.json`, `.agents/`, legacy docs；失败态 lock 不变且不删除文件 | command output + lock hash/managedFiles + no-side-effect filesystem evidence | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P5-APPLY-001..006` | `traces/`, test-install-modes 输出, doctor 输出, refresh CheckOnly 输出 | P1 |
+| PKG-LAYER-P6-READINESS | doctor readiness gate 必须只读区分 thin、legacy、vendor 和未安装项目并给出修复建议。 | CLI / doctor | thin clean / legacy residue / missing user package / vendor / no config | `docs/architecture/constraints.md`, `docs/harness/install-manifest-governance.md` | 文件系统只读；不得自动安装、迁移或删除 | doctor output + unchanged files + readiness fix command | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P6-READINESS-001..005`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/LAYERING-P6-READINESS-001/`, doctor 输出, smoke 输出 | P1 |
+| PKG-LAYER-P7-DEFAULT-THIN | 默认无参数安装必须输出 thin project，同时保留显式 legacy full/vendor/user 入口，并保证公开 plan 与实际输出一致。 | CLI / installer | default thin / explicit legacy full / vendor / user/project scope / thin plan / legacy plan | `docs/agent-package-redesign/target-layering-standard.md`, `docs/harness/new-project-usage.md` | `.codex-harness/`, `.codex/`, docs/spec；默认不得复制完整 `.agents`；plan 命令只读 | required/forbidden path assertions + plan output + package lock/config + doctor output | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P7-DEFAULT-THIN-001..006`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/LAYERING-P7-DEFAULT-THIN-001/`, test-install-modes 输出, doctor 输出, verify 输出 | P1 |
+| PKG-LAYER-P8-CLI-ALIAS | 首选 install-user/init-project 入口必须调用现有 install-agent scope 语义或明确文档化等价入口，不得出现第二套安装逻辑。 | CLI / docs | wrapper path / documented equivalent / no double implementation | `docs/harness/new-project-usage.md`, `docs/agent-package-redesign/target-layering-standard.md` | 输出与 `-Scope user/project` 一致；manifest/lock/doctor 不被绕过 | command output or doc assertion + smoke equivalence | integration / doc check | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P8-CLI-ALIAS-001..003`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/`, new-project-usage.md, refresh CheckOnly 输出 | P1 |
+
+## 规则
+
+- 每条 P0/P1 需求都必须恰好出现一次，或被明确拆分。
+- 每一行都必须指向至少一个测试层级和一个证据路径。
+- UI 行必须包含所需状态或明确豁免。
+- API / 数据行必须包含契约或 schema 校验证据。
+- 写操作、权限失败、非法状态流转和异步链路必须包含副作用或无副作用 Oracle。
+- 缺少 Oracle 或证据路径的 P0/P1 行不能进入实现。

package/package-source/docs/codex-harness-engineering/templates/testing/coverage-policy.md

@@ -0,0 +1,25 @@
+# 覆盖率策略
+
+**功能**:
+**覆盖率工具**:
+**覆盖率报告路径**:
+
+## 阈值
+
+| 范围 | 最低要求 | 备注 |
+| --- | --- | --- |
+| 业务规则 | 80% | 定价、库存、权限、校验 |
+| API / 服务层 | 80% | 包含成功和错误分支 |
+| UI 组件 | 覆盖关键状态 | 相比原始行覆盖率，更优先覆盖交互 / 状态 |
+| E2E | 覆盖 P0/P1 主流程 | 不按行覆盖率衡量 |
+| 视觉 | P0 UI + 高风险状态 | 必须提供截图证据 |
+
+## 豁免
+
+| 路径 / 模块 | 原因 | 批准人 | 替代证据 |
+| --- | --- | --- | --- |
+| | | | |
+
+## Stage 2 规则
+
+如果关键业务逻辑未被覆盖，且不存在豁免或替代证据，Stage 2 必须失败。

package/package-source/docs/codex-harness-engineering/templates/testing/e2e-plan.md

@@ -0,0 +1,139 @@
+# E2E 计划
+
+**功能**:
+**基础 URL**:
+**后端 URL**:
+**Seed 命令**:
+**测试数据计划**:
+**导航入口**: `docs/ai/repo-map.md` / `docs/context/repo-map.md`
+**关联代码理解摘要**:
+
+## 1. 功能概览
+
+- 目标:
+- 业务背景:
+- 适用角色:
+- 不覆盖范围:
+
+## 2. 代码入口与影响面
+
+先从 `repo-map` / codemap 进入，再补充局部文件阅读。不要先全仓盲扫。
+
+| 类别 | 入口 / 文件 | 说明 | 受影响测试 |
+| --- | --- | --- | --- |
+| 页面 / 路由 |  |  |  |
+| 组件 |  |  |  |
+| Hook / Store / State |  |  |  |
+| API / Service |  |  |  |
+| 数据模型 / 持久化 |  |  |  |
+
+## 3. 范围与角色
+
+- 范围内:
+- 范围外:
+- 必需角色:
+- 权限差异:
+- 登录态要求:
+
+## 4. 前置条件
+
+- 环境与服务:
+- Feature flag:
+- 账号 / 权限:
+- Seed 数据:
+- 外部依赖:
+- 已知豁免:
+
+## 5. 测试数据
+
+| 数据名称 | 用途 | 来源 | 重置方式 |
+| --- | --- | --- | --- |
+| 正常数据 | 主流程 |  |  |
+| 边界数据 | 边界 / 上下限 |  |  |
+| 非法数据 | 异常 / 权限 / 拒绝路径 |  |  |
+
+## 6. 核心主流程
+
+| ID | 角色 | 主流程 | 对应需求 | 测试数据 | 期望证据 |
+| --- | --- | --- | --- | --- | --- |
+| E2E-001 | 用户 |  |  |  | 报告 + 截图 / 视频 + 状态证据 |
+
+## 7. 异常与边界流程
+
+| ID | 类型 | 场景 | 预期结果 | 证据 |
+| --- | --- | --- | --- | --- |
+| E2E-NEG-001 | 异常 |  |  |  |
+| E2E-BND-001 | 边界 |  |  |  |
+
+至少检查：
+
+- 空数据
+- 最大 / 最小输入
+- 重复提交
+- 网络慢
+- 接口失败
+- 登录过期
+- 权限不足
+
+## 8. 页面与 UI 断言
+
+| 页面 | 状态 | 断言 | 测试层级 |
+| --- | --- | --- | --- |
+|  | 默认 |  | T5 / T6 |
+|  | 错误态 |  | T5 / T6 |
+|  | 空态 |  | T5 / T6 |
+|  | 成功态 |  | T5 / T6 |
+
+## 9. 接口与网络预期
+
+| 入口动作 | 请求 | 成功预期 | 失败预期 |
+| --- | --- | --- | --- |
+|  | `METHOD /path` |  |  |
+
+## 10. 可访问性与交互约束
+
+- 优先使用用户可见语义定位：
+  - `getByRole`
+  - `getByLabel`
+  - `getByPlaceholder`
+  - `getByTestId`
+- 避免把 DOM 层级或脆弱 CSS 选择器作为主定位手段。
+- 记录关键按钮、表单标签、错误提示、loading、键盘操作和 aria 期望。
+
+## 11. Mock 排雷
+
+- [ ] 从 `repo-map`、代码入口和测试目录搜索 `mock`、`fixture`、`fake`、`hardcoded`。
+- [ ] P0 / P1 主流程使用真实后端或明确声明的 mock server。
+- [ ] 必须 mock 的状态已在 `test-matrix.md`、`verify-matrix.md` 或豁免说明中写明。
+- [ ] 前端页面如仍依赖本地假数据，先创建清理任务，再把该 E2E 标记为可执行。
+
+## 12. 受影响测试与执行顺序
+
+| 类别 | 测试 / 命令 | 原因 | 优先级 |
+| --- | --- | --- | --- |
+| Existing |  |  | P0 |
+| New |  |  | P0 |
+
+推荐顺序：
+
+1. 先跑 affected tests / contract checks。
+2. 再跑本计划对应的最小 E2E 集。
+3. 最后跑 P0 / P1 回归或跨故事整链路。
+
+## 13. 失败归因入口
+
+失败后不要直接改测试，先分类：
+
+1. 测试代码问题
+2. 产品 Bug
+3. 需求变更
+4. 环境 / 数据问题
+5. Flaky 问题
+
+分类结果写入 `docs/testing/failure-triage.md` 或等价报告。
+
+## 14. 风险与待确认问题
+
+- 高风险点:
+- 未确认点:
+- 需要人工验收的部分:

package/package-source/docs/codex-harness-engineering/templates/testing/failure-findings.example.json

@@ -0,0 +1,21 @@
+{
+  "session": "<session-id>",
+  "report": "artifacts/testing/<session>/<agent>/test-report.md",
+  "verdict": "FAIL",
+  "findings": [
+    {
+      "id": "FINDING-001",
+      "severity": "HIGH",
+      "failureClass": "frontend_ui",
+      "ownerHint": "frontend",
+      "requirementId": "REQ-001",
+      "testCaseId": "E2E-001",
+      "evidencePath": "artifacts/testing/<session>/<agent>/screenshots/FINDING-001.png",
+      "summary": "主结账按钮无法点击。",
+      "expected": "点击结账后应打开订单确认步骤。",
+      "actual": "点击后界面没有任何可见变化。",
+      "retryCount": 0,
+      "status": "open"
+    }
+  ]
+}

package/package-source/docs/codex-harness-engineering/templates/testing/failure-triage.md

@@ -0,0 +1,62 @@
+# 失败归因
+
+## 一级分类
+
+先做五选一，不要一上来就改代码或改断言。
+
+| 一级分类 | 定义 | 允许动作 | 禁止动作 |
+| --- | --- | --- | --- |
+| `TEST_CODE_ISSUE` | 定位器、断言、等待时机、fixture 或测试搭建错误 | 修测试代码，保持原测试意图 | 弱化断言掩盖产品问题 |
+| `PRODUCT_BUG` | 实际行为违反需求、契约或设计预期 | 输出 bug report，按 owner 修业务代码 | 把 bug 改写成测试通过 |
+| `REQUIREMENT_CHANGE` | 规格、文案、流程或契约已明确变化 | 先更新真相源，再更新测试 | 不更新规格就改测试预期 |
+| `ENV_OR_DATA_ISSUE` | 服务未启动、数据不完整、权限、端口、外部依赖问题 | 修环境 / 数据并重跑 | 删除测试或直接跳过 |
+| `FLAKY` | 偶发、非确定性、重跑不稳定 | 收集证据，修等待/隔离/时序 | 用 `waitForTimeout` 掩盖问题 |
+
+## 二级归因
+
+在一级分类后，再细分 owner。
+
+| 失败类别 | 对应一级分类 | 典型信号 | 归属方 | 修复目标 | 回归执行方 |
+| --- | --- | --- | --- | --- | --- |
+| `REQ_GAP` | `REQUIREMENT_CHANGE` | 缺少验收示例、业务规则含糊、没有可观察判定依据 | 产品 | 产品 / 需求负责人 | 原审查人或测试代理 |
+| `TRACE_GAP` | `REQUIREMENT_CHANGE` | 需求未映射到 UI / API / 测试 / 证据 | requirements-trace | 追溯负责人 | 原审查人或测试代理 |
+| `DESIGN_GAP` | `REQUIREMENT_CHANGE` | 缺少状态、选择器、交互或视觉规则 | 设计 | 设计负责人 | 原视觉 / 测试代理 |
+| `CONTRACT_GAP` | `REQUIREMENT_CHANGE` | 缺字段、类型错误、错误码错误、鉴权规则不清楚 | 契约 | 契约负责人 | 契约测试者 |
+| `FRONTEND_BUG` | `PRODUCT_BUG` | 按钮不可点击、路由错误、状态缺失 | 前端 | 原开发者 | 原测试代理 |
+| `BACKEND_BUG` | `PRODUCT_BUG` | 500、业务规则错误、权限未生效 | 后端 | 后端开发者 | API 测试者 |
+| `TEST_BUG` | `TEST_CODE_ISSUE` | 断言错误、等待不稳定、fixture 无效或误报 | 测试 | 测试作者 | 原测试代理 |
+| `TEST_DATA_GAP` | `ENV_OR_DATA_ISSUE` | 缺少 seed、账号状态错误、数据重置不可靠 | 测试 / 数据 | 测试数据负责人 | E2E 测试者 |
+| `ENV_BUG` | `ENV_OR_DATA_ISSUE` | 端口冲突、服务未启动、依赖缺失 | 环境 | controller / 操作人 | test-runner |
+| `FLAKY` | `FLAKY` | 间歇性、非确定性失败 | test-runner | 对应 worker + 测试负责人 | 原测试代理 |
+| `SECURITY_RISK` | `PRODUCT_BUG` | 认证、权限、密钥或敏感数据问题 | 安全 | 安全 / 后端负责人 | 安全审查者 |
+
+## 归因记录模板
+
+```md
+### Finding ID
+
+- 一级分类:
+- 二级分类:
+- 失败测试 / 命令:
+- 责任方:
+- 根因:
+- 证据:
+  - 日志:
+  - trace:
+  - screenshot / video:
+  - network / console:
+- 修复动作:
+- 重新运行结果:
+- 后续验证:
+```
+
+## 规则
+
+- 不要默认把所有失败都归给前端。
+- 先从 `repo-map`、`verify-matrix`、`acceptance examples` 和相关测试计划确认预期，再判断失败性质。
+- 需求或追溯缺陷应回退给产品 / 追溯负责人，不应由实现者自行猜测修补。
+- 契约缺陷应先在契约或对应 owner 流程中修复；不要在前端 / 后端绕过问题。
+- 不要只靠代码评审就关闭 finding；应重跑最小相关测试。
+- 提出 finding 的测试者 / 审查者应在修复后负责关闭它。
+- 环境和网络失败除非超出重试预算并重复出现，否则不应视为产品失败。
+- `FLAKY` 不是兜底垃圾桶；必须附带重跑结果和时序 / 隔离分析。

package/package-source/docs/codex-harness-engineering/templates/testing/test-data-plan.md

@@ -0,0 +1,36 @@
+# 测试数据计划
+
+**功能**:
+**Seed 负责人**:
+**重置命令**:
+**Seed 命令**:
+
+## 1. 账号
+
+| 角色 | 用户名 / 邮箱 | 权限 | 用途 |
+| --- | --- | --- | --- |
+| guest | N/A | 匿名 | 浏览 |
+| user | | 标准用户 | 核心流程 |
+| admin | | 管理员 | 管理流程 |
+
+## 2. 领域数据
+
+| Data ID | 类型 | 状态 | 用途 |
+| --- | --- | --- | --- |
+| seed-normal-001 | | 正常 | 正常路径 |
+| seed-empty-001 | | 空 | 空状态 |
+| seed-error-001 | | 无效 / 错误 | 错误路径 |
+
+## 3. 边界情况
+
+- 空数据:
+- 长文本:
+- 无效值:
+- 权限拒绝:
+- 网络 / API 错误:
+
+## 4. 重置规则
+
+- 测试必须可重复执行。
+- E2E 不得依赖手工准备的本地数据。
+- 破坏性测试必须重置或隔离其数据。

package/package-source/docs/codex-harness-engineering/templates/testing/test-matrix.md

@@ -0,0 +1,26 @@
+# 测试矩阵
+
+**功能**:
+**会话**:
+**最后更新**:
+
+| Requirement ID | 优先级 | 来源 / 风险 | 页面 / 组件 | 状态 | API / 契约 | 测试层级 | 测试用例 ID | Oracle | 测试数据 | 负责人 | 证据路径 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-001 | P0 | PRD / business_rule | | 默认 | | T5 E2E | E2E-001 | response + db | seed/default | 测试 | | planned |
+| PKG-LAYER-P5-MIGRATE-CONTRACT | P1 | `docs/agent-package-redesign/migration-plan.md` / 迁移安全边界 | docs / install manifest governance | Phase 5 contract | `-MigratePlan` / `-MigrateApply` 契约 | doc + package sync | `LAYERING-P5-CONTRACT-001` | 文档契约一致；禁止自动删除、自动覆盖和默认 thin 切换 | root docs、agent docs、package templates、ai-sync metadata | harness | `traces/LAYERING-P5-CONTRACT-001/`, refresh CheckOnly 输出 | done |
+| PKG-LAYER-P5-MIGRATE-APPLY | P1 | `docs/agent-package-redesign/migration-plan.md` / legacy vendor 迁移写入风险 | CLI / PowerShell installer | legacy full / drift / unknown / missing / manual-review / thin no-op | `-MigrateApply`, `-Confirm`, `.codex-harness/locks/package.lock.json` | integration | `TC-PKG-LAYER-P5-APPLY-001..006` | command output + lock hash/managedFiles + no-side-effect filesystem evidence | full install fixture、drift file、unknown file、missing vendor file、legacy docs、thin project fixture | harness | `traces/LAYERING-P5-APPLY-001/`, `tools/harness/tests/test-install-modes.ps1` 输出, doctor 输出, refresh CheckOnly 输出 | verified |
+| PKG-LAYER-P6-READINESS | P1 | `docs/agent-package-redesign/migration-plan.md` / 默认切换前 readiness 风险 | CLI / doctor | thin clean / legacy residue / missing user package / vendor / no config | `tools/harness/doctor.ps1`, `.codex-harness/state/config.json`, package lock | integration | `TC-PKG-LAYER-P6-READINESS-001..005` | doctor output + unchanged files + actionable remediation hints | thin project fixture、vendor fixture、legacy residue fixture、missing user package fixture、no config fixture | harness | `traces/LAYERING-P6-READINESS-001/`, doctor 输出, test-install-modes 输出 | verified |
+| PKG-LAYER-P7-DEFAULT-THIN | P1 | `docs/agent-package-redesign/target-layering-standard.md` / 默认安装兼容风险 | CLI / installer | default thin / explicit legacy full / vendor / user/project scope / thin plan / legacy plan | default install, `-Mode full`, `-Scope project`, `-Scope vendor`, `-Scope user`, `-Plan` | integration | `TC-PKG-LAYER-P7-DEFAULT-THIN-001..006` | required/forbidden path assertions + plan output + package lock/config + doctor output | empty temp project、user package fixture、legacy full fixture、vendor fixture、plan fixtures | harness | `traces/LAYERING-P7-DEFAULT-THIN-001/`, test-install-modes 输出, doctor 输出, verify 输出 | verified |
+| PKG-LAYER-P8-CLI-ALIAS | P1 | `docs/harness/new-project-usage.md` / 双实现风险 | CLI / docs | wrapper path / documented equivalent / no double implementation | install-user/init-project wrapper or documented `tools/install/install-agent.ps1 -Scope` equivalent | integration / doc check | `TC-PKG-LAYER-P8-CLI-ALIAS-001..003` | wrapper command output or doc assertion + smoke equivalence + no copied install logic | `p8-install-user-wrapper`, `p8-init-project-wrapper`, `p8-wrapper-no-double-implementation` | harness | `traces/LAYERING-P8-CLI-ALIAS-001/`, `docs/harness/new-project-usage.md`, refresh CheckOnly 输出 | planned |
+| PKG-LAYER-P9-RELEASE-VERIFY | P1 | `docs/agent-package-redesign/README.md` / 发布收口风险 | release verification | default install / compatibility / migration / docs state | smoke、doctor、refresh CheckOnly、`tools/harness/verify.ps1` | release | `LAYERING-P9-RELEASE-VERIFY-001` | fresh release evidence; 文档状态与实现一致；future work 边界明确 | 当前 PR 分支、traces、package surface、release docs | harness | `traces/LAYERING-P9-RELEASE-VERIFY-001/`, smoke 输出, doctor 输出, verify 输出 | planned |
+
+## 覆盖规则
+
+- 每条 P0/P1 需求都必须出现在这个矩阵中。
+- 每条 P0/P1 行都必须指向一个验收示例或场景 ID。
+- 每个必需 UI 状态都必须映射到 story、组件、E2E、视觉一致性，或给出明确豁免。
+- API / 数据变更必须映射到契约和 API 集成证据。
+- 计划中的实现任务应能够从这个矩阵推导出 affected tests。
+- 每个测试用例都必须声明来源和 Oracle，不能只声明测试层级。
+- POST / PUT / PATCH / DELETE、状态流转、权限和异步场景必须声明副作用或无副作用证据。
+- `planned` 或 `blocked` 的 P0/P1 行在最终 Verify 前必须给出解释。

package/package-source/docs/codex-harness-engineering/templates/testing/test-report.md

@@ -0,0 +1,41 @@
+# 测试报告
+
+**会话**:
+**代理**:
+**结论**: PASS / FAIL / BLOCKED
+**开始时间**:
+**结束时间**:
+
+## 环境
+
+- 前端:
+- 后端:
+- 分支:
+- Seed:
+
+## 摘要
+
+| 测试区域 | 总计 | PASS | FAIL | BLOCKED | 证据 |
+| --- | --- | --- | --- | --- | --- |
+| 单元 | | | | | |
+| 组件 | | | | | |
+| 契约 | | | | | |
+| API 集成 | | | | | |
+| E2E | | | | | |
+| 视觉 | | | | | |
+
+## Findings
+
+| Finding ID | 严重程度 | 失败类别 | 责任方提示 | 证据 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| | | | | | |
+
+## 返回给 Controller
+
+```text
+Verdict:
+Report:
+Findings:
+Needs repair:
+Owner hints:
+```

package/package-source/docs/codex-harness-engineering/templates/testing/verify-matrix.md

@@ -0,0 +1,46 @@
+# 验证矩阵
+
+**功能**:
+**任务 ID**:
+**生成时间**:
+
+| 检查项 | 命令 / 证据 | 必需 | 退出码 / 结论 | 报告路径 |
+| --- | --- | --- | --- | --- |
+| 验收 / 示例 | `ACCEPTANCE_EXAMPLES.md` + `ACCEPTANCE_CRITERIA.md` | P0/P1 必需 | | |
+| 追溯 | `TRACEABILITY_MATRIX.md` | P0/P1 必需 | | |
+| 静态检查 | `git diff --check` | 必需 | | |
+| 类型检查 | | 项目相关 | | |
+| Lint | | 项目相关 | | |
+| 开发验证 | affected tests / unit / component / local contract / typecheck / lint | 代码变更时必需 | | |
+| 单元 | | 代码变更时必需 | | |
+| 组件 | | UI 变更时必需 | | |
+| 契约 | | API / 数据变更时必需 | | |
+| API 集成 | | 后端变更时必需 | | |
+| Oracle 审查 | `TEST_STRATEGY.md` + `test-matrix.md` | P0/P1 / 高风险必需 | | |
+| 副作用断言 | DB diff / cache / event / audit / file evidence | 写操作、状态流转、异步必需 | | |
+| 权限无副作用 | denied response + unchanged data + no leak | 权限 / 多租户必需 | | |
+| 假测试检测 | Stage 2 review | 测试改动时必需 | | |
+| 受影响测试 | changed-code-related tests | 业务逻辑变更时必需 | | |
+| 用户验收链路 | story entry + action + business Oracle + side effect / no-side-effect evidence | feature_impl 完成前必需 | | |
+| E2E | | P0/P1 主流程变更时必需 | | |
+| P0 回归 | 核心 P0 场景 | 发布前必需 | | |
+| 发布候选验证 | cross-story flow + P0/P1 regression + contract/API + E2E/visual as applicable | release 完成前必需 | | |
+| 失败态验收 | negative path / denied path / invalid state / downstream failure evidence | P0/P1 / 高风险必需 | | |
+| 视觉一致性 | `visual-parity-review.md` | UI 变更时必需 | | |
+| 覆盖率 | `coverage-summary.json` | 如策略适用 | | |
+| PKG-LAYER-P5-MIGRATE-APPLY 自然语言用例 | `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 中 `TC-PKG-LAYER-P5-APPLY-001..006` | P1 必需 | planned | `traces/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P5-MIGRATE-APPLY TDD RED/GREEN/REFACTOR | `tools/harness/tests/test-install-modes.ps1` 先补迁移执行失败断言，再实现通过 | P1 必需 | planned | `traces/` |
+| PKG-LAYER-P5-MIGRATE-APPLY 验收链路 | clean legacy full、drift、unknown、missing vendor、manual-review、thin no-op smoke | P1 必需 | planned | `traces/`, doctor 输出, refresh CheckOnly 输出 |
+| PKG-LAYER-P6-READINESS 自然语言用例 | `TC-PKG-LAYER-P6-READINESS-001..005` 覆盖 thin clean、missing user package、legacy residue、vendor、no config | P1 必需 | verified | `traces/LAYERING-P6-READINESS-001/`, doctor/test-install-modes 输出 |
+| PKG-LAYER-P6-READINESS 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `readiness-thin-clean`、`readiness-missing-user-package`、`readiness-legacy-residue`、`readiness-vendor-lock`、`readiness-no-config` | P1 必需 | verified | `traces/LAYERING-P6-READINESS-001/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P7-DEFAULT-THIN 自然语言用例 | `TC-PKG-LAYER-P7-DEFAULT-THIN-001..006` 覆盖默认 thin、显式 legacy full、project/vendor/user scope、thin plan 和 legacy plan | P1 必需 | verified | `traces/LAYERING-P7-DEFAULT-THIN-001/`, test-install-modes 输出 |
+| PKG-LAYER-P7-DEFAULT-THIN 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `p7-default-thin-install`、`p7-legacy-full-install`、`p7-scope-project-install`、`p7-scope-vendor-install`、`p7-scope-user-install`、`p7-install-plan-profiles` | P1 必需 | verified | `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P8-CLI-ALIAS 自然语言用例 | `TC-PKG-LAYER-P8-CLI-ALIAS-001..003` 覆盖等价入口、install-user wrapper、init-project wrapper 和 no-double-implementation 风险 | P1 必需 | planned | `traces/LAYERING-P8-CLI-ALIAS-001/`, docs/harness/new-project-usage.md |
+| PKG-LAYER-P8-CLI-ALIAS 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `p8-install-user-wrapper`、`p8-init-project-wrapper`、`p8-wrapper-no-double-implementation` | P1 必需 | planned | `traces/LAYERING-P8-CLI-ALIAS-001/`, `tools/harness/tests/test-install-modes.ps1` |
+
+## 最终规则
+
+最终交付要求每一行必需项都有 fresh evidence，或提供明确的 BLOCKED / exemption 记录并获得 owner 批准。
+开发验证和验收验证是两类独立证据：单元、组件、局部 smoke、类型检查、lint 或 affected tests 不能替代用户验收链路；各子任务局部测试通过也不能替代发布候选验证。
+用户验收链路、发布候选验证和失败态验收必须在实现完成后以当前变更集重新运行，证据需要能回溯到 Requirement ID、入口、测试数据、Oracle 和证据路径。
+Stage 17 只应确认新鲜度与回归状态；缺失的验收示例或首次测试范围定义不应在这里补写。

package/package-source/docs/codex-harness-engineering/templates/trace/eval-case.yaml

@@ -0,0 +1,24 @@
+id: codex-harness-docs-check
+name: Codex Harness 文档完整性检查
+description: 检查 Codex Harness 文档是否包含任务、上下文、执行、验证、CI、MCP、回归和 trace 模板。
+input:
+  docs_root: docs/codex-harness-engineering
+checks:
+  - id: has-readme
+    type: file_exists
+    path: docs/codex-harness-engineering/README.md
+  - id: has-agents-template
+    type: file_exists
+    path: docs/codex-harness-engineering/templates/runtime/AGENTS.md
+  - id: has-ci-template
+    type: file_exists
+    path: docs/codex-harness-engineering/templates/ci/github-action-codex-review.yml
+  - id: has-mcp-template
+    type: file_exists
+    path: docs/codex-harness-engineering/templates/config/mcp-config.toml
+  - id: has-trace-schema
+    type: file_exists
+    path: docs/codex-harness-engineering/templates/trace/trace.schema.json
+expected:
+  result: pass
+  minimum_score: 1.0