@chenmk/superflow 0.1.1 → 0.1.3

package/assets/context-templates/external-systems.md

@@ -1,166 +1,69 @@
-# 上游系统约定
+# 外部系统与集成约定
 
-> **初始版来源**：sdd-cli 散落的对账/跨仓规则 + openspec/changes/v1.1-add-charging-package-suite 涉及的外部系统引用
-> **维护方**：架构 / 集成开发
-> **自动化率**：80-95%（MQ topic 常量、API client 调用点静态可挖）
+> **用途**：记录当前项目依赖的外部系统、接口、消息、文件、账号和联调方式。
+> **维护方**：集成负责人 / 模块 owner / 测试负责人
 
-## 1. 系统拓扑概览
+## 1. 系统拓扑
 
+```text
+<当前系统>
+  ├─ HTTP / RPC -> <外部系统 A>
+  ├─ MQ / Event -> <外部系统 B>
+  ├─ File / Object Storage -> <外部系统 C>
+  └─ Webhook / Callback <- <外部系统 D>
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│ evcharge-operator-api (本服务)                                  │
-│   Spring Boot 2.x                                               │
-│   base port: 9250（worktree 派生端口 = 9250 + P/CR 编号）         │
-│   职责：充电套餐核心业务 + 站点 / 设备管理 + 计费对账              │
-└─────────────────────────────────────────────────────────────────┘
-        ↕ (HTTP / MQ / 定时任务 / 回调)
-        ├── BEM (停车月票权益服务)
-        ├── 财务对账系统（定期对账）
-        ├── Lark / 飞书（需求 / 文档 / 通知）
-        ├── 云效 / 钉钉（CI / 任务协作 / bug tracker）
-        ├── 车位 / 设备 IoT（扫码 / 充电桩事件）
-        └── 支付 / 退款通道（第三方）
-```
 
-## 2. 上游系统清单
-
-### 2.1 BEM（停车月票权益服务）
-
-- **职责**：管理停车月票权益，与充电套餐权益互斥 / 同步
-- **集成方式**：HTTP API（同步）+ MQ 事件（异步）
-- **关键事件**：
-  - 充电套餐退款 → BEM 同步退款（CDPT-186 历史事故：同步缺失）
-  - 充电套餐续费 → BEM 续费月票（CDPT-169 历史事故：续费缺失）
-- **数据流向**：
-  - 出：本服务发退款 / 续费请求到 BEM
-  - 入：BEM 回调停车权益变化（webhook / MQ）
-- **失败处理**：BEM 调用失败必须重试 + 告警，不能静默成功
-- **占位**（待人工补）：API 路径、MQ topic、SDK 版本号、对账窗口期
-
-### 2.2 财务对账系统
-
-- **职责**：充电订单 / 退款 / 套餐开通 / 续费 的财务对账
-- **集成方式**：定时任务拉取对账文件 + T+1 对账
-- **关键字段**：
-  - 订单号、金额、支付渠道、退款单号、套餐 ID、站点 ID、运营商 ID
-- **三方对账要求**（见 [decisions §1 ADR-003](./decisions.md#adr-003-sql-总-sql-文件作为版本合同)）：
-  - ① 源码/Mapper 读写字段
-  - ② 开发库结构
-  - ③ 测试库现状 + 版本总 SQL 执行后结构
-- **占位**（待人工补）：对账文件格式、对账时间窗、差异处理流程
-
-### 2.3 Lark / 飞书
-
-- **职责**：
-  - 需求来源（产品文档 / 截图 / 原型 / 会议纪要）
-  - 文档协作（API 文档 / 设计文档 / 验收记录）
-  - 通知（事故告警 / 部署通知 / 周报）
-- **集成方式**：
-  - 文档：人工导入（云文档链接）
-  - 通知：webhook 推送到飞书群机器人
-  - 部分自动化：openspec proposal 生成后同步到飞书文档（待定）
-- **占位**（待人工补）：webhook URL、群机器人 token、文档空间 ID
-
-### 2.4 云效 / 钉钉
-
-- **职责**：
-  - 任务协作（产品 / 开发 / 测试 / 运维）
-  - bug tracker（CDPT-XXX 编号）
-  - CI（自动跑测试 / 构建 / 部署）
-  - 代码托管（gitee / gitlab）
-- **集成方式**：
-  - 任务 / bug：人工操作（云效网页）
-  - CI：webhook 触发
-  - 事故编号命名规范：`CDPT-XXX`
-- **占位**（待人工补）：gitee 仓库地址、CI 配置位置
-
-### 2.5 车位 / 设备 IoT
-
-- **职责**：扫码充电触发、车位枪状态、充电事件
-- **集成方式**：
-  - 扫码：HTTP API（前端 → 本服务 → IoT 网关）
-  - 车位枪状态：MQ 事件（IoT → 本服务）
-  - 充电事件：MQ 事件（IoT → 本服务 → 财务对账）
-- **关键事件**：
-  - 扫码开启充电（CDPT-163 历史事故：开不了）
-  - 车位枪启用 / 停用（CDPT-199 历史事故：未绑定时按钮可点）
-- **占位**（待人工补）：MQ topic、IoT 网关 API、事件 schema
-
-### 2.6 支付 / 退款通道
-
-- **职责**：套餐购买支付、退款、续费扣款
-- **集成方式**：HTTP API（同步）+ webhook 回调
-- **关键流程**：
-  - 支付成功 → 开通套餐 → 同步 BEM
-  - 退款发起 → 支付通道退款 → 同步 BEM → 更新本地状态
-- **占位**（待人工补）：支付渠道（微信 / 支付宝 / 银联）、回调地址
-
-## 3. MQ 约定（占位 — 待人工补实际 topic）
-
-| Topic 模式 | 生产者 | 消费者 | 用途 |
-|-----------|--------|--------|------|
-| `evcharge.charging.event.v1` | 充电桩 / IoT | 本服务 | 充电事件（开始 / 停止 / 故障） |
-| `evcharge.billing.refund.v1` | 本服务 | BEM | 退款事件 |
-| `evcharge.billing.renew.v1` | 本服务 | BEM | 续费事件 |
-| `evcharge.billing.sync.v1` | BEM | 本服务 | 停车月票权益变化 |
-| `evcharge.finance.reconcile.v1` | 财务对账系统 | 本服务 | 对账差异推送 |
-
-> **占位说明**：上述 topic 是命名规范示例，**实际 topic 需从代码常量 / 配置文件核对**（grep `RocketMQTemplate` / `KafkaTemplate` / `@RocketMQMessageListener` 等）
-
-## 4. 共享表 / 跨仓约定
-
-### 4.1 跨仓对账清单（占位 — 待人工补）
-
-| 表 | 真源 | 消费仓 1 | 消费仓 2 | 消费仓 3 |
-|----|------|---------|---------|---------|
-| `t_package` | 本服务 | BEM（只读） | 财务对账 | 定时任务 |
-| `t_package_order` | 本服务 | BEM | 财务对账 | 退款通道 |
-| `t_site` | 本服务 | BEM | IoT 网关 | 第三方平台 |
-| `t_operator` | 本服务 | BEM | 财务对账 | 第三方平台 |
-
-> **占位说明**：实际表名 / 字段 / 关系 需从 `src/main/resources/sql/` 和 `application-*.yml` 核对
-
-### 4.2 关键表（占位 — 待人工补详细 schema）
-
-- `t_package` — 套餐主表
-- `t_package_order` — 套餐开通 / 续费 / 退款记录
-- `t_package_site` — 套餐与站点关系表（**注意：这是 CDPT-165 修复后引入的"中间表"，运营商边界过滤必须走这里**）
-- `t_site` — 站点表
-- `t_operator` — 运营商表
-- `t_site_operator` — 站点与运营商关系表
-
-> **占位说明**：详细字段、索引、外键、默认值需查 `sql/` 目录
-
-## 5. API 约定
-
-### 5.1 REST 风格
-
-- URL：`/api/v1/<resource>/<action>`
-- 鉴权：JWT / Session（占位，待补）
-- 错误码：4xx 业务错误 + 5xx 系统错误（占位，待补错误码表）
-- 分页：统一 `{ page, size, total }` 格式（占位）
-
-### 5.2 关键 API（占位 — 待人工补路径）
-
-| API | 方法 | 用途 | 关联事故 |
-|-----|------|------|---------|
-| 创建套餐 | POST | 运营商创建套餐 | CDPT-165 / CDPT-171 |
-| 套餐分页查询 | GET | 按运营商过滤 | CDPT-165 |
-| 套餐开通 | POST | 用户购买 / 批量开通 | CDPT-179 / CDPT-180 |
-| 套餐续费 | POST | 续费停车月票 | CDPT-169 |
-| 套餐退款 | POST | 单笔 / 批量退款 | CDPT-186 |
-| 套餐适用站点修改 | PUT | 修改适用站点 | CDPT-192 |
-| 扫码充电 | POST | 触发充电 | CDPT-163 |
-| 导出 Excel | GET | 各种导出 | CDPT-166 / CDPT-188 / CDPT-177 |
-
-> **占位说明**：实际 API 路径 / 入参 / 出参 需查 `src/main/java/` 的 Controller
-
-## 6. 维护提示
-
-- 本文件是**初始版**，superflow init Step 5 + 人工补全
-- **自动化补充重点**：
-  - 用 `superflow scan` 让 LLM 扫代码常量 → 自动填 MQ topic、API 路径、表名
-  - grep `RocketMQTemplate` / `KafkaTemplate` / `@RestController` 拿实际接口
-  - 读 `application.yml` 拿数据库连接 / Redis / MQ 连接配置
-- **不要在事故没复盘前**补充根因 — 留空让负责人填
-- 重要变更（升级支付渠道 / 接入新 IoT）必须追加本文件相关章节
+## 2. 外部系统清单
+
+| 系统 | 职责 | 集成方式 | 环境 | owner | 失败处理 |
+|------|------|----------|------|-------|----------|
+| `<系统 A>` | `<职责>` | `<HTTP/MQ/SDK/File>` | `<dev/test/prod>` | `<负责人>` | `<重试/告警/补偿>` |
+| `<系统 B>` | `<职责>` | `<HTTP/MQ/SDK/File>` | `<dev/test/prod>` | `<负责人>` | `<重试/告警/补偿>` |
+
+## 3. API / SDK 约定
+
+| 系统 | API/SDK | 调用方 | 鉴权 | 超时/重试 | 真实联调入口 |
+|------|---------|--------|------|-----------|--------------|
+| `<系统 A>` | `<路径/方法/SDK 方法>` | `<模块>` | `<方式>` | `<策略>` | `<curl/控制台/模拟器>` |
+
+维护要求：
+
+- 真实 API 路径、参数和响应以源码、官方文档或联调记录为准。
+- 不允许凭历史经验补字段；字段语义不确定时必须回到事实源。
+- 新增、删除或重命名字段时，要反查所有调用方、DTO、Mapper、日志和测试。
+
+## 4. 消息与异步链路
+
+| Topic / Queue / Event | 生产者 | 消费者 | Payload 真源 | 幂等键 | 验证方式 |
+|-----------------------|--------|--------|--------------|--------|----------|
+| `<事件名>` | `<系统>` | `<系统>` | `<schema/代码>` | `<字段>` | `<日志/DB/消费记录>` |
+
+异步任务完成证据至少包含：
+
+- 生产侧日志或发送记录。
+- 消费侧日志或处理记录。
+- 状态推进、数据库落库或下游回调。
+- 重试、死信或补偿策略说明。
+
+## 5. 文件、对象存储和批处理
+
+| 文件/任务 | 来源 | 格式 | 存储位置 | 触发方式 | 验证方式 |
+|-----------|------|------|----------|----------|----------|
+| `<文件/任务>` | `<来源>` | `<CSV/XLSX/JSON>` | `<路径/桶>` | `<手动/定时/API>` | `<样本/日志/结果>` |
+
+## 6. 环境与凭据
+
+| 环境 | 地址 | 凭据来源 | 测试账号 | 注意事项 |
+|------|------|----------|----------|----------|
+| dev | `<地址>` | `<env/secret manager>` | `<账号>` | `<说明>` |
+| test | `<地址>` | `<env/secret manager>` | `<账号>` | `<说明>` |
+| prod | `<地址>` | `<env/secret manager>` | `<账号>` | `<说明>` |
+
+不要把真实 secret、token、private key 写入本文件。只记录凭据来源和申请方式。
+
+## 7. 联调与验收要求
+
+- 有可用沙箱或测试环境时，不能只提交 mock 结果。
+- 如果真实联调暂不可用，必须写明阻塞原因、owner、恢复条件和临时替代验证。
+- `test-report.md` 必须包含实际请求、实际响应、日志或数据证据。
+- 对外部系统的兼容逻辑必须可观测，不能静默吞错。

package/assets/context-templates/incidents.md

@@ -1,89 +1,51 @@
-# 历史事故
+# 事故、返工与缺陷复盘
 
-> **初始版来源**：`openspec/changes/v1.1-add-charging-package-suite/bug-archive/yunxiao-2026-06-02-pending-confirmation/`（云效 2026-06-02 待确认批次）+ sdd-cli 引用过的 P 编号
-> **维护方**：测试 + 开发
-> **自动化率**：20-40%（commit "fix" + 注释 "FIX" 可挖，PR 描述/issue tracker 不可访问——私有仓）
+> **用途**：沉淀项目历史事故、返工、漏测和联调问题，避免同类问题重复发生。
+> **维护方**：测试负责人 / 开发负责人 / 模块 owner
 
-## 1. v1.1 充电套餐批次（2026-06-02 云效待确认）
+## 1. 事故索引
 
-来源目录：`openspec/changes/v1.1-add-charging-package-suite/bug-archive/yunxiao-2026-06-02-pending-confirmation/`
-原始文件：HTML（云效导出） + `raw-bugs.json`（待解析）
+| 编号 | 标题 | 发现时间 | 严重级别 | 状态 | 关联规则 |
+|------|------|----------|----------|------|----------|
+| INC-001 | `<标题>` | `YYYY-MM-DD` | `<P0/P1/P2/P3>` | `<待修复/已修复/已复盘>` | `<business-rules/decisions>` |
 
-### 1.1 套餐运营商 / 站点相关
+## 2. 复盘模板
 
-| CDPT | 标题 | 状态 | 关联规则 |
-|------|------|------|---------|
-| CDPT-165 | 创建套餐的查询条件，运营商与查询结果不匹配，创建的套餐是其他运营商的 | 待修复 | [business-rules §1.1](./business-rules.md#11-套餐业务) |
-| CDPT-171 | 应限制同一个站点不能创建相同名称的优惠套餐 | 待修复 | §1.1 |
-| CDPT-192 | 修改充电套餐的适用站点后，已开通套餐的记录，适用站点没有更新 | 待修复 | §1.1 |
-| CDPT-166 | 创建套餐页面，导出 Excel 中的使用站点列展示错误 | 待修复 | §4 |
-| CDPT-158 | 充电套餐的有效时段，应该允许跨天 | 待修复 | §1.1 |
-| CDPT-175 | 同车牌不同套餐、不同有效时间段 — 应该允许开通 | 待修复 | §1.1 |
-
-### 1.2 退款 / 对账 / 权益同步
-
-| CDPT | 标题 | 状态 | 关联规则 |
-|------|------|------|---------|
-| CDPT-186 | 充电套餐退款后，停车月票权益在 BEM 没有同步退款 | 待修复 | [business-rules §1.2](./business-rules.md#12-计费--退款--对账) |
-| CDPT-189 | 已退款的优惠套餐订单，扫码开票提示需优化 | 待修复 | §3 |
-| CDPT-169 | 续费充电套餐（停车月票），BEM 没有对该月票订单续费 | 待修复 | §6 |
-| CDPT-193 | 充电套餐适用多个站点时，无法开票 | 待修复 | §1.1 |
-
-### 1.3 批量开通 / 续费 / 退款
-
-| CDPT | 标题 | 状态 | 关联规则 |
-|------|------|------|---------|
-| CDPT-185 | 批量开通、续费、退款模板中手机号应支持填写 1 个或 2 个手机号 | 待修复 | [business-rules §2.1](./business-rules.md#21-批量开通--续费--退款) |
-| CDPT-180 | 批量开通、续费、退费时，遇到错误/异常数据整批数据都不插入业务系统，明确提示哪一行，哪个字段数据异常 | 待修复 | §2.1 |
-| CDPT-181 | 问题 1：批量开通上传文件类型错误时的提示需优化；问题 2：导入空的 Excel 模板也提示成功 | 待修复 | §2.1、§2.2 |
-| CDPT-178 | 批量开通、续费、退费模版字段，必填字段应加入【必填】两个字 | 待修复 | §2.1 |
-| CDPT-179 | 批量开通充电套餐，选择当天，1 天有效期，开通记录显示已过期。在页面开通显示生效中 | 待修复 | §2.1 |
-| CDPT-198 | 批量导入车位枪的文件格式错误，提示需优化 | 待修复 | §2.2 |
-| CDPT-199 | 站点没有绑定车位枪时，站点的【启用车位枪】按钮不允许打开 | 待修复 | [business-rules §1.3](./business-rules.md#13-车位--设备) |
-
-### 1.4 导出 / 查询 / 字段
-
-| CDPT | 标题 | 状态 | 关联规则 |
-|------|------|------|---------|
-| CDPT-188 | 套餐开通记录导出，剩余充电额度为不限额时，导出内容错误 | 待修复 | [business-rules §4](./business-rules.md#4-数据权限--字段约束) |
-| CDPT-177 | 开通套餐记录导出的 Excel 中不要合并不连续的有效期 | 待修复 | §4 |
-| CDPT-173 | 开通套餐页面的查询条件，【车牌号码】应支持模糊查询 | 待修复 | §4 |
-| CDPT-164 | 开通套餐的记录中，最近操作人取值错误（admin 后台开通） | 待修复 | §4 |
-| CDPT-163 | 开通充电套餐后，扫码开启充电，没有套餐可用 | 待修复 | §3 |
-| CDPT-194 | 停车权益记录，适用车场的名称没展示 | 待修复 | §4 |
-
-## 2. 历史 P 编号记录（sdd-cli 引用过）
-
-来源：`sdd-cli/assets/skills/superflow-implement/SKILL.md` 等地方提到的 P 编号示例
-
-| P 编号 | 描述 | 备注 |
-|--------|------|------|
-| P50 | worktree 启动端口示例（base 9250 → 9300） | 端口计算约定 |
-| P64 | prompt 命名示例（p64-export-plot-display.md） | 命名约定 |
-
-> **注**：完整 P 编号历史应从 git log + openspec/changes/archive/ 反推。本文件仅记录 sdd-cli 显式引用的。
+```markdown
+### INC-001: <标题>
+
+- **发现时间**：YYYY-MM-DD HH:mm
+- **发现渠道**：线上报警 / QA / 客户反馈 / 联调 / code review
+- **影响范围**：用户、订单、数据、接口、任务或环境范围。
+- **直接原因**：触发故障的直接技术原因。
+- **根因**：为什么流程、设计、测试或代码没有提前发现。
+- **修复 commit / PR**：<链接或 SHA>
+- **验证证据**：测试命令、真实请求、日志、DB 记录或截图。
+- **防复发措施**：
+  - 文档规则：补充到哪个 `docs/sdd-context/*.md`
+  - 代码防线：新增哪个测试、断言、告警或 guard
+  - 流程防线：哪个阶段必须新增检查项
+- **复盘人**：<name>
+```
 
-## 3. 事故复盘模板
+## 3. 常见问题分类
 
-每条事故建议补充以下信息（自动化扫不到，需人工补）：
+| 分类 | 典型表现 | Superflow 阶段加固 |
+|------|----------|-------------------|
+| 需求理解偏差 | 字段语义、状态流、边界条件理解错误 | clarify / docs |
+| 源码影响面遗漏 | 只改一处，没有反查所有引用 | design |
+| 数据库合同遗漏 | 代码依赖字段，但 SQL/migration 未更新 | docs / verify |
+| mock-only 假通过 | 只跑 mock 单测，未跑真实入口 | implement / verify |
+| 异步链路漏验 | MQ、定时任务、回调没有真实证据 | verify |
+| 上下文漂移 | 长会话压缩后忘记原始约束 | handoff / guard |
 
-```markdown
-### CDPT-XXX: <标题>
+## 4. 复盘回写要求
 
-- **发现时间**：YYYY-MM-DD
-- **发现渠道**：云效 / QA / 线上报警 / 客户反馈
-- **根因**：（一句话说清楚，不要泛泛说"业务逻辑错误"）
-- **影响范围**：（哪些模块 / 哪些数据 / 多少用户 / 持续多久）
-- **修复 commit**：（`git log --grep="CDPT-XXX"` 拿 SHA）
-- **修复时间**：YYYY-MM-DD
-- **复盘人**：<name>
-- **预防措施**：（代码 / 流程 / 测试 哪一层加固）
-- **关联规则**：[business-rules.md §X.Y](./business-rules.md)
-```
+事故复盘完成后，至少回写一处长期规则：
 
-## 4. 维护提示
+- 业务规则问题：写入 [business-rules.md](./business-rules.md)。
+- 架构或工程约定问题：写入 [decisions.md](./decisions.md)。
+- 外部系统或联调问题：写入 [external-systems.md](./external-systems.md)。
+- 测试策略问题：写入当前 OpenSpec change 的 `tests.md` 和 `test-report.md`。
 
-- **不要直接复制云效 HTML**——内容里含截图/附件链接，存 md 里维护性差
-- 建议用 `raw-bugs.json` 解析后写本文件（一次性脚本）
-- 后期可让 LLM 帮补全"根因 / 影响范围"等结构化字段
-- 修复完成后这条记录可以从"待修复"挪到"已闭环"区
+只在聊天记录里解释，不算复盘完成。

package/assets/context-templates-en/business-rules.md

@@ -0,0 +1,72 @@
+# Business Rules
+
+> **Purpose**: Capture long-lived project business rules, edge cases, state
+> transitions, and acceptance criteria.
+> **Owners**: Product owner / business owner / engineering owner
+> **Maintenance**: `superflow init --language en` creates this template. Fill it
+> with project-specific facts before relying on it for delivery decisions.
+
+## 1. Core Business Objects
+
+| Object | Meaning | Uniqueness Rule | Lifecycle States | Key Constraints |
+|--------|---------|-----------------|------------------|-----------------|
+| `<Object A>` | `<Meaning>` | `<Unique key>` | `<States>` | `<Constraints>` |
+| `<Object B>` | `<Meaning>` | `<Unique key>` | `<States>` | `<Constraints>` |
+
+## 2. State Transitions
+
+| State | Entry Condition | Allowed Actions | Forbidden Actions | Exit Condition |
+|-------|-----------------|-----------------|-------------------|----------------|
+| `<State A>` | `<Condition>` | `<Actions>` | `<Actions>` | `<Condition>` |
+| `<State B>` | `<Condition>` | `<Actions>` | `<Actions>` | `<Condition>` |
+
+Rules:
+
+- When a state field, enum, derived value, or sync value changes, reverse-scan
+  all readers, writers, filters, exports, scheduled jobs, callbacks, and
+  cross-repo consumers.
+- Record the real source of truth for derived state. Do not infer semantics
+  from field names alone.
+- Compatibility or fallback behavior must name the owner, removal condition,
+  and observability plan.
+
+## 3. Critical Business Rules
+
+| ID | Rule | Applies To | Edge Case | Acceptance Evidence |
+|----|------|------------|-----------|---------------------|
+| BR-001 | `<Rule>` | `<Page/API/job>` | `<Edge case>` | `<Test/evidence>` |
+| BR-002 | `<Rule>` | `<Page/API/job>` | `<Edge case>` | `<Test/evidence>` |
+
+## 4. Data And Permission Boundaries
+
+| Dimension | Rule | Evidence Source |
+|-----------|------|-----------------|
+| Tenant / organization / project | `<Isolation rule>` | `<Source/config/table>` |
+| User roles | `<Permission rule>` | `<Menu/API/auth point>` |
+| Data visibility | `<Query scope>` | `<Mapper/API/page>` |
+| Write permissions | `<Mutation rule>` | `<Service/transaction/audit>` |
+
+## 5. Batch, Import, Export, And Error Rules
+
+- Batch operations must define all-or-nothing vs partial-success behavior.
+- Import templates must define required fields, formats, enums, duplicates, and
+  empty-file behavior.
+- Export fields must match page/API semantics; document intentional differences.
+- Error messages must identify the object, row, field, or concrete fix.
+
+## 6. Real Acceptance Evidence
+
+Requirements involving external systems, databases, async jobs, message queues,
+payments, files, permissions, or state transitions cannot be closed with mock
+unit tests alone. `test-report.md` should record:
+
+- Real entry point: page, API, message, scheduled job, or external callback.
+- Real parameters: request body, message payload, file sample, or test account.
+- Real result: response, database record, log, downstream callback, or UI state.
+- Assertion: expected vs actual values.
+
+## 7. Maintenance Notes
+
+- Keep project facts here, not generic process slogans.
+- After incidents, rework, or integration misses, add reusable rules here.
+- Mark uncertain rules as `To confirm`, with owner and evidence source.

package/assets/context-templates-en/decisions.md

@@ -0,0 +1,72 @@
+# Architecture And Engineering Decisions
+
+> **Purpose**: Capture long-lived architectural choices, engineering conventions,
+> and the reasoning behind trade-offs.
+> **Owners**: Architect / tech lead / module owner
+> **Recommended format**: ADR (Architecture Decision Record)
+
+## ADR-001: <Decision Title>
+
+- **Status**: Proposed / Accepted / Deprecated / Replaced
+- **Date**: YYYY-MM-DD
+- **Context**: Why this decision is needed.
+- **Decision**: The selected approach.
+- **Alternatives**:
+  - Option A: benefits and costs.
+  - Option B: benefits and costs.
+- **Impact**: Repositories, modules, tables, APIs, jobs, or deployment paths.
+- **Consequences**: Benefits, costs, risks, and future constraints.
+- **Verification**: How to prove the decision is implemented correctly.
+
+## 1. Project Structure
+
+| Topic | Current Convention | Source Of Truth | Notes |
+|-------|--------------------|-----------------|-------|
+| Module boundaries | `<Description>` | `<Directory/doc/config>` | `<Notes>` |
+| Layering | `<Description>` | `<Entrypoint>` | `<Notes>` |
+| Naming | `<Description>` | `<README/code example>` | `<Notes>` |
+| Configuration | `<Description>` | `<env/config/secret source>` | `<Notes>` |
+
+## 2. Database And Persistence
+
+| Topic | Current Convention | Required Gate |
+|-------|--------------------|---------------|
+| Schema source of truth | `<SQL/migration/live schema>` | Verify before edits |
+| Release SQL / migration | `<Rule>` | Required fields must ship |
+| Shared table consumers | `<Repo/module list>` | Reverse-scan all consumers |
+| Soft delete / multi-tenancy | `<Rule>` | Mapper/XML queries must align |
+
+## 3. API And Integration
+
+| Topic | Current Convention | Verification |
+|-------|--------------------|--------------|
+| API style | `<REST/RPC/GraphQL/message>` | `<Contract/integration test>` |
+| Authentication | `<Method>` | `<Test account/permission matrix>` |
+| Error codes | `<Rule>` | `<API doc/test>` |
+| External calls | `<Rule>` | `<Sandbox/real env/simulator>` |
+
+## 4. Testing And Delivery
+
+- Unit tests prove local logic; they do not prove a real delivery path.
+- External entry points require real request, message, log, or state evidence.
+- Database-backed changes require schema and data evidence.
+- Async flows require message, log, state transition, retry, or compensation
+  evidence.
+- Before claiming completion, run the relevant Superflow guard and project
+  verification command.
+
+## 5. Superflow Usage Decisions
+
+- OpenSpec/SDD owns WHAT and contracts.
+- Superpowers owns source-level HOW, TDD order, review, and verification
+  discipline.
+- `.sdd/state.yaml` and `.sdd/handoff/` are the state source of truth for
+  preventing context drift.
+- Parallel workers must state which docs and code paths they may edit.
+- Refresh the handoff hash when docs, code, prompts, or test reports change.
+
+## 6. Deprecated Decisions
+
+| Old Decision | Why Deprecated | Replacement | Date |
+|--------------|----------------|-------------|------|
+| `<ADR ID>` | `<Reason>` | `<ADR ID>` | `YYYY-MM-DD` |

package/assets/context-templates-en/external-systems.md

@@ -0,0 +1,78 @@
+# External Systems And Integration Contracts
+
+> **Purpose**: Record external systems, APIs, messages, files, accounts, and
+> integration evidence for this project.
+> **Owners**: Integration owner / module owner / QA owner
+
+## 1. System Topology
+
+```text
+<Current system>
+  +- HTTP / RPC -> <External system A>
+  +- MQ / Event -> <External system B>
+  +- File / Object Storage -> <External system C>
+  +- Webhook / Callback <- <External system D>
+```
+
+## 2. External System Inventory
+
+| System | Responsibility | Integration Type | Environment | Owner | Failure Handling |
+|--------|----------------|------------------|-------------|-------|------------------|
+| `<System A>` | `<Responsibility>` | `<HTTP/MQ/SDK/File>` | `<dev/test/prod>` | `<Owner>` | `<Retry/alert/compensation>` |
+| `<System B>` | `<Responsibility>` | `<HTTP/MQ/SDK/File>` | `<dev/test/prod>` | `<Owner>` | `<Retry/alert/compensation>` |
+
+## 3. API / SDK Contracts
+
+| System | API/SDK | Caller | Auth | Timeout/Retry | Real Test Entry |
+|--------|---------|--------|------|---------------|-----------------|
+| `<System A>` | `<Path/method/SDK method>` | `<Module>` | `<Method>` | `<Policy>` | `<curl/console/simulator>` |
+
+Rules:
+
+- Real API paths, parameters, and responses must come from source code,
+  official docs, or integration records.
+- Do not invent fields from memory. If semantics are unclear, return to the
+  source of truth.
+- When a field is added, removed, or renamed, reverse-scan callers, DTOs,
+  mappers, logs, and tests.
+
+## 4. Messages And Async Flows
+
+| Topic / Queue / Event | Producer | Consumer | Payload Source | Idempotency Key | Verification |
+|-----------------------|----------|----------|----------------|-----------------|--------------|
+| `<Event>` | `<System>` | `<System>` | `<Schema/code>` | `<Field>` | `<Log/DB/consumer record>` |
+
+Async completion evidence should include:
+
+- Producer log or send record.
+- Consumer log or handling record.
+- State transition, database write, or downstream callback.
+- Retry, dead-letter, or compensation strategy.
+
+## 5. Files, Object Storage, And Batch Jobs
+
+| File / Job | Source | Format | Storage | Trigger | Verification |
+|------------|--------|--------|---------|---------|--------------|
+| `<File/job>` | `<Source>` | `<CSV/XLSX/JSON>` | `<Path/bucket>` | `<Manual/scheduled/API>` | `<Sample/log/result>` |
+
+## 6. Environments And Credentials
+
+| Environment | Address | Credential Source | Test Account | Notes |
+|-------------|---------|-------------------|--------------|-------|
+| dev | `<URL>` | `<env/secret manager>` | `<Account>` | `<Notes>` |
+| test | `<URL>` | `<env/secret manager>` | `<Account>` | `<Notes>` |
+| prod | `<URL>` | `<env/secret manager>` | `<Account>` | `<Notes>` |
+
+Do not write real secrets, tokens, or private keys here. Record only where they
+come from and how to request access.
+
+## 7. Integration Acceptance
+
+- When sandbox or test environments are available, mock-only evidence is not
+  enough.
+- If real integration is blocked, record the blocker, owner, recovery condition,
+  and temporary substitute verification.
+- `test-report.md` must include actual requests, responses, logs, or data
+  evidence.
+- Compatibility logic for external systems must be observable; do not silently
+  swallow errors.

package/assets/context-templates-en/incidents.md

@@ -0,0 +1,52 @@
+# Incidents, Rework, And Defect Reviews
+
+> **Purpose**: Capture incidents, rework, missed tests, and integration misses
+> so similar issues do not repeat.
+> **Owners**: QA owner / engineering owner / module owner
+
+## 1. Incident Index
+
+| ID | Title | Found At | Severity | Status | Related Rule |
+|----|-------|----------|----------|--------|--------------|
+| INC-001 | `<Title>` | `YYYY-MM-DD` | `<P0/P1/P2/P3>` | `<Open/fixed/reviewed>` | `<business-rules/decisions>` |
+
+## 2. Review Template
+
+```markdown
+### INC-001: <Title>
+
+- **Found at**: YYYY-MM-DD HH:mm
+- **Found by**: Production alert / QA / customer feedback / integration / code review
+- **Impact**: Users, orders, data, APIs, jobs, or environments affected.
+- **Immediate cause**: The technical trigger.
+- **Root cause**: Why design, process, tests, or code failed to catch it earlier.
+- **Fix commit / PR**: <link or SHA>
+- **Verification evidence**: Test command, real request, log, DB row, or screenshot.
+- **Prevention**:
+  - Documentation rule: which `docs/sdd-context/*.md` file was updated.
+  - Code guard: which test, assertion, alert, or guard was added.
+  - Process guard: which workflow phase now checks this.
+- **Reviewer**: <name>
+```
+
+## 3. Common Categories
+
+| Category | Typical Symptom | Superflow Phase To Harden |
+|----------|-----------------|---------------------------|
+| Requirement drift | Field semantics, state flow, or edge case misunderstood | clarify / docs |
+| Source impact missed | Only one reference changed, other consumers missed | design |
+| Database contract missed | Code depends on fields that release SQL does not ship | docs / verify |
+| Mock-only false pass | Mock unit tests pass but real entry fails | implement / verify |
+| Async flow unverified | MQ, scheduled job, or callback lacks real evidence | verify |
+| Context drift | Long session compression loses original constraints | handoff / guard |
+
+## 4. Required Backfill
+
+After an incident review, update at least one long-lived rule:
+
+- Business rule issue: [business-rules.md](./business-rules.md).
+- Architecture or engineering decision issue: [decisions.md](./decisions.md).
+- External integration issue: [external-systems.md](./external-systems.md).
+- Test strategy issue: current OpenSpec change `tests.md` and `test-report.md`.
+
+Explaining the issue only in chat does not count as a completed review.