@chenmk/superflow 0.2.3 → 0.2.5

package/README.md

@@ -81,6 +81,16 @@ state, and dependency guards for Claude Code, Codex, and OpenCode.
   required: `> use SuperFlow to handle this requirement` triggers clarify →
   docs → design → implement → verify → archive. Phase progression, guards,
   hashes, and hooks are flow-enforced, not user-discipline.
+- **`superflow check` audits document completeness.** Runs against a 13-item
+  required-file checklist per change. Missing a required doc? Exit 1. No more
+  surprises at the implement phase — the gate catches gaps while you're still
+  in docs.
+- **`superflow config` tunes review depth per change.** `--review-mode
+  off|standard|thorough` controls code-review intensity; `--auto-transition`
+  controls automatic phase progression. Match the rigor to the risk.
+- **Startup version check.** Every superflow command silently compares your
+  installed version against the npm registry. A new version triggers a
+  non-blocking upgrade hint on stderr.
 
 ## Workflow
 
@@ -165,6 +175,11 @@ best-effort and does not block initialization.
 | `superflow implement` | Check implement-phase skill deployment |
 | `superflow verify` | Check verify-phase skill deployment |
 | `superflow archive` | Check archive-phase skill deployment |
+| `superflow check <change>` | Audit 13-file SDD document completeness |
+| `superflow config <change> --review-mode <mode>` | Set review depth (off/standard/thorough) |
+| `superflow config <change> --auto-transition <bool>` | Toggle automatic phase progression |
+| `superflow status` | List active changes with phase, tasks, and doc gaps |
+| `superflow update --with-package` | Update superflow, OpenSpec, and Superpowers |
 
 ## Agent Usage
 

package/README.zh-CN.md

@@ -50,6 +50,9 @@ CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 n
 - **5 个阶段 × 5+ 门禁脚本硬阻断。** `superflow-guard.sh` + `superflow-hook-guard.sh` + `superflow-contract-hooks.sh` + `superflow-sql-sync-hook.py` + `superflow-test-report-lint.py` + `superflow-verify-integration.sh`。没有 handoff hash 不进实现，没有真实入口证据不写"通过"。
 - **用 handoff + state + sha256 治上下文漂移。** 长会话压缩、切 agent、并行 worktree——`.sdd/handoff/sdd-context.{md,json}` + sha256 + `.sdd/state.yaml` 让 Worker / Tester / Reviewer 始终基于同一份上下文，hash 对不上的旧 prompt 自动被 guard 拒绝。
 - **用户只说一句话，流水线跑 9 步。** 不用写复杂 prompt：`> 用 SuperFlow 处理这个需求` 触发 clarify → docs → design → implement → verify → archive。阶段推进、guard、hash、hook 全是流程强制，不靠用户自觉。
+- **`superflow check` 一键诊断文档缺口。** 对照 13 项必备 SDD 文件逐项核验，缺失即 exit 1。再也不会进了 implement 才发现 proposal 没写——check 在 docs 阶段就拦住你。
+- **`superflow config` 按需调整审查强度。** `--review-mode off|standard|thorough` 控制代码审查深度；`--auto-transition` 控制阶段自动流转。不同改动匹配不同强度，省 token 不省质量。
+- **启动自动检查新版本。** 每次执行 superflow 命令，后台静默对比 npm registry。发现新版本时 stderr 输出升级提示，不阻塞、不拖慢。
 
 ## 工作流
 
@@ -141,6 +144,11 @@ superflow init
 | `superflow design [change]` | 校验 SuperBridge Flow design 阶段技能部署 |
 | `superflow implement [task]` | 校验 SuperBridge Flow implement 阶段技能部署 |
 | `superflow pipeline` | 校验 SuperBridge Flow pipeline 阶段技能部署 |
+| `superflow check <change>` | 对照 13 项必备文件清单检查文档完整性 |
+| `superflow config <change> --review-mode <mode>` | 设置代码审查强度（off/standard/thorough） |
+| `superflow config <change> --auto-transition <bool>` | 控制阶段自动流转（true/false） |
+| `superflow status` | 展示所有 active change 的阶段、任务、文档缺口 |
+| `superflow update --with-package` | 更新 superflow 自身和 openspec/superpowers 依赖 |
 
 ## 系统支持
 

package/assets/skills/superflow-design/SKILL.md

@@ -64,12 +64,31 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    owner confirmation, unresolved handling, and test evidence. A request
    succeeding or a field being non-null is not enough; unconfirmed values are
    blockers and must be returned to `$superflow-docs` or the user.
-8. Record state:
+8. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+   balance, electricity fee, service fee, package settlement, proration,
+   allocation, reconciliation, or financial display changes,
+   include `Money Precision Boundary`. Prove calculation-state fields,
+   settlement/display-state fields, rounding boundary, scale, rounding mode,
+   allocation/reconciliation rule, and tests covering half-cent or residual
+   cases. If the design rounds money before later slicing, proration,
+   aggregation, discounting, or allocation, stop and redesign the calculation
+   boundary. When an additive identity has an authoritative total, the design
+   must calculate only N-1 components independently and derive the final
+   complement as `authoritative total - sum(other components)`. Independently
+   calculating and rounding all components before rebuilding the total is
+   blocked. A claimed exception must name the actual source of truth and owner
+   evidence. Read
+   `../superflow-pipeline/references/money-precision-algorithms.md` and also
+   freeze the exact representation, currency/minor-unit boundary, rounding
+   level and policy source, deterministic residual strategy with stable
+   tie-breaker, and positive/zero/negative evidence. For FX changes, freeze the
+   directional rate metadata and one canonical conversion path.
+9. Record state:
    ```bash
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> technical_design docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> design_doc design.md
    ```
-9. Update `design.md` with `Superpowers Technical Design Handoff`, update
+10. Update `design.md` with `Superpowers Technical Design Handoff`, update
    `sdd-quality-gate.md` with the technical design path and hash, then run
    `../superflow-pipeline/scripts/superflow-handoff.sh <change-dir> --refresh`.
    If the guard reports a stale or missing hash, record the printed hash in
@@ -77,7 +96,7 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    `--refresh` again. Do not set `design_doc` to the Superpowers document;
    `design_doc` is the OpenSpec/SDD contract design, while `technical_design`
    is the Superpowers HOW document.
-10. Run:
+11. Run:
 
 ```bash
 ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>

package/assets/skills/superflow-docs/SKILL.md

@@ -85,6 +85,17 @@ Binding` with:
 不确定项/阻塞处理 | 测试证据`. Unconfirmed values are blockers; do not
   invent numeric values, origin/source values, display meanings, or fallback
   mappings.
+- For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+  balance, electricity/service fee, package settlement, proration, allocation,
+  reconciliation, or financial display changes, `sdd-quality-gate.md` must
+  declare `Money Precision Boundary` as blocking. `tests.md` and the
+  `test-report.md` skeleton must reserve half-cent, residual, or multi-detail
+  cases and reconciliation evidence. Do not freeze docs that allow intermediate
+  money to be rounded before later slicing, aggregation, discounting, or
+  allocation. For additive identities, docs must name the authoritative total,
+  independently calculated N-1 components, and the final complement formula:
+  `authoritative total - sum(other components)`. Do not allow every component
+  to be calculated and rounded independently before rebuilding the total.
 - For low-freedom implementation handoff, docs include the five hard gates:
   field semantic contract, write-through persistence closure, real-entry call
   chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
@@ -302,6 +313,11 @@ test-report证据位置`.
   `RED 失败证据`, `GREEN 通过证据`, `接口自动化证据`, `DB 核查证据`,
   `日志核查证据`, `未自动化/阻塞用例`, and `Partially verified 边界`.
   Each section must reference concrete `tests.md` case IDs.
+- For money-related changes, `test-report.md` must also include `Money Precision
+  Boundary` evidence: original calculation inputs and precision, actual rounding
+  boundary and mode, half-cent/residual/multi-detail cases, and reconciliation
+  of original, discount, actual/refund, and allocated totals. Evidence must show
+  which total was authoritative and which complement was derived by subtraction.
 - `sdd-quality-gate.md` must include blocking checks for:
   executable tests frozen, RED/GREEN expectations present, interface automation
   commands present, DB/log assertions present, and mock/skipped cases excluded

package/assets/skills/superflow-implement/SKILL.md

@@ -111,6 +111,23 @@ Before implementation phase can exit:
   source, Mapper XML, entities, DTO/VO, SQL, scheduled jobs, MQ/event consumers,
   callbacks, third-party adapters, shared SDK/tables, and sibling repos when
   applicable. A prompt that only changes the direct setter/writer is blocked.
+- When a task changes money, fees, discounts, deductions, refunds, sharing,
+  payments, invoices, balances, electricity/service fees, package settlement,
+  proration, allocation, reconciliation, or financial display, every prompt
+  must include "金额精度边界继承". It must copy the technical design
+  `Money Precision Boundary`, keep calculation-state precision until the
+  confirmed settlement/display boundary, forbid early `setScale(2)` before
+  later slicing or aggregation, and require deterministic residual allocation.
+  For additive identities with an authoritative total, the prompt must compute
+  only N-1 components independently and derive the final complement as
+  `authoritative total - sum(other components)`; calculating and rounding all
+  components independently is blocked.
+  It must inherit `money-precision-algorithms.md`: exact decimal construction,
+  currency/provider minor units, rounding level and policy source,
+  deterministic residual tie-breaker, pre/post-round audit, signed-value tests,
+  and conditional FX metadata.
+  RED/GREEN coverage must include half-cent, residual, or multi-detail cases
+  and prove reconciliation identities in `test-report.md`.
 - Every implementation prompt must include a "上下文防漂移与状态继承" section.
   It must link `.sdd/handoff/sdd-context.md` as a clickable Markdown link,
   record the exact `handoff_hash`, and require Worker/Tester/Reviewer to read

package/assets/skills/superflow-pipeline/SKILL.md

@@ -402,6 +402,23 @@ SDD 设计、评审、实现 prompt 和测试报告中，字段/状态/枚举/
 - 兜底让异常数据、缺失字段、旧错误状态静默通过，且没有暴露机制，阻塞。
 - 无法证明字段值符合业务语义时，必须标记 `Blocked`，不得冻结设计或生成实现 prompt。
 
+### 金额精度边界门禁（阻塞级）
+
+凡涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、服务费、
+套餐结算、比例分摊、明细分配、对账或财务展示，必须从 docs、技术详设、实现
+prompt、代码评审、测试到 verify 继承同一份 `Money Precision Boundary`。
+
+- 最终结算/持久化/支付/开票/导出/展示边界前保留计算态原始精度。
+- 禁止提前 `setScale(2)` 后继续切片、分摊、汇总、抵扣或反推单价。
+- 多明细必须用确定性规则处理尾差，分配合计必须等于目标金额。
+- 存在加法恒等式且总额是真源时，只允许独立计算 N-1 个组成项；最后一个组成项
+  必须按 `权威总额 - 其余组成项合计` 差额反推。禁止所有组成项分别计算、分别
+  舍入后再相加重建权威总额。
+- tests.md 和 test-report.md 必须覆盖半分、尾差或多明细场景，并证明原始金额、
+  优惠金额、实付/退款金额和分配合计满足合同恒等式。
+- 缺少权威总额、差额反推公式、舍入边界、scale/rounding mode、分配规则或对账
+  证据时标记 `Blocked`。不适用差额反推时必须写明真实真源和 owner 证据。
+
 ### 低自由度研发 Agent 五项硬门禁（阻塞级）
 
 面向低能力或高自由发挥风险的研发 agent，SDD 文档必须把可猜测空间压到最低。
@@ -828,6 +845,7 @@ Load only the reference needed for the current phase:
 - OpenSpec format: `references/openspec-format.md`
 - Document quality: `references/quality-standards.md`
 - Quality gate: `references/quality-gate.md`
+- 金额精度算法基线：`references/money-precision-algorithms.md`
 - Batch prompt split: `references/batch-split-guide.md`
 - Batch prompt template: `references/batch-prompt-template.md`
 - Implementation orchestration: `references/orchestration.md`

package/assets/skills/superflow-pipeline/references/batch-prompt-template.md

@@ -181,6 +181,23 @@ Superpowers 技术详设复制 `外部枚举绑定确认` / `External Enum Bindi
 禁止用请求成功、值非空或字段存在替代外部枚举业务语义确认。未确认的外部枚举、
 支付来源、财务展示含义或兜底映射，必须停止并报告 `Blocked`。
 
+## 金额精度边界继承（强制）
+
+如果本批涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、
+服务费、套餐结算、比例分摊、明细分配、对账或财务展示，必须从 Superpowers
+技术详设复制 `Money Precision Boundary`。
+
+| 恒等式/权威总额 | 精确类型/构造 | 币种/渠道最小单位 | 舍入层级/mode/来源 | 分配策略/tie-breaker | 差额反推 | 审计证据 | 正负边界测试 |
+| ---------------- | ------------- | ----------------- | -------------------- | --------------------- | -------- | -------- | ------------ |
+| 原始=优惠+实付/原始金额 | BigDecimal/字符串 | CNY/最小单位 | 整单/HALF_UP/合同 | 最大余数/业务主键 | 实付=原始-优惠 | 舍入前后/尾差接收方 | 半分/尾差/退款 |
+
+中间计算不得提前舍入后继续切片、分摊、汇总或抵扣；多明细必须确定性处理尾差，
+并在 test-report.md 证明原始金额、优惠金额、实付金额和分配合计满足合同恒等式。
+存在权威总额时，只独立计算 N-1 个组成项，最后一个组成项按权威总额减去其余
+组成项合计差额反推；禁止所有组成项分别计算、分别舍入后重建总额。必须继承
+`money-precision-algorithms.md` 的币种单位、舍入来源、稳定排序、负数对称和条件性
+汇率合同。
+
 ## SDD 门禁激活（第一步，在所有编码工作之前执行）
 
 本机已配置 Codex Hooks，会在 Edit/Write 时自动拦截。你必须按以下顺序激活：

package/assets/skills/superflow-pipeline/references/implementation-prompt-template.md

@@ -148,6 +148,26 @@ Superpowers 技术详设复制 `外部枚举绑定确认` / `External Enum Bindi
 禁止用请求成功、值非空或字段存在替代外部枚举业务语义确认。未确认的外部枚举、
 支付来源、财务展示含义或兜底映射，必须停止并报告 `Blocked`。
 
+### 1.2 金额精度边界继承
+
+如果本批涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、
+服务费、套餐结算、比例分摊、明细分配、对账或财务展示，必须从 Superpowers
+技术详设复制 `Money Precision Boundary`，并在编码前填写：
+
+| 恒等式/权威总额 | 精确类型/构造 | 币种/内部与渠道单位 | 舍入层级/scale/mode/来源 | 分配策略/稳定 tie-breaker | 差额反推公式 | 舍入前后/尾差接收方 | 正数/零/退款测试 |
+| ---------------- | ------------- | ------------------- | ------------------------- | ------------------------- | ------------ | --------------------- | ---------------- |
+| 原始=优惠+实付/原始金额 | BigDecimal/字符串 | CNY/计算 scale/最小单位 | 整单/2/HALF_UP/合同 | 最大余数/业务主键 | 实付=原始-优惠 | \_\_\_\_ | TC-\_\_\_\_ |
+
+计算态必须保留原始费率、数量、乘积、比例和分配精度，只能在已确认的结算、
+持久化、支付、开票、导出或展示边界统一舍入。禁止先 `setScale(2)` 再继续切片、
+分摊、汇总、抵扣或反推单价。多明细分配必须确定性处理尾差，并证明原始金额、
+优惠金额、实付金额和分配合计满足合同恒等式。存在加法恒等式且总额是真源时，
+只能独立计算 N-1 个组成项，最后一个组成项必须按“权威总额减去其余组成项合计”
+差额反推；禁止所有组成项分别计算、分别舍入后再相加重建权威总额。缺少证据时
+停止并报告 `Blocked`。同时读取 `money-precision-algorithms.md`；禁止默认所有币种
+两位小数、从 `double` 构造金额或用数据库隐式舍入代替业务合同。汇率场景还要
+继承 base/quote、汇率来源与时间、唯一换算路径及目标结算单位。
+
 ### 2. 写入闭环
 
 凡本批涉及回填、落库、绑定、持久化、快照、同步、状态推进，必须填写：

package/assets/skills/superflow-pipeline/references/money-precision-algorithms.md

@@ -0,0 +1,85 @@
+# 金额精度算法基线
+
+金额正确性不是“统一保留两位小数”，而是表示、币种单位、计算、舍入、分配、
+汇率、存储和审计共同构成的合同。涉及金额的技术详设、实现提示、评审和验证必须
+应用本基线；若法律、财税、清算机构或支付渠道另有规则，以有证据的外部合同为准。
+
+## 1. 精确表示与单位
+
+- 计算态使用十进制精确类型（如 Java `BigDecimal`、JSR 354 `MonetaryAmount`）
+  或带明确币种的整数最小单位。禁止用二进制 `float`/`double` 表示或计算金额。
+- 从字符串、整数最小单位或精确数据库值构造十进制金额；禁止从 `double` 构造。
+- 每个金额合同必须携带币种、金额单位和 scale。不得假定所有币种都是两位小数；
+  同时区分 ISO 4217 小数位、内部计算 scale、结算 scale 和支付渠道最小单位。
+- 对外转换为整数最小单位时，只在适配器边界转换，并校验范围、溢出和渠道规则。
+- 数据库使用 `DECIMAL`/`NUMERIC`，代码、DDL、Mapper 和 API 的 precision/scale
+  必须一致。数据库写入时的隐式截断或舍入不能代替业务舍入合同。
+
+## 2. 舍入策略矩阵
+
+每个舍入点必须声明：业务层级（明细/订单/发票/支付/展示）、输入精度、输出
+scale、rounding mode、币种或现金最小增量、规则来源。禁止全局默认 `HALF_UP`，
+也禁止在同一恒等式中混用“逐行舍入”和“汇总后舍入”而没有对账规则。
+
+- 除法必须显式声明精度和 rounding mode；预期精确的运算可用 `UNNECESSARY`
+  作为断言，使非整除或意外舍入直接失败。
+- 中间费率、数量、乘积、比例和汇率保留计算精度，只在合同指定的结算边界舍入。
+- `CEILING`、`FLOOR` 等模式对负数含义不同；退款、冲正、负数分摊必须单独验证，
+  不能用正数用例推断。
+- 税额和发票必须冻结逐行或整单口径，只实现一个权威路径；若外部合同允许另一
+  口径，差异必须进入显式调节或对账规则。
+
+## 3. 权威总额与差额反推
+
+若合同存在 `总额 = 组成项 1 + ... + 组成项 N`，先识别权威总额。只独立计算
+N-1 个组成项，最后一项按 `权威总额 - 其余组成项合计` 差额反推。禁止所有组成
+项分别计算、分别舍入后相加重建权威总额。确实不适用时，必须记录真实权威来源和
+owner 证据。
+
+## 4. 比例分配与尾差
+
+比例分配必须先计算高精度理想份额，再量化到结算最小单位：
+
+1. 将权威总额转换为目标最小单位，得到必须守恒的整数总量。
+2. 计算各明细高精度理想份额及基础分配额。
+3. 计算 `剩余单位 = 权威总额单位 - 基础分配单位合计`。
+4. 每次分配一个最小单位，直到剩余为零。
+5. 明确确定性策略和稳定 tie-breaker（同余数时按业务主键等稳定字段排序）。
+
+默认优先使用最大余数法：按被截去余数从大到小补单位；退款或负数按相同绝对
+排序规则对称扣减。合同也可指定最大金额、最后一行等策略，但必须说明依据，不能
+依赖数据库自然顺序。必须验证合计守恒、顺序稳定、重复执行幂等。
+
+## 5. 汇率换算
+
+- 汇率是带方向的数据：记录 base/quote 币种、来源、时间点、有效期和精度。
+- 禁止提前截断或舍入汇率；存在权威方向汇率时，不用其倒数构造替代汇率。
+- 冻结唯一换算路径；跨币种中转使用合同指定的基准币种和顺序，最终仅在目标
+  结算边界按目标币种或渠道单位舍入。
+- 往返换算只能验证合同容差，不能当作精确恒等式。
+
+## 6. 审计与验证
+
+金额证据至少记录原始输入、公式/版本、币种与单位、舍入前值、舍入策略、舍入后
+值、尾差和尾差接收方；汇率场景另记录汇率元数据。测试至少覆盖正数、零、负数/
+退款、半最小单位、非整除、多明细、并列余数、极值/溢出和重复执行。
+
+核心不变量：
+
+- 权威总额始终等于组成项合计。
+- 分配结果始终等于目标结算金额。
+- 相同输入、策略版本和稳定排序始终产生相同结果。
+- 持久化、API 和支付渠道转换不会静默改变金额。
+
+## 官方依据
+
+- ISO 4217 currency codes：<https://www.iso.org/iso-4217-currency-codes.html>
+- JSR 354 Money and Currency API：<https://www.jcp.org/en/jsr/detail?id=354>
+- Java `BigDecimal`：<https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/math/BigDecimal.html>
+- MySQL exact-value `DECIMAL`：<https://dev.mysql.com/doc/refman/en/fixed-point-types.html>
+- PostgreSQL exact `numeric`：<https://www.postgresql.org/docs/15/datatype-numeric.html>
+- Stripe smallest currency unit：<https://docs.stripe.com/api/payment_intents/object>
+- Adyen currency minor units：<https://docs.adyen.com/development-resources/currency-codes/>
+- EU conversion and rounding rules：<https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A31997R1103>
+- HMRC VAT rounding：<https://www.gov.uk/hmrc-internal-manuals/vat-trader-records/vatrec12030>
+- SAP allocation residual strategies：<https://help.sap.com/docs/PRODUCT_ID/56471df1959f4cfd9e3bf7a6d2d5be42/56a2dfe71e8b2ea1e10000000a42189c.html>

package/assets/skills/superflow-pipeline/references/quality-gate.md

@@ -62,6 +62,7 @@
 | 44   | **上下文防漂移 handoff**           | **所有进入实现的任务强制**                                                              | `.sdd/handoff/sdd-context.md`、`.json`、`.sha256` 和 `.sdd/state.yaml` 已生成；design.md、sdd-quality-gate.md、prompt、test-report 记录同一 handoff_hash；`superflow-guard.sh <change-dir> docs` 通过                                                                                                                      |
 | 45   | **SDD 状态机字段**                 | **所有进入实现的任务强制**                                                              | `.sdd/state.yaml` 包含 workflow、phase、handoff_hash、build_mode、isolation、tdd_mode、review_mode、verify_mode、implementation_prompt、verification_report、archived；`superflow-state.sh status/next/recover` 输出一致                                                                                                   |
 | 46   | **外部枚举绑定确认**               | **涉及第三方、SDK、BEM/停车、支付退款、财务展示、来源字段、状态同步或外部字典时强制**   | api.md、sdd-quality-gate.md 和 Superpowers 技术详设包含 `外部枚举绑定确认` / `External Enum Binding`，列出 `业务字段                                                                                                                                                                                                       | 本系统真源字段/枚举 | 外部系统字段       | 外部枚举/字典值      | 展示文案/业务语义/财务语义 | 取值来源     | owner/确认时间                                                                                                | 不确定项/阻塞处理                                                                                                        | 测试证据`；不得用请求成功、值非空或字段存在替代业务语义确认；未确认时必须阻塞 |
+| 47   | **金额精度边界**                   | **涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、服务费、套餐结算、比例分摊、明细分配、对账或财务展示时强制** | Superpowers 技术详设包含 `Money Precision Boundary` 及金额恒等式、权威总额、独立计算项、差额反推项与公式、计算态来源、中间精度、舍入边界、scale/rounding mode、分配/对账规则、禁止提前舍入点和测试证据；存在加法恒等式且总额是真源时，最后一个组成项必须由权威总额减去其余组成项合计得到，禁止所有组成项分别计算和舍入后重建总额；测试必须覆盖半分、尾差或多明细分配场景 |
 
 ### 文档完整性强制检查（新增，全部项目必做）
 

package/assets/skills/superflow-pipeline/references/reviewer-checklist.md

@@ -133,12 +133,28 @@
 | 54 | 真实入口日志闭环 | 检查服务日志 | 从入口日志到业务校验、DB 查询、外部调用或异常返回有同一 trace/业务单号串联 |
 | 55 | 泛化失败归因 | 检查外部错误、业务日志和 DB 旁证 | 外部平台泛化失败时未直接写通过；已区分外部阻塞、合同漂移、代码异常 |
 
+## 金额精度检查
+
+| # | 检查项 | 检查方法 | 通过标准 |
+|---|--------|----------|----------|
+| 56 | 计算态与结算态分离 | 检查金额计算链和技术详设 | 最终边界前保留原始费率、数量、乘积和比例精度，未提前舍入后继续计算 |
+| 57 | 舍入边界明确 | 检查 `setScale`、`RoundingMode`、DB/API/展示转换 | 每个舍入点都有合同依据、scale 和 rounding mode，不存在隐式 double/float 精度损失 |
+| 58 | 分配与尾差确定性 | 检查比例分摊、明细拆分、退款和优惠分配 | 尾差按确定性规则落到明确明细，分配合计等于目标金额 |
+| 59 | 金额证据闭环 | 检查 tests.md 和 test-report.md | 覆盖半分、尾差或多明细场景，并证明原始金额、优惠金额、实付/退款金额及分配合计满足合同恒等式 |
+| 60 | 权威总额与恒等式 | 检查金额合同和真源证据 | 明确哪个总额是合同真源，以及总额与各组成项之间的加法恒等式；不适用时有真实真源和 owner 证据 |
+| 61 | 差额反推算法 | 检查金额组成项计算代码 | 存在权威总额时只独立计算 N-1 个组成项，最后一个组成项由权威总额减去其余组成项合计得到；未分别计算和舍入所有组成项后重建总额 |
+| 62 | 币种与最小单位 | 检查 DTO、适配器、支付渠道和数据库 | 未默认两位小数；内部 scale、ISO/渠道最小单位及转换边界明确，整数转换有溢出校验 |
+| 63 | 舍入策略来源 | 检查逐行/整单/发票/支付边界 | 每个舍入点有层级、scale、mode 和合同来源，未全局硬编码同一策略 |
+| 64 | 最大余数与稳定排序 | 检查多明细分配 | 高精度理想份额量化后逐最小单位分配尾差，同余数按稳定业务键排序，不依赖数据库自然顺序 |
+| 65 | 负数与退款对称性 | 检查退款、冲正和负数分摊 | 正数、零、负数/退款均有证据，明确 `CEILING`/`FLOOR` 等模式的符号差异 |
+| 66 | 汇率路径与元数据 | 检查跨币种换算 | base/quote、来源、时间、精度和唯一换算路径明确，只在目标结算边界舍入 |
+
 ## 检查记录格式
 
 ```
 批次评审报告：P{n} - {名称}
 
-检查项总数：55
+检查项总数：66
 通过：X 项
 未通过：X 项
 不适用：X 项

package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md

@@ -107,6 +107,52 @@ successful request, non-null value, or "field exists" proof is not enough. Do
 not invent numeric enum values, source/origin values, financial display
 semantics, fallback values, or compatibility mappings without owner approval.
 
+## Money Precision Boundary
+
+Use this whenever the change involves amount, fee, discount, deduction, refund,
+sharing, payment, invoice, balance, electricity fee, service fee, package
+settlement, proration, allocation, reconciliation, or financial display.
+
+| Amount identity | Authoritative total | Exact type/construction | Currency and unit | Calculation-state source | Rounding level/boundary | Scale/mode/source | Allocation strategy/tie-breaker | Complement derivation | Audit evidence | Test evidence |
+| --------------- | ------------------- | ----------------------- | ----------------- | ------------------------ | ----------------------- | ----------------- | ------------------------------- | --------------------- | -------------- | ------------- |
+| `original = discount + actual` | `original` | `<BigDecimal from string>` | `<CNY; internal scale; provider minor unit>` | `<rate * quantity>` | `<order/payment adapter>` | `<2/HALF_UP/contract>` | `<largest remainder/business key>` | `actual = original - discount` | `<pre/post round; residual recipient>` | `<positive/zero/refund/half-unit/tied residual IDs>` |
+
+Use `money-precision-algorithms.md` to complete the contract. State the exact
+decimal representation and construction source; currency and ISO/provider
+minor-unit boundary; rounding level, mode, and policy source; deterministic
+residual strategy and stable tie-breaker; negative/refund symmetry; persistence
+precision/scale and overflow checks. Never assume every currency has two
+decimal places or use database implicit conversion as the rounding policy.
+
+For FX changes, additionally record:
+
+| Base/quote | Rate source/time | Rate precision | Canonical path | Target unit/rounding | Round-trip tolerance | Evidence |
+| ---------- | ---------------- | -------------- | -------------- | -------------------- | -------------------- | -------- |
+| `<base/quote>` | `<source/timestamp>` | `<scale>` | `<direct/triangulated order>` | `<currency/provider rule>` | `<contract tolerance>` | `<case IDs>` |
+
+Required precision checks:
+
+```bash
+rg -ni "setScale|round|RoundingMode|BigDecimal|double|float|money\\(" <source-and-test-paths>
+rg -ni "amount|fee|price|discount|deduction|refund|pay|invoice|balance|serviceFee|chargeFee" <source-and-test-paths>
+```
+
+The design must separate calculation-state money from settlement/display-state
+money. Intermediate calculations must keep original rate, product, proportion,
+process evidence, and allocation precision. Round only at explicit outbound
+boundaries such as settlement posting, persistence fields that require cents,
+payment/fiscal interfaces, invoices, exports, or display. For multi-detail
+allocation, compute the high-precision target first, then distribute the final
+rounded amount deterministically so totals match and identities such as
+`original = discount + actual` hold. When an additive identity exists and its
+total is the authoritative source, calculate only the required N-1 components
+independently and derive the final complement as `authoritative total - sum(other
+components)`. Do not independently calculate and round every component and then
+rebuild the authoritative total. If complement derivation is not applicable,
+record why, identify the actual source of truth, and provide owner evidence.
+Do not calculate later slices, discounts, ratios, or unit prices from
+already-rounded money.
+
 ## Execution Architecture
 
 - Worker boundaries:
@@ -144,6 +190,9 @@ semantics, fallback values, or compatibility mappings without owner approval.
   that only shows "can call through this module" is not ready.
 - For field/status changes, prove reverse impact before coding: writers,
   readers, filters, derived sync paths, external consumers, and tests.
+- For money changes, prove the precision boundary before coding: calculation
+  state, settlement/display state, final rounding point, allocation rule, and
+  half-cent/residual tests.
 - Do not invent API fields, DB columns, status semantics, fallback behavior, or
   acceptance criteria.
 - Keep unresolved source facts as blockers. Do not convert them to guesses.

package/assets/skills/superflow-pipeline/references/test-execution-template.md

@@ -98,6 +98,22 @@ Controller、mock endpoint、绕过鉴权端点只能填写 `Mock only` 或 `测
 HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are skipped`
 都不能单独作为接口通过证据。
 
+## 4.4 金额精度边界证据
+
+涉及金额计算、结算、比例分摊、明细分配、优惠抵扣、退款、支付、开票或财务展示时
+必须填写：
+
+| 用例 ID | 恒等式/权威总额 | 币种/最小单位 | 差额反推 | 舍入前/后 | 策略/尾差接收方 | 正数/零/退款/并列余数 | 对账结论 |
+| ------- | ---------------- | ------------- | -------- | ----------- | ----------------- | --------------------- | -------- |
+| TC-M01  | 原始=优惠+实付/原始金额 | CNY/分 | 实付=原始-优惠 | ____/____ | 最大余数/____ | ____ | 一致/阻塞 |
+
+必须证明计算态在最终边界前未提前舍入，并证明原始金额、优惠金额、实付金额、退款金额
+或分配合计满足设计合同。存在权威总额时，还必须证明最后一个组成项确实由权威总额
+减去其余组成项合计得到，而不是所有组成项分别计算和舍入。只验证最终展示两位
+小数，不足以证明金额精度正确。证据还必须包含币种、渠道最小单位、舍入前值、
+舍入后值、尾差接收方，以及正数、零、负数/退款、并列余数和幂等验证。汇率场景
+另附 base/quote、汇率来源和目标结算舍入证据。
+
 ## 5. 详细结果
 
 ### 5.1 通过的测试

package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh

@@ -259,6 +259,28 @@ change_has_external_enum_risk() {
     "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
 }
 
+change_has_money_precision_risk() {
+  grep -RIEiq \
+    '金额|费用|价格|优惠|折扣|抵扣|退款|分账|支付|发票|余额|电费|服务费|套餐结算|比例分摊|明细分配|尾差|精度|舍入|(^|[^[:alnum:]_])(amount|fee|fees|price|discount|deduction|refund|payment|invoice|balance|proration|allocation|reconciliation|rounding)([^[:alnum:]_]|$)|revenue sharing|profit sharing|split payment|serviceFee|chargeFee|totalAmount|actualAmount|payAmount|refundAmount|discountAmount|invoiceAmount|balanceAmount' \
+    "$CHANGE_DIR/proposal.md" \
+    "$CHANGE_DIR/api.md" \
+    "$CHANGE_DIR/design.md" \
+    "$CHANGE_DIR/tests.md" \
+    "$CHANGE_DIR/spec.md" \
+    "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
+}
+
+change_has_fx_precision_risk() {
+  grep -RIEiq \
+    '汇率|换汇|外汇|币种转换|跨币种|兑换率|(^|[^[:alnum:]_])(exchange rate|fx rate|currency conversion|cross.currency|base currency|quote currency)([^[:alnum:]_]|$)' \
+    "$CHANGE_DIR/proposal.md" \
+    "$CHANGE_DIR/api.md" \
+    "$CHANGE_DIR/design.md" \
+    "$CHANGE_DIR/tests.md" \
+    "$CHANGE_DIR/spec.md" \
+    "$CHANGE_DIR"/specs/*/spec.md 2>/dev/null
+}
+
 change_has_architecture_boundary_risk() {
   grep -RIEiq \
     '跨仓|跨服务|sibling|SDK|MQ|topic|consumer|scheduler|定时|device|设备|callback|回调|third[- ]party|第三方|mini[- ]program|小程序|gateway|网关|adapter|适配|protocol|协议|interconnect|互联互通|调用链|入口|出口' \
@@ -303,6 +325,60 @@ require_external_enum_contract() {
   require_grep '不确定|阻塞|blocker|unknown|待确认' "$path" "$label unresolved/blocker column"
 }
 
+require_money_precision_contract() {
+  local path="$1"
+  local label="$2"
+  require_grep 'Money Precision Boundary|金额精度边界' "$path" "$label"
+  require_grep '计算态|calculation.state|calculation source|intermediate precision' "$path" "$label calculation state"
+  require_grep '结算态|展示态|settlement|display.state|rounding boundary' "$path" "$label settlement/display boundary"
+  require_grep 'scale|rounding mode|RoundingMode|舍入模式' "$path" "$label scale and rounding mode"
+  require_grep '分配|对账|allocation|reconciliation|residual|尾差' "$path" "$label allocation/reconciliation rule"
+  require_grep '权威总额|真源总额|authoritative total|source.of.truth total' "$path" "$label authoritative total"
+  require_grep '差额反推|总额.*减|authoritative total.*minus|derive.*complement|complement amount' "$path" "$label complement derivation"
+  require_grep '禁止.*分别计算|不得.*分别计算|禁止.*独立.*舍入|do not.*independently|must not.*calculate.*separately' "$path" "$label independent calculation prohibition"
+  require_grep '禁止提前舍入|不得提前.*舍入|forbidden early rounding|do not.*round' "$path" "$label forbidden early rounding"
+  require_grep '半分|尾差|多明细|half.cent|residual|multi.detail' "$path" "$label boundary test evidence"
+  require_grep 'BigDecimal|MonetaryAmount|整数最小单位|integer minor unit|exact decimal' "$path" "$label exact representation"
+  require_grep '禁止.*(float|double)|不得.*(float|double)|never.*(float|double)|do not.*(float|double)' "$path" "$label binary floating-point prohibition"
+  require_grep '币种|currency' "$path" "$label currency contract"
+  require_grep '最小单位|minor unit|provider unit|渠道单位' "$path" "$label minor-unit boundary"
+  require_grep '舍入层级|舍入点|rounding level|rounding point|明细.*整单|line.level.*aggregate' "$path" "$label rounding level"
+  require_grep '规则来源|合同依据|policy source|contract source' "$path" "$label rounding policy source"
+  require_grep '最大余数|largest remainder|稳定.*排序|stable tie.break|业务主键' "$path" "$label deterministic residual tie-breaker"
+  require_grep '正数.*零.*负数|正数.*退款|positive.*zero.*negative|positive.*refund' "$path" "$label signed-value evidence"
+  require_grep '舍入前.*舍入后|pre.round.*post.round' "$path" "$label rounding audit evidence"
+  require_grep 'DECIMAL|NUMERIC|数据库.*不适用|持久化.*不适用|persistence.*not applicable' "$path" "$label persistence precision contract"
+  if change_has_fx_precision_risk; then
+    require_grep 'base/quote|基础币种.*目标币种|基准币种.*报价币种' "$path" "$label FX direction"
+    require_grep '汇率来源|rate source' "$path" "$label FX source"
+    require_grep '汇率.*时间|rate.*timestamp|rate.*effective' "$path" "$label FX timestamp"
+    require_grep '唯一换算路径|权威换算路径|canonical conversion path|canonical path' "$path" "$label FX canonical path"
+    require_grep '目标.*结算.*舍入|target.*settlement.*round' "$path" "$label FX target rounding"
+  fi
+}
+
+require_money_precision_evidence() {
+  local path="$1"
+  local label="$2"
+  require_grep 'Money Precision Boundary|金额精度边界' "$path" "$label"
+  require_grep '半分|尾差|多明细|half.cent|residual|multi.detail' "$path" "$label boundary cases"
+  require_grep '原始金额|优惠金额|实付金额|分配合计|对账|original.*discount.*actual|allocated total|reconciliation' "$path" "$label reconciliation evidence"
+  require_grep '权威总额|真源总额|authoritative total' "$path" "$label authoritative total evidence"
+  require_grep '差额反推|总额.*减|authoritative total.*minus|derive.*complement|complement amount' "$path" "$label complement derivation evidence"
+  require_grep '币种|currency' "$path" "$label currency evidence"
+  require_grep '最小单位|minor unit|provider unit|渠道单位' "$path" "$label minor-unit reconciliation"
+  require_grep '正数.*零.*负数|正数.*退款|positive.*zero.*negative|positive.*refund' "$path" "$label signed-value cases"
+  require_grep '舍入前.*舍入后|pre.round.*post.round' "$path" "$label rounding audit evidence"
+  require_grep '尾差接收方|residual recipient' "$path" "$label residual audit evidence"
+  require_grep '并列余数|tied remainder' "$path" "$label tied-residual cases"
+  require_grep '幂等|idempoten' "$path" "$label allocation idempotence"
+  if change_has_fx_precision_risk; then
+    require_grep 'base/quote|基础币种.*目标币种|基准币种.*报价币种' "$path" "$label FX direction evidence"
+    require_grep '汇率来源|rate source' "$path" "$label FX source evidence"
+    require_grep '目标.*结算.*舍入|target.*settlement.*round' "$path" "$label FX target rounding evidence"
+  fi
+}
+
 transition_event=""
 
 if [[ -x "$VALIDATE" && -f "$CHANGE_DIR/.sdd/state.yaml" ]]; then
@@ -336,6 +412,9 @@ case "$PHASE" in
       require_external_enum_contract api.md "external enum binding contract"
       require_external_enum_contract sdd-quality-gate.md "external enum binding quality gate"
     fi
+    if change_has_money_precision_risk; then
+      require_grep 'Money Precision Boundary|金额精度边界' sdd-quality-gate.md "money precision quality gate"
+    fi
     require_markdown_links_valid
     transition_event="docs-complete"
     ;;
@@ -371,6 +450,9 @@ case "$PHASE" in
         if change_has_external_enum_risk; then
           require_external_enum_contract "$technical_design_rel" "external enum binding matrix"
         fi
+        if change_has_money_precision_risk; then
+          require_money_precision_contract "$technical_design_rel" "money precision boundary"
+        fi
       fi
     fi
     require_grep 'Superpowers Technical Design Handoff|Superpower 技术详设|technical_design|源码级 HOW' design.md "Superpowers technical design handoff"
@@ -399,6 +481,9 @@ case "$PHASE" in
         if change_has_external_enum_risk; then
           require_external_enum_contract "$prompt_rel" "prompt external enum binding inheritance"
         fi
+        if change_has_money_precision_risk; then
+          require_money_precision_contract "$prompt_rel" "prompt money precision inheritance"
+        fi
       fi
       require_grep '上下文防漂移|handoff_hash|sdd-context' "$prompt_rel" "prompt context drift inheritance"
     fi
@@ -427,6 +512,9 @@ case "$PHASE" in
     if change_has_external_enum_risk; then
       require_grep 'External Enum Binding|外部枚举绑定|第三方字段语义绑定|外部展示|展示文案|业务语义|财务语义|BEM|真实入口' test-report.md "external enum binding runtime evidence"
     fi
+    if change_has_money_precision_risk; then
+      require_money_precision_evidence test-report.md "money precision runtime evidence"
+    fi
     require_test_report_lint
     require_markdown_links_valid
     if [[ "$(state_get verification_report)" == "" || "$(state_get verification_report)" == "null" ]]; then

package/assets/skills/superflow-verify/SKILL.md

@@ -43,6 +43,16 @@ Use `.sdd/state.yaml` `verify_mode` after `scale`.
 prove the complete evidence chain: source/Mapper/XML, DB when needed, real
 entry point, interface automation, logs, SQL sync, and consumer behavior.
 
+Money-related changes always require full verification of
+`Money Precision Boundary`: original calculation inputs and intermediate precision, the actual
+rounding boundary and mode, half-cent/residual/multi-detail cases, deterministic
+allocation, and reconciliation identities. A final two-decimal display value
+or unit-test-only evidence is not sufficient.
+For additive identities, verification must prove which total was authoritative,
+which N-1 components were calculated independently, and which final complement
+was derived as `authoritative total - sum(other components)`. Evidence that all
+components were independently calculated and rounded is a failure.
+
 ## Required Superpowers
 
 Immediately load and apply these Superpowers when available:
@@ -94,7 +104,12 @@ Before pass:
    delivery or branch closeout.
 5. Code review findings are either fixed or explicitly recorded with accepted
    risk.
-6. Branch/worktree status is handled and `.sdd/state.yaml` has:
+6. For money-related changes, `test-report.md` records the `Money Precision
+   Boundary` cases and proves original, discount, actual/refund, and allocated
+   totals reconcile without early rounding. For additive identities it also
+   records the authoritative total and the subtraction used to derive the final
+   complement.
+7. Branch/worktree status is handled and `.sdd/state.yaml` has:
    `branch_status: handled`.
 
 Only then run: