aios/docs/aios-v2/05-TRACEABILITY-MATRIX.md

AIOS V2 需求—架构—代码—测试—部署追踪矩阵

• 文档版本：V2R1-hardening-candidate
• 状态：实现与测试代码已提交；测试执行和 Acceptance 证据待完成
• 基线需求：UR-001～UR-022
• 判定规则：测试文件存在不等于测试通过；只有实际执行并保存证据后，状态才能改为“已验证”

1. 状态定义

状态	含义
已实现	代码、配置或文档已经提交到当前加固分支
测试已提交	自动测试代码已经提交，但本报告没有实际执行结果
待验收	需要运行 deploy/aios-v2/acceptance/run-all.sh 或对应预发布检查并保存证据
未批准	尚未获得 Owner 的 Merge、Tag 或生产部署批准

2. 用户需求追踪

需求	架构/决策	主要实现	测试代码	部署/验收入口	当前状态
UR-001 唯一控制面	ADR-001；模块契约第 2～6 节	active-runtime/app/aios_v2/control_plane.py、gateway.py、orchestrator.py	tests/aios_v2_candidate/test_candidate_flow.py	deploy/aios-v2/acceptance/run-all.sh；公共生命周期旁路负向检查	已实现；测试已提交；待验收
UR-002 复用现有能力	ADR-002	active-runtime/app/aios_openclaw/、active-runtime/app/aios_hermes/、active-runtime/app/aios_v2/orchestrator.py	test_candidate_flow.py	OpenClaw/Hermes 联调	已实现；真实 Runtime 联调待验收
UR-003 OpenClaw/Hermes 解耦	ADR-002、ADR-010；模块契约第 11、12 节	OpenClaw Adapter、Hermes Adapter/Worker、内部 Lifecycle/Reconcile	test_candidate_flow.py、test_hermes_live_lifecycle.py	默认关闭的内部 Runtime API；Runtime audit/evidence 检查	已实现；Hermes 专项 17/17
UR-004 全面 Web 化	目标架构；模块契约第 15 节	active-runtime/app/aios_v2/app.py、console.py、gateway.py	test_candidate_flow.py	Web/API 冒烟、Healthcheck	已实现；UI/浏览器验收待执行
UR-005 多租户隔离	ADR-004	control_plane.py、persistence.py、execution_tracking.py、dispatch_store.py	test_candidate_flow.py::test_cross_tenant_task_read_is_denied	跨租户负向 Acceptance	已实现；测试已提交；待验收
UR-006 权威任务生命周期	ADR-001；模块契约第 4 节	control_plane.py、gateway.py、orchestrator.py	test_candidate_flow.py	/start、/complete、/fail 应返回拒绝；Runtime 严格 Reconcile	已实现；测试/接口验收待执行
UR-007 策略与审批	ADR-001	control_plane.py、gateway.py	test_candidate_flow.py	Approval、deny audit、policy version 检查	已实现；策略场景验收待执行
UR-008 幂等与并发安全	模块契约第 4、10、12 节	Task idempotency/revision、Hermes lease/revision、Dispatch 唯一约束	test_candidate_flow.py、test_hermes_live_lifecycle.py	Lease 到期重排、换主、相同终态幂等、不同终态冲突	已实现；专项测试通过
UR-009 可观测与执行证据	模块契约第 6、13 节	execution_tracking.py、gitops_status.py、console.py	test_candidate_flow.py::test_execution_tracking_persists_claim_heartbeat_and_result	/api/v2/executions、Evidence Receipt 检查	已实现；测试已提交；待验收
UR-010 GitOps 唯一变更流程	ADR-003	active-runtime/app/aios_v2/provenance_git.py、GitOps 工具与任务资产	test_provenance.py、Grant 隔离测试	Branch/Commit/Push 门禁、Controller clean、OID 同步	已实现候选控制；环境 GitOps 验收待执行
UR-011 持久化与恢复	ADR-006、ADR-010；模块契约第 10、12、16 节	persistence.py、dispatch_store.py、aios_hermes/adapter.py::SQLiteHermesStore、Provenance/Grant Store	test_candidate_flow.py、test_hermes_live_lifecycle.py	运行中 Job 重启恢复、重启后 Reconcile、SQLite quick_check	Hermes/Dispatch/Task 恢复测试通过；生产 HA/容量待验收
UR-012 审计与合规	ADR-001、ADR-004、ADR-009	control_plane.py AuditEvent、app.py callback audit、Provenance/Grant Event/Receipt	test_candidate_flow.py、test_provenance.py、test_provenance_grant_isolation.py	/api/v2/audit、Receipt/Event 完整性检查	已实现候选审计；不可变外部固化待预发布
UR-013 密钥安全	ADR-009；模块契约第 6、11、17 节	Ed25519 Signer/Verifier、protected file reader、SecretRef 配置	test_provenance.py、test_candidate_flow.py	Secret scanner、权限检查、容器/systemd credential 检查	已实现；环境密钥注入验收待执行
UR-014 部署与回滚	迁移与交付文档；模块契约第 17 节	deploy/aios-v2/systemd/、docker/、healthcheck/、rollback/	Acceptance 脚本与候选测试	systemd/Docker 安装、Healthcheck、备份与回滚演练	资产已提交；实际部署/回滚未执行
UR-015 文档与代码同步	ADR-005	tools/aios_v2_docs_code_check.py、docs/aios-v2/	文档门禁脚本	Acceptance Runner 调用文档门禁	已实现；门禁尚未实际执行
UR-016 Workflow Run Provenance	ADR-009；模块契约第 7 节	active-runtime/app/aios_v2/provenance.py、provenance_grants.py::WorkflowProvenanceIssuer	test_provenance.py、test_provenance_grant_isolation.py::test_parent_workflow_has_no_operational_rights	CLI issue-workflow、状态/撤销检查	已实现；测试已提交；待验收
UR-017 最小权限子 Grant	ADR-009；模块契约第 8 节	provenance_grants.py、provenance_scoped.py	test_provenance_grant_isolation.py	issue-grant、Grant status/revoke、Receipt 检查	已实现；专项测试已提交；待验收
UR-018 Runtime Result 信任绑定	ADR-009、ADR-010；模块契约第 10～12 节	orchestrator.py、dispatch_store.py、内部 Hermes Lifecycle/Reconcile	test_hermes_live_lifecycle.py	tenant/task/trace/principal/provenance/run/dispatch/job/cell/profile/worker 负向矩阵	已实现；专项 17/17
UR-019 Dispatch 持久化与恢复	ADR-009、ADR-010；模块契约第 10、12 节	dispatch_store.py、orchestrator.py、app.py、SQLiteHermesStore	Dispatch recovery 与 Hermes restart-reconcile 测试	进程重启后读取 Dispatch/Job 并完成 Reconcile	已实现；测试通过
UR-020 OpenClaw Ed25519 命令合同	ADR-009；模块契约第 11 节	active-runtime/app/aios_openclaw/contract.py、adapter.py、app.py	test_candidate_flow.py、test_provenance.py	真实 OpenClaw v2 合同联调、Key rotation、clock skew/expiry 负向验收	已实现；测试代码已升级；真实联调待执行
UR-021 服务级权限隔离	ADR-009；模块契约第 9 节	provenance_scoped.py、provenance_operations.py、app.py	test_provenance_grant_isolation.py	Application 仅加载 Runtime/Evidence/Audit；Git/Deploy/Rollback 单独 Scope	已实现；专项测试已提交；配置验收待执行
UR-022 CLI 单 Grant 授权	ADR-009；模块契约第 9 节	provenance_cli.py	test_provenance_grant_isolation.py 提供 Writer/Grant 基础验证；CLI 端到端待补执行证据	authorize --path ... --grant-id ...；旧批量 Grant 参数应不存在	已实现；CLI 端到端验收待执行

3. P0 加固项追踪

P0	风险	实现	测试/证据	状态
P0-1 公共生命周期旁路	客户端直接推进 RUNNING/COMPLETED/FAILED	gateway.py 公共入口拒绝；orchestrator.py 权威推进	API 负向 Acceptance	代码完成；待执行
P0-2 Dispatch 持久化	重启丢失 Runtime 绑定	dispatch_store.py SQLite Repository；app.py 接线	Dispatch restart recovery 测试	代码/测试已提交；待执行
P0-3 Result 严格绑定	伪造或错配 Runtime Result 更新 Task	orchestrator.py 校验 Runtime Execution、Tenant、Task、Trace、Principal、Provenance、Run	Runtime 正向恢复测试；负向 Acceptance	代码完成；完整验收待执行
P0-4 OpenClaw Ed25519	HMAC 共享密钥和合同不一致	aios_openclaw/contract.py v2 Ed25519；安全文件读取	候选 Flow 测试；真实 Runtime 联调	代码/测试已提交；联调待执行
P0-5 最小权限 Grant	单凭证拥有全部生产路径	Workflow + Child Grant + Scoped Writer + 单 Grant CLI	Grant isolation 专项测试	代码/测试已提交；待执行

4. Acceptance 证据要求

完整 Acceptance 至少应保存：

1. 测试命令、开始/结束时间、退出码和完整日志。
2. test_candidate_flow.py、test_provenance.py、test_provenance_grant_isolation.py 的实际结果。
3. 文档—代码同步门禁实际结果。
4. Secret scanner、依赖和容器/systemd 安全检查结果。
5. OpenClaw Ed25519 v2 真实联调结果。
6. Hermes 内部 Reconcile 正向与伪造上下文负向结果。
7. Control Plane、Dispatch、Provenance/Grant 的重启恢复结果。
8. 部署、Healthcheck、备份和回滚演练结果。
9. 分支、Commit、Controller clean、远端 OID 同步证据。
10. Owner 对 Merge、Tag 和生产部署的独立批准。

5. 当前发布门禁

Gate	状态	说明
实现	完成	五项 P0 代码与配置已提交当前加固分支
测试代码	完成	回归、Dispatch recovery、Grant isolation 测试已提交
测试执行	未完成	当前没有可验证的实际运行日志和退出码
文档同步	已提交	需求、契约、ADR、追踪矩阵已更新；门禁尚未执行
Acceptance	未完成	run-all.sh 尚无本轮实际执行证据
Gate A	未批准	只能在 Acceptance 通过并完成独立审查后批准
Merge/Tag/生产部署	未批准	需要 AIOS Owner 明确批准