@chenmk/superflow 0.2.4 → 0.2.5

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:

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

@@ -57,12 +57,31 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 6. For field/status/enum/sync changes, include `Field And Status Reverse
    Impact` and prove writers, readers, filters, derived sync paths, consumers,
    and tests. Direct setter-only design is blocked.
-7. Record state:
+7. 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.
+8. 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
    ```
-8. Update `design.md` with `Superpowers Technical Design Handoff`, update
+9. 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
@@ -70,7 +89,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    `--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.
-9. Run:
+10. Run:
    ```bash
    ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>
    ../superflow-pipeline/scripts/superflow-guard.sh <change-dir> design --apply

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

@@ -76,6 +76,17 @@ For complex requirements, verify these before writing docs:
   If the docs only prove that a value exists, is non-null, or lets the request
   succeed, stop and return to `$superflow-clarify`. If fallback/default/keep-old-value
   behavior is proposed without explicit requirement or owner approval, stop.
+- 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
@@ -293,6 +304,11 @@ Use references only as needed:
   `RED failure evidence`, `GREEN pass evidence`, `interface automation evidence`, `DB evidence`,
   `log evidence`, `manual/blocking cases`, and `Partially verified boundary`.
   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-en/superflow-implement/SKILL.md

@@ -60,6 +60,14 @@ Every implementation prompt must include these sections:
   DTO, converter, SQL, scheduled job, MQ, callback, and sibling repo references.
 - Field semantic contract: source field, source meaning, target field, target
   meaning, equivalence, evidence anchor, forbidden usage, and owner for unknowns.
+- Money precision boundary when monetary behavior changes: calculation-state
+  source and intermediate precision, settlement/display boundary, scale and
+  rounding mode, forbidden early rounding, deterministic residual allocation,
+  authoritative total, complement derivation as `authoritative total -
+  sum(other components)`, and half-cent or multi-detail reconciliation evidence.
+  It also inherits `money-precision-algorithms.md`: exact representation,
+  currency/provider minor units, rounding policy source, stable residual
+  tie-breaker, signed-value evidence, and conditional FX metadata.
 - Write-loop verification: business action, setter/assignment, converter, mapper
   insert/update, DB column, downstream reader, consumer entry, SQL check, test
   case.
@@ -99,6 +107,8 @@ Block prompt generation or execution when any of these are missing:
 - handoff files and matching hash;
 - technical_design for full workflow;
 - field/status reverse impact matrix when risky fields or states are touched;
+- money precision boundary when monetary calculation, settlement, allocation,
+  reconciliation, or financial display is touched;
 - architecture boundary and call-direction matrix for cross-service or external
   flows;
 - executable tests.md commands for L3/L4 or real-entry requirements;

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

@@ -120,6 +120,15 @@ The workflow must preserve these gates:
   removal rules.
 - Field/status reverse impact analysis for IDs, statuses, enums, payment,
   online/offline, sync markers, external state, or persisted behavior.
+- Money Precision Boundary for monetary calculation, settlement, allocation,
+  reconciliation, or financial display. Preserve calculation-state precision
+  until the confirmed final boundary, forbid early rounding, define scale and
+  rounding mode plus deterministic residual handling, and require half-cent or
+  multi-detail reconciliation evidence across design, prompts, review, tests,
+  and verify. When an additive identity has an authoritative total, calculate
+  only N-1 components independently and derive the final complement as
+  `authoritative total - sum(other components)`; never round every component
+  independently and rebuild the authoritative total.
 - Architecture boundary and call-direction analysis for multi-repo, service,
   SDK, MQ, scheduler, callback, gateway, adapter, device, or third-party flows.
 - SQL risk review before implementation for DB changes.
@@ -169,3 +178,4 @@ Use the reference files in this skill directory as templates:
 - references/dirty-worktree.md
 - references/subagent-progress.md
 - references/superpower-technical-design-template.md
+- references/money-precision-algorithms.md

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

@@ -24,6 +24,16 @@ review-checklist.md, sdd-quality-gate.md, test-report.md, and technical design.
 - Do not change forbidden files or root aggregate docs from a worker batch.
 - Use TDD: record RED failure before GREEN success.
 - Do not mark mock-only or unit-only evidence as real integration.
+- For monetary changes, inherit `Money Precision Boundary`, retain
+  calculation-state precision until the confirmed settlement/display boundary,
+  record scale and rounding mode, forbid early rounding before slicing or
+  allocation, and define deterministic residual handling. For additive
+  identities, calculate only N-1 components independently and derive the final
+  complement as `authoritative total - sum(other components)`; do not calculate
+  and round every component independently.
+- Inherit `money-precision-algorithms.md`: exact decimal construction, currency
+  and provider minor units, rounding policy source, deterministic residual
+  tie-breaker, signed-value tests, and conditional FX conversion metadata.
 
 ## Implementation Steps
 
@@ -44,5 +54,7 @@ log check, and hook commands.
 - Real-entry evidence
 - DB/log evidence
 - Hook evidence
+- Money precision evidence: half-cent/residual/multi-detail cases and
+  reconciliation of original, discount, actual, and allocated totals
 - Deviations
 - Blockers

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

@@ -23,6 +23,18 @@ Superpowers technical design is canonical for source-level HOW and execution.
 - Field semantic contract checked.
 - Write-loop checked.
 - No-fallback boundary confirmed.
+- Money Precision Boundary copied from the technical design when monetary
+  behavior changes. Keep calculation-state precision until the confirmed
+  settlement/display boundary, record scale and rounding mode, forbid early
+  rounding, and define deterministic residual allocation. For additive
+  identities, name the authoritative total, calculate only N-1 components
+  independently, and derive the complement as `authoritative total - sum(other
+  components)`. Do not calculate and round every component independently.
+- Read `money-precision-algorithms.md`; inherit exact decimal construction,
+  currency and provider minor units, rounding level/mode/policy source,
+  residual strategy and stable tie-breaker, pre/post-round audit, and
+  positive/zero/negative tests. FX changes also inherit base/quote metadata,
+  rate source/time, canonical path, and target settlement rounding.
 - RED test executed.
 - Allowed and forbidden files confirmed.
 - Blockers listed.
@@ -32,3 +44,7 @@ Superpowers technical design is canonical for source-level HOW and execution.
 Do not claim completion until build/test, real-entry execution, DB/log evidence,
 test-report update, and SuperBridge Flow hook scripts pass or are marked blocked
 with concrete reasons.
+
+For monetary changes, completion also requires half-cent, residual, or
+multi-detail allocation tests and reconciliation evidence proving that original,
+discount, actual, and allocated totals satisfy the contract identities.

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

@@ -0,0 +1,96 @@
+# Money Precision Algorithm Baseline
+
+Money correctness is a contract across representation, currency units,
+calculation, rounding, allocation, FX, persistence, and audit. Apply this
+baseline to monetary design, implementation prompts, review, and verification.
+An evidenced legal, tax, settlement, or provider contract takes precedence.
+
+## Exact representation and units
+
+- Use an exact decimal type such as Java `BigDecimal`, JSR 354
+  `MonetaryAmount`, or integer minor units coupled with an explicit currency.
+  Never represent or calculate money with binary `float` or `double`.
+- Construct decimals from strings, exact integers, or exact database values,
+  never from a `double`.
+- Every amount contract declares currency, unit, and scale. Never assume two
+  decimal places. Distinguish ISO 4217 minor units, internal calculation scale,
+  settlement scale, and provider-specific minor units.
+- Convert to integer minor units only at an adapter boundary, with provider
+  rule, range, and overflow checks.
+- Persist money as `DECIMAL` or `NUMERIC`. Code, DDL, mapper, and API
+  precision/scale must agree. Implicit database conversion is not a business
+  rounding policy.
+
+## Rounding policy matrix
+
+Every rounding point declares its business level, input precision, output
+scale, rounding mode, currency or cash increment, and policy source. Do not
+apply global `HALF_UP`, or mix line-level and aggregate-level rounding inside
+one identity without an explicit reconciliation rule.
+
+- Division declares precision and rounding mode. Use `UNNECESSARY` as an
+  assertion where an exact result is required.
+- Retain rate, quantity, product, ratio, and FX precision until a contracted
+  settlement boundary.
+- Negative values change the meaning of modes such as `CEILING` and `FLOOR`.
+  Test refunds and reversals explicitly instead of inferring from positives.
+- Freeze either line-level or invoice-level tax rounding as the authoritative
+  path. Route any permitted alternative through an explicit adjustment rule.
+
+## Authoritative totals and complement derivation
+
+For `total = component 1 + ... + component N`, identify the authoritative
+total, calculate only N-1 components independently, and derive the final
+component as `authoritative total - sum(other components)`. Never calculate and
+round all components independently and then rebuild the authoritative total.
+
+## Allocation and residual units
+
+Calculate high-precision ideal shares, then quantize at the settlement unit:
+
+1. Express the authoritative target in integer settlement units.
+2. Calculate ideal shares and base allocations.
+3. Compute `residual units = target units - sum(base allocation units)`.
+4. Assign one unit at a time until the residual reaches zero.
+5. Use a declared strategy and stable tie-breaker such as a business key.
+
+Prefer the largest-remainder method for neutral proportional allocation. Apply
+the same absolute ordering symmetrically to refunds and negative totals.
+Largest-value or last-row policies are allowed only when the contract requires
+them. Never depend on database natural order. Prove conservation, stable order,
+and idempotence.
+
+## FX conversion
+
+- Treat an FX rate as directional data with base/quote currencies, source,
+  timestamp, validity, and precision.
+- Never truncate or round the rate early. Do not synthesize an inverse when a
+  canonical directional rate exists.
+- Freeze one conversion path. For triangulation, use the contracted reference
+  currency and operation order, then round only at the target settlement unit.
+- Round-trip conversion is a tolerance check, not an exact identity.
+
+## Audit and verification
+
+Record raw inputs, formula/version, currency/unit, pre-round value, policy,
+post-round value, residual, and residual recipient. Record FX metadata when
+applicable. Test positive, zero, negative/refund, half-unit, non-terminating
+division, multi-detail, tied remainders, overflow, and repeated execution.
+
+Required invariants: authoritative total equals component sum; allocations
+equal the settlement target; identical inputs, policy version, and stable order
+produce identical outputs; persistence, API, and provider conversions do not
+silently change money.
+
+## Primary references
+
+- ISO 4217: <https://www.iso.org/iso-4217-currency-codes.html>
+- JSR 354: <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 `DECIMAL`: <https://dev.mysql.com/doc/refman/en/fixed-point-types.html>
+- PostgreSQL `numeric`: <https://www.postgresql.org/docs/15/datatype-numeric.html>
+- Stripe minor units: <https://docs.stripe.com/api/payment_intents/object>
+- Adyen minor units: <https://docs.adyen.com/development-resources/currency-codes/>
+- EU conversion 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 residuals: <https://help.sap.com/docs/PRODUCT_ID/56471df1959f4cfd9e3bf7a6d2d5be42/56a2dfe71e8b2ea1e10000000a42189c.html>

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

@@ -16,6 +16,15 @@
 - Field/status reverse impact matrix exists when risky fields or states change.
 - Architecture boundary and call-direction matrix exists for cross-service or
   external flows.
+- Money precision boundary exists when amount, fee, discount, deduction,
+  refund, sharing, payment, invoice, balance, electricity fee, service fee,
+  package settlement, proration, allocation, reconciliation, or financial
+  display changes. It must separate calculation state from settlement/display
+  state, forbid early rounding, and include half-cent, residual, or
+  multi-detail allocation evidence. For additive identities, it must name the
+  authoritative total and derive the final complement as `authoritative total -
+  sum(other components)` instead of calculating and rounding every component
+  independently.
 - SQL risk review exists for DB changes.
 - No fallback or guesswork is allowed without explicit owner approval.
 

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

@@ -5,6 +5,21 @@
 - Is handoff_hash current and repeated in prompts/report?
 - Did Superpowers technical design cover source-level HOW?
 - Were field/status and architecture-boundary risks checked?
+- For monetary changes, were calculation and settlement states separated, were
+  scale and rounding mode explicit, and was early rounding rejected?
+- Do half-cent, residual, and multi-detail tests prove deterministic allocation
+  and reconciliation of original, discount, actual/refund, and allocated totals?
+- For additive identities, is the authoritative total explicit, with only N-1
+  components calculated independently and the final complement derived as
+  `authoritative total - sum(other components)`?
+- Reject designs that calculate and round every component independently before
+  rebuilding an authoritative total.
+- Are exact decimal construction, currency and provider minor units, rounding
+  level/policy source, and persistence precision explicit?
+- Does allocation use a declared residual strategy and stable tie-breaker, with
+  positive, zero, negative/refund, tied-remainder, and idempotence evidence?
+- For FX, are base/quote, source/time, canonical path, and target settlement
+  rounding explicit, without early rate rounding or synthesized inverses?
 - Are SQL changes reviewed and tied to total version SQL when needed?
 - Are RED/GREEN evidence and real-entry evidence present?
 - Are mock-only results clearly labeled?

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

@@ -83,6 +83,52 @@ third-party adapters, and sibling repos when the table or DTO is shared.
 The technical design must say which references are intentionally unchanged and
 why. A change is not ready when only the direct setter/writer is designed.
 
+## 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>` | `<currency; internal scale; provider minor unit>` | `<rate * quantity>` | `<order/payment adapter>` | `<scale/mode/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 exact
+representation and construction; currency and ISO/provider minor-unit boundary;
+rounding level, mode, and policy source; residual strategy and stable
+tie-breaker; negative/refund symmetry; persistence precision/scale and overflow
+checks. Never assume every currency has two decimals or treat implicit database
+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:
@@ -119,6 +165,9 @@ why. A change is not ready when only the direct setter/writer is designed.
   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-en/superflow-pipeline/references/test-execution-template.md

@@ -20,3 +20,21 @@
 - Result:
 - Evidence:
 - Blocker if not executed:
+
+## Money Precision Boundary Evidence
+
+Required when monetary calculation, settlement, proration, allocation,
+reconciliation, or financial display changes:
+
+| Case | Identity/authoritative total | Currency/minor unit | Complement | Pre/post round | Strategy/residual recipient | Positive/zero/refund/tied residual | Reconciliation |
+|---|---|---|---|---|---|---|---|
+| TC-M01 | `original = discount + actual` / `original` | CNY/minor unit | `actual = original - discount` | | largest remainder / | | pass/blocked |
+
+Prove that calculation-state values were not rounded before the confirmed final
+boundary and that original, discount, actual, refund, and allocated totals obey
+the design contract. When an authoritative total exists, prove the final
+component was derived by subtraction instead of independently calculated and
+rounded. Record currency, provider minor unit, pre/post-round values, residual
+recipient, and positive/zero/negative or refund, tied remainder, and idempotent
+recalculation evidence. FX cases also record base/quote, rate source, and target
+settlement rounding. A two-decimal display assertion alone is insufficient.

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

@@ -248,6 +248,28 @@ change_has_field_status_risk() {
     "$CHANGE_DIR"/*.md "$CHANGE_DIR"/**/*.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|residual|precision|rounding)([^[:alnum:]_]|$)|revenue sharing|profit sharing|split payment|electricity fee|service fee|package settlement|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 \
     'cross-repo|cross-service|sibling|SDK|MQ|topic|consumer|scheduler|scheduled|device|callback|third[- ]party|mini[- ]program|gateway|adapter|protocol|interconnect|call chain|entry|exit' \
@@ -281,6 +303,60 @@ require_prompt_set() {
   fi
 }
 
+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 '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|business key' "$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|base currency.*quote currency' "$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|base currency.*quote currency' "$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
@@ -310,6 +386,9 @@ case "$PHASE" in
     require_grep 'RED|red-green|GREEN' tests.md "RED/GREEN test contract"
     require_grep 'curl|Postman|Newman|pytest|RestAssured|automation command' tests.md "interface automation command"
     require_grep 'handoff_hash|sdd-context|context package|anti-drift' sdd-quality-gate.md "handoff/context-drift gate"
+    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"
     ;;
@@ -342,6 +421,9 @@ case "$PHASE" in
         if change_has_field_status_risk; then
           require_grep 'Field And Status Reverse Impact|Field And Status Reverse Impact|write point.*read|read/filter points|derived/sync points' "$technical_design_rel" "field/status reverse impact 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|Superpowers Technical Design|technical_design|source-level HOW' design.md "Superpowers technical design handoff"
@@ -367,6 +449,9 @@ case "$PHASE" in
         if change_has_field_status_risk; then
           require_grep 'Field And Status Reverse Impact|Field And Status Reverse Impact|read/filter points|derived/sync points' "$prompt_rel" "prompt field/status reverse impact inheritance"
         fi
+        if change_has_money_precision_risk; then
+          require_money_precision_contract "$prompt_rel" "prompt money precision inheritance"
+        fi
       fi
       require_grep 'context anti-drift|handoff_hash|sdd-context' "$prompt_rel" "prompt context drift inheritance"
     fi
@@ -392,6 +477,9 @@ case "$PHASE" in
     require_grep 'interface automation|curl|Postman|Newman|pytest|RestAssured' test-report.md "interface automation evidence"
     require_grep 'DB|database|SELECT|SHOW CREATE' test-report.md "DB evidence"
     require_grep 'superflow-verify-integration|superflow-delivery-check|superflow-test-report-lint' test-report.md "SuperBridge Flow hook/script evidence"
+    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-en/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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenmk/superflow",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "SuperBridge Flow workflow CLI for Claude Code, Codex, and OpenCode",
   "license": "MIT",
   "type": "module",