@chenmk/superflow 0.2.4 → 0.3.0

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

@@ -14,6 +14,10 @@ do not mark archived until the user confirms final closeout.
 - `phase: archive`.
 - `verify_result: pass`.
 - `verification_report` points to an existing report.
+- Every checkbox in `tasks.md` is checked.
+- The verification report contains `Verification Result: PASS` and
+  `Archive Readiness: PASS`.
+- `branch_status: handled` and `verified_at` are recorded.
 - `superflow-state.sh recover <change-dir>` gives a coherent archive recovery action.
 
 ## Procedure
@@ -42,6 +46,8 @@ do not mark archived until the user confirms final closeout.
   the user explicitly accepts the boundary.
 - Do not use archive to hide missing API, DB, hook, SQL, test-report, or real
   integration evidence.
+- Never call `openspec archive` directly to bypass the lifecycle gate. The
+  installed archive-command hook blocks that path when native hooks are active.
 - In a standard `openspec/changes/<name>` layout, archive must use OpenSpec
   archive semantics so delta specs are merged and the change is moved to
   `openspec/changes/archive/`. State-only archive is only a fallback for

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

@@ -50,6 +50,15 @@ any full SDD document or implementation prompt is generated.
   external input. If semantics are unclear, mark the feature blocked instead of
   inventing a fallback.
 - Process one feature at a time, in product-document order.
+- When the pipeline selected embedded deep-clarification mode, investigate facts
+  from the repository, source documents, configuration, tests, logs, and tools
+  before asking. Ask the user only about an unresolved decision that needs owner
+  intent; do not ask for facts that can be found locally.
+- In embedded deep-clarification mode, ask exactly one decision question at a
+  time. Include the recommended answer and its important consequence, wait for
+  the answer, then record the result before asking the next question. Do not
+  create SDD artifacts or implementation prompts while a current-feature
+  decision remains pending.
 - For long PRDs, Lark/Feishu exports, screenshots, or mixed product docs, do
   not read the whole document and generate all tasks in one pass. First create
   a source index, then process one bounded section or feature at a time. Each
@@ -85,6 +94,10 @@ Create or update these files in the active OpenSpec change directory:
 - Business semantic evidence when status/enum/sync/default behavior is involved:
   source-of-truth field, enum mapping, consumer interpretation, business basis,
   explicitly rejected fallback/default choices, and unresolved owner questions.
+- Deep-clarification decision evidence when this mode is active: each question,
+  recommendation, user decision, consequence, and the resulting
+  `confirmed`/`candidate`/`pending`/`rejected` entry in
+  `.sdd/handoff/brainstorm-summary.md`.
 
 Use the detailed workflow in:
 
@@ -127,14 +140,20 @@ Use the detailed workflow in:
     If a proposed default, fallback, old-value retention, or null conversion is
     not explicitly approved by the requirement or owner, mark it rejected and do
     not include it in the design.
-11. Ask only current-feature clarification questions.
-12. Wait for programmer confirmation.
-13. Draft a rough API contract: path, action, core request, core response. Field types can be approximate.
-14. Wait for programmer confirmation of the rough API.
-15. Produce a precise API section with field names, types, requiredness, defaults, enums, errors, examples, and curl.
-16. Mark the feature as `frozen` only when understanding, rough API, precise API,
+11. If embedded deep-clarification mode is active, resolve one decision at a
+    time. For each question, state the recommended answer and consequence, wait
+    for the programmer response, then update
+    `.sdd/handoff/brainstorm-summary.md` under `confirmed`, `candidate`,
+    `pending`, or `rejected`. Stop asking once only repository-verifiable facts
+    remain.
+12. Ask only any remaining current-feature clarification questions.
+13. Wait for programmer confirmation.
+14. Draft a rough API contract: path, action, core request, core response. Field types can be approximate.
+15. Wait for programmer confirmation of the rough API.
+16. Produce a precise API section with field names, types, requiredness, defaults, enums, errors, examples, and curl.
+17. Mark the feature as `frozen` only when understanding, rough API, precise API,
     and validation data needs are confirmed or explicitly blocked.
-17. Only after the current feature is frozen or blocked, move to the next
+18. Only after the current feature is frozen or blocked, move to the next
     indexed feature. Do not batch-confirm multiple features from memory or a
     compressed chat summary.
 

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

@@ -54,15 +54,56 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    adapter/protocol translator/device gateway into a business-entry
    orchestrator, stop and return to `$superflow-docs` unless the OpenSpec/SDD
    contract explicitly grants that ownership with approval evidence.
-6. For field/status/enum/sync changes, include `Field And Status Reverse
+6. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+   gateways, cloud services, or other external integrations, include
+   `External Integration Configuration And Deployment Contract`. Inventory
+   every endpoint, app/tenant/project ID, Topic, Tag, Consumer Group,
+   namespace, webhook, ACL/role, feature switch, timeout, and credential
+   reference. Prove the source and injection/provisioning method for local,
+   test, and production environments, plus owner, creation timing, readiness
+   check, rollback, and unresolved blockers. Runtime values and server-side
+   resources must not exist only as hard-coded annotations/constants. Test
+   auto-creation or pre-existing resources must not be treated as proof that
+   production will provision them. Missing production provisioning evidence
+   blocks design completion.
+7. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
+   duplicate consumption, or repeated external delivery, include
+   `Concurrency And Idempotency Ownership`. Use a stable business idempotency
+   key and an application-layer atomic claim in a short transaction; persist
+   `PENDING` before the external call, release database locks before calling
+   externally, model success/failure/uncertain states, and reuse the original
+   business code on retry. A unique index is not the default and may only be an
+   optional fallback with proven natural uniqueness, historical cleanup,
+   NULL/soft-delete semantics, and a conflict contract. Check-then-insert,
+   process-local locks, and random IDs alone are blocked.
+8. 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:
+9. 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.
+10. 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
+11. 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 +111,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:
+12. 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,28 @@ 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 third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment gateways,
+  cloud services, or other external integrations, `api.md` and
+  `sdd-quality-gate.md` must include `External Integration Configuration And
+  Deployment Contract`. Inventory endpoints, app/tenant/project IDs,
+  Topic/Tag/Consumer Group, namespace, webhook, ACL/role, feature switches,
+  timeout, and credential references across local, test, and production
+  environments. Record injection/provisioning method, runtime owner,
+  provisioning owner/time, readiness evidence, rollback, secret handling, and
+  blockers. Environment-dependent values must not be hard-coded; test
+  auto-creation or existing test resources do not prove production readiness.
+  Missing production provisioning evidence blocks document freeze.
+- 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 +315,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

@@ -37,6 +37,11 @@ hotfix:
 
 ## Routing
 
+- When the user explicitly asks for rigorous questioning, or a bounded feature
+  has unresolved owner decisions, mutually exclusive approaches, an unclear
+  source of truth, unclear acceptance behavior, or cross-system responsibility,
+  use `superflow-clarify` in embedded deep-clarification mode. This is a mode
+  inside the normal clarify phase, not a separate command the user must remember.
 - New or unclear requirement: use superflow-clarify.
 - Confirmed requirement needing full docs: use openspec-propose, then
   superflow-docs.
@@ -49,6 +54,29 @@ hotfix:
 - Urgent small behavior repair: use superflow-hotfix, unless API, DB, cross-repo,
   status, SQL, SDK, or real-entry gates are involved.
 
+## Embedded Deep Clarification
+
+When the router selects embedded deep clarification, follow these rules inside
+`superflow-clarify`:
+
+- Do not activate it for a clear, bounded hotfix or tweak whose intended behavior
+  and acceptance result are already evidenced. Do not turn routine work into an
+  interview.
+- Establish facts from the requirement, repository, configuration, tests, logs,
+  or available tools before asking the user. Ask only for a decision the user or
+  owner must make.
+- Ask exactly one decision question at a time. State the recommended option and
+  its important consequence, then wait for the answer before the next question.
+- After each answer, update `.sdd/handoff/brainstorm-summary.md` with
+  `confirmed`, `candidate`, `pending`, and `rejected` entries. Do not rely on
+  chat memory for a resolved decision.
+- Do not create or change proposal, spec, design, tasks, tests, or implementation
+  artifacts until all decisions that affect the current feature are confirmed or
+  explicitly marked blocked.
+- Exit deep clarification once only repository-verifiable facts remain and the
+  user confirms the current feature understanding. Continue through the existing
+  clarify workflow without invoking an external skill dependency.
+
 ## Required Artifacts
 
 For a full change, the docs phase must create or refresh:
@@ -120,6 +148,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 +206,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/api-design-template.md

@@ -11,6 +11,14 @@ Use api.md as the canonical contract before implementation.
 - Frontend mapping: screen field, API field, DTO/VO field, DB field, test case.
 - External dependency contract: SDK version, topic/path, parameter source,
   sample request/response, timeout and retry behavior.
+- External Integration Configuration And Deployment Contract for third-party
+  platforms/tools, SDKs, MQ/Kafka, callbacks, payment providers, cloud
+  services, or other external integrations. Inventory endpoint,
+  app/tenant/project IDs, Topic/Tag/Consumer Group, namespace, webhook,
+  ACL/role, feature switches, timeout, and credential references for local,
+  test, and production; record injection/provisioning method, runtime owner,
+  provisioning owner/time, readiness evidence, rollback, secret handling, and
+  blockers.
 - File contract when upload/download/export is involved: Content-Type,
   Content-Disposition, filename rule, body format, frontend detection rule.
 - Compatibility and migration notes.
@@ -20,3 +28,8 @@ Use api.md as the canonical contract before implementation.
 
 Do not allow design, tasks, tests, or prompts to proceed if API changes are only
 summarized as core fields, same as existing endpoint, or to be added later.
+Environment-dependent external configuration and server-side resources must
+not exist only as hard-coded annotations, constants, or business code. Test
+auto-creation, existing historical resources, or successful local startup do
+not prove production readiness; missing production provisioning evidence
+blocks release.

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

@@ -24,6 +24,32 @@ 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 third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+  providers, cloud services, or other external integrations, inherit
+  `External Integration Configuration And Deployment Contract`. Cover
+  local/test/production sources and provisioning, injection/creation,
+  runtime/provisioning owners and timing, readiness evidence, rollback, secret
+  handling, and blockers. Do not hard-code environment-dependent values or
+  infer production readiness from test auto-creation.
+- For concurrent requests, batch issue/activation/renewal, duplicate callbacks
+  or consumption, and repeated external delivery, inherit `Concurrency And
+  Idempotency Ownership`. Define a stable business idempotency key,
+  application-layer atomic claim owner, short transaction boundary,
+  PENDING/SUCCESS/FAILED state machine, retry reuse of the original business
+  code, external-call boundary, and uncertain-result reconciliation. Release
+  database locks before external calls. A unique index is not the default and
+  may only be an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
+- 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 +70,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,35 @@ Superpowers technical design is canonical for source-level HOW and execution.
 - Field semantic contract checked.
 - Write-loop checked.
 - No-fallback boundary confirmed.
+- External Integration Configuration And Deployment Contract copied from the
+  API, quality gate, and technical design for third-party platforms/tools,
+  SDKs, MQ/Kafka, callbacks, payment providers, cloud services, or other
+  external integrations. Cover local/test/production sources and provisioning,
+  injection/creation, runtime/provisioning owners and timing, readiness
+  evidence, rollback, secret handling, and blockers. Do not hard-code
+  environment-dependent external values or treat test auto-creation as
+  production readiness evidence.
+- Concurrency And Idempotency Ownership copied from the technical design for
+  concurrent requests, batch issue/activation/renewal, duplicate callbacks or
+  consumption, and repeated external delivery. Define a stable business
+  idempotency key, application-layer atomic claim owner, short transaction
+  boundary, PENDING/SUCCESS/FAILED state machine, retry reuse of the original
+  business code, external-call boundary, and uncertain-result reconciliation.
+  Release database locks before external calls. A unique index is not the
+  default; it is only an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
+- 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 +61,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,32 @@
 - 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.
+- External Integration Configuration And Deployment Contract exists for
+  third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment providers,
+  cloud services, or other external integrations. It inventories environment
+  sources and provisioning for endpoints, app/tenant/project IDs,
+  Topic/Tag/Consumer Group, namespace, webhook, ACL/role, switches, timeouts,
+  and credential references; names runtime/provisioning owners, timing,
+  readiness evidence, rollback, secret handling, and blockers; and forbids
+  environment-dependent hard-coded values. Test auto-creation, existing test
+  resources, or local startup do not prove production readiness.
+- Concurrency And Idempotency Ownership exists for concurrent requests, batch
+  issue/activation/renewal, duplicate callbacks/consumption, or repeated
+  external delivery. It defines the business idempotency key,
+  application-layer atomic claim owner, short transaction boundary,
+  PENDING/SUCCESS/FAILED state machine, retry code reuse, external-call
+  boundary, and uncertain-result reconciliation. A unique index is not the
+  default; it is only an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
+- 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?