zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/docs/agent-specs/2026-06-10-P1RMetaCompletedApproval审阅版.md
zizi 16e9f4ee72 test(p1r): 收口 Meta completed approval 门禁 
只推进 11 个 MetaSchema 管理 operation 到 dedicated/completed，保留 FunctionChain 与 ProtectionNode 的 5 个 operation 为 dedicated/needs_verification。同步 scanner approval 白名单、coverage report、P1R gate 测试和阶段留痕，避免把 Meta 扩写成整域 completed。
2026-06-10 17:09:01 +08:00

15 KiB
Raw Blame History

P1R Meta Completed Approval 审阅版

日期：2026-06-10

结论

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

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

推荐审批策略：

Meta domain-level approval candidate

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

审批路径

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：
85c5422 test(p1r): 收口 P1R-7 completed approval 门禁

当前 coverage 状态

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

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

Meta 当前状态：

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 逐类证明：

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 执行版：

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 的硬门槛。