pomaster 0.3.0 → 0.4.0

package/seeds/specs/hard/backend/03-directory-boundary-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/03-directory-boundary-protocol.md
+seed_source_sha256: 95a917cfe3c929b5a0a40de5f6215b25ef4a358a4e7f1c7cb2daa08defcf6bcc
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:directory-boundary-protocol
+criticality: critical
+injection_mode: always
+stages: [implement, check]
+triggers: []
+requires: []
+---
+
+# 目录边界协议
+
+## Scope
+
+约束实现阶段的模块目录、公开入口、依赖方向和越界识别。
+
+## Non-Scope
+
+不规定某种框架的固定包名。
+
+## Terms
+
+越界指绕过公开入口依赖其他模块内部实现。
+
+## MUST
+
+- 修改前必须搜索现有实现，并保持依赖只指向声明的公开入口。
+
+## MUST NOT
+
+- 不得把跨域逻辑塞入共享工具或直接引用其他模块内部文件。
+
+## SHOULD
+
+- 应以最小写集完成任务，并复用已有边界内能力。
+
+## Contract
+
+新增依赖必须能说明提供方、消费方、稳定入口与验证方式。
+
+## Checklist
+
+- [ ] 写集、入口、依赖方向和受影响消费者已复核。
+
+## Examples
+
+- 通过领域端口调用基础设施适配器，而不是从 Controller 直接访问实现类。
+
+## Anti-patterns
+
+- 为绕过循环依赖建立含混的 `common` 目录。
+
+## Ownership
+
+代码作者说明边界影响，模块所有者审批公开入口变化。
+
+## Change Policy
+
+公开入口变化按契约变更处理，迁移完成前保留兼容路径。
+

package/seeds/specs/hard/backend/04-layering-architecture-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/04-layering-architecture-protocol.md
+seed_source_sha256: 4a2ab2aa695a7b78136a2fd96076a869c367bb008a417be508756c632ad4ed6e
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:layering-architecture-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check]
+triggers: [layering, module-boundary, domain-design]
+requires: []
+---
+
+# 分层架构协议
+
+## Scope
+
+规范 Controller、Application/Service、Domain、Repository 与 Infrastructure 的职责。
+
+## Non-Scope
+
+不要求简单系统机械创建所有层或使用特定框架注解。
+
+## Terms
+
+依赖方向指高层策略不依赖低层技术细节的约束。
+
+## MUST
+
+- 业务不变量、事务编排和外部适配必须位于可解释且可测试的边界。
+
+## MUST NOT
+
+- 不得在 Controller、ORM Entity 或基础设施适配器中散落权威业务规则。
+
+## SHOULD
+
+- 应让层间数据转换显式并避免同一校验在多层重复实现。
+
+## Contract
+
+每层必须声明输入、输出、失败语义、依赖和测试责任。
+
+## Checklist
+
+- [ ] 调用链、转换点、事务所有者和异常映射已明确。
+
+## Examples
+
+- Controller 校验传输格式，应用服务编排用例，领域对象维护不变量。
+
+## Anti-patterns
+
+- Service 仅转发，而 Controller 同时处理事务、SQL 和业务判断。
+
+## Ownership
+
+架构所有者维护分层约束，各层维护者提供边界测试。
+
+## Change Policy
+
+跨层迁移必须记录兼容影响并分阶段消除旧依赖。
+

package/seeds/specs/hard/backend/05-task-workflow-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/05-task-workflow-protocol.md
+seed_source_sha256: b0d176f1f2d19cd14739ff4de39d77659036516ab1377b83c261ecc53a2de2dd
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:task-workflow-protocol
+criticality: critical
+injection_mode: always
+stages: [prepare, implement, check, release]
+triggers: []
+requires: []
+---
+
+# 后端任务工作流协议
+
+## Scope
+
+定义 Backend Ready、阶段选择、影响识别和执行路由。
+
+## Non-Scope
+
+不替代 BP 业务事实或项目级实施方案。
+
+## Terms
+
+stage 为 `prepare`、`implement`、`check` 或 `release`。
+
+## MUST
+
+- 必须确认任务事实、stage、写集、契约影响、风险和验证计划。
+
+## MUST NOT
+
+- 不得把 planned、推测或未运行检查描述为 verified。
+
+## SHOULD
+
+- 应在发现跨角色缺口时生成明确问题或 blocker。
+
+## Contract
+
+每次执行必须输出范围、选中规范、变更结果、检查证据和剩余风险。
+
+## Checklist
+
+- [ ] 当前 stage 与任务目标一致。
+
+## Examples
+
+- 简单内部 Mapper 修复只加载当前 stage 的 always 基线。
+
+## Anti-patterns
+
+- 因协议 critical 就无条件加载其完整正文。
+
+## Ownership
+
+执行者维护任务状态，评审者核对证据与声明一致性。
+
+## Change Policy
+
+阶段语义变化必须同步注入器、索引和生命周期消费者。
+

package/seeds/specs/hard/backend/06-ai-generated-code-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/06-ai-generated-code-protocol.md
+seed_source_sha256: a88614806137f33161b741d2a9fbc6ee310fa4f0cbf6acd222de07c14aee3d75
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:ai-generated-code-protocol
+criticality: critical
+injection_mode: always
+stages: [prepare, implement, check]
+triggers: []
+requires: []
+---
+
+# AI 生成代码协议
+
+## Scope
+
+约束 Agent 的前置检查、事实边界、复用搜索、实现与验证声明。
+
+## Non-Scope
+
+不授权 Agent 自行决定业务事实或扩大写集。
+
+## Terms
+
+权威事实包括已确认的 PRD、契约、schema、配置来源和仓库证据。
+
+## MUST
+
+- 写入前必须读取规范、搜索复用点，并按风险运行可复核检查。
+
+## MUST NOT
+
+- 不得发明字段、接口、错误码、迁移、锁、Redis key、topic、secret 或环境阈值。
+
+## SHOULD
+
+- 应显式标记假设、未知项和需要升级确认的决策。
+
+## Contract
+
+生成内容必须绑定输入来源、目标写集和验证结果。
+
+## Checklist
+
+- [ ] 已检查既有实现、镜像路径、未提交改动和任务边界。
+
+## Examples
+
+- 缺少隔离级别事实时记录待确认项，而不是选择一个默认值。
+
+## Anti-patterns
+
+- 用聊天记忆替代仓库、契约、测试或运行证据。
+
+## Ownership
+
+Agent 对变更与声明负责，用户拥有超出既定范围的决策权。
+
+## Change Policy
+
+新增高频误改模式时应追加明确禁止项和回归测试。
+

package/seeds/specs/hard/backend/07-evidence-acceptance-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/07-evidence-acceptance-protocol.md
+seed_source_sha256: fb86312eaadaec81d21e20abfb979e0127138002731ddc4fb1ead9ec90cd10bb
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:evidence-acceptance-protocol
+criticality: critical
+injection_mode: always
+stages: [prepare, check, release]
+triggers: []
+requires: []
+---
+
+# 证据与验收协议
+
+## Scope
+
+定义计划证据、实现证据、检查证据、发布证据和例外门禁。
+
+## Non-Scope
+
+不替代各领域协议规定的具体测试方法。
+
+## Terms
+
+证据是可由他人复核的代码坐标、hash、测试、报告或运行结果。
+
+## MUST
+
+- 验收结论必须绑定当前任务、review range、版本和可复核证据。
+
+## MUST NOT
+
+- 不得以口头完成声明、过期报告或无来源截图通过门禁。
+
+## SHOULD
+
+- 应记录失败检查、未覆盖风险和经批准例外的到期条件。
+
+## Contract
+
+验收记录至少包含检查项、命令或来源、结果、时间范围与责任方。
+
+## Checklist
+
+- [ ] 计划、实现、测试、运行和发布证据处于同一变更范围。
+
+## Examples
+
+- 用 migration 测试与 schema hash 证明数据库变更已验证。
+
+## Anti-patterns
+
+- 只列“测试通过”，不提供测试范围与结果来源。
+
+## Ownership
+
+实现者提供证据，评审与发布责任人决定门禁是否满足。
+
+## Change Policy
+
+降低证据要求必须作为受控例外记录，不得静默删除门禁。
+

package/seeds/specs/hard/backend/08-contract-change-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/08-contract-change-protocol.md
+seed_source_sha256: 805c146b31c70d08f876631bc19273076eb242d78fcb3b3a3bd33437e28a6953
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:contract-change-protocol
+criticality: critical
+injection_mode: always
+stages: [prepare, implement, check, release]
+triggers: []
+requires: []
+---
+
+# 契约变更协议
+
+## Scope
+
+识别 API、错误码、schema、消息、配置与运行行为的兼容影响。
+
+## Non-Scope
+
+不定义具体业务契约内容。
+
+## Terms
+
+公共契约是已有调用方、持久化数据或运行依赖所观察的稳定行为。
+
+## MUST
+
+- 变更前必须识别消费者、兼容窗口、迁移、回滚和版本策略。
+
+## MUST NOT
+
+- 不得在没有迁移说明时删除、重命名或改变已发布语义。
+
+## SHOULD
+
+- 应优先采用可并行部署、可观测并可撤回的演进方式。
+
+## Contract
+
+变更记录必须包含旧行为、新行为、影响面、兼容判断和验证证据。
+
+## Checklist
+
+- [ ] API、数据、消息、配置和运行消费者均已检查。
+
+## Examples
+
+- 新字段先以兼容方式发布，消费者迁移后再结束旧版本窗口。
+
+## Anti-patterns
+
+- 只修改实现而不更新 OpenAPI、migration、事件 schema 或变更记录。
+
+## Ownership
+
+契约提供方维护兼容方案，消费者确认迁移完成。
+
+## Change Policy
+
+破坏性变更必须经过显式审批、版本升级和可执行回退方案。
+

package/seeds/specs/hard/backend/09-role-responsibility-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/09-role-responsibility-protocol.md
+seed_source_sha256: 603b285faa271b77140f28e1038f850cd01b17ed1813b965898c4746233b342f
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:role-responsibility-protocol
+criticality: advisory
+injection_mode: reference
+stages: [prepare, check]
+triggers: [ownership, handoff]
+requires: []
+---
+
+# 角色与责任协议
+
+## Scope
+
+规范 Owner、RACI、评审责任、升级和跨角色交接。
+
+## Non-Scope
+
+不保存具体项目的人员名单或排班。
+
+## Terms
+
+Owner 指对契约、实现或证据完整性承担最终维护责任的角色。
+
+## MUST
+
+- 高风险决策、公共契约和运行门禁必须有可识别的责任角色。
+
+## MUST NOT
+
+- 不得用“团队共同负责”掩盖审批、维护或事故响应空缺。
+
+## SHOULD
+
+- 应在 handoff 中明确输入、输出、截止条件和拒收标准。
+
+## Contract
+
+责任记录至少包含决策者、执行者、评审者、被通知方和升级路径。
+
+## Checklist
+
+- [ ] 跨 BP、Frontend、Backend、Test 与 Ops 的边界已明确。
+
+## Examples
+
+- API 提供方维护契约，调用方确认兼容窗口内完成迁移。
+
+## Anti-patterns
+
+- 交接只发送文档链接，不说明版本、状态和待办。
+
+## Ownership
+
+治理维护者定义角色模型，项目自行绑定实际责任人。
+
+## Change Policy
+
+角色模型变化不得回写或推测消费项目的人员事实。
+

package/seeds/specs/hard/backend/10-security-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/10-security-protocol.md
+seed_source_sha256: 56387f03edd35df50a5a701f4daab174b744d490663393f43331cf5401149f67
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:security-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [security, api-input, authentication, authorization, file-processing, secrets]
+requires: []
+---
+
+# 安全协议
+
+## Scope
+
+规范认证、鉴权、输入与文件校验、注入防护、密钥和安全默认值。
+
+## Non-Scope
+
+不替代隐私保留规则或具体基础设施加固 Overlay。
+
+## Terms
+
+信任边界是数据或调用从较低信任域进入较高权限域的位置。
+
+## MUST
+
+- 所有信任边界必须执行服务端校验、最小权限、失败关闭和安全审计。
+
+## MUST NOT
+
+- 不得信任前端隐藏、客户端校验、代理头或用户提供的资源归属。
+
+## SHOULD
+
+- 应采用参数化接口、集中密钥管理和可轮换凭据。
+
+## Contract
+
+安全设计必须列出资产、威胁、控制、失败语义、日志限制和验证证据。
+
+## Checklist
+
+- [ ] 认证、鉴权、输入、输出、文件、secret 与审计路径已检查。
+
+## Examples
+
+- 下载接口同时验证操作权限、数据范围和资源归属。
+
+## Anti-patterns
+
+- 把 token、密码或敏感 payload 写入日志与异常。
+
+## Ownership
+
+服务端拥有最终安全判断，安全评审者维护阻断门禁。
+
+## Change Policy
+
+放宽安全控制必须经过显式风险审批、范围限制和到期复审。
+

package/seeds/specs/hard/backend/11-environment-configuration-protocol.md

@@ -0,0 +1,67 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/11-environment-configuration-protocol.md
+seed_source_sha256: eb9e82e9df64ce238501bc51cd359f36150f911c149904e2ed5a43d9b652b1bd
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:environment-configuration-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [environment-configuration, configuration, secrets, runtime]
+requires: []
+---
+
+# 环境与配置协议
+
+## Scope
+
+规范环境、profile、secret、超时、配置来源、变更和漂移。
+
+## Non-Scope
+
+不规定具体环境名称、凭据或连接参数数值。
+
+## Terms
+
+配置漂移是声明基线与构建、部署或运行时有效值不一致。
+
+## MUST
+
+- 配置必须有类型、来源、默认行为、敏感级别、验证与变更路径。
+
+## MUST NOT
+
+- 不得把 secret 写入仓库、日志、示例、命令行历史或生成文档。
+
+## SHOULD
+
+- 应在启动时校验关键配置，并对版本与来源提供可观测证据。
+
+## Contract
+
+配置变更必须说明兼容影响、部署顺序、回滚和漂移检测方式。
+
+## Checklist
+
+- [ ] 本地、CI、测试与运行环境的来源和覆盖顺序已核对。
+
+## Examples
+
+- 缺少必需配置时启动失败并输出不含 secret 的稳定错误。
+
+## Anti-patterns
+
+- 用环境默认值掩盖未声明的生产行为。
+
+## Ownership
+
+应用维护者定义消费契约，平台维护者提供受控配置与 secret 来源。
+
+## Change Policy
+
+配置键重命名必须提供双读或迁移窗口并验证旧值清理。

package/seeds/specs/hard/backend/12-api-contract-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/12-api-contract-protocol.md
+seed_source_sha256: 35519d81548cabff729de888e0bf9e0d5b40a0274c9fa3684641b50e75938ca0
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:api-contract-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check]
+triggers: [api-contract, api-change]
+requires: []
+---
+
+# API 契约协议
+
+## Scope
+
+规范请求响应、版本、字段、权限、错误、幂等、分页、兼容与 TraceId。
+
+## Non-Scope
+
+不替代领域规则、最终鉴权或具体 endpoint 事实。
+
+## Terms
+
+正式契约是 OpenAPI 或项目明确指定的等价权威来源。
+
+## MUST
+
+- method、path、字段、状态码、错误码、权限和兼容策略必须与实现一致。
+
+## MUST NOT
+
+- 不得把 Mock、聊天记录或调用方猜测当作正式契约。
+
+## SHOULD
+
+- 应对新增字段、分页、重试和版本演进采用向后兼容默认值。
+
+## Contract
+
+每个接口必须定义输入、输出、失败、幂等、权限、追踪与版本语义。
+
+## Checklist
+
+- [ ] 契约、实现、生成客户端、测试和 handoff 已同步。
+
+## Examples
+
+- 冲突返回稳定错误码与 TraceId，而不是泄露内部异常。
+
+## Anti-patterns
+
+- 修改响应字段但不更新正式契约和调用方兼容测试。
+
+## Ownership
+
+Backend 维护服务端契约，消费者确认联调与兼容结果。
+
+## Change Policy
+
+破坏性 API 变化必须按契约变更协议执行版本与迁移。
+