# P1R Meta Completed Approval 审阅版

日期：2026-06-10

## 结论

推荐把 Meta 作为剩余业务域 completed approval 的第一候选，但当前 Meta 仍不是 `completed`。

本审阅版只冻结 Meta completed approval 的范围、证据缺口、推荐审批粒度和后续执行版要求。不修改 OpenAPI，不修改 scanner，不修改 coverage report，不修改业务代码，不把 Meta 或其它 domain 推进 `completed`。

推荐审批策略：

```text
Meta domain-level approval candidate
```

前提是后续执行版能一次性证明 Meta 16 个 operation 的真实运行态、数据迁移、状态机、权限、审计、幂等和失败路径证据。如果任一 operation 无法满足 completed 证据，必须退回 operation-level approval，不能整域推进。

## 审批路径

```mermaid
flowchart TB
    Start["当前 coverage<br/>Meta 16 dedicated / needs_verification"] --> Review["本审阅版<br/>冻结 Meta completed 证据标准"]
    Review --> FreshReview["fresh spec/scope review<br/>fresh quality/feasibility review"]
    FreshReview --> ExecDoc["执行版<br/>列出测试、迁移、scanner/report/gate 修改"]
    ExecDoc --> ExecReview["执行版 fresh 双 review"]
    ExecReview --> UserApproval{"用户明确批准<br/>Meta completed 推进?"}
    UserApproval -->|否| Stop["保持 needs_verification"]
    UserApproval -->|是| Implement["只按执行版允许路径修改<br/>scanner / gate / report / 必要测试"]
    Implement --> Verify["focused tests + P1R gates<br/>真实 Flyway _test + XML 防空跑<br/>allowed/protected diff"]
    Verify --> ImplReview["fresh implementation 双 review"]
    ImplReview --> FinalApproval{"用户批准提交和 push?"}
    FinalApproval -->|否| LocalOnly["保留本地 evidence"]
    FinalApproval -->|是| Commit["提交并 push"]
```

## 已验证事实

### 工作区与远端

- 工作区：`/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0`。
- 分支：`dev/1.0.0`。
- 当前远端：`origin/dev/1.0.0`。
- 本轮已执行 `git pull --ff-only origin dev/1.0.0`，结果为 `Already up to date.`。
- 当前 HEAD：

```text
85c5422 test(p1r): 收口 P1R-7 completed approval 门禁
```

### 当前 coverage 状态

当前 `docs/superpowers/reports/p1r-api-coverage.json` summary：

```text
totalOperations              233
completedOperations          101
needsVerificationOperations  132
incompleteOperations         0
genericPersistenceOperations 0
ssePlaceholderOperations     0
missingOperations            0
blockedOperations            0
```

Meta 当前状态：

```text
meta_count 16
implementationStatus dedicated:16
completionStatus needs_verification:16
```

Meta 16 个 operation：

| operationId | method/path | 当前状态 |
| --- | --- | --- |
| `listMetaSchemas` | `GET /admin-api/muse/governance/meta-schemas` | `dedicated / needs_verification` |
| `getMetaSchema` | `GET /admin-api/muse/governance/meta-schemas/{schemaKey}` | `dedicated / needs_verification` |
| `getMetaSchemaVersion` | `GET /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}` | `dedicated / needs_verification` |
| `saveMetaSchemaDraft` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts` | `dedicated / needs_verification` |
| `validateMetaSchemaDraft` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/validate` | `dedicated / needs_verification` |
| `previewMetaSchemaDraftImpact` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/impact-preview` | `dedicated / needs_verification` |
| `publishMetaSchemaDraft` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/publish` | `dedicated / needs_verification` |
| `activateMetaSchemaVersion` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/activate` | `dedicated / needs_verification` |
| `rollbackMetaSchemaVersion` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/rollback` | `dedicated / needs_verification` |
| `deprecateMetaSchemaVersion` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/deprecate` | `dedicated / needs_verification` |
| `setMetaSchemaGrayRules` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/gray-rules` | `dedicated / needs_verification` |
| `listProtectionNodes` | `GET /admin-api/muse/governance/protection-nodes` | `dedicated / needs_verification` |
| `getProtectionNode` | `GET /admin-api/muse/governance/protection-nodes/{nodeKey}` | `dedicated / needs_verification` |
| `listFunctionChains` | `GET /admin-api/muse/governance/function-chains` | `dedicated / needs_verification` |
| `previewFunctionChainImpact` | `POST /admin-api/muse/governance/function-chains/{chainKey}/impact-preview` | `dedicated / needs_verification` |
| `activateFunctionChainVersion` | `POST /admin-api/muse/governance/function-chains/{chainKey}/versions/{version}/activate` | `dedicated / needs_verification` |

### 已有 dedicated 实现证据

Meta 已有 dedicated Controller：

- `AdminMetaSchemaController`
- `AdminProtectionNodeController`
- `AdminFunctionChainController`

这三个 Controller 均使用 `/muse/governance/...` 类级路由，方法级 `@GetMapping` / `@PostMapping` 覆盖 Meta 16 个 operation，并通过 `@PreAuthorize` 绑定管理端权限。

这三个 Controller 都调用 `MetaApiVersionGuard.requireVersion(...)` 校验 `X-API-Version`，缺少版本头时不回退到旧合同兜底结果。

Meta 已有 dedicated Service / Guard / DAL：

- `MetaSchemaServiceImpl`
- `MetaSchemaValidationServiceImpl`
- `MetaSchemaImpactPreviewServiceImpl`
- `ProtectionNodeServiceImpl`
- `FunctionChainServiceImpl`
- `MetaCommandServiceImpl`
- `MetaAuditServiceImpl`
- `MetaVersionStateGuard`
- `MetaProtectionNodeGuard`
- `FunctionChainGuard`
- Meta DO / Mapper / Convert 文件

Meta 旧合同兜底路由已有退役测试：

- `AdminMuseMetaContractControllerTest.should_notKeepGenericMetaContractControllerOnClasspath`

### 已有状态机、幂等、审计与失败边界证据

`MetaSchemaServiceImpl` 已覆盖：

- save draft
- publish
- activate
- rollback
- deprecate
- gray rules
- command reservation
- command replay
- governance audit

`MetaCommandServiceImpl` 已覆盖：

- `reserveCommand(...)`
- `recordSucceeded(...)`
- request hash
- operation / actor / target envelope 校验
- 未完成 command 冲突
- succeeded command replay

`MetaAuditServiceImpl` 已把治理审计写入 `muse_meta_governance_audit`，并有测试证明审计不是复用 command `resultSnapshot` 冒充。

`MetaSchemaImpactPreviewServiceImpl` 依赖 `MetaImpactFacade`；默认 `UnavailableMetaImpactFacade` 在没有真实外部 owner bean 时抛出 `META_EXTERNAL_OWNER_UNAVAILABLE`，不是空成功。

### 已有 SQL 与测试证据

Meta 已有 migration：

- `muse-cloud/sql/muse/V10__extend_meta_real_api_schema.sql`

V10 追加：

- `muse_meta_command`
- `muse_meta_governance_audit`
- `muse_meta_validation_result`
- `muse_meta_impact_preview`
- `muse_meta_gray_rule`
- `muse_meta_function_chain_version`
- `muse_meta_function_chain_slot`
- `muse_meta_function_chain_node`
- `uk_muse_meta_schema_version_active_schema_id`
- `muse_meta_protection_node` 结构化字段

Meta 已有静态 SQL gate：

- `P1rMetaMigrationSqlTest`，3 个 `@Test`。

Meta 已有 coverage gate：

- `P1rMetaRealApiGateTest`，4 个 `@Test`。

该 gate 当前明确禁止 Meta operation 标记为 completed，并要求 Meta 保持 `dedicated / needs_verification`。

Meta 模块现有测试清单包含 16 个测试类，按源码 `@Test` 统计共 165 个测试方法；P1R Meta gate 额外包含 7 个测试方法。

## 推断

- Meta 是剩余四个业务域中最适合先走 completed approval 的候选，因为 operation 数量最少，主要围绕 Meta owner 自有治理事实，外部依赖比 Account / Market / Content 少。
- Meta 可以作为 domain-level approval 候选，但只有在后续执行版补齐真实 `_test`、XML 防空跑、审批后 coverage gate 和运行态失败路径证据后才成立。
- 当前 `P1rMetaRealApiGateTest` 的旧口径会阻止 Meta completed；后续用户批准前不能修改该 gate，用户批准后必须把它改成“只允许 Meta 16 个 operation completed，且不连带其它 domain”的审批后门禁。

## 假设

- 用户确认先从 Meta 推进剩余业务域 completed approval。
- 后续执行版允许在 fresh 双 review 与用户明确批准之后，修改 scanner、coverage report、`P1rMetaRealApiGateTest`、`P1rApiCoverageReportTest` 和必要的 Meta completed approval gate 测试。
- 如果真实 `_test` 或外部 owner fail-closed 证据证明某个 Meta operation 不满足 completed，用户接受把 Meta 从 domain-level approval 降级为 operation-level approval。

## 主要缺口

### 缺口 1：真实 Flyway `_test` 尚未覆盖 V10

当前只有 `P1rMetaMigrationSqlTest` 静态读取 V10 SQL。它证明 SQL 文本包含关键表、索引和字段，但不证明真实 PostgreSQL 可以执行，也不证明约束、partial unique index、trigger 和非法写入拒绝实际生效。

后续执行版必须新增真实 PostgreSQL `_test`，最低验证：

- schema version 到达 V10 或当前全量迁移目标中包含 V10。
- V10 追加表真实存在。
- `muse_meta_command` 的 `(tenant_id, command_id)` unique 生效。
- `muse_meta_schema_version` 的 active partial unique index 使用 `(tenant_id, schema_id)` 且同 schema 不能有两个 active 版本。
- `muse_meta_function_chain_version` 的 active partial unique index 生效。
- `muse_meta_protection_node` 结构化字段真实存在。
- V10 表的 `updated_at` trigger 可执行。
- 代表性非法 insert 被拒绝，例如重复 commandId、重复 active schema version、重复 active function chain version、必填字段为空。

### 缺口 2：当前 P1R gate 仍明确禁止 Meta completed

`P1rMetaRealApiGateTest.should_not_mark_meta_operations_as_completed` 和 `should_keep_current_meta_operations_dedicated_and_needs_verification` 当前是正确的防误升门禁。

后续执行版必须把 gate 修改分成两步：

1. 用户批准前：保持该 gate 不变，证明 Meta 仍未 completed。
2. 用户批准后：改为 completed approval gate，精确断言 Meta 16 个 operation 为 `dedicated / completed`，并断言 Account / Market / Content 仍为 `dedicated / needs_verification`。

### 缺口 3：外部 owner impact preview 需要明确 completed 口径

`MetaSchemaImpactPreviewServiceImpl` 调用 `MetaImpactFacade`。默认 `UnavailableMetaImpactFacade` 抛出 `META_EXTERNAL_OWNER_UNAVAILABLE`。

这说明当前系统没有伪造外部 owner 成功，但也意味着 completed approval 必须选择清楚：

- 如果 `previewMetaSchemaDraftImpact` 要算 completed，必须证明有真实 `MetaImpactFacade` 或明确接受 fail-closed 是该 operation 的完成口径。
- 如果真实外部 owner 不可用且该 operation 需要成功预览外部影响，必须保持该 operation `needs_verification`，不能把 bare mock 或空 summary 当 completed。

### 缺口 4：需要把 165 个 Meta 测试变成可审计 XML 证据

历史留痕记录 Meta 模块全量测试曾通过 165 个测试，但 completed approval 执行必须重新运行当前代码，并读取 Surefire XML 逐类证明：

```text
tests > 0
failures = 0
errors = 0
skipped = 0
```

后续执行版必须列出 required test classes 和最低测试数，不能只写 Maven exit 0。

### 缺口 5：scanner/report 修改必须是审批后动作

Meta completed approval 需要修改 scanner 的 completed allowlist 或 approval 模型，并重生成 coverage report。

这些动作只能在执行版 fresh 双 review 且用户明确批准后执行。用户批准前 protected diff 必须证明以下文件没有 staged/unstaged diff：

- `muse-cloud/scripts/p1r-audit-api-coverage.py`
- `docs/superpowers/reports/p1r-api-coverage.json`
- `docs/superpowers/reports/p1r-api-coverage.md`

## 推荐审批粒度

推荐先按 domain-level approval 设计 Meta 执行版：

```text
approved_completed_domains += {"meta"}
```

但执行版必须提供降级机制：

- 如果全部 16 个 operation 证据闭合，允许 domain-level approval。
- 如果 `previewMetaSchemaDraftImpact` 或其它高风险 operation 因外部 owner 不满足 completed 标准，必须降级为 operation-level approval。
- 降级时 scanner/report/gate 只能推进证据满足的 operation，不得把 Meta 整域加入 completed domain allowlist。

## 非目标

- 不修改 `docs/api-contracts/meta/openapi.yaml`。
- 不修改任何其它 OpenAPI 文件。
- 不修改 `muse-cloud/scripts/p1r-audit-api-coverage.py`。
- 不修改 `docs/superpowers/reports/p1r-api-coverage.json`。
- 不修改 `docs/superpowers/reports/p1r-api-coverage.md`。
- 不修改 Meta 业务实现代码。
- 不推进 Account / Market / Content completed。
- 不推进总 P1R completed。
- 不把 P1R-7 Events completed approval 或 source owner propagation evidence 当作 Meta completed 证据。

## 后续执行版必须包含

1. Meta 16 operation 的完整清单与目标状态。
2. 允许修改文件清单；至少区分用户批准前和批准后。
3. scanner approval 模型：domain-level Meta 或 operation-level fallback，二选一并写明触发条件。
4. `P1rMetaRealApiGateTest` 从禁止 completed 到审批后 completed gate 的修改策略。
5. `P1rApiCoverageReportTest` summary 期望从 `completed=101 / needsVerification=132` 到目标值的修改策略。
6. 真实 PostgreSQL Flyway `_test`：目标 schema version、V10 表、索引、约束、trigger、非法 insert 拒绝。
7. Meta focused tests：16 个测试类逐类 XML 计数下限。
8. P1R mixed gates：包含 Meta gate、coverage report gate，以及用于证明非目标 domain 不被推进的 Account / Market / Content gate。
9. `/tmp/p1r-meta-completed-approval-scan.*` 隔离 scanner 预验证。
10. 真实 worktree scanner/report 重生成只允许在执行版双 PASS 和用户批准后执行。
11. protected diff gate，必须覆盖 7 个 OpenAPI、scanner 和 coverage report。
12. allowed-diff gate，必须覆盖 unstaged / staged / untracked，并使用 `core.quotePath=false`。
13. implementation review 复核项：新增 completed 只覆盖用户批准范围；非目标 domain 状态不变；XML 防空跑和 `_test` 证据完整。
14. rollback 策略：撤回 scanner allowlist、coverage report、gate test 和新增 `_test`，恢复 Meta 为 `dedicated / needs_verification`。

## 验收标准

本审阅版可以视为完成的条件：

1. 文件写入 `docs/agent-specs/2026-06-10-P1RMetaCompletedApproval审阅版.md`。
2. `.agent` 记录 Meta completed approval 审阅版状态。
3. `git diff --check` 通过。
4. OpenAPI、scanner、coverage report 无 diff。
5. 本审阅版通过 fresh spec/scope review 和 fresh quality/feasibility review。

## 待确认项

1. 是否确认 Meta 作为剩余业务域 completed approval 第一候选。
2. 是否确认先按 Meta domain-level approval 设计执行版，并保留 operation-level fallback。
3. 是否确认用户批准前不得修改 scanner、coverage report、coverage gate 或 Meta 业务代码。
4. 是否确认真实 Flyway `_test` 是 Meta completed approval 的硬门槛。