# 需求追溯矩阵

**功能**:
**最后更新**:
**负责人**:

| 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。
- 每条 P0/P1 业务规则至少要在矩阵中出现一次，并绑定页面状态、Oracle 和测试层级。
- 缺少 Oracle 或证据路径的 P0/P1 行不能进入实现。
