# P1R2 元治理规格计划留痕

## 任务背景

本次进入 P1R-2 Meta Real API spec + plan 阶段，目标是先完成 Meta 域真实业务 API 的事实盘点、规格和执行计划，不进入代码实现。

P1R-2 的核心不是继续增强 `MuseContractPersistenceService`，也不是把通用持久化响应包装成 Meta 业务结果，而是把 Meta 域从“通用持久化可响应”推进到“真实 Meta 治理 API 可验收”的规格和计划阶段。

## 执行位置

```text
/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
```

分支：

```text
dev/1.0.0
```

说明：`/Users/qingse/Sync/local-git/oh-my-muse` 当前不是本阶段真实工作面，核验时位于 `feature/p1-muse-cloud-backend-20260524` 且有未跟踪文件。`dev/1.0.0` 已由上面的 superpowers worktree 占用。

## 已验证事实

P1R 覆盖矩阵中 Meta 域当前状态：

```text
16 generic_persistence / incomplete
```

Meta 16 个 operation 全部来自 `docs/api-contracts/meta/openapi.yaml`，当前没有 `dedicated / needs_verification`、`catch_all`、`sse_placeholder` 或 `missing`。

当前 Meta 模块事实：

- `muse-module-meta-server` 只有 `AdminMuseMetaContractController`。
- 该 Controller 使用 wildcard 路由接管 `meta-schemas`、`protection-nodes`、`function-chains`。
- 当前请求统一委托 `MuseContractPersistenceService.handle(...)`。
- 当前没有 Meta 专用 Controller、Service、DTO、DO、Mapper、command/audit 服务和状态机。

当前 DDL 事实：

- V3 已有 `muse_meta_schema`、`muse_meta_schema_version`、`muse_meta_field`、`muse_meta_visibility_policy`、`muse_meta_protection_node`、`muse_meta_function_chain`。
- V3 不足以覆盖 validation result、impact preview、gray rule、FunctionChain version/slot/node relation、Meta command/audit。
- MetaSchema active 唯一约束不能按 `tenant_id + schema_key` 过度约束，应按 `tenant_id + schema_id`，因为 V3 允许 `(domain, scope, target_type, schema_key)` 组合唯一。

## 本阶段产物

- 规格：`docs/superpowers/specs/2026-05-27-P1R-2-meta-real-api-design.md`
- 计划：`docs/superpowers/plans/2026-05-27-P1R-2-meta-real-api.md`

## Review 结果

本阶段使用 fresh subagent 做了两轮文档 review。

第一轮 review 未通过，阻塞点包括：

- `blocked` 状态没有 OpenAPI/coverage 可执行入口。
- Meta wildcard catch-all 路由退役顺序不清。
- Task 1 clean worktree 预期未考虑新增 review 文档。
- DDL active 唯一约束 identity 与 V3 不一致。
- rollback/deprecate 缺少 OpenAPI required 字段落地要求。
- `previewMetaSchemaDraftImpact` 缺少等价幂等键。
- 权限和 `code/data/msg` controller 验收不够明确。

修正后第二轮 review 通过：

- P1R-2 收口状态统一为 `dedicated / needs_verification`，禁止 `completed` 和 coverage `blocked` 收口。
- 增加 Task 9，专门退役 Meta 合同兜底路由，并要求 route ownership 测试证明 16 个路径不再调用 `MuseContractPersistenceService`。
- `validateMetaSchemaDraft` / `previewMetaSchemaDraftImpact` 确认为使用 `schemaKey + draftVersion + actor + draftHash` 的等价幂等键，不静默改 OpenAPI。
- rollback/deprecate/publish/activate/gray/function-chain activate 均补齐 commandId、reason、version、validationResultId、impactPreviewId、权限、同源校验和 audit 要求。
- 计划补充 `P1rMetaMigrationSqlTest` 聚焦验证 V10 迁移 SQL 和 active 唯一索引边界。

## 当前阶段边界

本阶段只完成规格和计划，没有实现代码。

未修改：

- `docs/api-contracts/meta/openapi.yaml`
- `docs/superpowers/reports/p1r-api-coverage.*`
- `muse-cloud/scripts/**`
- `muse-cloud/muse-module-meta/**` 实现代码

当前不应把任何 Meta operation 标为 `completed`。

## 下一步

进入 P1R-2 实现前，应从 `docs/superpowers/plans/2026-05-27-P1R-2-meta-real-api.md` Task 1 开始，按 fresh subagent + 两轮 review 执行。

实现阶段完成口径：

- Meta 16 个 operation 退出 `generic_persistence`。
- Meta 16 个 operation 全部为 `dedicated / needs_verification`。
- Content 51 个 operation 保持 `dedicated / needs_verification`。
- 不修改脚本掩盖缺口。
- 不把 Meta 标为 `completed`。