@chenmk/superflow 0.2.3 → 0.2.5

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.3",
+  "version": "0.2.5",
   "description": "SuperBridge Flow workflow CLI for Claude Code, Codex, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,7 @@
   },
   "files": [
     "dist",
+    "scripts",
     "assets",
     "README.md",
     "README.zh-CN.md",
@@ -36,6 +37,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/cli/index.ts",
+    "postinstall": "node scripts/postinstall.js",
     "prepack": "npm run build",
     "prepublishOnly": "npm test && npm run build",
     "test": "vitest run",

package/scripts/postinstall.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkgPath = join(__dirname, '..', 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+const LANGUAGE_ZH = 'zh';
+const LANGUAGE_EN = 'en';
+
+export function isGlobalInstall(env = process.env) {
+  return env.npm_config_global === 'true';
+}
+
+export function resolveInstallLanguage(env = process.env) {
+  const lang = env.SUPERFLOW_LANG || env.LC_ALL || env.LANG || '';
+  const normalized = lang.toLowerCase();
+  if (normalized.includes('zh') || normalized.includes('cn')) return LANGUAGE_ZH;
+  if (normalized.includes('en')) return LANGUAGE_EN;
+  return LANGUAGE_ZH;
+}
+
+export function buildInstallMessage(version, language) {
+  if (language === LANGUAGE_ZH) {
+    return [
+      `✅ @chenmk/superflow v${version} 安装成功`,
+      '',
+      '   快速开始：',
+      '     superflow init              # 在当前项目初始化',
+      '     superflow --help            # 查看全部命令',
+    ].join('\n');
+  }
+  return [
+    `✅ @chenmk/superflow v${version} installed successfully`,
+    '',
+    '   Quick start:',
+    '     superflow init              # Initialize in current project',
+    '     superflow --help            # Show all commands',
+  ].join('\n');
+}
+
+function printInstallMessage(version, language) {
+  console.log(buildInstallMessage(version, language));
+}
+
+export function runPostinstall(env = process.env) {
+  if (!isGlobalInstall(env)) return;
+  printInstallMessage(pkg.version, resolveInstallLanguage(env));
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runPostinstall();
+}