@pzy560117/codex-harness 0.1.0 → 0.1.1

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

@@ -0,0 +1,689 @@
+# 自然语言测试用例
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 编写规则
+
+- 每条 PRD 需求必须先识别需求类型、优先级、风险因子，再按下方“需求类型覆盖矩阵”生成自然语言测试用例。
+- P0 需求默认不少于 5 条自然语言测试用例；P1 需求默认不少于 3 条；P2 需求可为 1-2 条，但必须说明不进入 TDD 候选的原因。
+- 低于默认数量必须写明豁免原因、替代证据和 owner 批准人。
+- 每条用例必须绑定 Requirement ID、PRD 来源、测试层级、测试数据、Oracle 和证据路径。
+- 写操作必须说明业务副作用；权限拒绝、非法状态、校验失败和重放请求必须说明无副作用证据。
+- TDD 候选用例必须写清 RED 预期失败，供 `qa_contract.tdd_contract.red` 消费。
+- 自然语言用例先于测试脚本和实现代码存在；缺失时不得进入 `feature_impl`。
+
+## 需求类型覆盖矩阵
+
+| 需求类型 | 最少用例数 | 必须覆盖 |
+| --- | ---: | --- |
+| 只读查询 / 详情 | 3 | 正常返回、空数据、无权限或不可见数据 |
+| 列表 / 搜索 / 筛选 / 排序 / 分页 | 5 | 默认列表、筛选命中、无结果、分页边界、排序或组合条件 |
+| 新增 / 创建 | 6 | 成功创建、必填缺失、格式非法、重复提交、权限拒绝无副作用、数据库副作用 |
+| 编辑 / 更新 | 6 | 成功更新、部分字段更新、非法字段、并发或版本冲突、权限拒绝无副作用、非目标字段不变 |
+| 删除 / 撤销 / 取消 | 6 | 成功删除、重复删除、非法状态删除、权限拒绝、关联数据处理、副作用或软删除证据 |
+| 表单校验 | 4 起 | 合法值、必填、边界值、非法格式；每个核心字段至少覆盖 1 个负例 |
+| 权限需求 | 每个关键角色至少 2 | 允许路径、拒绝路径；高风险场景补水平越权和垂直越权 |
+| 状态机 / 审批 / 订单流 | 每个关键状态转移至少 2 | 合法转移成功、非法转移失败且无污染 |
+| 异步任务 / 队列 / Webhook | 5 | 投递成功、消费成功、失败重试、幂等、最终失败或告警 |
+| 外部系统集成 | 5 | 成功、超时、错误码映射、重试或降级、数据不一致处理 |
+| 文件上传 / 导入 / 导出 | 5 | 正常文件、空文件、格式错误、大文件或边界、权限或数据范围 |
+| 报表 / 统计 / 金额 / 库存 | 6 | 计算正确、空数据、边界值、舍入或时区、权限范围、不变量守恒 |
+| UI 交互 | 5 | 默认态、加载态、成功态、错误态、空态；必要时补移动端或可访问性 |
+| 安全 / 高风险需求 | 6 起 | 正常、拒绝、越权、注入或非法输入、敏感信息不泄露、审计证据 |
+
+## 加量规则
+
+- 多角色、多租户、资金、库存、权限、删除、审批、外部集成、异步链路、历史缺陷或合规要求出现任一项时，在矩阵最少用例数基础上加 1-3 条。
+- 一个需求同时属于多种类型时，按风险最高的类型取基准，再补齐其他类型的必需路径。
+- 写操作至少包含 1 条成功副作用用例和 1 条失败无副作用用例。
+- 权限相关需求至少覆盖 1 条允许路径和 1 条拒绝路径；涉及数据隔离时必须补水平越权用例。
+- 状态机需求必须按关键状态转移拆用例，不得只写一条端到端 happy path。
+- TDD 候选优先选择可在单元、组件、契约或 API 层快速 RED 的行为；纯视觉检查、长链路 E2E 或一次性人工验收不应作为唯一 TDD 种子。
+
+## 用例清单
+
+### TC-REQ-001-001: <用例标题>
+
+- Requirement ID: `<FR-001>`
+- PRD 来源: `<prd-lite.md#section-or-line>`
+- 需求类型: `<从覆盖矩阵选择>`
+- 最小用例依据: `<矩阵行 + 风险加量说明>`
+- 风险因子: `<none / 多角色 / 多租户 / 资金 / 库存 / 权限 / 删除 / 审批 / 外部集成 / 异步链路 / 历史缺陷 / 合规>`
+- 矩阵基准用例数:
+- 风险加量:
+- 最终要求用例数:
+- 用户角色:
+- 优先级: `P0/P1/P2`
+- 覆盖路径: `happy_path / edge_case / error_path / permission / state_transition / concurrency`
+- 前置条件:
+- 测试数据:
+- 操作步骤:
+  1.
+- 预期结果:
+- Oracle:
+  - response_or_ui:
+  - database_or_state:
+  - side_effect_or_no_side_effect:
+- 推荐测试层级: `unit / component / contract_or_api / integration / e2e`
+- TDD 候选: `yes / no`
+- RED 预期失败:
+- 不进入 TDD 原因: `<仅当 TDD 候选为 no 时填写>`
+- 证据路径:
+- 关联 `tdd_contract`: `<task-id>.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `<task-id>.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix>`
+
+### TC-PKG-LAYER-P5-APPLY-001: clean legacy full 项目确认迁移后写入 vendor managed lock
+
+- Requirement ID: `PKG-LAYER-P5-MIGRATE-APPLY`
+- PRD 来源: `docs/agent-package-redesign/migration-plan.md#phase-5`
+- 需求类型: `编辑 / 更新`
+- 最小用例依据: `写操作，覆盖成功写入、失败无副作用、非法状态和边界输入`
+- 风险因子: `历史缺陷 / 文件系统写入 / 删除风险`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: 临时 git 项目已通过 `-Mode full` 安装，`.agents/` vendor 文件与当前 package hash 一致。
+- 测试数据: full install fixture、当前 `install-manifest.json`、`.codex-harness/locks/package.lock.json`。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -MigrateApply -Confirm`。
+- 预期结果: 命令 exit 0；lock 中只新增 hash 一致的 vendor managed files；`.agents/` 和 legacy docs 未被删除。
+- Oracle:
+  - response_or_ui: 输出 `status=confirmed-write` 和 `adopt-vendor-managed` 统计。
+  - database_or_state: `.codex-harness/locks/package.lock.json` 记录 version、sourceCommit、installMode/vendor 和 managedFiles。
+  - side_effect_or_no_side_effect: `.agents/` 仍存在；不写入 missing vendor 文件。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 未实现 `-MigrateApply` 时参数不存在，或未写入 expected lock 字段。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P5-APPLY-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P5-APPLY-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P5-APPLY-002: blocked-user-drift 阻断迁移写入
+
+- Requirement ID: `PKG-LAYER-P5-MIGRATE-APPLY`
+- PRD 来源: `docs/harness/install-manifest-governance.md#迁移执行契约`
+- 需求类型: `编辑 / 更新`
+- 最小用例依据: `写操作失败无副作用`
+- 风险因子: `历史缺陷 / 用户改动保护`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `error_path`
+- 前置条件: legacy full fixture 中至少一个 manifest vendor 文件被本地修改。
+- 测试数据: `.agents/workflows/*.md` 追加本地 drift。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -MigrateApply -Confirm`。
+- 预期结果: 命令 exit 非 0；输出 `blocked-user-drift`；lock 内容保持不变。
+- Oracle:
+  - response_or_ui: 输出 `status=blocked`、阻断路径和人工处理建议。
+  - database_or_state: lock hash 和 managedFiles 未变化。
+  - side_effect_or_no_side_effect: drift 文件未被覆盖或删除。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 未实现阻断逻辑时命令错误落锁或没有非 0 退出。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P5-APPLY-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P5-APPLY-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P5-APPLY-003: unknown legacy file 阻断迁移写入
+
+- Requirement ID: `PKG-LAYER-P5-MIGRATE-APPLY`
+- PRD 来源: `docs/harness/install-manifest-governance.md#迁移执行契约`
+- 需求类型: `编辑 / 更新`
+- 最小用例依据: `写操作非法状态`
+- 风险因子: `未知本地文件 / 删除风险`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `error_path`
+- 前置条件: legacy full fixture 的 `.agents/` 下存在 manifest 未声明文件。
+- 测试数据: `.agents/LOCAL-ONLY.txt`。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -MigrateApply -Confirm`。
+- 预期结果: 命令 exit 非 0；输出 `unknown-legacy-file`；lock 不变。
+- Oracle:
+  - response_or_ui: 输出 `status=blocked` 和未知文件路径。
+  - database_or_state: `.codex-harness/locks/package.lock.json` 未新增 unknown 文件。
+  - side_effect_or_no_side_effect: unknown 文件仍存在。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 未实现 unknown 阻断时命令错误落锁。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P5-APPLY-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P5-APPLY-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P5-APPLY-004: missing vendor file 只报告不写入 managedFiles
+
+- Requirement ID: `PKG-LAYER-P5-MIGRATE-APPLY`
+- PRD 来源: `docs/harness/install-manifest-governance.md#迁移执行契约`
+- 需求类型: `编辑 / 更新`
+- 最小用例依据: `写操作边界输入`
+- 风险因子: `manifest 缺失文件`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `edge_case`
+- 前置条件: legacy full fixture 删除一个 manifest 声明的 vendor 文件，且无 drift/unknown/manual-review 阻断。
+- 测试数据: 删除 `.agents/` 下一个 manifest vendor 文件。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -MigrateApply -Confirm`。
+- 预期结果: 命令报告 `missing-vendor-file`；缺失文件不被写入 managedFiles。
+- Oracle:
+  - response_or_ui: 输出 missing 路径和 nextSteps。
+  - database_or_state: managedFiles 不包含缺失路径。
+  - side_effect_or_no_side_effect: 不凭空重建缺失文件。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 未实现 missing 过滤时缺失文件被错误纳入 lock。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P5-APPLY-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P5-APPLY-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P5-APPLY-005: manual-review legacy docs 阻断自动迁移
+
+- Requirement ID: `PKG-LAYER-P5-MIGRATE-APPLY`
+- PRD 来源: `docs/agent-package-redesign/migration-plan.md#phase-5`
+- 需求类型: `编辑 / 更新`
+- 最小用例依据: `写操作非法状态`
+- 风险因子: `用户文档保护`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `error_path`
+- 前置条件: legacy full fixture 中存在 `docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/` 残留。
+- 测试数据: legacy docs 目录。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -MigrateApply -Confirm`。
+- 预期结果: 命令 exit 非 0；输出 `manual-review`；不删除 legacy docs。
+- Oracle:
+  - response_or_ui: 输出人工复核目录。
+  - database_or_state: lock 不因 legacy docs 自动改变。
+  - side_effect_or_no_side_effect: legacy docs 目录仍存在。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 未实现 manual-review 阻断时命令继续写 lock。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P5-APPLY-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P5-APPLY-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P5-APPLY-006: thin project 无 legacy vendor 时 no-op
+
+- Requirement ID: `PKG-LAYER-P5-MIGRATE-APPLY`
+- PRD 来源: `docs/harness/new-project-usage.md#旧项目迁移`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `无 legacy vendor 的只读/无操作边界`
+- 风险因子: `none`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `edge_case`
+- 前置条件: thin `-Scope project` fixture 不存在 `.agents/`。
+- 测试数据: thin project fixture。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -MigrateApply`。
+- 预期结果: 命令 exit 0；输出 `Status: no-legacy-vendor` 或 `status=no-op`；不创建 vendor managed lock。
+- Oracle:
+  - response_or_ui: 输出 no-op/no-legacy-vendor。
+  - database_or_state: `.codex-harness/locks/package.lock.json` 不新增 vendor managed files。
+  - side_effect_or_no_side_effect: 不创建 `.agents/`。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 未实现 no-op 入口时参数不存在或错误创建 vendor 内容。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P5-APPLY-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P5-APPLY-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P6-READINESS-001: thin clean 项目 readiness PASS
+
+- Requirement ID: `PKG-LAYER-P6-READINESS`
+- PRD 来源: `docs/agent-package-redesign/migration-plan.md#phase-6`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `doctor readiness 只读检查`
+- 风险因子: `none`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: thin project fixture 完整。
+- 测试数据: `.codex-harness/state/config.json`、lock、manifest snapshot、spec docs。
+- 操作步骤:
+  1. 运行 `tools/harness/doctor.ps1`。
+- 预期结果: doctor exit 0。
+- Oracle:
+  - response_or_ui: readiness PASS 或无 error。
+  - database_or_state: 文件系统无变化。
+  - side_effect_or_no_side_effect: doctor 只读。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: readiness gate 未实现时缺少 PASS/修复建议断言。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P6-READINESS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P6-READINESS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P6-READINESS-002: thin 项目缺少用户级 package 时 readiness WARN
+
+- Requirement ID: `PKG-LAYER-P6-READINESS`
+- PRD 来源: `docs/agent-package-redesign/migration-plan.md#phase-6`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `doctor readiness 只读检查，覆盖不可见用户级 package 边界`
+- 风险因子: `用户环境漂移 / package root 缺失`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `edge_case`
+- 前置条件: thin project fixture 的 `.codex-harness/state/config.json` 指向不存在的用户级 packageRoot。
+- 测试数据: `readiness-missing-user-package` fixture、篡改后的 packageRoot、完整 lock 和 manifest snapshot。
+- 操作步骤:
+  1. 运行 `tools/harness/doctor.ps1`。
+- 预期结果: doctor exit 0；输出 `Readiness gate: WARN`、`ProjectShape: thin-project-missing-user-package` 和重新安装用户级 package 的修复命令。
+- Oracle:
+  - response_or_ui: 输出 `FixCommand: powershell -NoProfile -ExecutionPolicy Bypass -File .\agent\tools/install/install-agent.ps1 -Scope user`。
+  - database_or_state: `.codex-harness/state/config.json`、lock、项目文件内容保持不变。
+  - side_effect_or_no_side_effect: doctor 不创建 package root、不改写 config、不删除任何文件。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: readiness gate 未实现时不会区分 missing user package，也不会输出修复命令。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P6-READINESS-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P6-READINESS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P6-READINESS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P6-READINESS-003: thin 项目存在 legacy residue 时 readiness WARN
+
+- Requirement ID: `PKG-LAYER-P6-READINESS`
+- PRD 来源: `docs/harness/install-manifest-governance.md#readiness-gate`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `doctor readiness 只读检查，覆盖 legacy residue warning`
+- 风险因子: `legacy 残留 / 删除风险`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `edge_case`
+- 前置条件: thin project fixture 中手动创建 `.agents/` 和 `docs/testing/` legacy residue。
+- 测试数据: `readiness-legacy-residue` fixture、legacy residue 目录、完整 thin config/lock/snapshot。
+- 操作步骤:
+  1. 运行 `tools/harness/doctor.ps1`。
+- 预期结果: doctor exit 0；输出 `Readiness gate: WARN`、`ProjectShape: thin-project-with-legacy-residue` 和先运行 `-MigratePlan` 的修复命令。
+- Oracle:
+  - response_or_ui: 输出 `.agents`、`docs\testing` 残留 warning 和 `-MigratePlan` fix command。
+  - database_or_state: `.agents/` 和 `docs/testing/` 仍存在。
+  - side_effect_or_no_side_effect: doctor 不自动迁移、不删除 legacy residue。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: readiness gate 未实现时只输出旧 warning，缺少 project shape 和 migration fix command。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P6-READINESS-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P6-READINESS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P6-READINESS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P6-READINESS-004: vendor 项目 readiness PASS 并提示显式 vendor 修复命令
+
+- Requirement ID: `PKG-LAYER-P6-READINESS`
+- PRD 来源: `docs/harness/new-project-usage.md#兼容入口`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `doctor readiness 只读检查，覆盖 vendor 兼容路径`
+- 风险因子: `兼容性 / vendor lock`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: 项目已通过 `-Scope vendor` 安装，存在完整 `.agents/`、vendor config 和 package lock。
+- 测试数据: `readiness-vendor-lock` fixture、vendor managed lock、`.agents/tools/install/install-agent.ps1`。
+- 操作步骤:
+  1. 运行 `tools/harness/doctor.ps1`。
+- 预期结果: doctor exit 0；输出 `Readiness gate: PASS`、`ProjectShape: vendor-project` 和显式 `-Scope vendor` 修复命令。
+- Oracle:
+  - response_or_ui: 输出 vendor project 分类和 `FixCommand: powershell -NoProfile -ExecutionPolicy Bypass -File .\.agents\tools/install/install-agent.ps1 -ProjectRoot . -Scope vendor`。
+  - database_or_state: vendor lock 和 `.agents/` 文件不变。
+  - side_effect_or_no_side_effect: doctor 只读，不重新 vendor 安装。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: readiness gate 未实现时无法区分 vendor-project 或缺少显式 vendor 修复命令。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P6-READINESS-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P6-READINESS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P6-READINESS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P6-READINESS-005: 未安装项目 readiness FAIL 并提示 thin init
+
+- Requirement ID: `PKG-LAYER-P6-READINESS`
+- PRD 来源: `docs/agent-package-redesign/migration-plan.md#phase-6`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `doctor readiness 只读检查，覆盖未安装空项目`
+- 风险因子: `none`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `error_path`
+- 前置条件: 临时 git 项目没有 `.codex-harness/state/config.json`、package lock 和 `.agents/`。
+- 测试数据: `readiness-no-config` empty git fixture。
+- 操作步骤:
+  1. 运行 `tools/harness/doctor.ps1`。
+- 预期结果: doctor exit 非 0；输出 `Readiness gate: FAIL`、`ProjectShape: not-installed` 和 `-Scope project` 初始化命令。
+- Oracle:
+  - response_or_ui: 输出 `FixCommand: powershell -NoProfile -ExecutionPolicy Bypass -File .\agent\tools/install/install-agent.ps1 -ProjectRoot . -Scope project`。
+  - database_or_state: 空项目不新增 `.codex-harness/`、`.codex/` 或 `.agents/`。
+  - side_effect_or_no_side_effect: doctor 只读，不自动初始化项目。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: readiness gate 未实现时未安装项目只表现为旧错误或缺少 thin init 修复命令。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P6-READINESS-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P6-READINESS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P6-READINESS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P7-DEFAULT-THIN-001: 默认安装输出 thin project
+
+- Requirement ID: `PKG-LAYER-P7-DEFAULT-THIN`
+- PRD 来源: `docs/agent-package-redesign/target-layering-standard.md#项目默认目录输出`
+- 需求类型: `新增 / 创建`
+- 最小用例依据: `默认安装创建项目 runtime 输出`
+- 风险因子: `兼容性 / 文件系统写入`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: 空临时 git 项目。
+- 测试数据: 默认安装命令无 `-Mode` / `-Scope`。
+- 操作步骤:
+  1. 运行默认安装命令。
+- 预期结果: 默认输出为 thin project，不复制完整 `.agents/skills`、`.agents/workflows` 或 legacy docs。
+- Oracle:
+  - response_or_ui: install success。
+  - database_or_state: `.codex-harness/state/config.json` 标记 project/thin；必需 spec/ai/architecture 文件存在。
+  - side_effect_or_no_side_effect: legacy/vendor 目录不存在。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 默认仍走 legacy full 时 forbidden path 断言失败。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P7-DEFAULT-THIN-002: 显式 legacy full 入口继续输出完整兼容包
+
+- Requirement ID: `PKG-LAYER-P7-DEFAULT-THIN`
+- PRD 来源: `docs/harness/new-project-usage.md#兼容入口`
+- 需求类型: `新增 / 创建`
+- 最小用例依据: `默认安装创建项目 runtime 输出，兼容入口必须有独立正向用例`
+- 风险因子: `兼容性 / 文件系统写入`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: 空临时 git 项目。
+- 测试数据: `p7-legacy-full-install` fixture、显式 `-Mode full`。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -Mode full -InitSmoke`。
+- 预期结果: 安装成功；存在完整 `.agents/`、legacy docs 和 vendor lock；readiness 分类为 legacy/full warning。
+- Oracle:
+  - response_or_ui: 输出 `Mode: full` 和 install completed。
+  - database_or_state: `.agents/tools/install/install-agent.ps1`、`.agents/skills/*`、`docs/harness/*`、`docs/testing/*` 存在。
+  - side_effect_or_no_side_effect: 只写入临时 fixture，不影响默认 thin fixture。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 默认 thin 改造误伤 full 入口时 `.agents/` 或 legacy docs 缺失。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P7-DEFAULT-THIN-003: 显式 Scope project 与默认 thin 输出一致
+
+- Requirement ID: `PKG-LAYER-P7-DEFAULT-THIN`
+- PRD 来源: `docs/agent-package-redesign/target-layering-standard.md#项目默认目录输出`
+- 需求类型: `新增 / 创建`
+- 最小用例依据: `默认安装创建项目 runtime 输出，Scope project 必须作为等价 thin 入口`
+- 风险因子: `兼容性 / 文件系统写入`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: 空临时 git 项目。
+- 测试数据: `p7-scope-project-install` fixture、显式 `-Scope project`。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -Scope project -InitSmoke`。
+- 预期结果: 输出与默认 thin 一致；存在 `.codex-harness/`、`.codex/`、`docs/spec/`；不存在 `.agents/` 和 legacy docs。
+- Oracle:
+  - response_or_ui: 输出 `Scope: project`。
+  - database_or_state: package lock `installMode=project`、`vendor=false`。
+  - side_effect_or_no_side_effect: 不创建完整 `.agents/`，不复制 legacy docs。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: Scope project 仍输出 legacy project 或 plan 与实际输出不一致。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P7-DEFAULT-THIN-004: Scope vendor 保持 vendor-only 输出
+
+- Requirement ID: `PKG-LAYER-P7-DEFAULT-THIN`
+- PRD 来源: `docs/harness/install-manifest-governance.md#vendor-project`
+- 需求类型: `新增 / 创建`
+- 最小用例依据: `默认安装创建项目 runtime 输出，vendor 兼容入口必须独立验证`
+- 风险因子: `兼容性 / 文件系统写入`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: 空临时 git 项目。
+- 测试数据: `p7-scope-vendor-install` fixture、显式 `-Scope vendor`。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -ProjectRoot <fixture> -Scope vendor`。
+- 预期结果: 只安装完整 `.agents/` vendor package 和 `.codex-harness/` 元数据，不输出 project runtime/spec docs。
+- Oracle:
+  - response_or_ui: 输出 `Scope: vendor`。
+  - database_or_state: `.agents/tools/install/install-agent.ps1` 存在，package lock `installMode=vendor`、`vendor=true`。
+  - side_effect_or_no_side_effect: `tools/harness/codex-loop.ps1` 和 `docs/spec/` 不进入项目根。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 默认 thin 改造误把 project runtime/spec 写入 vendor-only 项目。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P7-DEFAULT-THIN-005: Scope user 只安装用户级 package
+
+- Requirement ID: `PKG-LAYER-P7-DEFAULT-THIN`
+- PRD 来源: `docs/harness/new-project-usage.md#用户级安装`
+- 需求类型: `新增 / 创建`
+- 最小用例依据: `默认安装创建项目 runtime 输出，用户级 package 入口必须不污染项目`
+- 风险因子: `兼容性 / 用户目录写入`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: 测试将 `USERPROFILE` 指向临时目录。
+- 测试数据: `p7-scope-user-install` fixture、临时 user profile。
+- 操作步骤:
+  1. 运行 `tools/install/install-agent.ps1 -Scope user`。
+- 预期结果: 用户级 skills/workflows/package lock 存在；项目根不创建 `.codex-harness/`、`tools/harness/codex-loop.ps1` 或 `docs/spec/`。
+- Oracle:
+  - response_or_ui: 输出用户 package root 和 user package lock。
+  - database_or_state: `.codex/packages/codex-harness/package.lock.json` 存在且 `latestVersion=version`。
+  - side_effect_or_no_side_effect: 不写入业务项目 runtime。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: 默认 thin 改造误把 user scope 当成 project install。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P7-DEFAULT-THIN-006: thin plan 与实际输出一致且 legacy plan 显式保留
+
+- Requirement ID: `PKG-LAYER-P7-DEFAULT-THIN`
+- PRD 来源: `docs/agent-package-redesign/target-layering-standard.md#安装计划契约`
+- 需求类型: `新增 / 创建`
+- 最小用例依据: `默认安装创建项目 runtime 输出，公开 plan 契约必须覆盖`
+- 风险因子: `契约漂移 / 兼容性`
+- 矩阵基准用例数: 6
+- 风险加量: 0
+- 最终要求用例数: 6
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `edge_case`
+- 前置条件: 空临时 git 项目。
+- 测试数据: `p7-default-plan`、`p7-scope-project-plan`、`p7-legacy-project-plan` fixtures。
+- 操作步骤:
+  1. 运行默认 `-Plan`。
+  2. 运行 `-Scope project -Plan`。
+  3. 运行 `-Mode project -Plan`。
+- 预期结果: 默认和 `-Scope project` plan 不包含 `docs/testing/`、`docs/harness/`、`docs/requirement-prep-kit/`、`docs/knowledge/`；显式 `-Mode project -Plan` 仍包含 legacy project docs。
+- Oracle:
+  - response_or_ui: plan 输出 `PlanOnly: True` 和 `No files will be changed.`。
+  - database_or_state: 三个 plan 命令均不创建 `.agents/` 或 `.codex-harness/`。
+  - side_effect_or_no_side_effect: plan 命令只读；thin plan 与实际 thin forbidden paths 一致。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: plan 仍列 legacy docs 或 plan 命令写文件。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P7-DEFAULT-THIN-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P8-CLI-ALIAS-001: CLI 薄入口等价调用 Scope user/project
+
+- Requirement ID: `PKG-LAYER-P8-CLI-ALIAS`
+- PRD 来源: `docs/harness/new-project-usage.md`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `薄 wrapper 或文档化等价入口`
+- 风险因子: `双实现风险`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: tools/install/install-agent.ps1 已支持 `-Scope user/project/vendor`。
+- 测试数据: wrapper 或文档命令。
+- 操作步骤:
+  1. 运行首选 install-user/init-project 命令或验证文档中仅声明等价命令。
+- 预期结果: 首选入口不复制第二套安装逻辑，输出与 `-Scope user/project` 一致。
+- Oracle:
+  - response_or_ui: 命令成功或文档明确未实现 wrapper。
+  - database_or_state: 输出目录与对应 Scope smoke 一致。
+  - side_effect_or_no_side_effect: wrapper 不绕过 manifest/lock/doctor。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: wrapper 缺失或文档声称不可用命令时断言失败。
+- 不进入 TDD 原因:
+- 证据路径: `traces/`, `tools/harness/tests/test-install-modes.ps1 输出`, `docs/harness/new-project-usage.md`
+- 关联 `tdd_contract`: `LAYERING-P8-CLI-ALIAS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P8-CLI-ALIAS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P8-CLI-ALIAS-002: install-user wrapper 只安装用户级 package
+
+- Requirement ID: `PKG-LAYER-P8-CLI-ALIAS`
+- PRD 来源: `docs/harness/new-project-usage.md`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `薄 wrapper 或文档化等价入口`
+- 风险因子: `双实现风险`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: `tools/install/install-user.ps1` 与 package template 中的 `tools/install/install-user.ps1` 已存在。
+- 测试数据: `p8-install-user-wrapper` fixture，`USERPROFILE` 指向隔离临时目录。
+- 操作步骤:
+  1. 在隔离用户目录下运行 `tools/install/install-user.ps1`。
+  2. 对比输出和 `tools/install/install-agent.ps1 -Scope user` 的关键结果。
+- 预期结果: wrapper 输出 `AliasScope: user`、完成用户级 package lock，不创建业务项目 `.codex-harness/` 或 `.agents/`。
+- Oracle:
+  - response_or_ui: 输出包含 `AliasScope: user`、`Install completed.`、`Mode: user`、`UserPackageLock:`。
+  - database_or_state: 用户级 lock 位于临时 `%USERPROFILE%\.codex\packages\codex-harness\package.lock.json`。
+  - side_effect_or_no_side_effect: 业务项目目录不被 wrapper 写入，wrapper 只转发参数给 `tools/install/install-agent.ps1`。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: wrapper 缺失、参数转发错位或未生成用户级 lock。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P8-CLI-ALIAS-001/`, `tools/harness/tests/test-install-modes.ps1 输出`
+- 关联 `tdd_contract`: `LAYERING-P8-CLI-ALIAS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P8-CLI-ALIAS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+### TC-PKG-LAYER-P8-CLI-ALIAS-003: init-project wrapper 只初始化 thin project
+
+- Requirement ID: `PKG-LAYER-P8-CLI-ALIAS`
+- PRD 来源: `docs/harness/new-project-usage.md`
+- 需求类型: `只读查询 / 详情`
+- 最小用例依据: `薄 wrapper 或文档化等价入口`
+- 风险因子: `双实现风险`
+- 矩阵基准用例数: 3
+- 风险加量: 0
+- 最终要求用例数: 3
+- 用户角色: harness maintainer
+- 优先级: `P1`
+- 覆盖路径: `happy_path`
+- 前置条件: `tools/install/init-project.ps1` 与 package template 中的 `tools/install/init-project.ps1` 已存在。
+- 测试数据: `p8-init-project-wrapper` fixture，空临时 git repo。
+- 操作步骤:
+  1. 运行 `tools/install/init-project.ps1 -ProjectRoot <fixture> -InitSmoke -SkipBaselineCommit`。
+  2. 对比输出和 `tools/install/install-agent.ps1 -Scope project` 的 thin required/forbidden paths。
+  3. 检查 wrapper 源码不复制 `tools/install/install-agent.ps1` 安装逻辑。
+- 预期结果: wrapper 输出 `AliasScope: project`，项目存在 `.codex-harness/state/config.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/manifests/install-manifest.json`、`docs/spec/01..14`，且不存在 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/`、`docs/requirement-prep-kit/`。
+- Oracle:
+  - response_or_ui: 输出包含 `AliasScope: project`、`Install completed.`、`Scope: project`。
+  - database_or_state: 项目 thin 输出与 `-Scope project` smoke required/forbidden paths 一致。
+  - side_effect_or_no_side_effect: wrapper 只定位同目录 `tools/install/install-agent.ps1` 并通过 hashtable splatting 转发参数，不维护第二套安装逻辑。
+- 推荐测试层级: `integration`
+- TDD 候选: `yes`
+- RED 预期失败: wrapper 缺失、输出 legacy docs、创建 `.agents/` 或源码复制安装逻辑。
+- 不进入 TDD 原因:
+- 证据路径: `traces/LAYERING-P8-CLI-ALIAS-001/`, `tools/harness/tests/test-install-modes.ps1 输出`, `docs/harness/new-project-usage.md`
+- 关联 `tdd_contract`: `LAYERING-P8-CLI-ALIAS-001.qa_contract.tdd_contract.red.source_case_ids`
+- 关联验收链路: `LAYERING-P8-CLI-ALIAS-001.qa_contract.story_full_chain.source_case_ids / acceptance_validation.source_case_ids / verify-matrix`
+
+## 覆盖检查
+
+| Requirement ID | PRD 来源 | 需求类型 | 优先级 | 风险因子 | 矩阵基准用例数 | 风险加量 | 最终要求用例数 | 已写用例数 | 自然语言用例 | TDD 候选 | 非 TDD 映射 | Oracle 完整 | 数据完整 | 证据路径 | 豁免 / 批准 |
+| --- | --- | --- | --- | --- | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | --- | --- |
+| PKG-LAYER-P5-MIGRATE-APPLY | migration-plan / install-manifest-governance | 编辑 / 更新 | P1 | 文件系统写入 / 用户改动保护 | 6 | 0 | 6 | 6 | TC-PKG-LAYER-P5-APPLY-001..006 | yes | verify-matrix | yes | yes | traces/, test-install-modes 输出 | none |
+| PKG-LAYER-P6-READINESS | migration-plan | 只读查询 / 详情 | P1 | none / 用户环境漂移 / legacy 残留 | 3 | 0 | 3 | 5 | TC-PKG-LAYER-P6-READINESS-001..005 | yes | verify-matrix | yes | yes | traces/, doctor/test-install-modes 输出 | none |
+| PKG-LAYER-P7-DEFAULT-THIN | target-layering-standard | 新增 / 创建 | P1 | 兼容性 / 文件系统写入 / 契约漂移 | 6 | 0 | 6 | 6 | TC-PKG-LAYER-P7-DEFAULT-THIN-001..006 | yes | verify-matrix | yes | yes | traces/, test-install-modes 输出 | none |
+| PKG-LAYER-P8-CLI-ALIAS | new-project-usage | 只读查询 / 详情 | P1 | 双实现风险 | 3 | 0 | 3 | 3 | TC-PKG-LAYER-P8-CLI-ALIAS-001..003 | yes | verify-matrix | yes | yes | traces/, docs/harness/new-project-usage.md | none |