@1aboveio/skills 0.19.2 → 0.20.1

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

@@ -11,9 +11,7 @@ export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
   'ensure-coverage',
   'implement-and-pr',
   'rush-issues',
-  'resolve-issues',
   'rush-release',
-  'resolve-release',
   'review-pr',
   'smoke',
   'engineering-runtime',
@@ -66,23 +64,7 @@ export const WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES = deepFreeze([
     ],
     generatedIdentities: [],
   },
-  {
-    invokedSkill: 'resolve-issues',
-    members: [
-      'tdd',
-      'harness-runtime',
-      'e2e-test',
-      'ensure-coverage',
-      'implement-and-pr',
-      'resolve-issues',
-      'review-pr',
-      'smoke',
-      'engineering-runtime',
-    ],
-    generatedIdentities: [
-      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
-    ],
-  },
+
   {
     invokedSkill: 'rush-release',
     members: [
@@ -91,22 +73,7 @@ export const WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES = deepFreeze([
     ],
     generatedIdentities: [],
   },
-  {
-    invokedSkill: 'resolve-release',
-    members: [
-      'harness-runtime',
-      'e2e-test',
-      'ensure-coverage',
-      'resolve-issues',
-      'resolve-release',
-      'review-pr',
-      'smoke',
-      'engineering-runtime',
-    ],
-    generatedIdentities: [
-      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
-    ],
-  },
+
 ]);
 
 // First-party content is distributed as an exact public npm release, so its identity is the package
@@ -119,7 +86,7 @@ export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
     id: 'first-party',
     type: 'first-party',
     package: '@1aboveio/skills',
-    version: '0.19.2',
+    version: '0.20.1',
   },
   matt: {
     id: 'matt-pocock',

package/skills/cicd-pipeline/mergify/SKILL.md

@@ -128,7 +128,7 @@ conflict, never hold the batch window open. Mechanics and the grouping rule
 
 - [cloud-build](../cloud-build/SKILL.md) — the CI the queue gates on
 - [cloud-debug](../cloud-debug/SKILL.md) — when the CI job itself is failing
-- [resolve-issues](../../engineering/resolve-issues/SKILL.md) — consumes this skill's delivery
+- [rush-issues](../../engineering/rush-issues/SKILL.md) — consumes this skill's delivery
   watch contract when it delivers merge-ready PRs through Mergify
 - `mergify-config`, `mergify-merge-queue`, `mergify-merge-protections`, `mergify-ci`,
   `mergify-stack` (vendor plugin skills) — reference for raw CLI invocation. They document

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

@@ -6,9 +6,7 @@
     "ensure-coverage",
     "implement-and-pr",
     "rush-issues",
-    "resolve-issues",
     "rush-release",
-    "resolve-release",
     "review-pr",
     "smoke",
     "engineering-runtime"
@@ -58,26 +56,6 @@
       ],
       "generatedIdentities": []
     },
-    {
-      "invokedSkill": "resolve-issues",
-      "members": [
-        "tdd",
-        "harness-runtime",
-        "e2e-test",
-        "ensure-coverage",
-        "implement-and-pr",
-        "resolve-issues",
-        "review-pr",
-        "smoke",
-        "engineering-runtime"
-      ],
-      "generatedIdentities": [
-        {
-          "member": "resolve-issues",
-          "path": "generated/workflow-repair-policy.json"
-        }
-      ]
-    },
     {
       "invokedSkill": "rush-release",
       "members": [
@@ -85,25 +63,6 @@
         "engineering-runtime"
       ],
       "generatedIdentities": []
-    },
-    {
-      "invokedSkill": "resolve-release",
-      "members": [
-        "harness-runtime",
-        "e2e-test",
-        "ensure-coverage",
-        "resolve-issues",
-        "resolve-release",
-        "review-pr",
-        "smoke",
-        "engineering-runtime"
-      ],
-      "generatedIdentities": [
-        {
-          "member": "resolve-issues",
-          "path": "generated/workflow-repair-policy.json"
-        }
-      ]
     }
   ],
   "digestAlgorithm": "sha256-path-content-v2",
@@ -383,7 +342,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
       "contentDigest": "eff6c7b5931bce5b2265a619bccddd371a89df6ce7bc2edc74f11d00060a71dd",
       "digestExcludes": []
@@ -396,7 +355,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
       "contentDigest": "d97abeff7bdc5ae2e4be2f631d09dba46d4753ce1e67334793364329af59f066",
       "digestExcludes": []
@@ -409,7 +368,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
       "contentDigest": "00cfdd3e5bfbc3e37b1369ad93aae91161e671829760a8867ea9be25047ba461",
       "digestExcludes": []
@@ -422,7 +381,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
       "contentDigest": "58b0556228a9271cf9e33727a05fc08a4fdfd29512ec0936b169f0a55d60e6ef",
       "digestExcludes": []
@@ -435,24 +394,11 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
       "contentDigest": "4664873230f22de2fcf46b7b529570cfedabdc850620031d8f96baf89fcdc5b4",
       "digestExcludes": []
     },
-    {
-      "installName": "resolve-issues",
-      "ownership": "owned",
-      "sourcePath": "skills/engineering/resolve-issues",
-      "expectedSource": {
-        "id": "first-party",
-        "type": "first-party",
-        "package": "@1aboveio/skills",
-        "version": "0.19.2"
-      },
-      "contentDigest": "a2df894683012581ce57e92d6e2dacd7eb377e4a0547a98acaea04878ef6aa3a",
-      "digestExcludes": []
-    },
     {
       "installName": "rush-release",
       "ownership": "owned",
@@ -461,24 +407,11 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
       "contentDigest": "01c192d8b4fd416af4ea02e8000e5fce0cee723a6ac2f8c0c48372087e1a262e",
       "digestExcludes": []
     },
-    {
-      "installName": "resolve-release",
-      "ownership": "owned",
-      "sourcePath": "skills/engineering/resolve-release",
-      "expectedSource": {
-        "id": "first-party",
-        "type": "first-party",
-        "package": "@1aboveio/skills",
-        "version": "0.19.2"
-      },
-      "contentDigest": "ffba0c83491676794c74721f4c6dbae430f5bc186e5a55f0764e29eaeb13829b",
-      "digestExcludes": []
-    },
     {
       "installName": "review-pr",
       "ownership": "owned",
@@ -487,7 +420,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
       "contentDigest": "f048fd00c69f2dc666fc7a3096cfeee6dfba73933bfb69602f3f0e26159798cc",
       "digestExcludes": []
@@ -500,9 +433,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
-      "contentDigest": "90a7c4e1ad6da1e632ea2c5259e4967ffebb84353adccbca8dfc5d6bc50b60c1",
+      "contentDigest": "27861f6dac89c32a97a7d249ce2695cea2d3d80dd2e9bc0607b0c4048a0e3b25",
       "digestExcludes": []
     },
     {
@@ -513,15 +446,15 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2"
+        "version": "0.20.1"
       },
-      "contentDigest": "ab98e937973720aedf6f79a63e99650fe3488f4f798d46ed3ae606f0b12a2a41",
+      "contentDigest": "3e0952beee7078463464872943d414fa944b395ae723ec78b385a28a3548897a",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "0fb67095c481e3a37f57b149e3557c5e450fa93fa3077888ab1eb2bf1ac3d196",
+  "releaseIdentity": "baec385a2bc0414623c97a83ac4ebf3c44ede2654185b748a03ef955cb3f1c8d",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",
@@ -579,7 +512,7 @@
         "sourceId": "first-party",
         "sourceType": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.19.2",
+        "version": "0.20.1",
         "installPath": null,
         "members": [
           "harness-runtime",
@@ -587,9 +520,7 @@
           "ensure-coverage",
           "implement-and-pr",
           "rush-issues",
-          "resolve-issues",
           "rush-release",
-          "resolve-release",
           "review-pr",
           "smoke",
           "engineering-runtime"
@@ -597,7 +528,7 @@
         "commands": [
           {
             "transport": "npm",
-            "command": "npx @1aboveio/skills@0.19.2 install --group engineering-workflow --yes"
+            "command": "npx @1aboveio/skills@0.20.1 install --group engineering-workflow --yes"
           }
         ],
         "onFailure": {

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

@@ -288,7 +288,7 @@ function validateManifest(manifest) {
     add('digest-algorithm-invalid', 'engineering-runtime', 'The coherence digest algorithm is missing or unsupported.');
   }
   if (JSON.stringify(manifest.ownedMembers) !== JSON.stringify(WORKFLOW_OWNED_MEMBERS)) {
-    add('owned-census-invalid', 'engineering-runtime', 'The exact ten-member Workflow ownership census is missing or malformed.');
+    add('owned-census-invalid', 'engineering-runtime', 'The exact eight-member Workflow ownership census is missing or malformed.');
   }
   if (JSON.stringify(manifest.dependencies) !== JSON.stringify([
     { groupId: 'matt-pocock-toolkit', members: MATT_DEPENDENCY_MEMBERS },
@@ -297,11 +297,9 @@ function validateManifest(manifest) {
     add('dependency-census-invalid', 'engineering-runtime', 'The exact Matt and harness runtime dependency census is missing or malformed.');
   }
   if (!exactContract(manifest.dependencyClosures, WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES)) {
-    const names = new Set(Array.isArray(manifest.dependencyClosures)
-      ? manifest.dependencyClosures.map((closure) => closure?.invokedSkill)
-      : []);
-    const member = WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES.find((closure) => !names.has(closure.invokedSkill))?.invokedSkill
-      ?? 'resolve-issues';
+    const actual = Array.isArray(manifest.dependencyClosures) ? manifest.dependencyClosures : [];
+    const member = WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES.find((closure, index) =>
+      !isDeepStrictEqual(actual[index], closure))?.invokedSkill ?? 'engineering-runtime';
     add('dependency-closure-invalid', member, 'The invoked-skill dependency closure is missing, weakened, reordered or malformed.');
   }
 

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

@@ -11,9 +11,7 @@ export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
   'ensure-coverage',
   'implement-and-pr',
   'rush-issues',
-  'resolve-issues',
   'rush-release',
-  'resolve-release',
   'review-pr',
   'smoke',
   'engineering-runtime',
@@ -66,23 +64,7 @@ export const WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES = deepFreeze([
     ],
     generatedIdentities: [],
   },
-  {
-    invokedSkill: 'resolve-issues',
-    members: [
-      'tdd',
-      'harness-runtime',
-      'e2e-test',
-      'ensure-coverage',
-      'implement-and-pr',
-      'resolve-issues',
-      'review-pr',
-      'smoke',
-      'engineering-runtime',
-    ],
-    generatedIdentities: [
-      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
-    ],
-  },
+
   {
     invokedSkill: 'rush-release',
     members: [
@@ -91,22 +73,7 @@ export const WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES = deepFreeze([
     ],
     generatedIdentities: [],
   },
-  {
-    invokedSkill: 'resolve-release',
-    members: [
-      'harness-runtime',
-      'e2e-test',
-      'ensure-coverage',
-      'resolve-issues',
-      'resolve-release',
-      'review-pr',
-      'smoke',
-      'engineering-runtime',
-    ],
-    generatedIdentities: [
-      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
-    ],
-  },
+
 ]);
 
 // First-party content is distributed as an exact public npm release, so its identity is the package
@@ -119,7 +86,7 @@ export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
     id: 'first-party',
     type: 'first-party',
     package: '@1aboveio/skills',
-    version: '0.19.2',
+    version: '0.20.1',
   },
   matt: {
     id: 'matt-pocock',

package/skills/engineering/smoke/SKILL.md

@@ -113,7 +113,7 @@ The **per-PR golden-path liveness floor** (`ensure-coverage` CI contract, gate 8
 - **CI (gate 8, blocking)** — wired in `e2e-test/assets/ci-gates.*`; boots the app, drives the paths into `smoke-results.json`, runs `smoke.mjs verdict`. The mechanical backstop.
 - **`resolve-issues`** — final step of the [epic integration gate](../resolve-issues/references/deliverables.md#deliverables-the-shippable-component-not-the-whole-epic): boot the assembled integration branch and run the golden paths; a DEAD whose broken paths are `fail` belongs to a specific unit → reopen its fix loop. **A DEAD built from `blocked`/`missing` paths is a gate-environment problem, not a unit's defect** — report it and fix the environment; reopening a fix loop on it spends a producer spawn and an adversarial review on code that is fine, and the round lands in the unit's budget all the same.
 - **`/smoke`** — standalone, any time, against `local` or a URL.
-- **`resolve-release`** — [the exposure gate](../resolve-release/SKILL.md#the-release-loop): the `prod-preview` profile against the 0%-traffic candidate URL (read-only, so it excludes every mutating path), then the `prod-active` profile against the live service after the shift. A DEAD **before** exposure deletes the candidate (no rollback, no user impact); a DEAD after it triggers the rollback policy.
+- **Legacy `resolve-release` flow (archived)** — the `prod-preview` profile against the 0%-traffic candidate URL (read-only, so it excludes every mutating path), then the `prod-active` profile against the live service after the shift. A DEAD **before** exposure deletes the candidate (no rollback, no user impact); a DEAD after it triggers the rollback policy.
 - **The dev-deploy recorder** (`cloud-build` → Post-deploy smoke gate) — the integration pipeline runs this gate after its 100%-traffic deploy and publishes the verdict as a **SHA-keyed commit status**, never failing the build; that recorded ALIVE is what `resolve-release` requires when pinning a release candidate (its principle 11).
 
 ## Reference Map

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

@@ -5,13 +5,15 @@ description: >
   extracts (optional chargebacks): executive summary, top statistics, payment
   journey Sankey, and topics (volume, WoW trend, auth rate, BIN-country
   contribution, decline-by-reason, decline-by-country). Amounts report in USD
-  (Forex Service daily conversion). Chargebacks use Visa same-month and
-  Mastercard lagged 拒付率. 运营影响 is 3DS / 风控拦截 / soft-decline retry
-  only. Use whenever the user asks for payment overview, auth-rate analysis,
+  (Forex Service daily conversion). Chargebacks separate normal and
+  pre-dispute cases; Visa pre-disputes are excluded from VAMP-style metrics
+  and calculated separately, while Mastercard 拒付率 is lagged. 运营影响 is
+  3DS / 风控拦截 / soft-decline retry only. Use whenever the user asks for payment overview, auth-rate analysis,
   decline mix, BIN/issuer-country contribution, settlement GMV, payment journey,
   Sankey funnel, FX-to-USD, chargeback rate, 运营影响, or "business analysis of
   transactions" — even if they do not say payment-analysis. Do NOT use for
-  supervised fraud-rule mining (that is fraud-analysis).
+  supervised fraud-rule mining (fraud-analysis) or TLD / MCC-miscoding
+  clusters (tld-detection).
 ---
 
 # Payment Analysis
@@ -30,7 +32,7 @@ optional topic fuel, not required for the journey core.
 
 **Produce:** Markdown + preferred Chinese/bilingual HTML under
 `reports/payment-analysis/`.  
-**Do not produce:** supervised precision/recall packages (`fraud-analysis`).
+**Do not produce:** supervised precision/recall packages (`fraud-analysis`) or TLD clusters (`tld-detection`).
 
 Read the playbook for the step you are on. Paths under `references/` are
 relative to this skill.
@@ -57,7 +59,8 @@ Compute auth + settlement metrics from [metrics.md](references/metrics.md).
 Convert non-USD amounts per [fx.md](references/fx.md) before any sum or share.
 If chargebacks are present, monthly 拒付率 follows
 [chargebacks.md](references/chargebacks.md) (Visa same-month, Mastercard lagged,
-skip empty brand-months, no blended Visa+Mastercard ratio).
+Visa pre-disputes excluded from the normal/VAMP-style numerator and calculated
+separately, skip empty brand-months, no blended Visa+Mastercard ratio).
 
 ### 3 — Journey Sankey
 
@@ -98,16 +101,19 @@ Do not change numbers, joins, or chart data.
 - [ ] Amount axes/legends include currency (`授权尝试金额 USD`, …)
 - [ ] No supervised fraud-rule metrics
 - [ ] Non-USD amounts converted per fx.md; all-USD books say 金额均为 USD
+- [ ] Normal chargebacks, pre-disputes, and unclassified cases are distinct
+- [ ] Visa pre-disputes are excluded from VAMP-style metrics and calculated separately
 - [ ] Chargeback monthly rates skip empty brand-months; no blended Visa+MC ratio
 - [ ] 运营影响 only from auth-rate-actions.md when triggered
 - [ ] Language matches terminology.md; banned strings have no unexplained hits
 
-## Boundary with fraud-analysis
+## Boundary with fraud-analysis and tld-detection
 
 | Need | Skill |
 |---|---|
 | Volume, journey Sankey, auth rate, decline mix, settlement overview, 运营影响 routing | `payment-analysis` |
 | Proxy/confirmed fraud labels, holdout precision/recall, 3DS/block **packages** | `fraud-analysis` |
+| Potential TLD clusters, currency-amount-pair ladders, MCC miscoding, stuffing | `tld-detection` |
 
 Routing 3DS / 风控拦截 / retry from this extract is not a fraud-analysis rule
 package.

package/skills/payment/payment-analysis/references/chargebacks.md

@@ -1,4 +1,4 @@
-# Chargeback / dispute rate (Visa vs Mastercard)
+# Chargeback / dispute rate (normal vs pre-dispute; Visa vs Mastercard)
 
 Topic **4.8 拒付 / 争议**. Put the Visa / Mastercard formulas as a **note
 under the monthly rate chart**. Count rates follow card-network monitoring
@@ -10,43 +10,67 @@ below are the processor restatements used in production monitoring
 (Stripe, Braintree). Caption the report as **network-style estimates
 from this extract**, not as a Visa/Mastercard identification notice.
 
+## Classify case stage first
+
+Before calculating rates, classify each row from an explicit processor or
+network case-stage/type/status field:
+
+- **Normal chargeback / dispute**: a formally opened chargeback/dispute.
+- **Pre-dispute**: explicitly identified as pre-dispute, RDR, CDRN, early
+  resolution, or the processor's equivalent pre-dispute product.
+- **Unclassified**: the extract does not reliably identify the case stage.
+
+Use the processor's data dictionary when labels are unclear. Do not infer
+pre-dispute status from reason code, amount, timing, outcome, or free-text
+description alone. Report counts and amounts for all three classes separately;
+never silently treat pre-dispute or unclassified rows as normal chargebacks.
+
+If no reliable classification field exists, report the separation as
+unavailable. An all-case Visa dispute rate may be shown as descriptive only,
+but it must not be called a normal chargeback rate or VAMP-style estimate.
+
 ## When a point is drawn
 
-A monthly point for a card brand is drawn **only if**
+A monthly point for a brand and case-stage series is drawn **only if**
 
-- numerator (chargebacks **received** that calendar month for that brand) > 0, and
+- numerator for that specific series **received** in that calendar month > 0, and
 - denominator (sales count for that brand, month as defined below) > 0.
 
 Otherwise **omit the point**. Do not plot `0`. Do not invent a prior-month
-sale count. If a brand has no drawable points, omit the series. If no
-series remain, omit the rate chart (keep the reason-category bars if CBs
-exist).
+sale count. If a series has no drawable points, omit it. If no series remain,
+omit the rate chart (keep case-stage and reason-category bars if cases exist).
 
 ## Formulas (count)
 
-Numerator for both brands: chargebacks **received** in calendar month `M`
-(`Chargeback date`), `Payment method` = that brand. Not original
-transaction month. Inquiries / RDR-cleared cases are not in this extract;
-count every CB row.
+Numerators use cases **received** in calendar month `M` (`Chargeback date`),
+`Payment method` = that brand. Do not use original transaction month. Apply
+the case-stage classification before counting.
 
-| Brand | Programme (current) | Rate |
+| Brand / series | Programme alignment | Rate |
 |---|---|---|
-| Visa | VAMP dispute/sales count (same month) | `CB_Visa(M) / Sales_Visa(M)` |
-| Mastercard | ECP / ECM chargeback rate (lagged sales) | `CB_MC(M) / Sales_MC(M−1)` |
+| Visa normal chargeback | VAMP dispute/sales timing (same month) | `Normal_CB_Visa(M) / Sales_Visa(M)` |
+| Visa pre-dispute | Descriptive; excluded from VAMP | `PreDispute_Visa(M) / Sales_Visa(M)` |
+| Mastercard normal chargeback | ECP / ECM chargeback timing (lagged sales) | `Normal_CB_MC(M) / Sales_MC(M−1)` |
 
 `Sales_*` = settlement type Sale, that brand, **transaction/capture month**.
 Do not mix refunds into the denominator.
 
 Mastercard **must** use the previous calendar month’s sales. If `M−1`
-sales are missing from the extract, skip Mastercard for month `M`.
+sales are missing from the extract, skip Mastercard for month `M`. Keep any
+Mastercard pre-dispute rows separate from its normal chargeback numerator; this
+skill does not calculate a Mastercard pre-dispute rate unless the user asks.
 
 ## Visa notes (do not over-claim VAMP)
 
 Since 2025-04 Visa folded VDMP/VFMP into **VAMP**. Full VAMP Count is
 `opened Visa chargebacks (TC15) + reported fraud (TC40 EFW)`, same-month
-sales in the denominator. This skill’s extract usually has chargebacks
-only → report **Visa 拒付率 = Visa CB count / Visa same-month sales**.
-Do not label it “VAMP ratio” unless TC40/EFW is in the file.
+sales in the denominator. **Pre-dispute cases are not opened chargebacks and
+must be excluded from the TC15/VAMP-style numerator.** This skill's extract
+usually has chargebacks only → report **Visa normal 拒付率 = normal Visa CB
+count / Visa same-month sales**, plus **Visa pre-dispute rate = Visa
+pre-dispute count / Visa same-month sales** as a separate descriptive series.
+Do not add the two series together. Do not label the normal rate “VAMP ratio”
+unless TC40/EFW is present and the extract supports the full VAMP definition.
 
 VAMP also has volume and enumeration legs; those are out of scope here.
 
@@ -62,7 +86,8 @@ it for ECP.
 ## Amount rate (optional footnote)
 
 `abs(dispute amount) / sale amount` with the **same month alignment as
-the count rate** for that brand. Secondary; the line chart is count %.
+the count rate** for that brand. Keep normal and pre-dispute amounts separate.
+Secondary; the line chart is count %.
 
 ## Window caveat
 

package/skills/payment/payment-analysis/references/event-layers.md

@@ -53,6 +53,10 @@ Reporting amounts are USD. Conversion rules: [fx.md](fx.md).
 Chargeback **programme 拒付率** uses received month (`Chargeback date`) per
 [chargebacks.md](chargebacks.md). If you also show origination-month incidence,
 label that separately so it is not mistaken for the Visa/Mastercard rate.
+Before calculating a programme-style rate, identify the processor field that
+distinguishes normal chargebacks from pre-disputes. Keep unclassified cases
+separate; pre-disputes are excluded from Visa VAMP-style metrics and reported
+as a separate Visa rate.
 
 ## Decline taxonomy (auth)
 

package/skills/payment/payment-analysis/references/metrics.md

@@ -38,18 +38,20 @@ Do not equalize settled sales to approved auth amount without a timing caveat.
 
 ## Chargebacks
 
-Monthly **拒付率** by brand is [chargebacks.md](chargebacks.md): Visa
-same-month sales, Mastercard previous-month sales, skip empty brand-months,
-no blended Visa+Mastercard ratio. The table below is mix / match, not that
-programme rate.
+Monthly **拒付率** by brand is [chargebacks.md](chargebacks.md): classify normal,
+pre-dispute, and unclassified cases first; Visa uses same-month sales and
+reports pre-disputes separately; Mastercard normal chargebacks use
+previous-month sales. Skip empty brand-months and do not blend Visa+Mastercard.
+The table below is mix / match, not that programme rate.
 
 | KPI | Formula | Notes |
 |---|---|---|
-| CB count / dispute amount | as filed | Amounts USD after [fx.md](fx.md); use abs for magnitude if signed |
+| Normal / pre-dispute / unclassified count and amount | as classified | Amounts USD after [fx.md](fx.md); use abs for magnitude if signed |
 | Reason mix | by Reason category / code | Fraud ≠ all CBs |
 | Match rate to auths | matched / CB rows | State join key |
-| Visa monthly 拒付率 | CB_Visa(M) / Sales_Visa(M) | Received month; not VAMP unless TC40 in file |
-| Mastercard monthly 拒付率 | CB_MC(M) / Sales_MC(M−1) | Skip M if M−1 sales missing |
+| Visa normal monthly 拒付率 | Normal_CB_Visa(M) / Sales_Visa(M) | Excludes pre-disputes; received month; not VAMP unless TC40 is present |
+| Visa pre-dispute rate | PreDispute_Visa(M) / Sales_Visa(M) | Separate descriptive series; excluded from VAMP-style numerator |
+| Mastercard normal monthly 拒付率 | Normal_CB_MC(M) / Sales_MC(M−1) | Excludes pre-disputes; skip M if M−1 sales missing |
 
 Lag: chargeback date is later than original auth. Programme rates use
 **received** month, not origination vintage.

package/skills/payment/payment-analysis/references/report-template.md

@@ -54,8 +54,8 @@ KPI cards / table from auth + settlement: attempts, approvals, auth rate,
 attempt amount, approved amount, sale count/amount, refund count/amount, net
 settled, distinct PAN/BIN/countries, portfolio constants (MID, MCC, provider).
 
-Chinese labels: 授权尝试, 授权成功, 授权成功率, 授权成功金额, 清算销售, 退款,
-净清算, 发卡行国家.
+Chinese labels: 授权尝试, 授权成功, 授权成功率, 授权成功金额,
+已清算交易笔数, 已清算金额, 退款, 净清算, 发卡行国家.
 
 ### 3. Payment journey (Sankey) / 支付旅程
 
@@ -79,7 +79,7 @@ Each topic: short lede + chart(s) + supporting table.
 | 4.5 Decline reason | count bars |
 | 4.6 Decline by country | stacked count bars |
 | 4.7 Settlements | sale/refund amount bars; country contribution dual axis |
-| 4.8 Chargebacks | reason-category bars; Visa / Mastercard monthly 拒付率 line per [chargebacks.md](chargebacks.md) (note under the rate chart; skip empty brand-months) |
+| 4.8 Chargebacks | normal vs pre-dispute counts/amounts; reason-category bars; Visa normal 拒付率 and separate Visa pre-dispute-rate series; Mastercard normal monthly 拒付率 per [chargebacks.md](chargebacks.md) (note under the rate chart; skip empty brand-months) |
 
 Use both authorization and settlement data when both files are present.
 

package/skills/payment/payment-analysis/references/terminology.md

@@ -24,7 +24,11 @@ writing English or Chinese copy. After writing, run the proofread step in
 | BIN country | 发卡行国家 / BIN 国家 | 客户国家；收货国；发卡国 |
 | Settlement | 清算 | |
 | Sale / Refund | 销售 / 退款 | 把销售金额写成清算金额 |
+| Settled transaction count | 已清算交易笔数 | 清算销售 |
+| Settled amount | 已清算金额 | 清算销售金额 |
 | Chargeback / dispute | 拒付 / 争议 | 与清算混用 |
+| Normal chargeback / dispute | 正常拒付 / 正常争议 | 与预争议合并 |
+| Pre-dispute | 预争议 | 计入 VAMP；与正常拒付合并 |
 | Clerical | 差错 | 文书；文书错误 |
 | Quality | 产品服务质量 | 质量；质量争议 |
 | Incidence | 发生率（必须写出分母） | |
@@ -37,7 +41,8 @@ writing English or Chinese copy. After writing, run the proofread step in
 | This analysis window | 当前分析时段内 | 本窗口 |
 | SCA | SCA | 强客户认证（可在首次括注后只用 SCA） |
 | Authentication / 3DS | 鉴权 / 认证 / 3DS | 把 3DS 叫转化 |
-| Visa / Mastercard 拒付率 | Visa / Mastercard 拒付率 | VAMP ratio（无 TC40 时）；ECM（从本抽取断言商户在项目中） |
+| Visa normal 拒付率 / Visa pre-dispute rate | Visa 正常拒付率 / Visa 预争议率 | 合并二者；把预争议计入 VAMP；VAMP ratio（无 TC40 时） |
+| Mastercard normal 拒付率 | Mastercard 正常拒付率 | ECM（从本抽取断言商户在项目中） |
 | Amounts in USD | 金额均为 USD | 未做汇率折算（当全部已是 USD） |
 | Count-heavy / amount-light | 授权尝试笔数多但金额小 | 走廊；笔数负担型走廊 |
 

package/skills/payment/payment-analysis/references/visualization.md

@@ -22,7 +22,7 @@ ECharts (Sankey). Markdown tables remain required beside charts.
 ## Axis hygiene
 
 - Label every axis with the full metric name. Amount axes/legends include
-  currency (`授权尝试金额 USD`, `授权拒绝金额 USD`, `清算销售金额 USD`,
+  currency (`授权尝试金额 USD`, `授权拒绝金额 USD`, `已清算金额 USD`,
   `拒付金额 USD`). Do not use bare `笔数` / `金额` / `%`.
 - Only one axis draws the main grid on dual-axis charts.
 - Stacked bars = mix within a group (e.g. decline reasons by country), never rate.