@1aboveio/skills 0.19.2 → 0.20.1

package/skills/payment/tld-detection/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: tld-detection
+description: >
+  Explicit-only. Potential TLD (transaction-laundering) clusters from
+  descriptor partitions, then exact currency-amount pairs, with same-descriptor
+  baseline contrasts, high/medium/low risk tiers, exposure sizing, and a
+  ≤3-sentence decision.
+  Not payment-analysis or fraud-analysis.
+disable-model-invocation: true
+---
+
+# TLD Detection
+
+Find **potential TLD clusters** in an authorization extract. TLD here is
+transaction laundering, not a domain name: hidden activity stuffed under a
+normal MCC, often mixed across descriptors.
+
+First partition the cleaned authorizations by **descriptor**. Inside each
+descriptor, the clustering key is the **currency-amount-pair**. Geometric
+relationships between exact anchors are the stuffing signal (掺量). BIN
+country is not a membership key; report it in the cluster-versus-baseline
+comparison after membership is frozen.
+
+**Produce:** cluster results and a separate run-specific methodology document
+under `reports/tld-detection/`.
+**Do not produce:** confirmed laundering, a legal finding, or supervised
+fraud-rule packages (`fraud-analysis`).
+
+Paths under `references/` are relative to this skill.
+
+## Workflow
+
+Follow these steps in order. Detail:
+[references/workflow.md](references/workflow.md).
+
+| Step | Do | Gate |
+|---|---|---|
+| 0 Pre-flight | File, grain, columns, window | Stop if auth grain, descriptor, amount, or currency column is missing; caption missing BIN country |
+| 1 Clean | Dedup | Record drop counts; do not filter BIN country |
+| 2 Cluster | Partition; rank pairs; identify anchors; freeze exact keys; compare with same-descriptor baseline | Partition = descriptor; ≥3 levels; adjacent levels = 2x; ≥100 attempts; absolute residual cap per candidate currency |
+| 3 Risk | Assign high/medium/low investigation priority | Mixed BIN countries are neutral; exact 100% single-country concentration is a standout |
+| 4 Decision | Conclusion + basis for the book | ≤3 sentences; no new evidence |
+| 5 Report | Answer highest-risk, cluster-characteristic, and exposure questions; write + proofread | Sort high → medium → low; no confirmed-TLD wording |
+
+### 0 — Pre-flight
+
+Authorization extract, one row per auth attempt. Record paths, time field,
+amount, currency, BIN/issuer country, descriptor, MCC, response. Grain and
+column aliases: [workflow.md](references/workflow.md).
+
+### 1 — Clean
+
+[references/clean.md](references/clean.md). Deduplicate first. Do not
+FX-convert the clustering key. Do not drop non-US BIN rows.
+
+### 2 — Cluster
+
+[references/clustering.md](references/clustering.md). Build normalized
+descriptor partitions, then rank currency-amount-pairs inside each descriptor. Use
+`scripts/detect_ladders.py` to detect geometric anchor relationships with
+adjacent, currency-specific absolute residual caps. Every cluster must contain
+at least three theoretical levels with a fixed 2x relationship between adjacent
+levels (for example 1x, 2x, 4x, 8x); search both up and down from every candidate
+seed. A theoretical level may
+keep multiple exact anchors, but each additional anchor must clear the stated
+portfolio support floor. Freeze membership by exact descriptor, currency,
+and amount; keep only clusters with ≥100 authorization attempts. Compare each
+cluster with the baseline formed by removing that cluster from the same
+descriptor. Do not invent clusters from MCC or comparison features.
+
+### 3 — Risk
+
+[references/decision.md](references/decision.md). Assign every identified
+currency-amount pair exactly one investigation-priority tier: High, Medium,
+or Low. BIN-country mixture is neutral and never downgrades a cluster. Treat
+an exact 100% single-BIN-country cluster as a standout; separately report the
+cluster's share of that descriptor-country slice without using an arbitrary
+coverage threshold or risk points.
+
+### 4 — Decision
+
+Write the conclusion and the basis in **at most 3 sentences** for the whole
+book. A one-line table per cluster is allowed under that.
+
+### 5 — Report
+
+[references/report-template.md](references/report-template.md). Terms:
+[references/terminology.md](references/terminology.md).
+
+```text
+reports/tld-detection/<scope>_clusters.md
+reports/tld-detection/<scope>_clusters.zh.md
+reports/tld-detection/<scope>_clusters.zh.html
+reports/tld-detection/<scope>_methodology.md
+reports/tld-detection/<scope>_methodology.zh.md
+reports/tld-detection/<scope>_methodology.zh.html
+```
+
+Keep detection results in the cluster reports. Lead with the highest-risk
+clusters, characterize every identified cluster and its descriptor share, then
+quantify exposure by risk tier, descriptor, and across all authorization
+attempts. Sort High → Medium → Low, then by evidence strength and attempts
+inside each tier. Put the
+actual run's cleaning, partitioning, parameter selection, sensitivity evidence,
+baseline definition, and audit details in the methodology documents; link the
+paired files in both directions. HTML is preferred when there are charts. Grep
+banned strings after writing.
+
+## Progress
+
+Track a task plan. One item is `in_progress` at a time.
+
+1. Pass pre-flight
+2. Freeze cleaned universe and descriptor partitions
+3. Assign High / Medium / Low risk tiers
+4. Publish descriptor currency-amount pairs + same-descriptor baselines
+5. Write ≤3-sentence decision
+6. Write report + separate run methodology and proofread
+
+## Boundary
+
+| Need | Skill |
+|---|---|
+| Potential TLD clusters, currency-amount pairs, stuffing / 掺量, MCC miscoding, descriptor mixing | `tld-detection` |
+| Volume, journey Sankey, auth rate, decline mix, settlement overview | `payment-analysis` |
+| Proxy/confirmed fraud labels, holdout precision/recall, rule packages | `fraud-analysis` |
+
+A suspected-fraud *rate contrast* in this skill is not a fraud-analysis
+rule package.
+
+## Reference index
+
+| Need | Read |
+|---|---|
+| Grain, columns, window | [workflow.md](references/workflow.md) |
+| Dedup | [clean.md](references/clean.md) |
+| Currency-amount pairs, anchors, same-descriptor baseline | [clustering.md](references/clustering.md) |
+| ≤3-sentence conclusion | [decision.md](references/decision.md) |
+| Report chapters | [report-template.md](references/report-template.md) |
+| Language / banned strings | [terminology.md](references/terminology.md) |
+
+## Sanity check
+
+- [ ] Auth grain; dedup counts are stated; no BIN-country row filter
+- [ ] Partition key is normalized descriptor; missing descriptor is an explicit bucket
+- [ ] Clustering key is original currency + amount, not USD
+- [ ] Each rung-pool currency has an explicit adjacent absolute-residual cap and sensitivity evidence
+- [ ] Multi-anchor levels state their portfolio support floor; final membership uses exact selected amount keys
+- [ ] Cluster attempts ≥100
+- [ ] Every cluster has a High / Medium / Low risk tier and results sort in that order
+- [ ] Currency-amount pairs show seed and representative anchors; `*` marks a multi-amount level
+- [ ] Same amount pair may recur across descriptor partitions; never merge them automatically
+- [ ] BIN country is post-membership reporting data, not a membership key; Mixed is neutral
+- [ ] Exact 100% single-country concentration is a standout; descriptor-country coverage is shown without a risk threshold
+- [ ] Each cluster baseline is the same descriptor after removing that cluster
+- [ ] Definition summary contains only descriptor, seed, anchors, and attempts
+- [ ] Anchor table reports attempts, authorization success rate, and suspected-fraud share for every level, including n < 30
+- [ ] Characteristics contain descriptor total, cluster attempts/share, MCC, and cluster-vs-baseline auth rate, suspected-fraud share, top 3 banks, and top 3 BIN countries
+- [ ] Decision prose is ≤3 sentences (conclusion + basis)
+- [ ] Report answers highest-risk, identified-cluster characteristics, and by-tier/by-descriptor exposure
+- [ ] Run-specific methodology is separate from results; report and methodology link to each other
+- [ ] Zero families → ranking only; no descriptor-invented clusters
+- [ ] Language matches terminology.md; no confirmed-laundering claim

package/skills/payment/tld-detection/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "TLD Detection"
+  short_description: "Risk-tiered TLD clusters from exact currency-amount pairs"
+
+policy:
+  # Codex counterpart to SKILL.md disable-model-invocation: true
+  # (Claude Code / Pi). Keeps explicit invoke; blocks description-based
+  # auto-selection.
+  allow_implicit_invocation: false

package/skills/payment/tld-detection/evals/evals.json

@@ -0,0 +1,107 @@
+{
+  "skill_name": "tld-detection",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We think some merchants are stuffing TLD volume through a normal MCC. Authorizations_2026-03.csv has descriptors, MCC, BIN country, amount, currency, timestamp, and response codes. Find potential TLD clusters.",
+      "expected_output": "Deduplicates auths without a US-BIN filter; partitions by normalized descriptor; detects exact currency-amount pairs with explicit absolute residual caps; freezes membership; compares each cluster with the same descriptor after removing that cluster; assigns High, Medium, or Low investigation priority; and quantifies exposure by risk tier and descriptor.",
+      "expectations": [
+        "Uses normalized descriptor as the partition key and does not use BIN country as a membership key.",
+        "Uses adjacent currency-specific absolute residual caps with sensitivity evidence and no percentage tolerance.",
+        "Requires at least three theoretical levels with a fixed 2x relationship between adjacent levels.",
+        "Reports only currency-amount pairs with at least 100 exact-member attempts and compares each with the same descriptor after removing that cluster.",
+        "Reports Top 3 issuing banks and BIN countries only after membership is frozen.",
+        "Assigns every identified cluster High, Medium, or Low risk without treating the tier as confirmation of TLD.",
+        "Sorts results High to Medium to Low and reports exact-member exposure separately by tier and descriptor.",
+        "Keeps run-specific methodology in a separate linked document.",
+        "Provides a Verdict of at most three sentences without confirmed-laundering language."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Same descriptor seems to mix several ticket sizes that look like 9.99, 19.99, 39.99, 79.99. Another TLD name might be split across three billing descriptors. Cluster the book and tell me if those patterns hold.",
+      "expected_output": "Builds descriptor partitions and identifies qualifying currency-amount pairs independently inside them using at least three theoretical levels and a fixed 2x relationship; matching amounts across descriptors never merge membership.",
+      "expectations": [
+        "Builds descriptor partitions before currency-amount pairs.",
+        "Requires at least three theoretical levels and rejects non-2x relationships.",
+        "Requires at least 100 exact-member attempts before reporting a cluster.",
+        "Reports materially different currency-amount pairs under one descriptor.",
+        "Assesses MCC fit without calling a descriptor fabricated."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "For each detected currency-amount pair, compare its behavior with the rest of the same descriptor.",
+      "expected_output": "Keeps BIN country out of the membership key, freezes exact membership, builds a same-descriptor baseline by removing only that cluster, compares the required rates and Top 3 dimensions, reports both BIN-country conditional shares, and charts transaction date and BIN-country local-hour distributions against that baseline.",
+      "expectations": [
+        "Does not partition detection by BIN country.",
+        "Uses the same descriptor after removing the current cluster as baseline.",
+        "Reports authorization success rate and suspected fraud as a share of attempts for Cluster and Baseline.",
+        "In each cluster definition, the anchor table reports attempts, authorization success rate, and suspected-fraud share for every theoretical level, including levels with fewer than 30 attempts.",
+        "For each Top 3 cluster BIN country, reports its share of the cluster and the cluster's share of all attempts in the same descriptor-country slice.",
+        "Treats exact 100% single-country concentration as a standout, Mixed as neutral, and country-slice coverage as descriptive without a risk threshold.",
+        "Charts transaction-date and BIN-country local-hour shares for Cluster and Baseline, normalizing each series independently."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Inside descriptor ACME, USD 10.00 is followed by 19.99 with 180 attempts, 20.00 with 40 attempts, and then 39.99. Build the potential TLD ladders.",
+      "expected_output": "Uses an explicit USD adjacent absolute residual cap; selects a primary exact anchor deterministically; may retain another exact anchor at the same theoretical level only if it clears the stated multi-anchor support floor; and applies exact descriptor, currency, and amount membership afterward.",
+      "expectations": [
+        "Runs ladder discovery only inside descriptor ACME.",
+        "Uses absolute adjacent residuals rather than percentage matching.",
+        "Selects the highest-count candidate as the primary anchor.",
+        "Retains an additional anchor only when it independently clears the declared support floor.",
+        "Never assigns every amount in a tolerance interval to the ladder."
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Inside one descriptor I see an approximate EUR x2 amount pattern, but its selected exact amount keys total only 96 authorization attempts. Should it be reported?",
+      "expected_output": "Does not report the 96-attempt family; records it below threshold, keeps its transactions outside reported clusters, publishes its ranking, and does not invent a cluster from MCC or comparison features.",
+      "expectations": [
+        "Does not report the 96-attempt family.",
+        "Keeps its rows outside reported clusters.",
+        "Does not invent a cluster from comparison features.",
+        "Still provides a no-ladder Verdict of at most three sentences."
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Descriptors ALPHA and BETA both have the exact USD 9.99, 19.99, 39.99 ladder with over 100 attempts, across several BIN countries. Should those transactions become one cluster?",
+      "expected_output": "Creates two descriptor-local currency-amount pairs, permits the same exact amounts in both descriptors, keeps their membership and same-descriptor baselines separate, and reports each independently.",
+      "expectations": [
+        "Creates two ladders because descriptor is the partition boundary.",
+        "Permits the same exact pairs in different descriptor ladders.",
+        "Does not merge matching fingerprints across descriptors.",
+        "Does not merge membership, metrics, or baselines.",
+        "Treats BIN country as post-membership reporting data."
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "USD 14.xx amounts are representative, but one percentage tolerance becomes too wide at larger amounts. Detect the ladders without sweeping a numeric interval into membership.",
+      "expected_output": "Runs a documented absolute-cap sensitivity grid, uses a currency-specific adjacent residual cap, searches every descriptor-local rung-pool seed, allows only sufficiently supported exact multi-anchors, rejects upper rungs outside the absolute cap, and freezes exact membership before BIN-country attribution.",
+      "expectations": [
+        "Does not use a percentage tolerance.",
+        "Reports the tested cap grid and selected cap.",
+        "Uses finite exact anchor sets with a stated multi-anchor support floor.",
+        "Rejects an upper rung whose adjacent residual exceeds the cap.",
+        "Computes BIN-country reporting values only after exact membership is frozen."
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "One cluster is 100% US BIN and covers 21.3% of its descriptor's US BIN attempts. Another is mixed and covers 33.8% of one descriptor-country slice. Grade and order the risk.",
+      "expected_output": "Treats the exact 100% single-country concentration as a standout and uses 21.3% only to explain its scale; treats Mixed as neutral and 33.8% as descriptive rather than a threshold; combines independent structural and behavioral evidence; assigns High, Medium, or Low risk; and sorts High to Medium to Low.",
+      "expectations": [
+        "Does not classify Mixed as Weak or automatically lower its risk tier.",
+        "Does not infer risk from a 20%, 33.8%, or other country-slice coverage threshold.",
+        "Requires exact 100% single-country composition for the BIN-country standout.",
+        "Reports cluster composition and descriptor-country slice coverage as separate conditional percentages.",
+        "Uses at least one independent corroborating characteristic before making a 100% single-country cluster High risk.",
+        "Preserves stable cluster IDs while sorting High to Medium to Low."
+      ]
+    }
+  ]
+}

package/skills/payment/tld-detection/references/clean.md

@@ -0,0 +1,51 @@
+# Data cleaning
+
+Run on the authorization extract before any clustering. Record every drop
+count in the report appendix.
+
+Do not filter to US-BIN here. Issuer country remains available for the
+cluster-versus-baseline Top 3 BIN-country comparison.
+
+## 1. Exact-row dedup
+
+Drop bitwise-duplicate rows (same values in every column used). Count
+them. They are extract artefacts, not extra attempts.
+
+## 2. Identity dedup
+
+If `Transaction ID` / `Auth ID` is unique when present, keep one row per
+id (first by time).
+
+Otherwise, if `Order ID` is present, keep one row per
+(`Order ID`, time, amount, currency, masked PAN / last4 if present).
+Retries of the same order at different times stay distinct.
+
+If none of those identities exist, **skip this step** — keep the
+exact-row-deduped table and say identity-dup was skipped. Do not stop
+the run. Do not invent a customer id from BIN + amount.
+
+## 3. Amount and currency
+
+- Clustering key uses the **original** amount and currency.
+- Normalize `10`, `10.0`, `10.00` to the same decimal key.
+- Drop rows with missing amount or currency; count them.
+- Do not FX-convert before clustering. A 9.99 EUR rung is not a 9.99 USD
+  rung. Amount sums later stay inside one currency; never add EUR to USD.
+
+## 4. Missing dimensions
+
+Rows with missing descriptor or BIN / issuer country stay in the
+clustering universe. Missing descriptors enter the `UNKNOWN_DESCRIPTOR`
+partition; missing countries enter the `UNKNOWN_BIN_COUNTRY` reporting
+bucket after membership is frozen.
+
+## Output of this step
+
+A cleaned table plus a one-line census:
+
+```
+raw N → exact-dup drop n1 → identity-dup drop n2 (or skipped)
+→ missing amount/currency n3 → cleaned universe U
+```
+
+All later attempt counts use `U`, not `raw N`.

package/skills/payment/tld-detection/references/clustering.md

@@ -0,0 +1,219 @@
+# Currency-amount-pair clustering
+
+Goal: partition the cleaned universe by descriptor, find stuffing (掺量)
+as **approximate geometric ladders** inside each descriptor, then decompose
+each qualifying ladder into BIN-country attribution components and contrast
+it against the remainder.
+
+## Descriptor partition
+
+Partition key = `normalized descriptor`.
+
+- Trim, case-fold, and collapse repeated whitespace. Preserve the most
+  frequent source spelling for display.
+- Do not fuzzy-match or strip dynamic suffixes unless the extract documents
+  their semantics.
+- Use `UNKNOWN_DESCRIPTOR` for missing values; do not drop them.
+
+Freeze descriptor assignment before ranking amounts. Report each descriptor's
+attempt count and share of `U`. A ladder belongs to exactly one descriptor;
+the same exact currency-amount-pair may legitimately belong to ladders in
+different descriptors.
+
+BIN country is **not** a partition or membership key. Normalize it after
+ladder formation and report its attempt counts, shares, auth rates, suspected-
+fraud rates, and local-hour shapes as attribution components.
+
+## Currency-amount-pair
+
+Key = (`currency`, `amount`) on the original (not FX-converted) amount.
+
+Count = authorization **attempts** in the current partition. Rank
+descending by count. Ties: smaller amount first, then currency code.
+
+## High-count set and rung pool
+
+Work **per partition, then per currency**. In the table below, `|P|` is
+the authorization-attempt count of the current partition.
+
+| Set | Membership |
+|---|---|
+| High-count (seeds) | union of (a) pairs with count ≥ `max(30, 0.5% of \|P\|)` (b) the partition top 25 pairs by count (c) per currency in the partition, the top 10 pairs with count ≥ 30 |
+| Rung pool | pairs with count ≥ `max(5, 0.1% of \|P\|)` |
+
+State the thresholds. Use the high-count set for ranking. Test every rung-pool
+pair as a possible seed for a three-level 2x relationship; otherwise a
+representative lower-volume path can be structurally impossible to discover.
+Extra levels may be quieter amounts in
+the rung pool, and (c) keeps a smaller currency visible inside the partition.
+
+If the rung pool has fewer than three pairs in every currency of a partition,
+that partition has no three-level ladder to test. Still publish its ranking
+table when it is among the largest partitions or has a below-threshold family.
+
+## Ladder detection
+
+Ladder detection has two separate phases. **Discovery** uses an adjacent,
+currency-specific absolute residual cap. **Membership and every downstream
+metric use the exact descriptor plus selected currency-amount-pairs only.**
+Never widen final membership to a numeric interval or another descriptor.
+
+### Adjacent absolute-residual rule
+
+For exact amounts `a < b` in one descriptor and currency, multiplier `m` has:
+
+```text
+residual = |b - a · m|
+```
+
+They are adjacent anchors only when `residual ≤ ε_currency`. Do not use one
+percentage tolerance across amounts: its absolute allowance grows with the
+amount and can merge materially different upper-rung prices.
+
+Configure and report one cap per currency represented in a partition's rung
+pool. For a two-decimal currency, test a sensitivity grid such as `0.02,
+0.05, 0.10, 0.15, 0.25` and retain the smallest operationally justified cap
+under which material paths are stable. Fail closed when a rung-pool currency
+has no cap; currencies below the rung-pool threshold need no cap.
+
+Use the bundled deterministic implementation after producing a cleaned
+authorization CSV:
+
+```bash
+python3 {baseDir}/scripts/detect_ladders.py cleaned-authorizations.csv \
+  --descriptor-column descriptor --bin-country-column bin_country \
+  --currency-column currency --amount-column amount \
+  --cap USD=0.15 --multi-anchor-min-attempts 24 \
+  --sensitivity-cap USD=0.02 --sensitivity-cap USD=0.05 \
+  --sensitivity-cap USD=0.10 --sensitivity-cap USD=0.15 \
+  --sensitivity-cap USD=0.25
+```
+
+The CLI does not clean or deduplicate the CSV; complete
+[clean.md](clean.md) first.
+
+### Family from a seed (up and down)
+
+Starting from every rung-pool seed, expand recursively upward and downward
+using only adjacent matches. A theoretical level may contain several exact
+anchors. Select the highest-count match as its primary anchor; retain an
+additional match only when that exact pair independently clears the stated
+portfolio support floor (default 24 attempts, corresponding to the Worldpay
+portfolio rung floor). Record that floor and test it separately for a new
+portfolio.
+
+Every retained key must be in the partition's rung pool and match an anchor
+in the adjacent level. The finite retained keys become the explicit anchor
+set. Tolerance never acts on transactions after selection: final membership
+is exact equality on (`descriptor`, `currency`, `amount`). BIN country is
+attached only after this membership is frozen.
+
+### Required 2x family
+
+A candidate family must use **`m = 2`** between every adjacent theoretical
+level and contain **at least three theoretical levels**. Example: 1x, 2x, 4x,
+8x around the seed, including downward (`19.99` can find `9.99` and `39.99`).
+There is no two-level exception, and relationships based on `m = 3`, `4`, `5`,
+`10`, or any other multiplier do not form clusters.
+
+For each seed, rank qualifying paths by: more theoretical levels; more exact-
+member attempts; then lower summed adjacent residual. The attempt threshold
+below independently determines whether the family becomes a reported cluster.
+
+### Minimum cluster size
+
+Sum attempts only over rows in the partition whose keys are the selected
+exact currency-amount-pairs. A family is a reported cluster only when that
+exact membership has **≥100 authorization attempts**. Keep smaller
+families in the run methodology document as `below threshold`; do not validate them or
+issue cluster verdicts for them. Their rows remain in canonical baseline
+`B` and descriptor remainder `B_D` unless selected exact keys are claimed
+by another reported ladder in the same descriptor.
+
+### Several groups
+
+Within each partition, process unused rung-pool seeds in descending attempt
+count. A currency-amount-pair joins **at most one** reported cluster in that
+partition — the first qualifying family that claims it. Below-threshold
+families do not reserve keys. Never let a claim in one partition reserve the
+same pair in another partition.
+
+Name clusters `C1`, `C2`, … by descending total attempts. For each, record
+the descriptor partition, seed, currency, multiplier, absolute cap, summed
+fit residual, theoretical levels, all exact anchors and counts, multi-anchor
+levels, total attempts, and post-formation BIN-country components.
+
+Ignore one-off round amounts (`100`, `1000`) unless they sit on a ladder.
+A popular SKU price is not a cluster by itself.
+
+### None found
+
+If no family qualifies in any partition, **do not invent clusters** from
+MCC or comparison features. Publish the partition and pair rankings, contrast
+the top pairs only as context if useful, and skip cluster verdicts.
+
+## Baseline
+
+For each cluster, **Baseline** means every authorization in the same descriptor
+after removing that cluster's exact member keys. Other identified
+currency-amount pairs remain in this baseline. This is the only comparison
+population used in cluster characteristics. If the cluster consumes the whole
+descriptor, report comparison values as `n/a`.
+
+For the overall impact table only, `Baseline` means rows in the cleaned universe
+that belong to no identified currency-amount pair. Keep this distinct from the
+per-cluster same-descriptor baseline.
+
+If two currencies each have a ladder, they are separate clusters. Do not
+merge across currencies.
+
+## Contrast vs baseline
+
+Same window and descriptor. Compare each cluster with its baseline on:
+
+| Metric | Formula |
+|---|---|
+| Authorization success rate | approvals / attempts |
+| Suspected fraud as share of attempts | suspected-fraud attempts / attempts |
+| Top 3 issuing banks | count and share of that series |
+| Top 3 BIN countries | count and share of that series |
+
+Separately report Descriptor, descriptor total attempts, cluster attempts,
+cluster share of descriptor, and MCC.
+
+Require a stated min-n before ranking a cluster-versus-baseline rate
+(default attempts ≥ 30). Below that, show the contrast rate as `n/a (n=…)`.
+The definition anchor table is not a ranking contrast: always compute
+authorization success rate and suspected-fraud share for every theoretical
+level from that level's exact member attempts, including n < min-n. Combined
+`*` levels use the combined attempts of the level. Do not write `n/a` on the
+anchor table because the rung is small.
+
+Use the contrast to assign investigation-priority risk under
+[decision.md](decision.md), not as a fraud label. Treat materially different
+authorization, suspected-fraud, issuing-bank, date, and local-hour behavior as
+independent characteristics under thresholds declared in the run methodology.
+
+For each Top 3 cluster BIN country, report both its share of the cluster and
+the cluster's share of all attempts in the same descriptor-country slice. An
+exact 100% single-country cluster is a standout. `Mixed` is neutral, and
+country-slice coverage is descriptive only: do not set a universal threshold
+or award risk points for values such as 20% or 33.8%.
+
+## What not to do
+
+- Do not treat MCC as a partition or clustering key.
+- Do not discover ladders across descriptor boundaries.
+- Do not use BIN country as a ladder partition or membership key.
+- Do not k-means the amounts.
+- Do not convert to USD and then look for ladders.
+- Do not search only upward from the busiest rung.
+- Do not use a percentage tolerance across amounts.
+- Do not assign every amount inside an interval; select finite exact anchors first.
+- Do not retain a low-support additional anchor merely because it is near a primary anchor.
+- Do not report a cluster with fewer than three theoretical levels.
+- Do not use any adjacent-level multiplier other than 2x.
+- Do not report a cluster with fewer than 100 attempts.
+- Do not put the same pair in two clusters within one partition.
+- Do not merge matching amount fingerprints across descriptors.
+- Do not call the output a customer segment or a marketing cohort.

package/skills/payment/tld-detection/references/decision.md

@@ -0,0 +1,85 @@
+# Risk decision
+
+After currency-amount-pair detection and same-descriptor baseline comparison,
+assign investigation-priority risk tiers. This is prioritization, not a finding
+that transaction laundering occurred.
+
+## Eligibility versus risk
+
+The cluster gate (at least three theoretical levels, fixed 2x adjacency, at
+least 100 exact-member attempts) determines which currency-amount pairs enter
+the result. Passing that gate does not by itself determine High, Medium, or Low
+risk.
+
+Risk uses independent post-membership evidence:
+
+- structural strength beyond the minimum, such as a fourth or later level
+- cluster share of its descriptor
+- authorization-success and suspected-fraud differences versus the same-
+  descriptor baseline
+- issuing-bank differences versus that baseline
+- transaction-date and BIN-country-local-hour differences versus that baseline
+- externally evidenced MCC or merchant-business mismatch; never infer this
+  from a suggestive descriptor name alone
+
+Declare portfolio-specific thresholds for a materially different rate,
+distribution, or descriptor share in the run methodology before assigning
+risk. Do not invent universal cutoffs after seeing the results.
+
+## BIN-country evidence
+
+BIN country is post-membership evidence, not a partition, membership key, or
+veto. `Mixed` is neutral and must never reduce a risk tier by itself.
+
+For every Top 3 cluster BIN country, report both conditional views:
+
+```text
+cluster composition = cluster attempts in country / all cluster attempts
+country-slice coverage = cluster attempts in country /
+                         all attempts in the same descriptor and country
+```
+
+An exact **100% single-BIN-country cluster** is a standout characteristic.
+Country-slice coverage explains how large that concentration is inside the
+descriptor-country population, but it has no fixed threshold and contributes
+no independent risk points. Values such as 20% or 33.8% are descriptive, not
+self-interpreting risk signals. Any value below 100% is not promoted merely
+because it is numerically high.
+
+## Risk tiers
+
+Assign exactly one tier to every identified currency-amount pair:
+
+| Tier | Use when |
+|---|---|
+| High | An exact 100% single-country standout has at least one independent corroborating risk characteristic, or several independently strong non-country characteristics converge |
+| Medium | At least two independent characteristics materially differ from the same-descriptor baseline, but High is not justified |
+| Low | The structural cluster gate is met, but observed corroborating evidence is limited or not material |
+
+Do not use a generic 0–100 score unless the business has approved and calibrated
+its weights and cutoffs. Missing fields reduce confidence and must be disclosed;
+they are not evidence that risk is Low.
+
+Sort report results `High → Medium → Low`. Within a tier, sort by the number and
+magnitude of independently supported characteristics, then by exact-member
+attempts. Preserve stable cluster IDs when sorting an existing result.
+
+## Length and required content
+
+The Verdict is at most three sentences for the whole book:
+
+1. State the highest risk tier found and that it is an investigative priority,
+   not confirmation that TLD occurred.
+2. For High-risk clusters, give descriptor, representative anchors, attempts,
+   descriptor share, standout evidence, and the clearest independent
+   corroborating characteristic.
+3. Give exact-member exposure by risk tier and as a share of all authorization
+   attempts.
+
+If no currency-amount pair qualifies, state that none qualified, name the top
+descriptor and candidate amounts, and report zero identified-cluster exposure.
+Do not invent a cluster. Do not recommend filing a SAR, terminating a merchant,
+or correcting an MCC.
+
+First use of TLD is “transaction laundering (TLD)”. Proofread with
+[terminology.md](terminology.md).