# P1R Meta Remaining 5 Completed Approval 审阅版

日期：2026-06-10

## 结论

推荐把 Meta 剩余 5 个 `dedicated / needs_verification` operation 作为下一段 completed approval 候选，但当前不建议直接推进 `completed`。

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

推荐审批策略：

```text
operation-level approval for Meta remaining 5
```

原因是 MetaSchema 11 个 operation 已完成 operation-level approval；剩余 5 个 operation 分属 ProtectionNode 和 FunctionChain，证据形态不同。如果改成 Meta domain-level approval，会把两类治理读模型和功能链写命令一次性绑定，风险比继续 operation-level approval 更高。

## 审批路径

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

## 已验证事实

### 工作区与当前状态

- 正确 worktree：`/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0`。
- 当前分支：`dev/1.0.0`。
- 当前本地与 `origin/dev/1.0.0` 对齐。
- 当前 HEAD：

```text
16e9f4e test(p1r): 收口 Meta completed approval 门禁
```

当前 coverage summary：

```text
totalOperations              233
completedOperations          112
needsVerificationOperations  121
incompleteOperations         0
genericPersistenceOperations 0
ssePlaceholderOperations     0
```

Meta 当前状态：

```text
meta dedicated/completed:11
meta dedicated/needs_verification:5
```

### 本轮候选 operation

本审阅版只覆盖以下 5 个 Meta operation：

| operationId | method/path | 当前状态 |
| --- | --- | --- |
| `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` |

非候选范围：

- 已 completed 的 MetaSchema 11 个 operation。
- Account 33、Market 32、Content 51。
- 总 P1R completed。
- 任何 OpenAPI 合同修改。
- 任何 Meta 业务实现补丁。

### 已有 dedicated 实现证据

ProtectionNode 已有 dedicated Controller / Service：

- `AdminProtectionNodeController`
- `ProtectionNodeService`
- `ProtectionNodeServiceImpl`

`AdminProtectionNodeController` 使用 `/muse/governance/protection-nodes` 类级路由，覆盖 list/detail 两个 operation，且使用 `@PreAuthorize("@ss.hasPermission('muse:meta:query')")`。Controller 调用 `MetaApiVersionGuard.requireVersion(...)`，缺少 `X-API-Version` 时不回退到旧合同兜底结果。

`ProtectionNodeServiceImpl` 只读取 `muse_meta_protection_node` 持久化事实和 `policySnapshot` 中的 `chainKey` 轻量关联，不调用 `MuseContractPersistenceService`。查询只返回 `status='active'` 的保护节点；detail 不存在时抛出 `META_PROTECTION_NODE_NOT_FOUND`。

FunctionChain 已有 dedicated Controller / Service：

- `AdminFunctionChainController`
- `FunctionChainService`
- `FunctionChainServiceImpl`

`AdminFunctionChainController` 使用 `/muse/governance/function-chains` 类级路由，覆盖 list / impact-preview / activate 三个 operation，且绑定管理端权限：

- 查询：`muse:meta:query`
- 影响预览与激活：`muse:meta:function-chain`

`FunctionChainServiceImpl` 已覆盖：

- active version 读取。
- open slot 与 protection node count 计算。
- preview commandId / requestHash 幂等预占与成功回放。
- targetVersion 解析。
- validation result 和 impact preview 持久化。
- activate commandId / requestHash 幂等回放。
- published-only 激活。
- expected active version 冲突检测。
- validationResult / impactPreview 同源校验。
- protection boundary violation 阻断。
- active version 原子更新。
- governance audit 与 command succeeded 记录。

### 已有保护边界证据

`FunctionChainGuard` 与 `MetaProtectionNodeGuard` 已声明保护节点不能被替换或降级：

- `requireActivationAllowed(...)` 只允许 `published` 状态激活。
- `requireNoProtectionBoundaryViolation(...)` 在影响预览发现保护边界违规时抛出 `META_PROTECTION_NODE_IMMUTABLE`。
- `MetaProtectionNodeGuard.requireNotReplaced(...)` 禁止把 canonical 保护节点换成其它节点。
- `MetaProtectionNodeGuard.requireNotDowngraded(...)` 禁止不可替换保护节点降级为可替换。
- `MetaProtectionNodeGuard.requireFunctionChainNodePreservesProtection(...)` 统一 FunctionChain 编排下的保护边界语义。

`FunctionChainServiceImpl` 的 activation 流程在写 active version 前会调用 `requireProtectionBindingsPreserved(...)`，并基于 active / target version 的 node binding diff 阻断保护节点移除、解绑或降级。

### 已有 SQL 与测试证据

V10 migration 已包含 FunctionChain 和 ProtectionNode 相关结构：

- `muse_meta_function_chain_version`
- `muse_meta_function_chain_slot`
- `muse_meta_function_chain_node`
- `uk_muse_meta_function_chain_version_active`
- `muse_meta_protection_node` 结构化字段追加
- 对应 `updated_at` trigger

当前只有静态 SQL gate：

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

与剩余 5 个 operation 直接相关的现有测试：

| 测试类 | `@Test` 数量 |
| --- | ---: |
| `ProtectionNodeServiceTest` | 3 |
| `FunctionChainServiceTest` | 12 |
| `AdminProtectionNodeControllerTest` | 7 |
| `AdminFunctionChainControllerTest` | 7 |
| `FunctionChainGuardTest` | 4 |
| `MetaProtectionNodeGuardTest` | 5 |

`P1rMetaRealApiGateTest` 当前明确要求：

- Meta 16 个 operation 都必须是 `dedicated`。
- MetaSchema 11 个 operation 必须是 `completed`。
- FunctionChain / ProtectionNode 5 个 operation 必须保持 `needs_verification`。
- Meta 仍不是 16/16 completed。

### 保护面当前无 diff

本审阅版写入前已只读检查：

```bash
git -c core.quotePath=false diff --name-only -- docs/api-contracts muse-cloud/scripts docs/superpowers/reports
```

输出为空，说明 OpenAPI、scanner、coverage report 当前无 unstaged diff。

## 推断

- ProtectionNode 的两个 operation 是治理读模型，完成证据主要来自真实持久化、版本头、权限、active 过滤、detail not-found、结构化字段和非 generic fallback。
- FunctionChain 的三个 operation 是治理读写混合，完成证据必须覆盖幂等、状态机、active partial unique、保护节点不可降级、validation / impact preview 同源校验、审计和命令回放。
- 这 5 个 operation 可以继续 operation-level approval；不需要把 `meta` 加入 domain-level completed 白名单。
- 如果执行版能证明 V10 真实 `_test`、FunctionChain active 唯一约束、ProtectionNode 结构化字段、XML 防空跑和 P1R mixed gates，剩余 5 个 operation 才具备进入用户批准点的条件。

## 假设

- 用户希望继续 P1R 主线，并优先收口 Meta 剩余 operation，而不是切到 Account / Market / Content。
- 用户仍要求 completed 状态推进必须单独批准，不能由 dedicated gate、review PASS 或文档结论自动推进。
- 如果真实 `_test` 或 focused tests 发现 FunctionChain / ProtectionNode 证据不足，用户接受继续保持对应 operation `needs_verification`。

## 主要缺口

### 缺口 1：真实 Flyway `_test` 尚未证明 V10 FunctionChain / ProtectionNode 约束

现有 `P1rMetaMigrationSqlTest` 只做静态 SQL 文本检查。后续执行版必须新增真实 PostgreSQL `_test`，最低验证：

- schema version 到达至少 V10。
- `muse_meta_function_chain_version`、`muse_meta_function_chain_slot`、`muse_meta_function_chain_node` 真实存在。
- `muse_meta_function_chain_version` 的 `(tenant_id, chain_id, version_no)` unique 生效。
- `uk_muse_meta_function_chain_version_active` partial unique 生效，同 tenant / chain 不能有两个 active 版本。
- `muse_meta_protection_node` 的结构化字段真实存在。
- FunctionChain / ProtectionNode 相关 `updated_at` trigger 可执行。
- 代表性非法 insert 被拒绝，例如重复 active function chain version、缺少必填字段、重复 chain version。

### 缺口 2：FunctionChain 影响预览仍使用 Meta owner 自有影响摘要

`FunctionChainServiceImpl` 当前对外部 AI runtime / New-API / SSE 影响使用固定 0 和 `externalRuntime=pending` 摘要，没有接入真实外部 owner。

这不一定阻塞 completed，但执行版必须明确 completed 口径：

- 如果 `previewFunctionChainImpact` 的完成定义是 Meta owner 自有链路影响预览，则必须证明 pending 摘要是设计边界，不是伪成功。
- 如果完成定义要求真实外部 runtime 影响，则 `previewFunctionChainImpact` 必须继续保持 `needs_verification`。

### 缺口 3：FunctionChain activation 需要强证据证明保护边界不可绕过

已有 `FunctionChainGuard` 与 `MetaProtectionNodeGuard`，但 completed approval 需要当前代码的 XML 证据和 P1R gate 明确覆盖：

- `published` 以外版本不能激活。
- expected active version 不匹配时拒绝。
- validation result 与 impact preview 不同源时拒绝。
- impact preview 包含 protection boundary violation 时拒绝。
- active 版本切换时旧 active 被关闭，新 active 唯一。
- commandId / requestHash 成功回放不重复写审计或状态。

### 缺口 4：ProtectionNode 查询需要证明不是静态配置或 generic fallback

执行版必须要求测试证明：

- list 从 `muse_meta_protection_node` 读取 active 节点。
- `chainKey` 过滤来自 `policySnapshot` 中的 `chainKey`。
- detail 返回结构化治理字段。
- missing node 返回 `META_PROTECTION_NODE_NOT_FOUND`。
- Controller 缺版本头或未知版本时不调用 Service。
- Controller 不注入 `MuseContractPersistenceService`。

### 缺口 5：coverage gate 仍明确禁止剩余 5 个 operation completed

`P1rMetaRealApiGateTest` 当前是正确的防误升门禁。执行版必须把 gate 修改分成两步：

1. 用户批准前：保持剩余 5 个 operation 为 `needs_verification`。
2. 用户批准后：只把这 5 个 operation 推进 `completed`，并断言 Account / Market / Content 仍保持 `dedicated / needs_verification`。

### 缺口 6：需要 XML 防空跑证据

后续执行版必须列出 required test classes，并读取 Surefire XML 证明：

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

最低应覆盖：

- `ProtectionNodeServiceTest`
- `FunctionChainServiceTest`
- `AdminProtectionNodeControllerTest`
- `AdminFunctionChainControllerTest`
- `FunctionChainGuardTest`
- `MetaProtectionNodeGuardTest`
- `P1rMetaRealApiGateTest`
- `P1rApiCoverageReportTest`
- 新增或修订的 Meta Flyway `_test`

## 推荐审批粒度

推荐继续 operation-level approval：

```text
APPROVED_COMPLETED_OPERATIONS += {
  "meta:listProtectionNodes",
  "meta:getProtectionNode",
  "meta:listFunctionChains",
  "meta:previewFunctionChainImpact",
  "meta:activateFunctionChainVersion"
}
```

不推荐本轮把 `meta` 加入 completed domain allowlist，原因：

- MetaSchema 11 已经走 operation-level approval。
- 剩余 5 个 operation 的证据集中在 FunctionChain / ProtectionNode，不需要覆盖未来 Meta 新 operation。
- operation-level approval 能精确防止未来 Meta operation 误继承 completed。

## 非目标

- 不修改 `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。
- 不把 MetaSchema 11 个 operation 的 completed 证据扩写成剩余 5 个 operation 的证据。

## 后续执行版必须包含

1. 剩余 5 个 operation 的完整清单与目标状态。
2. 用户批准前和批准后的允许修改文件清单。
3. scanner approval 模型：只允许新增 5 个 operation-level approval。
4. `P1rMetaRealApiGateTest` 从“剩余 5 个必须 needs_verification”改为“剩余 5 个批准后必须 completed”的策略。
5. `P1rApiCoverageReportTest` summary 从 `completed=112 / needsVerification=121` 到 `completed=117 / needsVerification=116` 的修改策略。
6. 真实 PostgreSQL Flyway `_test`：FunctionChain / ProtectionNode 相关表、索引、约束、trigger 和非法 insert 拒绝。
7. FunctionChain focused tests：list、preview、activate、replay、conflict、validation / impact preview 同源、protection boundary、audit。
8. ProtectionNode focused tests：list、detail、active filter、chainKey filter、missing node、结构化字段、版本头和权限。
9. P1R mixed gates：coverage report gate、Meta gate、Account / Market / Content 非目标 gate。
10. XML 防空跑：逐类读取 surefire XML 并断言 tests > 0。
11. protected diff gate：覆盖 7 个 OpenAPI、scanner 和 coverage report。
12. allowed-diff gate：覆盖 unstaged / staged / untracked，并使用 `core.quotePath=false`。
13. implementation review 复核项：新增 completed 只覆盖剩余 5 个 operation，Meta 最终 16/16 completed，Account / Market / Content 不变。
14. rollback 策略：撤回 scanner allowlist、coverage report、gate test 和新增 `_test`，恢复剩余 5 个 operation 为 `dedicated / needs_verification`。

## 验收标准

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

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

## 待确认项

1. 是否确认下一段优先处理 Meta 剩余 5 个 operation，而不是 Account / Market / Content。
2. 是否确认继续使用 operation-level approval，不把 `meta` 加入 domain-level completed allowlist。
3. 是否确认用户批准前不得修改 scanner、coverage report、coverage gate 或 Meta 业务代码。
4. 是否确认真实 Flyway `_test` 是剩余 5 个 operation completed approval 的硬门槛。