@1aboveio/skills 1.0.10 → 1.0.11

package/skills/risk-compliance/portfolio-payment-analysis/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: portfolio-payment-analysis
+description: >
+  Analyze submerchants in Helipay/Worldpay aggregator exports: compare merchants
+  and investigate selected merchants' authorization, settlement and disputes,
+  including descriptor mapping and overlapping exports. Portfolio-level payment
+  overviews belong to payment-analysis; fraud rule discovery belongs to fraud-detection.
+release-version: 0.45.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Portfolio payment analysis
+
+Before report drafting or substantive review, read
+`{house-style baseDir}/references/analytical-reporting.md` and its
+required writing-pattern and definition references. Use `write-report` for the report stage
+with this skill's merchant template, not `write-doc` or the portfolio report layout. Give
+delegated writers and reviewers the same resolved reference paths and require the reads;
+keep merchant metrics, confidentiality and specialist checks unchanged. Individual native
+selections also need `write-report` and its required `terminology` dependency; installation
+metadata does not load instructions. Missing required resources leave the report stage incomplete.
+
+Produce an internal submerchant report in Chinese by default, with merchant comparisons
+and detail for merchants the user selects. Treat the extracts as confidential; do not
+publish them or include cardholder data in the report. Use the installed
+`payment-analysis` skill as the base: read its `SKILL.md` and relevant references for
+periods, event layers, metrics, daily USD FX, disputes, visualization and editorial
+checks. This skill owns the aggregator report structure in
+[metrics and reporting](references/metrics-and-reporting.md); that template replaces
+the base report's chapter order and mandatory Sankey. Inherit the base's metric,
+FX, dispute, terminology and fact-preservation rules. Pass the aggregator template
+to editorial review. Scope any payment-stage evidence to a merchant; do not include a
+portfolio funnel or Sankey.
+
+For a clean individual native installation, select `portfolio-payment-analysis`,
+`payment-analysis`, `write-report`, `editorial-review`, `polish-cn`, `terminology`, and `house-style`; the native
+picker does not install dependencies automatically. The generated Payment install
+group recipe includes the dependency closure.
+
+## Workflow
+
+1. Inventory authorized Helipay/Worldpay inputs, source coverage, event dates,
+   timezone, currencies, identifiers, field dictionaries and reporting periods.
+   Record missing and partial layers. Use the requested period and merchant selection;
+   otherwise apply the base skill's period-selection rule, then pass both required
+   CLI dates explicitly. Identify an unsupported or unresolved period
+   rather than inventing one.
+2. Read [identity and reconciliation](references/identity-and-reconciliation.md)
+   before deduplication or joining. Build the mapping and reconciliation evidence;
+   scope every join to the same verified merchant and source namespace. Unknown or
+   conflicting identities are not reassigned by descriptor or order similarity.
+3. Read [metrics and reporting](references/metrics-and-reporting.md). Compute
+   merchant rates with merchant-specific denominators and disclose sample counts.
+   Include week-by-week comparisons for every submerchant within the report period,
+   using Monday–Sunday weeks and explicit partial-week labels. Compare other periods
+   for individual merchants when explicitly requested and supported.
+   Read [risk history](references/risk-history.md) for 340FRD, dispute histories
+   and VAMP. Use the base skill's FX and dispute rules; leave unsupported figures
+   unresolved, not zero.
+4. Present merchant findings, comparison, selected merchant detail and merchant-specific
+   investigation actions. Explain missing data, conflicts, unmatched records, rate
+   denominators and attribution limits. Keep totals only as internal reconciliation
+   evidence; do not report portfolio summaries, trends, decomposition, funnels or
+   overall dispute chapters.
+   Follow the base skill's editorial review, Chinese polish and fact-preservation
+   checks when producing a complete report.
+
+## CLI and scope
+
+The bundled workflow uses Python 3 standard-library scripts and local Worldpay CSV
+exports. It makes no network calls. Authorization data is required; settlement and
+dispute files are used when supplied. Run all three commands:
+
+```sh
+python3 {portfolio-payment-analysis baseDir}/scripts/analyze.py --input PATH --output OUTPUT --main-start YYYY-MM-DD --main-end YYYY-MM-DD
+python3 {portfolio-payment-analysis baseDir}/scripts/build_report.py --facts OUTPUT/facts.json --output OUTPUT
+# After editing or polishing presentation.json, rerender without rebuilding its narrative:
+python3 {portfolio-payment-analysis baseDir}/scripts/render.py --model OUTPUT/presentation.json --output OUTPUT
+```
+
+The calculator caps the requested end at the earliest last event date among supplied
+layers. It reports the effective cutoff and compares the corresponding prior-month
+dates. Source event ranges alone do not establish continuous coverage. Check period lengths
+and source coverage before interpreting a comparison.
+
+The report outputs are `overview.zh.html` and `overview.zh.md`, backed by the reviewed
+`presentation.json`. Supporting internal files are `facts.json`, `merchant-metrics.csv`,
+`merchant-mapping.csv`, `merchant-weekly.csv`, `merchant-segments.csv`,
+`merchant-detail-comparison.csv`, `merchant-risk-history.csv`, and
+`coverage-and-reconciliation.json`; legacy aggregate fields
+in these files are not report deliverables. The HTML is self-contained, supports
+merchant filtering and printing, and sends no data to external services. Use
+`--detail-merchant ID` on `build_report.py` (repeat it for several IDs) when the user
+names merchants. Otherwise expand the largest merchant by attempts and the lowest-rate
+merchant with at least 30 attempts, while keeping every other merchant available in
+collapsed detail sections. This is a navigation rule, not a significance test.
+Section 2 retains full weekly history. Section 3 uses charts to compare only this week
+with last week, matching weekdays when the current week is partial. Every merchant
+has BIN-country, card-product (payment method × card type), fixed USD amount-bucket,
+authentication and unsuccessful-response charts. Country and card-product charts use
+compact paired bars. Amount buckets use side-by-side histograms, unsuccessful responses
+use side-by-side bars, and authentication uses paired pies for counts and USD amounts,
+not rates. Each pair compares aligned weeks. Use the shared `comparison_charts.py` for
+all report charts. Section 3 omits settlement sales/refunds. Include merchant risk
+history charts as specified in the risk reference. Treat 340FRD file generation date
+as its report date, retaining the earliest date for exact repeats. Monthly dispute
+and fraud charts offer counts and network-style rate estimates with numerator and
+denominator details; weekly charts retain counts. Visa uses same-month sales,
+Mastercard ECP uses prior-month sales, and EFM uses fraud chargebacks divided by
+prior-month e-commerce sales, not all 340FRD Mastercard reports. Fix groups across the union of the
+two comparison periods, and display
+only those two ranges in chart legends and expandable metric-row tables. Follow the
+segment and denominator contract in the reporting reference.
+Include merchant-specific historical refund and dispute follow-ups in the action table
+when supported, without adding portfolio history chapters. If the user says a merchant is
+historical and out of this report, pass `--exclude-merchant ID` (repeat it for several IDs).
+That removes the merchant from comparison, weekly tables, detail, the action list, and every
+linked merchant CSV. State the exclusion once: it is not a closure finding and not missing data.
+Do not lead the report with an excluded merchant. A later rebuild without the flag puts the
+merchant back.
+
+The generated lowest-authorization-rate sentence only chooses an authorization review. It is
+not the investigation order. If fraud or predispute history would change who a reader checks
+first, put that merchant and month in the opening, and say whether the month is inside the
+report window. Do not title a real extract 样本报告; 样本 is only for a small attempt count.
+
+A packed week cell that includes dollars must say 授权成功 USD. The rule against repeating a
+metric label applies only when the column header already names that measure. When the sales
+column contains both 0.00 and blank, say which merchants have an observed zero and which have
+no settlement layer. An invalid or post-cutoff 340FRD file must state the effect on counts, not
+only the date. Unmatched fraud records must state the count and amount excluded from merchant
+figures.
+
+The report includes per-submerchant weekly counts, rates, successful authorization
+amount USD, settled sales, refunds and dispute observations. Each merchant's breakdown
+uses date/week columns and metric rows; successful authorization amount has its own
+row and never substitutes settled sales. Only adjacent full calendar weeks with available observations and valid
+denominators receive week-over-week changes; partial weeks retain their metrics but
+have no week-over-week change. Read the weekly contract in the reporting reference.
+
+The optional `--fx-rates` accepts caller-supplied daily USD rates. The CLI does not
+verify their provenance; obtain and preserve Forex Service evidence as specified by
+the base FX contract before relying on converted amounts. Without a required rate,
+the affected amount is unavailable while count metrics remain available. Render unavailable
+cells blank, not N/A; show only `USD 33...` in a USD value cell, without repeating its
+metric label. Remove extra explanatory prose while retaining necessary coverage limits.
+
+Source fields remain unchanged in JSON. CSV exports prefix spreadsheet-sensitive
+text with an apostrophe so opening a report does not execute merchant names or
+labels as formulas; numeric metrics remain numeric.
+
+Treat internal authorization counters together with `layer_observed.auth`: a zero
+observation count with that flag false is not confirmed zero business activity.
+The report and business CSV cells remain blank in that case. Distinguish observed
+dispute snapshots from deduplicated case-stage counts and verified opening counts;
+they answer different questions and need not match. Formatting-only aliases of a
+verified provider are duplicates, not new snapshots. Sales or refunds without
+stable event identity remain observations, not confirmed monetary totals.
+
+The report is an extract-based operational view. The v1 CLI refuses generation if
+any authorization or settlement identity has conflicting values; resolve those
+sources before rerunning. This conservative refusal can block clean periods too.
+It never substitutes totals from an unlabeled clean subset. An absent layer or a
+window without observed settlement/dispute rows produces unavailable metrics, not
+confirmed zero activity. Dispute rows remain observed
+snapshots until opening semantics are verified. The CLI computes supported
+network-style extract estimates, not official network assessments; unsupported rate
+cells stay blank. Merchant-scoped settlement and join evidence must not imply that all
+current-period sales descend from current-period approvals. Review the saved
+`presentation.json` as the narrative source, then rerender both formats. Preserve
+raw customer data in the input project; use synthetic fixtures for repository tests.

package/skills/risk-compliance/portfolio-payment-analysis/references/identity-and-reconciliation.md

@@ -0,0 +1,46 @@
+# Merchant identity and reconciliation
+
+## Identity and mapping
+
+Use `Sub merchant ID` as the stable merchant identity, scoped to the verified
+processor/aggregator namespace. Preserve IDs as strings, including leading zeros.
+A descriptor is a display label, not a key: record the source, observed label,
+merchant ID, coverage dates and mapping status. Retain multiple labels for one ID
+and distinguish identical labels belonging to different IDs. Do not merge IDs
+because their descriptors resemble each other. Report absent or unverified IDs in
+an explicit unknown bucket, without attributing them to a named merchant. Expose
+unknown counts and amounts and any mapping conflicts.
+
+## Event grain, overlap and corrections
+
+Identify each source's event key and grain from its dictionary before counting:
+authorization attempts, settlement sale/refund events and dispute stage openings
+are different events. Namespace keys by source and merchant where appropriate.
+Keep source paths and snapshot evidence. Deduplicate repeated exports only when
+verified event identity and material values agree. Repeated identical records count
+once. For differing values on one event, use a verified revision sequence or timestamp
+only when the source establishes correction semantics; disclose the restatement.
+Otherwise retain the conflict in reconciliation and mark affected metrics unresolved.
+A missing or ambiguous event key is not permission to collapse rows on order ID,
+amount, date or descriptor. Report raw, unique, duplicate, conflicting and unresolved
+counts per layer and the scope and coverage of each input.
+
+## Join boundaries
+
+Join only within the same verified merchant identity and compatible source namespace,
+using the documented event relationship (for example, order ID within merchant for
+an auth-to-sale relationship). A shared order ID alone is not globally unique. Preserve
+one-to-many captures and refunds without multiplying authorization counts; report
+match rates and unmatched or ambiguous records. If an identity or relationship is
+unverified, leave it unjoined and disclose the affected figures. An unknown merchant
+bucket is not a shared identity: do not join unknown records to each other just because
+they share a bucket. Never transfer a case or transaction across merchant boundaries.
+
+## Disputes
+
+Use `payment-analysis`'s `references/chargebacks.md`: distinguish stage-opening
+pre-disputes and formal chargebacks from later status updates or repeated snapshots.
+Count distinct verified stage openings, including a verified escalation as a separate
+stage, not as an extra unique case. If stage, opening date, link or revision cannot
+be established, mark affected cells unresolved. Never invent a stage or count status
+updates as new disputes. Keep unclassified cases separate and report coverage.

package/skills/risk-compliance/portfolio-payment-analysis/references/metrics-and-reporting.md

@@ -0,0 +1,170 @@
+# Metrics and report
+
+## Calculation and coverage
+
+Use the installed `payment-analysis` references for formulas, FX, disputes and
+terminology. For each merchant rate, show the merchant-specific numerator,
+denominator, population and dates. A zero denominator is undefined. A known zero
+requires coverage of the relevant period and population; missing layers, unverified
+identity, conflicts and missing historical coverage are not zeros. Show small samples
+with raw counts and a caveat. Do not rank unavailable rates.
+
+Keep authorization, settlement, refund and dispute measures separate. Approval is
+not settlement. Scope countries, decline reasons, authentication, settlement and
+disputes to the merchant and the relevant event population. Do not imply that all
+sales in a period descend from approvals in that period. Dispute snapshots are not
+necessarily new openings; apply the base dispute rules and disclose unverified stage,
+opening and coverage. Missing FX leaves affected USD amounts unresolved rather than
+creating mixed-currency totals. Apply the verified 340FRD and dispute history contract
+in [risk history](risk-history.md); do not use those observations as VAMP inputs.
+
+For an explicitly requested merchant-specific period comparison, state each date
+range, actual duration, cutoff and coverage. Prior-month endpoints may clamp to the
+month's last day, changing duration. Do not infer a merchant's onboarding or departure
+from observation in only one period. An extract-based comparison is not proof of
+complete coverage or causation. Portfolio totals may support internal reconciliation,
+including the unknown bucket, but are not report content.
+
+## Weekly submerchant comparison
+
+Include every Monday–Sunday calendar week intersecting the effective report period
+for every submerchant, including weeks with no observed events. Preserve the full
+calendar boundaries and the included date range. Mark edge weeks shorter than seven
+days as partial; never silently compare a partial week with a full week.
+
+Show per-merchant weekly attempts, approvals, approval rate, successful authorization
+amount USD, sales USD, refunds and observed dispute records. Successful authorization
+amount sums `Transaction amount` only where `Response type` is approval, using the
+authorization date and daily USD rates from the base FX contract. Never substitute
+settlement amount. Missing approved amounts, currencies or rates make the affected
+sum unavailable; no auth observations also yield an unavailable sum. Observed auths with no approvals have
+an observed approved amount of zero. Keep the merchant's numerator and denominator together.
+Use authorization time, settlement date and dispute date consistently with the base
+metrics. Missing layer observations or FX make affected measures unavailable, not
+zero growth or confirmed zero activity.
+
+Week-over-week changes use only the immediately preceding calendar week. Both weeks
+must be full seven-day bins. Compare only measures whose layer has observations in
+both weeks; relative changes additionally require a positive previous denominator.
+Attempt and sales changes are `(current / previous) - 1`; approval-rate changes are
+`100 * (current rate - previous rate)` percentage points. Do not average merchants,
+bridge a missing week, infer onboarding from a first observation, or report portfolio
+trends. A full calendar week does not prove continuous export coverage: all changes
+remain descriptive comparisons of the supplied observations.
+
+## Merchant detail breakdowns
+
+Section 3 provides the same breakdown suite for every merchant, comparing only this
+week with last week. This week is the Monday-based week containing the effective
+cutoff; compare the included weekdays with the same weekdays seven days earlier.
+For example, a Friday cutoff compares Monday–Friday with the preceding Monday–Friday,
+not a five-day period with a seven-day period. Restrict both populations to the
+requested main-period source scope and disclose unavailable earlier observations.
+Show the exact two date ranges in every chart legend and supporting table. Section 2
+continues to own the full weekly history; no main-period-total or older-week columns
+belong in section 3.
+
+Charts are the primary presentation, with these fixed layouts:
+
+- BIN country and card product: compact paired bar charts; two differently colored
+  bars per category compare the weeks for every metric, including rates.
+- Amount buckets: two histograms side by side, one color per week, using the same
+  six bins and y-axis scale. Default to count; counts and USD weights can be selected,
+  but not approval-rate/share metrics. The unequal/open-ended amount bands are shown
+  as equal-width categories, explicitly labeled as binned values rather than density.
+  Unknown amounts are listed separately, never drawn as a numeric interval.
+- Unsuccessful response reasons: two bar charts side by side, one color per week,
+  with identical category order and scale. Do not re-rank or rescale each week.
+- Authentication: paired pies for the aligned weeks, with count and USD selectors
+  only. If any category value is unavailable or negative, do not draw that period's
+  pie from an incomplete sum. Keep the supporting cells blank.
+
+Do not include settlement sales/refund charts in section 3. Sections 1 and 2 still
+retain their settlement metrics. A metric selector switches supported measures,
+including successful authorization amount USD where applicable. Render unavailable cells
+blank and chart values as gaps, not zeros. Do not repeat a metric label in a cell whose
+column header already names that measure: use `USD 33...`, not `授权成功金额 USD 33...`.
+A packed week cell that also shows attempts and a rate must say `授权成功 USD`, because the
+report also shows settled sales. Use the shared
+`comparison_charts.py` for all report charts. Expandable supporting tables keep metrics as rows and the two periods
+as columns. HTML is self-contained with no external chart service; Markdown retains
+the supporting values.
+Derive groupings only from the merchant's authorized attempts in those two periods;
+do not join settlement amounts into authorization groups.
+
+- BIN country: `Issuing bank country`; keep the merchant's top ten by attempts across
+  the two comparison periods, `Other` for the rest, and a separate unknown group.
+- Card product: `Payment method` × `Card type`, following payment-analysis. Preserve
+  every observed combination and unknown components.
+- Amount bucket: use each attempt's `Transaction amount` converted to USD by its
+  authorization date. Fixed half-open ranges are `[0,25)`, `[25,50)`, `[50,100)`,
+  `[100,200)`, `[200,500)`, `[500,+inf)`. Missing, nonfinite, negative or unconvertible
+  amounts belong to unknown; never silently put them into the zero bucket.
+- Authentication: every observed `Authentication method` value, with unknown separate.
+- Unsuccessful response: code × message among non-approvals only. Keep the merchant's
+  top ten reasons across the two comparison periods, Other and unknown. The share denominator is
+  that merchant's non-approvals, not all attempts. Unknown responses are not confirmed
+  issuer declines or fraud.
+
+Freeze group membership from the union of the two comparison periods before calculating each.
+Never re-rank each period independently. Synthetic Other/unknown have distinct keys and display
+labels from literal source strings with those names. For all-attempt groups show
+count, share of merchant attempts, approvals, rate, attempt amount USD and approved
+amount USD. For non-approval reasons show count, share of merchant non-approvals and
+unsuccessful amount USD. Group counts and amounts reconcile to the corresponding
+merchant population; a zero denominator is unavailable, not zero percent.
+
+Missing merchant-week observations remain blank. A group absent from an observed
+merchant-week may have zero observed counts, but no approval rate when its count is
+zero. Missing amount or FX invalidates the affected amount sum, not the count.
+Export the two-period group values in `merchant-detail-comparison.csv` for review.
+Add per-merchant dispute and fraud history and monthly VAMP charts using the periods,
+series and availability rules in [risk history](risk-history.md). Use 340FRD file
+generation dates as report dates. Monthly charts switch between counts and rates;
+rate tables and `merchant-risk-history.csv` expose numerator, denominator and its
+month. Keep weekly counts without inventing a weekly monitoring rate. Mastercard
+EFM rates use fraud chargebacks, not the 340FRD count series. These are not
+authorization-cohort metrics. Settlement sales/refunds are omitted from section 3.
+
+## Chinese report structure
+
+Use this template for editorial review in place of the base report's chapter order
+and Sankey. Do not add portfolio summary, trends, change decomposition, funnel or
+overall dispute chapters.
+
+- Scope header: title, period, effective cutoff, sources and timezone/coverage caveats;
+  include a comparison period only when a merchant comparison across periods is requested.
+- 商户要点: merchant-specific findings with counts, denominators and date basis. The lowest authorization rate chooses an authorization review, not the investigation order. If fraud or predispute history would change who is checked first, name that merchant and month here, and say whether the month is inside the report window. A user-excluded historical merchant appears once as an exclusion, not as a finding, and is absent from the tables.
+- 1. 子商户比较: stable IDs and display labels, merchant-level attempts, approvals,
+  rates, settlement, refunds and observed disputes where supported. Keep small samples
+  visible and unavailable values distinct from zero.
+- 2. 子商户逐周对比: a merchant-by-week matrix of approvals/attempts and rates,
+  followed by per-merchant tables with date/week columns horizontally and metrics
+  vertically, including successful authorization amount USD as a separate row from
+  settled sales. Preserve the same orientation for selected and collapsed merchants.
+  Keep all merchants reachable; default detail selections may be expanded while other
+  merchant weekly tables are collapsed. Explain partial weeks and unavailable changes.
+- 3. 重点子商户: the full merchant breakdown suite above, using interactive this-week
+  versus last-week charts and two-period supporting tables. No report-period total
+  or older weeks in the two-week comparisons. Risk history uses its own longer windows.
+  Priority merchants are expanded, and all other merchants remain accessible in
+  collapsed sections, including when merchants are explicitly selected. Default priority means the largest by attempts and
+  the lowest authorization rate among merchants with at least 30 attempts; this is
+  a navigation rule, not a significance test. Keep source limitations beside the
+  affected merchant and show group denominator definitions once. Remove extra explanatory
+  prose; keep only limitations needed to interpret the evidence.
+- 4. 商户行动表: identify the merchant, evidence and next investigation for each row;
+  distinguish hypotheses from facts. Include supported historical refund and dispute
+  follow-ups for the relevant merchant, not portfolio history.
+- 5. 归因与覆盖: sources, identity, deduplication, conflicts, unknowns, join coverage,
+  FX and unresolved attribution limits. Link supporting CSV/JSON reconciliation
+  evidence without presenting aggregate totals in the report or exposing cardholder data.
+
+## Done when
+
+A reader can identify which merchants to investigate and why, including a stated historical exclusion; each rate identifies
+its merchant, population and period; unsupported data is not presented as zero; and
+merchant attribution does not cross identity boundaries. Internal reconciliation
+accounts for unknowns and conflicts without advertising aggregate fields as deliverables.
+The Markdown and HTML use the same reviewed narrative and separate verified findings
+from operational hypotheses.

package/skills/risk-compliance/portfolio-payment-analysis/references/risk-history.md

@@ -0,0 +1,89 @@
+# Merchant risk history
+
+Use the common effective cutoff. Retain 12 calendar months and eight Monday–Sunday
+weeks, with missing periods blank and the final period partial where applicable.
+Every merchant has dispute and fraud counts. Monthly charts also offer a rate view,
+with numerator, denominator and denominator month in the expandable table and CSV.
+Weekly charts show counts: do not invent a weekly card-network monitoring formula.
+All charts use `comparison_charts.py`; nulls are gaps, never fabricated zeros.
+
+## 340FRD reporting date and attribution
+
+**Use the DART-340 file generation date as the fraud report date.** This is the
+user-confirmed reporting convention for this adapter. Validate the header date
+against the filename. Deduplicate exact full records across eligible valid files;
+for an exact repeat, use its earliest file generation date. Do not move fraud back
+to the original transaction month or count repeated deliveries again.
+
+Validate the v3.5 ASCII header, 17-field details and trailer. Exclude invalid files
+and files generated after the cutoff, recording aggregate evidence. Match ARN plus
+MID only to a unique settled Sale in the verified Worldpay-Acquiring namespace
+(`Worldpay  - Acquiring`, whitespace normalized). Original transaction date, currency
+and amount must agree, and the sale must have a resolved submerchant ID. A MID or
+descriptor alone is not a submerchant identity. Preserve unmatched/ambiguous counts
+without exporting raw card data or join identifiers.
+
+Full-record variants remain distinct observed records. If variants share an ARN/MID
+and their event identity is unresolved, leave affected fraud-rate cells unavailable;
+do not silently collapse variants or claim that every record is a unique TC40 event.
+
+## Counts and rates are distinct
+
+Observed dispute counts group provider, MID, dispute ID and stage, using the earliest
+supplied date for that stage. Updates do not add cases; reversals do not subtract
+incidence. RDR and formal escalation can each appear in their respective series.
+Conflicting identities/brands are quarantined; unknown stages remain unresolved.
+
+A monitoring-style chargeback numerator needs an opening and its received date.
+`First CB Request` with `1st chargeback` is the adapter's supported opening pair.
+Response-, loss- or reversal-only cases cannot be promoted to openings. Preserve
+observed counts while leaving affected rate cells blank. Keep independently supported
+merchant/brand/month cells computable.
+
+## Monthly count-rate formulas
+
+Scope every numerator and denominator to the same submerchant, brand and verified
+processor namespace. Count settled Sale transactions by their recorded transaction/
+capture month; never use approvals, refunds, or another merchant's sales. Report
+these as **network-style estimates from the extract**, not official identifications.
+Source coverage can be partial and October-style month-to-date results are provisional.
+
+| Series | Numerator in report month M | Denominator |
+|---|---|---|
+| Visa Predispute | Observed Visa RDR cases, descriptive only | Visa sales in M |
+| Visa Dispute | Supported Visa formal openings | Visa sales in M |
+| Mastercard chargeback, ECP | Supported Mastercard formal openings | Mastercard sales in M−1 |
+| Visa fraud report rate | Attributable Visa 340FRD reports, dated by file generation | Visa sales in M |
+| Mastercard EFM fraud chargeback rate | Supported fraud chargebacks with reason 4837 or 4863 | Mastercard e-commerce sales in M−1 |
+
+The Mastercard fraud **count** chart still shows 340FRD reports. Its EFM **rate** uses
+a different numerator: fraud-related chargebacks, not all 340FRD Mastercard records.
+Label that series explicitly and expose the rate numerator. Unknown reason/channel
+classification or unresolved openings must not silently disappear from a rate.
+Visa Predispute is descriptive and excluded from VAMP.
+
+Draw a rate only with an available positive numerator and positive denominator.
+Preserve genuine zero counts, but leave their rate point blank under the base skill's
+point convention. Missing prior-month sales remain missing; use calendar arithmetic
+across year boundaries. Record formulas, denominator dates, status and reason with
+each rate. Do not infer continuous coverage from min/max event dates.
+
+## VAMP
+
+The file-generation-date reporting convention resolves the fraud report-date choice.
+Do not continue to list that choice as missing. It does not establish TC40 event
+identity, TC15/TC05 processing dates, corrections, CE3.0/pre-dispute exclusions,
+VisaNet CNP eligibility, completeness or descriptor/acquirer/market grouping.
+Keep official VAMP unavailable until the remaining inputs are verified.
+
+VAMP is eligible TC40 fraud plus TC15 disputes divided by TC05 settled transactions
+for the same reporting month. Do not deduplicate across TC40 and TC15. RDR does not
+automatically erase a related TC40. Do not manufacture VAMP by adding the observed
+count series or the descriptive pre-dispute rate.
+
+## Sources
+
+- [Stripe monitoring calendars, VAMP, ECP and EFM](https://docs.stripe.com/disputes/monitoring-programs): monthly timing, captured-payment denominators, and EFM fraud-chargeback reasons.
+- [Visa VAMP fact sheet](https://corporate.visa.com/content/dam/VCOM/corporate/visa-perspectives/security-and-trust/documents/visa-acquirer-monitoring-program-fact-sheet-2025.pdf).
+- [Antom monitoring date basis](https://docs.antom.com/ac/dispute/monitor): processor context, not proof of Worldpay processing dates.
+- User-provided DART_340.pdf v3.5 (2021-10-19), §§ 1.1, 5.2, A.2.1–A.2.3, SHA-256 `d7e0b2b01b1f8483ffd78c19b2d289bac17154c15a92c436ca32dbdd4aea6997`. Do not bundle the private PDF, local path or raw data.

package/skills/risk-compliance/portfolio-payment-analysis/release-check.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const bundle = readJson(join(resolve(here, '../../..'), 'package.json'));
+  if (bundle.name === '@1aboveio/skills' && bundle.nativeCodex?.schemaVersion === 1) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }