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-P1RMetaRemaining5CompletedApproval审阅版.md

16 KiB
Raw Blame History

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。

推荐审批策略：

operation-level approval for Meta remaining 5

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

审批路径

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：
16e9f4e test(p1r): 收口 Meta completed approval 门禁

当前 coverage summary：

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

Meta 当前状态：

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

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

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

tests > 0
failures = 0
errors = 0
skipped = 0

最低应覆盖：

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

推荐审批粒度

推荐继续 operation-level approval：

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