@1aboveio/skills 0.14.0 → 0.16.1

package/skills/data-science/pyspark/references/production-validation.md

@@ -0,0 +1,130 @@
+# Production Validation
+
+Playbook for workflow step 5: **canary → (optional) profile → write →
+reconciliation** on the cluster. Use a **small sample**, typically **one month**
+of source data. Bind canary and write to the same pinned snapshot. Local tests
+do not substitute.
+
+## Fail-Closed Admission
+
+Do not launch until all applicable facts are recorded and valid:
+
+- exact commit/module hash;
+- production Spark, Python, Java, and table-format runtimes;
+- source snapshot or date boundary (the one-month sample);
+- scheduler pause/ownership state;
+- zero competing warehouse work;
+- explicit validate-only or write-enabled mode;
+- durable writable log and event-log destination;
+- restart/recovery plan for writes.
+
+Classify existing processes and working-tree changes before touching them. Do
+not kill or overwrite another operator's work.
+
+## 1. Canary
+
+Implement the validate-only guard **in the Spark job**, not only in a wrapper.
+Validate with one aggregate action, then return before any writer.
+
+```python
+import json
+
+from pyspark.sql import functions as F
+
+
+def validate_candidate(candidate):
+    # first() is a Spark action: it executes the lazy transform plan.
+    metrics = candidate.agg(
+        F.count("*").alias("row_count"),
+        F.countDistinct("event_id").alias("distinct_event_count"),
+        F.sum(
+            F.when(F.col("event_id").isNull(), 1).otherwise(0)
+        ).alias("null_event_id_count"),
+        F.sum(
+            F.when(F.col("event_count_1h") < 0, 1).otherwise(0)
+        ).alias("invalid_event_count_1h"),
+        F.count("amount_usd_1h").alias("non_null_amount_usd_1h_count"),
+    ).first().asDict()
+
+    blockers = []
+    if metrics["row_count"] != metrics["distinct_event_count"]:
+        blockers.append("event_id is not unique")
+    if metrics["null_event_id_count"]:
+        blockers.append("event_id contains nulls")
+    if metrics["invalid_event_count_1h"]:
+        blockers.append("event_count_1h contains negative values")
+    if blockers:
+        raise RuntimeError(f"validation blocked: {blockers}")
+    return metrics
+
+
+def run(validate_only, source_snapshot):
+    source = extract(source_snapshot)
+    candidate = transform(source)
+
+    metrics = validate_candidate(candidate)
+    print(json.dumps(metrics, sort_keys=True))
+
+    if validate_only:
+        print("validate-only: skipping publication")
+        return
+
+    publish(candidate)
+```
+
+Pin every source read to the same immutable snapshot. If the source cannot be
+pinned, the canary does not prove what the writer will publish. Reference every
+derived output in at least one validation aggregate so Catalyst cannot prune it.
+
+Launch through the production `spark-submit` path and runtimes:
+
+```bash
+export PYSPARK_DRIVER_PYTHON="$DRIVER_PYTHON"
+export PYSPARK_PYTHON="$EXECUTOR_PYTHON"
+
+spark-submit \
+  --name "$CANARY_NAME" \
+  --conf spark.pyspark.driver.python="$DRIVER_PYTHON" \
+  --conf spark.pyspark.python="$EXECUTOR_PYTHON" \
+  --conf spark.eventLog.enabled=true \
+  job.py --validate-only
+```
+
+Do not replace another operator's scheduler files in place.
+
+Prove the canary did not write:
+
+1. Validation completed with zero blockers.
+2. The terminal log says publication was skipped.
+3. The event log reports zero Spark output records and bytes.
+
+Do not add `.cache()` or `.persist()` to warm the canary.
+
+## 2. Profiling (optional)
+
+After the canary, profile only when wall time exceeds **5 minutes** and the run
+was not resource-constrained. Otherwise skip. When required, follow
+[Diagnosis And Profiling](diagnosis-and-profiling.md).
+
+## 3. Write
+
+Write-enabled only after a successful canary and **explicit authorization**.
+Re-check admission. Publish the same pinned sample. Do not present canary time
+as write performance.
+
+If a write is cancelled, prove from logs/source that publication was not
+reached. YARN `KILLED` alone does not prove no commit occurred.
+
+## 4. Reconciliation
+
+Independent cluster read of the published scope — not a reuse of canary
+aggregates. Follow [Reconciliation](reconciliation.md). Fail closed on mismatch.
+
+## Evidence And Ownership
+
+Safe evidence: counts, null rates, distinct counts, min/max dates, hashes,
+stage metrics, plan-node counts, commit IDs. Do not print credentials or
+entity-level rows.
+
+After the run: confirm processes are terminal, restore scheduler ownership,
+and report compute/validation, publication, and end-to-end time separately.

package/skills/data-science/pyspark/references/reconciliation.md

@@ -0,0 +1,38 @@
+# Reconciliation
+
+Cluster check after an authorized write in production validation. Use the **same
+one-month sample** as the canary. Local fixtures do not prove this.
+
+Independently read the published table or Hudi commit. Do not reuse canary
+aggregates. Fail closed on mismatch.
+
+## What To Reconcile
+
+Against the canary metrics and the previous path/oracle:
+
+- row count and distinct identity count
+- schema and required columns
+- date/partition coverage of the sample
+- write mode, commit success, and downstream readability
+- validation blockers still zero on the published scope
+
+## Bidirectional Row Parity
+
+Counts alone miss wrong values, swapped identities, and duplicate multiplicity.
+Compare full rows both ways with `exceptAll`, not `subtract`:
+
+```python
+expected = old_build(source).select(*OUTPUT_COLUMNS)
+actual = published.select(*OUTPUT_COLUMNS)
+
+assert expected.exceptAll(actual).count() == 0
+assert actual.exceptAll(expected).count() == 0
+```
+
+Pin `source` to the same snapshot the writer used. Keep the previous
+implementation only as this oracle while parity is being proven.
+
+## Evidence
+
+Safe evidence: counts, distinct counts, null rates, min/max dates, hashes, and
+commit IDs. Do not print credentials or entity-level production rows.

package/skills/{backend → data-science}/pyspark/references/transformation-design.md

@@ -158,5 +158,33 @@ assert candidate.columns == OUTPUT_COLUMNS
 ```
 
 For composite identity, list every component, for example
-`IDENTITY_COLUMNS = ["transaction_id", "transaction_leg_id"]`. Add the
-bidirectional identity and row-parity tests from [Parity Testing](parity-testing.md).
+`IDENTITY_COLUMNS = ["transaction_id", "transaction_leg_id"]`.
+
+## Local proof
+
+These checks belong in **local tests** (workflow step 4). Cluster row parity is
+[Reconciliation](reconciliation.md) after a write.
+
+Keep a bounded previous-path oracle on **synthetic** fixtures. Assert critical
+rules directly so oracle and candidate cannot share the same mistake:
+
+```python
+by_id = {row.event_id: row for row in actual.collect()}
+assert by_id["at-24h"].count_24h == 2       # inclusive lower boundary
+assert by_id["after-24h"].count_24h == 1    # one unit outside
+assert by_id["same-time-b"].count_1h == 2   # stable tie ordering
+```
+
+Cover empty and single-event groups; exact boundaries and one unit beyond;
+same-timestamp ties; null key/time/amount; open/close/eviction; floating-point
+residue; one dense hot key; duplicate and missing identities.
+
+Assert the expensive plan shape is absent without snapshotting the whole plan:
+
+```python
+plan = actual._jdf.queryExecution().executedPlan().toString().lower()
+assert not ("join" in plan and "event_time" in plan and "interval" in plan)
+```
+
+Mutation-prove high-risk tests (cutoff direction, tie-breaker, pair join,
+required column) so they fail when the rule is broken.

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -361,7 +361,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
       "contentDigest": "eff6c7b5931bce5b2265a619bccddd371a89df6ce7bc2edc74f11d00060a71dd",
       "digestExcludes": []
@@ -374,7 +374,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
       "contentDigest": "08230dc57a53d6526692b50138038abbd80abce1a067e01c52ad6acc182caf7e",
       "digestExcludes": []
@@ -387,7 +387,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
       "contentDigest": "9eea7bfba348ddaea1b934c9a7fabdd9b101df8a146e1c93e947da4d335f1d98",
       "digestExcludes": []
@@ -400,7 +400,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
       "contentDigest": "58b0556228a9271cf9e33727a05fc08a4fdfd29512ec0936b169f0a55d60e6ef",
       "digestExcludes": []
@@ -413,9 +413,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
-      "contentDigest": "9eac84bee618e57564eb702d198484b6e78f8d27e3db621d087f0dd2dc048b58",
+      "contentDigest": "a3743e0b48f0ddb54cd98d1dad22907c5f5613d13525d758c4915f1661788062",
       "digestExcludes": []
     },
     {
@@ -426,7 +426,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
       "contentDigest": "b5af4dccf703362d4f41cac4fdff48305f652a00338d85975a2e5c35ec6bc61c",
       "digestExcludes": []
@@ -439,7 +439,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
       "contentDigest": "f048fd00c69f2dc666fc7a3096cfeee6dfba73933bfb69602f3f0e26159798cc",
       "digestExcludes": []
@@ -452,7 +452,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
       "contentDigest": "90a7c4e1ad6da1e632ea2c5259e4967ffebb84353adccbca8dfc5d6bc50b60c1",
       "digestExcludes": []
@@ -465,15 +465,15 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       },
-      "contentDigest": "0d71ce70f3180bba021005e056f028ef5a2018eb187078ab8c691a5a000a924e",
+      "contentDigest": "1d85a6268819b2c2d4622355baeb4f8576e05a9725341339785badae8fe887d3",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "5c171520b6818f86f6b88cd60e5e4e0168dd6f89256690925c02758105c6c8a5",
+  "releaseIdentity": "e4cd408398f14ccc6847f86e4f0deb5a733b95ff23773ab6a4669c1c7a336130",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",
@@ -531,7 +531,7 @@
         "sourceId": "first-party",
         "sourceType": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0",
+        "version": "0.16.1",
         "installPath": null,
         "members": [
           "harness-runtime",
@@ -547,7 +547,7 @@
         "commands": [
           {
             "transport": "npm",
-            "command": "npx @1aboveio/skills@0.14.0 install --group engineering-workflow --yes"
+            "command": "npx @1aboveio/skills@0.16.1 install --group engineering-workflow --yes"
           }
         ],
         "onFailure": {

package/skills/engineering/engineering-runtime/scripts/workflow-policy.mjs

@@ -97,7 +97,7 @@ export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
     id: 'first-party',
     type: 'first-party',
     package: '@1aboveio/skills',
-    version: '0.14.0',
+    version: '0.16.1',
   },
   matt: {
     id: 'matt-pocock',

package/skills/engineering/resolve-issues/generated/workflow-repair-policy.json

@@ -237,7 +237,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -248,7 +248,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -259,7 +259,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -270,7 +270,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -281,7 +281,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -292,7 +292,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -303,7 +303,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -314,7 +314,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     },
     {
@@ -325,7 +325,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0"
+        "version": "0.16.1"
       }
     }
   ],
@@ -426,7 +426,7 @@
         "sourceId": "first-party",
         "sourceType": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.14.0",
+        "version": "0.16.1",
         "installPath": null,
         "members": [
           "harness-runtime",
@@ -442,7 +442,7 @@
         "commands": [
           {
             "transport": "npm",
-            "command": "npx @1aboveio/skills@0.14.0 install --group engineering-workflow --yes"
+            "command": "npx @1aboveio/skills@0.16.1 install --group engineering-workflow --yes"
           }
         ],
         "onFailure": {

package/skills/engineering/resolve-issues/scripts/run-state.mjs

@@ -3412,7 +3412,7 @@ export const WORKFLOW_PREFLIGHT_COMMANDS = Object.freeze([
 
 const WORKFLOW_VERIFIER_URL = new URL('../../engineering-runtime/scripts/workflow-coherence.mjs', import.meta.url)
 const WORKFLOW_FALLBACK_POLICY_URL = new URL('../generated/workflow-repair-policy.json', import.meta.url)
-export const WORKFLOW_TRUSTED_FALLBACK_POLICY_SHA256 = '626a05e1854f9dff6842f4bd9163b02fbb9bd74d5407b964a8d5c7bb84100b67'
+export const WORKFLOW_TRUSTED_FALLBACK_POLICY_SHA256 = '41c079a5d5a346693847ab6f6067b409ba48a5c92acbe9eab46a1633ced6494e'
 const WORKFLOW_REPAIR_RECIPE_REFERENCE = Object.freeze({
   id: 'engineering-workflow-dependency-first',
   generatedFrom: 'skills/distribution/generated/recipes.json',

package/skills/payment/fraud-analysis/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/payment/fraud-analysis/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: fraud-analysis
+description: >
+  Analyze tabular payment, transfer, collection, payout, account, or fraud-case
+  data (CSV, XLSX, TXT) to find interpretable features and operable risk rules.
+  Supports third-party fraud (including stolen credentials and account takeover),
+  first-party fraud or deliberate account abuse, and authorized payment scams
+  (including APP scams), across card payments, collections, bank transfers, and
+  payouts. Produces temporal holdout metrics, domain-appropriate actions, strategy
+  impact, and a business report. Use for fraud, scam, mule, account-takeover,
+  chargeback, dispute, transfer, collection, or payout risk analysis even when the
+  user does not name this skill.
+---
+
+# Fraud Analysis
+
+Analyze fraud through composable dimensions rather than treating every case as
+card fraud:
+
+- **Archetype** — the genuine customer's relationship to the fraud
+- **Mechanism** — how compromise, deception, or abuse occurred
+- **Context** — the product or money-movement surface where a rule fires
+
+Run this **10-step** loop:
+
+0. Pre-flight → 1. Profile → 2. Label → 3. Time split → 4. Engineer features →
+5. Shortlist → 6. Score rules → 7. Map actions + packages → 8. Write report →
+9. Review
+
+**Produce:** operable rules and portfolio impact in a business report.  
+**Do not produce:** a black-box model as the main answer.
+
+> Paths under `references/` are relative to this skill directory. Step detail:
+> [references/workflow.md](references/workflow.md).
+
+## Required references
+
+| File | When |
+|---|---|
+| [references/workflow.md](references/workflow.md) | Every step — full procedure |
+| [references/taxonomy.md](references/taxonomy.md) | Step 1; select archetype, mechanism, and context |
+| [references/feature-engineering.md](references/feature-engineering.md) | Step 4; shared decision-time rules |
+| [references/report-template.md](references/report-template.md) | Step 8; common report contract and overlay selection |
+| [references/terminology.md](references/terminology.md) | Step 8; fixed terms and language proofread |
+| [references/review-checklist.md](references/review-checklist.md) | Step 9; common and selected-profile checks |
+
+After Step 1, read only the selected profile references:
+
+| Dimension | References |
+|---|---|
+| Archetype | `references/archetypes/<archetype>.md` |
+| Mechanism | `references/mechanisms/<mechanism>.md` when present |
+| Context | `references/contexts/<context>.md` for every selected context |
+
+Current packs: archetypes `third-party-fraud`, `first-party-fraud`,
+`authorized-payment-scam`; mechanism `account-takeover`; contexts
+`card-payment`, `payment-collection`, `bank-transfer`, `payout`.
+
+## Progress
+
+Track a task plan. One item is `in_progress` at a time.
+
+1. Pass pre-flight
+2. Select analysis profile
+3. Formalize label
+4. Freeze time split
+5. Engineer candidate features
+6. Select shortlist
+7. Score candidate rules
+8. Map actions and packages
+9. Write business report and proofread language
+10. Independent review
+
+Suggested notes: `preflight=…`, `profile=…`, `label=…`, `cut=…`,
+`allowed/excluded=…`, `shortlist=…`, `N rules, holdout|in-sample`,
+`packages=…`, `report=…`, `verdict=…`.
+
+## Input
+
+CSV / XLSX / TXT; one row per event or case; optional outcome column. A dataset
+may contain more than one event type, but every scored rule needs a declared
+event grain and decision point.
+
+## Workflow
+
+Follow [references/workflow.md](references/workflow.md) for each step. The map:
+
+| Step | Do | Gate |
+|---|---|---|
+| 0 Pre-flight | Label provenance; pass / needs-user-input / descriptive-only / blocked | No supervised metrics until pass |
+| 1 Profile | Archetype + mechanism(s) + context(s) from taxonomy | Read selected packs before Step 2 |
+| 2 Label | Formalize positive / negative / unlabeled | Both classes defined before scoring |
+| 3 Time split | Freeze train/holdout before features | No random shuffle as headline |
+| 4 Features | Engineer candidates at decision time | Train-only thresholds |
+| 5 Shortlist | Lift / support / stability / operability | Train only |
+| 6 Score | occurrence → precision → recall on holdout | Headline = holdout |
+| 7 Actions | Map to context packs + strategy packages | Freeze packages before report |
+| 8 Report | Business report per template; grep terminology banned strings | No review process in the file |
+| 9 Review | Checklist + selected packs | Prefer fresh independent reviewer |
+
+## Output contract
+
+| Item | Requirement |
+|---|---|
+| Analysis profile | Archetype, role, consent, technical authentication, mechanism, context, confidence, grain, decision point |
+| Rule metrics | occurrence → precision → recall; headline window identified |
+| Strategy coverage | triggered count + rate and amount + share, with currency |
+| Domain impact | Measures and denominators from selected context packs only |
+| Uncertainty | Proxy labels, immature outcomes, weak identity links, and unresolved attribution stated |
+| Report file | Business content only; no reviewer model, verdict, or repair log |
+
+Steps 0–7 are analysis and its entry gate. Step 8 writes the report. Step 9
+reviews it.

package/skills/payment/fraud-analysis/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "fraud-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Analyze transfers.csv. The transactions passed login and MFA, but customers later confirmed they did not initiate them. Most transfers followed a password reset and new beneficiary setup. Find rules we can apply before transfer execution.",
+      "expected_output": "Routes to third-party fraud with account-takeover mechanism and bank-transfer context; separates technical authentication from customer consent; excludes later customer confirmation from pre-transfer features; proposes point-in-time access, beneficiary, and transfer features."
+    },
+    {
+      "id": 2,
+      "prompt": "Analyze collections_and_payouts.xlsx for customers who knowingly receive funds from many unrelated payers and rapidly cash out to linked beneficiaries. Confirmed investigation outcomes identify participating account holders.",
+      "expected_output": "Routes to first-party fraud with payment-collection and payout contexts; uses confirmed knowing participation as the label; engineers point-in-time fan-in, fan-out, collection-to-payout, account, device, and graph features; reports hold/review workload, delay, legitimate-customer impact, and exposure."
+    },
+    {
+      "id": 3,
+      "prompt": "Analyze bank_transfers.csv for APP scams. Customers themselves sent the payments after impersonation calls. We have later scam claims, reimbursement decisions, beneficiary data, warning interactions, and transfer timestamps.",
+      "expected_output": "Routes to authorized payment scam with APP subtype and bank-transfer context; treats customers as deceived victims; distinguishes claims and reimbursement decisions from decision-time features; evaluates warnings, confirmation, review, delay, completion, and reimbursement impact."
+    },
+    {
+      "id": 4,
+      "prompt": "Review card_auths.csv and propose pre-authorization rules for confirmed stolen-card transactions. It includes BIN, token, amount, CVV response, AVS response, issuer decline code, 3DS result, and chargeback outcome.",
+      "expected_output": "Routes to third-party fraud and card-payment; preserves card/BIN/history feature guidance; excludes current CVV, AVS, authorization response, 3DS result, and chargeback outcome at pre-auth; evaluates block, 3DS, or monitor actions with correct authorization denominators."
+    },
+    {
+      "id": 5,
+      "prompt": "Analyze suspicious payout accounts. Some may be knowing mules, some may be scam victims, and some may have been taken over. The file has behavior flags but no completed investigations or customer-consent evidence.",
+      "expected_output": "Keeps archetype unclassified rather than forcing mule, scam, or ATO attribution; treats behavior flags as proxy signals; avoids a blended confirmed-fraud label; limits severe actions and clearly states attribution and evidence gaps."
+    },
+    {
+      "id": 6,
+      "prompt": "Use outcome.csv where the existing case_result column has CONFIRMED_FRAUD, LEGITIMATE, and PENDING. Treat CONFIRMED_FRAUD as positive and analyze the rules.",
+      "expected_output": "Records file-column provenance; maps CONFIRMED_FRAUD to positive, LEGITIMATE to negative, and PENDING to unlabeled rather than negative; reports all counts and computes the base rate over labeled mature rows."
+    },
+    {
+      "id": 7,
+      "prompt": "For transfers.csv, define positives as accounts with at least three payouts within one hour after receiving funds. Find first-party fraud rules.",
+      "expected_output": "Pre-flight recognizes a user-defined positive condition and asks the user to define the negative condition before profile selection or supervised analysis; does not treat every other account as negative; leaves unmatched rows unlabeled."
+    }
+  ]
+}

package/skills/payment/fraud-analysis/references/archetypes/authorized-payment-scam.md

@@ -0,0 +1,41 @@
+# Archetype: authorized payment scam
+
+The genuine customer consents to a payment but is deceived about the recipient
+or purpose. The customer is the victim and is not knowingly party to the fraud.
+
+Use subtype `app-scam` only for an authorized push payment, normally a bank
+transfer. Record the scam subtype when supported, such as impersonation,
+purchase, investment, romance, or invoice redirection; do not infer it from
+amount or beneficiary shape alone.
+
+## Label guidance
+
+Prefer adjudicated scam outcomes. Customer reports, recalls, warnings ignored,
+beneficiary risk, and reimbursement decisions can be useful but may be proxies
+or policy outcomes rather than ground truth. Distinguish scams from civil
+disputes and first-party participation.
+
+## Feature families
+
+- New beneficiary, beneficiary risk, payee-name mismatch, and counterparty graph
+- Unusual amount, frequency, payment purpose, and deviation from customer history
+- Session/payment journey, warning interaction, confirmation responses, and
+  contact-channel changes available before execution
+- Urgency patterns, repeated limit-sized payments, and rapid beneficiary changes
+- Prior complaints or confirmed beneficiary outcomes known before the payment
+
+## Actions and impact
+
+Potential actions include contextual warning, payee confirmation, customer
+confirmation, cooling-off delay, manual review, transfer hold, or reject where
+policy permits. Measure warning/review/hold volume and value, completion and
+abandonment, review workload, delay, reimbursement exposure, and confirmed scam
+value captured. Do not optimize only for authorization success.
+
+## Review overlay
+
+- Genuine customer consent and deception are both supported.
+- The customer is not knowingly participating; otherwise route to first-party.
+- APP terminology is used only for push payments.
+- Post-payment reports, recalls, reimbursements, and investigations do not leak.
+- Warnings and holds account for vulnerable-customer and policy considerations.