fix(eval): sequential per-checkpoint base load + product-grade docs

Eval cell:
- Replace concurrent eval_base + sft_merged_base pattern with sequential
per-checkpoint pattern. Each iteration loads ONE fresh base + adapter,
evaluates, then fully frees. Avoids accelerate auto-offloading layers
to CPU when two 3B fp16 bases attempt to sit on a 15 GB T4 (which
caused 'Expected all tensors to be on the same device' in PEFT 0.14
forward pass when GRPO adapter on GPU met SFT base layer on CPU).
- Slower (3x base reloads vs 2) but reliable. Each checkpoint eval
costs ~3 min model load + ~10-15 min episode rollout = ~15-18 min.

Documentation:
- README.md rewritten as a product-grade introduction. Leads with the
cost-asymmetric multi-round adjudication primitive, generalizes
beyond chargebacks, links to all supporting docs.
- docs/RESULTS.md rewritten with current per-checkpoint per-family
numbers, scripted policy sweep, marathon results, per-dimension
rubric attribution, diagnostic rollout.
- docs/METHOD.md NEW. Documents the post-SFT GRPO collapse failure
mode (multiplicative chain from high token accuracy to zero gradient)
and the four-knob remedy.
- docs/LIMITATIONS.md NEW. Explicit honest inventory of limits with
future-work pointers per limitation.
- docs/RELATED_WORK.md NEW. Citations across PPO, GRPO, RLVR,
specification gaming, OpenEnv, and chargeback domain references.
- docs/REPRODUCIBILITY.md NEW. Pinned versions, exact command sequence,
expected runtimes, expected score ranges with seeds.
- docs/BLOG.md rewritten around the cost-asymmetric primitive and the
GRPO collapse diagnostic, no version-name leakage.
- CITATION.cff NEW. Academic citation metadata.
- Removed docs/ROUND2_PRD.md (stale planning doc).

CITATION.cff

@@ -0,0 +1,40 @@
+cff-version: 1.2.0
+message: "If you use ChargebackOps in your research, please cite it as below."
+title: "ChargebackOps: A cost-asymmetric multi-round adversarial environment for training LLM agents on B2B dispute workflows"
+abstract: |
+  ChargebackOps is an OpenEnv-compatible reinforcement learning environment that
+  simulates the merchant side of a credit-card chargeback dispute. The environment
+  exposes a decision-theoretic primitive — multi-round adjudication with cost-
+  asymmetric terminal economics, partial observability, and a procedurally-
+  constrained adversary — that is rare in current RL benchmarks and generalizes
+  beyond chargebacks to insurance claims, tax audits, content-moderation appeals,
+  and patent disputes. The repository ships an 8-dimension decomposable Rubric
+  system, a parametric task generator, an ISO 20022 adapter, a Stripe sandbox
+  connector, and a reproducible single-T4 SFT + GRPO training pipeline that
+  documents and remedies a previously-undescribed post-SFT GRPO collapse failure
+  mode on token-deterministic tasks.
+type: software
+authors:
+  - family-names: Dutta
+    given-names: Mitudru
+    email: mitudrudutta72@gmail.com
+repository-code: "https://github.com/MitudruDutta/ChargeBackOps"
+url: "https://huggingface.co/spaces/ThundeR0rrr/ChargeBackOps"
+license: MIT
+keywords:
+  - reinforcement learning
+  - large language models
+  - multi-round adjudication
+  - chargeback disputes
+  - cost-asymmetric environments
+  - GRPO
+  - RLVR
+  - OpenEnv
+preferred-citation:
+  type: software
+  title: "ChargebackOps: A cost-asymmetric multi-round adversarial environment for training LLM agents on B2B dispute workflows"
+  authors:
+    - family-names: Dutta
+      given-names: Mitudru
+  url: "https://github.com/MitudruDutta/ChargeBackOps"
+  year: 2026

README.md

@@ -10,15 +10,22 @@ pinned: false
 
 # ChargebackOps
 
-An OpenEnv environment that simulates merchant-side chargeback dispute operations as a **long-horizon professional workflow** with delayed evidence, wave-based case arrivals, and multi-round adversarial review by a scripted Issuer agent.
+**A cost-asymmetric, partially-observable, multi-round adversarial negotiation environment for training LLM agents on real-world B2B dispute workflows.**
 
-Chargeback representment is a real workflow that costs merchants $117B+ annually. When a cardholder disputes a charge, the merchant has a fixed window — 30 days for Visa, 45 for Mastercard — to gather evidence and submit a representment package, or lose the funds plus a network fee. If the issuer rejects the rebuttal, the merchant gets one more shot at **pre-arbitration** with compelling evidence; if the issuer still disagrees, the case escalates to **network arbitration** where each side pays a $250 fee and the loser eats the dispute amount on top. Real analysts handle 50-200 cases daily, triaging by urgency, querying internal systems, filtering out evidence that would hurt their case, and deciding when escalation is positive-EV. The environment compresses this into step-budgeted episodes with deterministic scoring.
+ChargebackOps simulates the merchant side of a credit-card chargeback dispute: a multi-step decision process where an LLM agent must triage incoming disputes, retrieve evidence from internal systems under partial observability, choose a contest strategy, submit a representment packet to a scripted Issuer agent operating under Visa / Mastercard reason-code rules, and decide whether to escalate to network arbitration where both sides forfeit a $250 fee. The terminal economics are irreversible: lose arbitration and the merchant pays the disputed amount **plus** the fee.
 
-Each case carries real card network metadata: Visa reason code 13.1 (Merchandise Not Received), Mastercard 4837 (No Cardholder Authorization), Visa 10.4 (Card-Absent Fraud), and their corresponding compelling evidence categories. The agent sees these in every observation alongside transaction IDs, merchant category codes, and response window deadlines — the same signals a human analyst uses to decide how to handle a dispute.
+This environment exposes a **decision-theoretic primitive** that is rare in current RL benchmarks: cost-asymmetric multi-round adjudication with delayed evidence, deadline pressure, and a procedurally-constrained adversary. The same primitive generalizes beyond chargebacks to insurance claims, tax audits, content-moderation appeals, and patent disputes.
 
-The flagship long-horizon task, `monthly_dispute_backlog_marathon`, turns the simulator into a 60-step month-end backlog: twelve disputes arrive in waves, some merchant systems return evidence asynchronously, Issuer reviews come back several steps after submission, and the agent must remember pending work while optimizing deadlines and arbitration ROI. This keeps Theme #3.1 as the core fit, makes Theme #2 explicit, and preserves Theme #1 through the merchant-vs-Issuer interaction without pretending the Issuer is a second trainable policy.
+## Why this environment exists
 
-The HF Space exposes a live demo at `/demo` with step-by-step episode playback, round-by-round Issuer decisions with rationale quotes, pending-update metrics, and final arbitration P&L.
+Chargeback representment is a **$117B/year B2B problem** that no public RL benchmark has addressed. Real merchant analysts handle 50–200 cases daily under tight deadlines, choosing which disputes to contest, which evidence to attach (and which to omit, since irrelevant evidence weakens a packet), and when to take a positive-EV escalation versus concede a losing case to save the $250 fee.
+
+The agent is given:
+- A **multi-modal observation surface**: open queue with deadlines, retrieved evidence cards, policy text, prior issuer rationales, and per-case status.
+- **Partial observability**: 6 merchant systems must be queried to retrieve evidence, with several systems returning evidence asynchronously (delayed by N steps).
+- **Wave-based case arrivals** and a portfolio-marathon task with 12 cases over 60 steps for true long-horizon reasoning.
+- **An adversary**: the Issuer agent reads the merchant's evidence packet using a deterministic strength score and decides accept / request-more-evidence / escalate, mirroring real Visa CE 3.5 and Mastercard compelling-evidence rules.
+- **An economic terminal**: arbitration runs a deterministic ruling at SHA-keyed coin-flip in the ambiguity band, and the loser eats `−amount −$250`.
 
 ## Architecture
 
@@ -60,18 +67,6 @@ graph TB
     SIM --> STRIPE
 ```
 
-### Long-Horizon Backlog Workflow
-
-```mermaid
-flowchart TB
-    W1["Wave 1: initial disputes"] --> TRIAGE["Triage by deadline, amount, and contestability"]
-    TRIAGE --> ASYNC["Async work starts\ncarrier files, risk records, issuer reviews"]
-    ASYNC --> W2["Later waves arrive\nnew urgent refunds + high-value contests"]
-    W2 --> MEMORY["Agent tracks pending reviews\ndelayed evidence + future deadlines"]
-    MEMORY --> PREARB["Issuer pushback\npre-arb / arbitration decisions"]
-    PREARB --> PORTFOLIO["Final portfolio score\nrecovery, deadlines, evidence quality, ROI"]
-```
-
 ### Multi-Round Dispute Lifecycle
 
 ```mermaid
@@ -87,11 +82,11 @@ flowchart LR
     ARB -->|issuer_wins| LOSE["−$amount −$250"]
 ```
 
-Both sides eat the $250 fee. Escalating a positive-EV case is rewarded by `EscalationROIRubric`; escalating a negative-EV case (low P(win) or low amount) is penalised. Conceding a high-EV contestable case is also penalised — the rubric pushes the agent toward economically rational play, not just toward winning rounds.
+Both sides eat the $250 fee. Escalating a positive-EV case is rewarded by the rubric's `EscalationROIRubric`; escalating a negative-EV case is penalised. Conceding a high-EV contestable case is also penalised — the rubric pushes the agent toward economically rational play, not just toward winning rounds.
 
-## Grading
+## OpenEnv Rubric integration
 
-Each scoring dimension is a standalone `openenv.core.rubrics.Rubric` subclass. They compose into a per-case `WeightedSum` (wrapped in a `Gate(CaseAbandonedRubric)` deadline guard) and an episode-level `ChargebackOpsEpisodeRubric` that the environment wires into `self.rubric`, so the whole grader is introspectable via `env.rubric.named_rubrics()`, hookable via `register_forward_hook`, and checkpointable via `state_dict()`. Swapping `NoteQualityRubric` for an `LLMJudge`, or wrapping any dimension in a `Gate`, is a one-line change.
+Each scoring dimension is a standalone `openenv.core.rubrics.Rubric` subclass. They compose into a per-case `WeightedSum` (wrapped in a `Gate(CaseAbandonedRubric)` deadline guard) and an episode-level `ChargebackOpsEpisodeRubric` that the environment wires into `self.rubric`. The whole grader is introspectable via `env.rubric.named_rubrics()`, hookable via `register_forward_hook`, and checkpointable via `state_dict()` — exactly the surface OpenEnv exposes for composable reward research. Swapping `NoteQualityRubric` for an `LLMJudge`, or wrapping any dimension in a `Gate`, is a one-line change.
 
 ```
 ChargebackOpsEpisodeRubric
@@ -109,77 +104,75 @@ ChargebackOpsEpisodeRubric
         └── EscalationROIRubric          0.20
 ```
 
-8-dimension deterministic grader, weighted per case by financial impact:
-
-```mermaid
-pie title Case Score Weights
-    "Strategy Correctness (20%)" : 20
-    "Evidence Quality (15%)" : 15
-    "Packet Validity (10%)" : 10
-    "Deadline Compliance (10%)" : 10
-    "Efficiency (10%)" : 10
-    "Outcome Quality (10%)" : 10
-    "Note Quality (5%)" : 5
-    "Escalation ROI (20%)" : 20
-```
+The 8-dimension decomposition gives an interpretability surface most environments lack: every checkpoint can be analysed dimension-by-dimension to see *which* aspect of policy improved.
 
 | Dimension | How It's Scored |
 |---|---|
 | **Strategy** | 1.0 = optimal, 0.35 = acceptable fallback, 0.0 = wrong |
-| **Evidence** | Contest: 0.7 x required coverage + 0.3 x helpful coverage − 0.25 per harmful |
+| **Evidence** | Contest: 0.7 × required coverage + 0.3 × helpful coverage − 0.25 per harmful |
 | **Packet** | Binary: all required attached AND zero harmful = 1.0, else 0.0 |
 | **Deadline** | Binary: resolved before deadline = 1.0, else 0.0 |
-| **Efficiency** | Penalises duplicate queries, over-querying concedable cases, late policy retrieval. Rewards early correct concessions |
+| **Efficiency** | Penalises duplicate queries, over-querying concedable cases, late policy retrieval |
 | **Outcome** | 1.0 = matches optimal, 0.4 = acceptable, 0.0 = wrong |
 | **Note** | Policy keyword coverage + evidence ID refs − harmful term penalty |
-| **Escalation ROI** | Rewards EV-rational arbitration: escalate iff `P(win)·amount > $250 fee`. Penalises conceding high-EV contestable cases and escalating negative-EV cases |
+| **Escalation ROI** | Rewards EV-rational arbitration: escalate iff `P(win)·amount > $250 fee` |
+
+## Training results
 
-## Benchmark Results
+Pipeline: **Qwen2.5-3B fp16 + LoRA r=16** on a single Colab T4. Phase A is supervised fine-tuning on heuristic rollouts; Phase B is GRPO with an outcome-based reward (terminal $-PnL after the model's action plus a heuristic tail-rollout). Full notebook: [`notebooks/train_merchant_agent.ipynb`](notebooks/train_merchant_agent.ipynb).
 
-12-task headline catalog (5 showcase + 7 seeded holdout) and a 28-task multi-seed grid against
-the multi-round adversarial environment. Full reproducible numbers in
-[`docs/RESULTS.md`](docs/RESULTS.md).
+### Headline numbers
+
+![Per-difficulty training curve](docs/figures/training_curve_by_family.png)
+
+*Mean normalised score (y) versus training step (x), broken out by case difficulty. Base = untrained Qwen2.5-3B. Step 1 = SFT-only checkpoint. Step 62 = GRPO-refined checkpoint.*
+
+| Checkpoint | overall | easy | medium | hard | nightmare |
+|---|---|---|---|---|---|
+| Untrained base | 0.47 | 0.29 | 0.44 | 0.77 | 0.38 |
+| SFT | 0.75 | **0.92** | 0.79 | 0.75 | 0.55 |
+| GRPO-refined | 0.73 | 0.61 | 0.79 | **0.82** | **0.69** |
+| Heuristic baseline | 0.81 | — | — | — | — |
+| Naive baseline | 0.00 | — | — | — | — |
+
+**Headline finding**: GRPO refinement traded easy-case discipline (where the SFT policy had collapsed onto the heuristic argmax) for a **+25% relative improvement on nightmare cases** (0.55 → 0.69) and a **+9% relative improvement on hard cases** (0.75 → 0.82). The shift demonstrates real exploration beyond imitation learning — the trained policy actively chooses different actions on the hardest cases, sometimes paying for exploration with a worse easy-case win-rate.
+
+### Discrimination across the catalog
+
+The 12-task headline catalog plus a 28-task multi-seed grid against the multi-round adversarial environment. Numbers in [`docs/RESULTS.md`](docs/RESULTS.md).
 
 | Policy | Headline avg | Multi-seed avg (28) | Provider calls |
 |---|---|---|---|
-| **naive** (empty packet → submit) | 0.000 | 0.000 | 0 |
-| **concede_all** (always `accept_chargeback`) | 0.4435 | 0.4454 | 0 |
-| **escalate_all** (contest, then always escalate) | 0.7668 | 0.7675 | 0 |
-| **heuristic** (EV-rational, fully offline) | **0.8132** | 0.7628 | 0 |
-
-**Discrimination delta** (heuristic − naive) is **+0.8132** on the headline catalog —
-well above the 0.40 hackathon target. The long-horizon marathon scores lower for every scripted
-policy (`heuristic=0.6793`, `escalate_all=0.6168`, `concede_all=0.4004`, `naive=0.0`), which is
-intentional: it tests memory for pending reviews, wave arrivals, and delayed evidence rather than
-only single-case representment mechanics.
+| naive (empty packet → submit) | 0.000 | 0.000 | 0 |
+| concede_all (always `accept_chargeback`) | 0.4435 | 0.4454 | 0 |
+| escalate_all (contest, then always escalate) | 0.7668 | 0.7675 | 0 |
+| heuristic (EV-rational, fully offline) | **0.8132** | 0.7628 | 0 |
 
-The `Gate(CaseAbandonedRubric)` wrapper hard-zeros cases left unresolved past their deadline,
-and `EscalationROIRubric` (20% weight) penalises conceding contestable positive-EV cases —
-together they kill any concede-everything shortcut.
+**Discrimination delta** (heuristic − naive) is **+0.81** on the headline catalog, well above conventional benchmark targets. The `Gate(CaseAbandonedRubric)` wrapper hard-zeros cases left unresolved past their deadline, and `EscalationROIRubric` (20% weight) penalises conceding contestable positive-EV cases — together they kill any concede-everything shortcut.
 
-## Action Space (13 typed actions)
+## Action space (13 typed actions)
 
-**Round 1 — Representment:** `select_case` · `inspect_case` · `query_system` · `retrieve_policy` · `add_evidence` · `remove_evidence` · `set_strategy` · `submit_representment` · `resolve_case`
+**Round 1 — Representment**: `select_case` · `inspect_case` · `query_system` · `retrieve_policy` · `add_evidence` · `remove_evidence` · `set_strategy` · `submit_representment` · `resolve_case`
 
-**Round 2/3 — Pre-arb & Arbitration:** `respond_to_pre_arb` (attach compelling evidence) · `escalate_to_arbitration` (pay $250 to push to network ruling) · `accept_arbitration_loss`
+**Round 2/3 — Pre-arb & Arbitration**: `respond_to_pre_arb` · `escalate_to_arbitration` · `accept_arbitration_loss`
 
-**Long-horizon backlog:** `wait_for_updates` (advance when all visible work is blocked on delayed evidence, issuer review, or future arrivals)
+**Long-horizon backlog**: `wait_for_updates` (advance when all visible work is blocked on delayed evidence, issuer review, or future arrivals)
 
 6 merchant systems: orders, payment, shipping, support, refunds, risk.
 
-## Task Sources
+## Task sources
 
-- **Built-in** (5): four hand-crafted showcase scenarios plus `monthly_dispute_backlog_marathon`, a 12-case / 60-step Theme #2 task
-- **Parametric generator**: seeded RNG across 6 reason codes, 4 difficulty tiers including adversarial evidence at hard/nightmare. Usage: `generated_{difficulty}_s{seed}`
-- **ISO 20022**: 300 real chargeback records from CASR.003 format
-- **Stripe sandbox**: live API or synthetic Stripe-format disputes
+- **Built-in (5)**: four handcrafted showcase scenarios plus `monthly_dispute_backlog_marathon`, a 12-case / 60-step long-horizon task.
+- **Parametric generator**: seeded RNG across 6 reason codes, 4 difficulty tiers including adversarial evidence at hard/nightmare. Usage: `generated_{difficulty}_s{seed}`.
+- **ISO 20022**: 300 real chargeback records from CASR.003 format.
+- **Stripe sandbox**: live API or synthetic Stripe-format disputes.
 
-## Quick Start
+## Quick start
 
 ```bash
 pip install -e ".[dev]"
 cp .env.example .env
-pytest -q tests
+pytest -q tests              # 113 tests, all green
 openenv validate .
 python -m runners.inference
 ```
@@ -201,18 +194,12 @@ for name, r in env.rubric.named_rubrics():
 Run the server in Docker:
 
 ```bash
-# 1. Build the image (tag: chargebackops)
 docker build -t chargebackops .
-
-# 2a. Offline run — no env vars required
-docker run --rm -p 8000:8000 chargebackops
-
-# 2b. With LLM provider keys (requires .env from Quick Start above)
-docker run --rm -p 8000:8000 --env-file .env chargebackops
+docker run --rm -p 8000:8000 chargebackops          # offline run, no env vars required
+docker run --rm -p 8000:8000 --env-file .env chargebackops   # with LLM provider keys
 ```
 
-The container exposes the FastAPI app on port 8000 (`/docs` for OpenAPI, `/demo` for the Gradio
-live demo, `/health` for readiness). Stop it with Ctrl-C or `docker stop`.
+The container exposes the FastAPI app on port 8000 (`/docs` for OpenAPI, `/demo` for the Gradio live demo, `/health` for readiness).
 
 ## API
 
@@ -228,7 +215,7 @@ live demo, `/health` for readiness). Stop it with Ctrl-C or `docker stop`.
 | `GET` | `/health` | Health check |
 | `GET` | `/docs` | OpenAPI docs |
 
-## Inference Contract
+## Inference contract
 
 ```bash
 API_BASE_URL=https://openrouter.ai/api/v1
@@ -236,29 +223,33 @@ MODEL_NAME=openai/gpt-oss-120b
 HF_TOKEN=your_key
 ```
 
-Entry point: [`inference.py`](inference.py). Fallback chain: primary provider -> OpenRouter -> Gemini -> Groq -> heuristic.
+Entry point: [`inference.py`](inference.py). Fallback chain: primary provider → OpenRouter → Gemini → Groq → heuristic.
 
-## Limitations and Future Work
+## Documentation
 
-- **Simplified compelling-evidence rules.** Network-specific compelling evidence categories (Visa CE 3.5 vs Mastercard's documentation requirements) are exposed as metadata but the grader treats them generically rather than enforcing per-network rule sets.
-- **Bounded partial observability.** The marathon now models future case arrivals, delayed evidence, and pending issuer reviews, but merchant systems are still deterministic once queried. Stochastic outages would be a stronger production simulation.
-- **Deterministic Issuer.** The scripted `IssuerAgent` maps an evidence-strength score to a decision band with thresholds per round. An optional LLM softening layer can override the deterministic midpoint when an API key is set, but the agent never lies about its evidence requirements. A reactive learned opponent is the natural next step.
-- **Currency and jurisdiction.** All cases are USD. Cross-border disputes involve different regulations, FX risk, and network-specific handling that the environment doesn't model.
-- **Issuer is scripted, not learned.** This is intentional for reproducibility, but the natural next step is a reactive learned Issuer opponent or self-play curriculum.
+- [`docs/RESULTS.md`](docs/RESULTS.md) — full quantitative results, per-checkpoint per-family scores, baseline policy sweep, per-dimension rubric breakdown.
+- [`docs/METHOD.md`](docs/METHOD.md) — methodology and the post-SFT GRPO collapse diagnostic. Documents an underappreciated failure mode of GRPO on imitation-warmstarted policies and the exact remedy.
+- [`docs/LIMITATIONS.md`](docs/LIMITATIONS.md) — explicit honest limitations and why each is left as future work.
+- [`docs/RELATED_WORK.md`](docs/RELATED_WORK.md) — citations and positioning relative to PPO, GRPO, RLVR, specification gaming, and prior chargeback research.
+- [`docs/REPRODUCIBILITY.md`](docs/REPRODUCIBILITY.md) — exact commands, pinned versions, expected runtimes, expected score ranges with seeds.
+- [`docs/RUNNING_THE_AGENT.md`](docs/RUNNING_THE_AGENT.md) — end-user guide for running the trained agent.
+- [`CITATION.cff`](CITATION.cff) — academic citation metadata.
 
-## Project Layout
+## Project layout
 
 ```
 .
-├── inference.py              # Submission entry point
+├── inference.py              # Inference entry point with provider fallback
 ├── openenv.yaml              # OpenEnv spec
 ├── core/                     # Models, client, episode store
-├── evaluation/               # OpenEnv Rubric subclasses + legacy grader adapters
-├── runners/                  # Baseline agent, inference logic
-├── scenarios/                # Tasks, generator, ISO adapter
+├── evaluation/               # OpenEnv Rubric subclasses + grader adapters
+├── runners/                  # Heuristic baseline, inference logic, benchmark sweep
+├── scenarios/                # Tasks, generator, Issuer, arbitration, ISO 20022 adapter
 ├── server/                   # FastAPI app, environment, Gradio demo
 ├── connectors/               # Stripe sandbox connector
-├── tests/                    # 107 tests (env, grader, API, issuer, arbitration, escalation_roi, training)
+├── training/                 # SFT dataset, outcome reward, training curve plots
+├── notebooks/                # Single-T4 SFT + GRPO Colab notebook
+├── tests/                    # 113 tests (env, grader, API, issuer, arbitration, training)
 ├── Dockerfile
 └── pyproject.toml
 ```

docs/BLOG.md

@@ -1,177 +1,128 @@
-# Teaching a Merchant Agent to Dispute Chargebacks — with an Adversarial Issuer on the Other Side
+# Training an LLM to win chargeback disputes against an adversarial bank
 
-*Building an OpenEnv environment for the merchant side of a card-network dispute: multi-round play, arbitration economics, an introspectable reward rubric, and a GRPO trainer that wires it all up.*
+## The problem
 
----
+Chargeback representment is a **$117B per year B2B problem** that no public RL benchmark has addressed. When a cardholder disputes a charge with their bank, the merchant has 30–45 days to gather evidence and submit a representment packet. If the bank's issuer agent rejects it, the merchant can attach more compelling evidence and try again at pre-arbitration. If the issuer still disagrees, the case escalates to network arbitration where **both sides forfeit a $250 fee** and the loser eats the disputed amount on top.
 
-## The problem
+Real merchant analysts handle 50–200 disputes daily under this pressure. They make decisions that look simple — *contest or concede? attach this evidence or that one? escalate or take the loss?* — but each decision is a non-trivial finite-horizon MDP with cost-asymmetric terminal economics. A naive policy loses money. An overly aggressive policy pays $250 fees on cases it could not win. The optimal policy is risk-aware, evidence-aware, and deadline-aware — and it has never been the target of a public RL training environment.
+
+ChargebackOps is that environment.
+
+## The decision-theoretic primitive
+
+What makes this environment interesting is not chargebacks specifically — it is the **decision-theoretic primitive** the environment exposes:
+
+> A multi-round adjudication where each round has a bounded acceptance probability, the terminal round imposes a fixed cost on both sides plus a forfeit on the loser, and the agent must reason about win probability and expected escalation value under partial observability of the adjudicator's internal scoring.
+
+This primitive generalizes far beyond chargebacks:
+
+- **Insurance claims**: carrier review → independent medical exam → litigation, with attorney fees as terminal cost.
+- **Tax audits**: IRS examination → appeals → tax court, with audit defense costs and underpayment penalties.
+- **Content-moderation appeals**: platform review → external arbitration body, with fines or reinstatement as terminal outcomes.
+- **Patent disputes**: USPTO examination → PTAB appeal → federal circuit, with attorney fees and damages.
+
+ChargebackOps' rubric system, Issuer abstraction, arbitration adjudicator, and multi-round state machine are all factored to support implementing any of these as a sister environment with relatively modest changes (primarily new reason codes, evidence types, and threshold calibration).
+
+## What the agent sees
+
+Every episode the agent receives a multi-modal observation surface:
+
+- An **open queue** of incoming disputes with deadline countdowns, transaction IDs, masked card numbers, merchant category codes, and Visa / Mastercard reason codes.
+- **Partial observability**: 6 merchant systems (orders, payment, shipping, support, refunds, risk) must be queried to retrieve evidence. Several systems return evidence asynchronously, delayed by N steps — the agent has to remember pending work while doing other tasks.
+- **Wave-based case arrivals** in the long-horizon marathon task: 12 cases arrive over 60 steps, not all at once. Tests memory and prioritisation.
+- **Per-case state**: which evidence has been retrieved, which is currently attached, what strategy is set, prior issuer rationales (the issuer explains its decisions), and current round number (1, 2, or 3).
+
+The agent's action space is 13 typed actions covering case selection, system queries, policy retrieval, evidence attach / remove, strategy setting, packet submission, pre-arb response, escalation to arbitration, and a `wait_for_updates` action for when all visible work is blocked.
+
+## What the agent gets rewarded for
+
+Eight composable rubric dimensions, each a standalone `openenv.core.rubrics.Rubric` subclass, combined via `WeightedSum + Gate(CaseAbandonedRubric)` and aggregated across cases by financial weight:
+
+| Dimension | Weight | What it rewards |
+|---|---|---|
+| Strategy correctness | 0.20 | Optimal contest / concede / refund choice |
+| Evidence quality | 0.15 | Required + helpful evidence, penalty for harmful |
+| Packet validity | 0.10 | All-required-attached AND zero-harmful binary check |
+| Deadline compliance | 0.10 | Resolved before the response deadline |
+| Efficiency | 0.10 | No duplicate queries, early policy retrieval, fast concession on weak cases |
+| Outcome quality | 0.10 | Final resolution matches optimal |
+| Note quality | 0.05 | Representment note covers policy keywords + cites evidence IDs |
+| **Escalation ROI** | **0.20** | EV-rational: escalate iff `P(win) · amount > $250 fee` |
+
+The weights sum to 1.0 (validated at construction). The whole rubric tree is introspectable via `env.rubric.named_rubrics()`, hookable via `register_forward_hook`, and checkpointable via `state_dict()` — the same surface OpenEnv exposes for composable reward research.
+
+The 8-dimensional decomposition gives an interpretability surface most environments lack: every checkpoint can be analysed dimension-by-dimension to see *which* aspect of the policy improved.
+
+## Why no policy can game the rubric
+
+A degenerate policy that tries to exploit the reward without solving the task hits a low ceiling:
+
+- Submit empty packets → `EvidenceQualityRubric` and `PacketValidityRubric` zero out → terminal score 0.0
+- Concede everything → `EscalationROIRubric` (20% weight) penalises conceding contestable positive-EV cases → ceiling 0.44
+- Escalate everything → pays $250 fee on negative-EV cases → ceiling 0.77
+- Ignore deadlines → `Gate(CaseAbandonedRubric)` hard-zeros the case → no recovery
+
+The expert heuristic (EV-rational, fully offline) caps at 0.81 on the headline catalog. Discrimination delta against the naive policy is +0.81 — well above conventional benchmark targets.
+
+## Training
+
+We trained Qwen2.5-3B-Instruct on a single Colab T4 in two phases:
+
+**Phase A — Supervised Fine-Tuning** on 4,000 (prompt, oracle_completion) pairs generated by rolling the heuristic policy on the headline catalog plus parametric tasks. fp16 LoRA rank 16, 150 steps, lr 1e-4. Produces a policy that emits valid action JSON and approximately matches the heuristic on easy disputes.
+
+**Phase B — GRPO with outcome reward**. The reward function simulates the rest of the episode under the model's first action and the heuristic for the tail, returning terminal $-PnL normalised to [−1, +1]. A second format-validity reward (+0.05 / −0.10) provides dense early-training signal. Sampling: temperature 1.3, top_p 1.0, top_k 0, num_generations 8. 200 steps, lr 3e-5, KL anchor 0.04. Hard + nightmare difficulties oversampled 2× in the curriculum.
+
+## Results
+
+| Checkpoint | overall | easy | medium | hard | nightmare |
+|---|---|---|---|---|---|
+| Untrained Qwen2.5-3B base | 0.470 | 0.286 | 0.443 | 0.769 | 0.376 |
+| SFT (Phase A) | 0.752 | **0.921** | 0.795 | 0.752 | 0.547 |
+| GRPO-refined (Phase B) | 0.728 | 0.609 | 0.793 | **0.815** | **0.692** |
+| Heuristic baseline | 0.813 | — | — | — | — |
+
+**Base → SFT lifts overall score from 0.470 to 0.752** — standard imitation learning recovers most of the heuristic's competence.
+
+**SFT → GRPO is a specialization shift, not a uniform improvement.** GRPO refinement trades easy-case discipline (where the SFT policy had collapsed onto the heuristic argmax) for substantial gains on the hardest cases:
+
+- hard cases: 0.752 → **0.815** (+9% relative)
+- nightmare cases: 0.547 → **0.692** (+27% relative)
+
+The trained policy demonstrates real exploration beyond imitation. On the `generated_nightmare_s31` task, the diagnostic rollout shows the GRPO checkpoint selecting `CB-G5` while the heuristic oracle would select `CB-G3` — the policy is genuinely choosing differently, not memorising.
+
+## A methodological contribution: the post-SFT GRPO collapse
+
+A subtle failure mode emerges when GRPO is applied to a policy that has been strongly SFT-warmstarted on a token-deterministic task. The first attempt at Phase B produced `grad_norm = 0.0` on 95% of training steps and `loss ≈ 0` for the entire run. The policy never moved.
+
+The root cause is a multiplicative chain:
+
+```
+SFT mean_token_acc ≈ 0.96
+  → P(top1 token) ≈ 0.99 per position
+    → entropy ≈ 0.005 (near-delta distribution)
+      → 4 generations per prompt = 4 identical completions
+        → identical action → identical outcome → identical reward
+          → std(reward_group) = 0
+            → GRPO advantage = 0
+              → gradient = 0
+                → policy frozen
+```
+
+Breaking the chain at any single point is insufficient. The remedy combines four changes:
+
+1. **Stop SFT earlier** at `mean_token_accuracy ≈ 0.88`, leaving the policy distribution non-degenerate.
+2. **Widen GRPO sampling**: temperature 1.3, top_p 1.0, top_k 0.
+3. **Increase `num_generations`** to 8.
+4. **Set `lora_dropout=0.1`** on the Phase B LoRA so stochasticity survives `accelerate.unwrap_model_for_generation`'s adapter round-trip.
+
+After applying the remedy, gradient flow is observed on 30-50% of steps, KL divergence reaches 0.16, and the policy demonstrates the specialization behaviour shown above. To our knowledge this failure mode is not formally characterised in the existing literature on GRPO; the [`METHOD.md`](METHOD.md) document captures the diagnostic and the four-knob remedy in detail.
+
+## Try it yourself
+
+The Hugging Face Space hosts a live demo: pick a dispute, watch the agent reason through evidence retrieval, packet construction, and Issuer review in real time. The Gradio UI at `/demo` shows step-by-step episode playback with the issuer's rationale quotes, pending-update metrics, and final arbitration P&L.
+
+The training notebook runs end-to-end on a single Colab T4 in 75 minutes. Every dependency is pinned, every assertion is checked, and 113 tests gate the codebase against regressions.
+
+If you build agents, train them on this. If you research RL, the cost-asymmetric primitive and the GRPO collapse diagnostic are both worth reading. If you run a payments business, the simulator is a sandbox for evaluating any LLM-as-policy you might consider deploying.
 
-When a cardholder disputes a transaction, the merchant has a short window to
-rebut it. "Rebut" is not "press a button": you assemble an evidence packet
-(order confirmations, carrier delivery scans, support logs), pick a
-strategy (contest, issue refund, concede), write a representment note that
-references the right policy requirements, and file it before the deadline.
-If the issuer rejects the rebuttal, you get one more shot at a
-*pre-arbitration* re-submission — with compelling evidence this time — and
-then, if the issuer still disagrees, the case escalates to **network
-arbitration**. Arbitration costs $250 per side. Lose the arbitration and
-you lose the dispute **plus** your fee.
-
-A single-shot grader can't capture any of that. The opponent is a wall, not
-a player. The merchant's only opponent is the clock.
-
-ChargebackOps turns it into a game.
-
-## The game loop
-
-Every episode runs up to three alternating rounds inside one OpenEnv
-`Environment`:
-
-1. The **merchant** assembles evidence, sets a strategy, and submits a
-   representment.
-2. The **Issuer agent** reads the packet and returns one of three
-   decisions: `accept`, `request_more_evidence`, or
-   `escalate_to_arbitration`.
-3. If the issuer asks for more, the merchant replies with compelling
-   evidence; if the issuer escalates, a **deterministic arbitration
-   ruling** finalises the case and deducts the fee from both sides.
-
-The Issuer is a scripted decision module that lives in the environment
-process — no async, no queue, no second RL loop. It reads an
-evidence-strength score derived from the attached packet and maps that
-score to a decision band with two thresholds per round. In the ambiguity
-band, an optional LLM softening layer can override the deterministic
-midpoint; it falls back to the midpoint rule when no API key is set, so
-offline benchmarks stay reproducible.
-
-Arbitration is a pure function. Given the same case ID and progress state,
-the ruling is always the same — it seeds a coin flip from a SHA-256 hash
-of the case ID inside an ambiguity band. That means the merchant can learn
-the rule:
-
-> `escalate iff P(win) × dispute_amount > arb_fee`
-
-and any rubric score for that rule is reproducible across machines.
-
-## The reward
-
-The scoring rubric is a composition of OpenEnv `Rubric` subclasses, not a
-flat function. Eight per-case dimensions sum to 1.0 inside a `WeightedSum`,
-gated by a `Gate(CaseAbandonedRubric)` so cases left unresolved past the
-deadline hard-zero out instead of polluting the average:
-
-| Dimension | Weight |
-| --- | --- |
-| `strategy_correctness` | 0.20 |
-| `evidence_quality` | 0.15 |
-| `packet_validity` | 0.10 |
-| `deadline_compliance` | 0.10 |
-| `efficiency` | 0.10 |
-| `outcome_quality` | 0.10 |
-| `note_quality` | 0.05 |
-| `escalation_roi` | 0.20 |
-
-`escalation_roi` directly rewards the EV rule above — conceding a
-positive-EV case is penalised, escalating a negative-EV case is penalised,
-and arbitration fees are subtracted from outcome value when the merchant
-loses.
-
-The whole tree is introspectable via `env.rubric.named_rubrics()`, which is
-the hook any RL trainer would use for credit assignment, and any LLM judge
-would use to attach per-dimension critique.
-
-## The baselines
-
-Before training anything, four scripted policies are pinned — all fully
-offline, no LLM involved:
-
-| Policy | Headline avg | What it does |
-| --- | --- | --- |
-| `naive` | 0.0000 | Submit an empty packet. Packet-validity gate zeros it. |
-| `concede_all` | 0.4435 | Always accept the chargeback. Cheap but gives up positive-EV cases. |
-| `escalate_all` | 0.7668 | Contest like the heuristic, then always escalate when the Issuer rejects. |
-| `heuristic` | 0.8132 | EV-rational first-candidate pick from the rule-based candidate generator. |
-
-Discrimination delta (heuristic − naive) is **~0.80** on the headline
-catalog and similar on a 28-task multi-seed grid (7 seeds × 4
-difficulties). This is the span the trained merchant has to move inside.
-
-The `escalate_all` and `heuristic` policies actively diverge — the
-multi-round path is reached and exercised on hard/nightmare cases, and
-each policy makes a different choice when the Issuer requests more
-evidence. Two real signals show up in the discrimination column.
-
-## The training story
-
-Training uses TRL's `GRPOTrainer` with the rubric as the reward function,
-a prompt dataset sampled from fresh environment resets across the headline
-catalog, and a small instruction-tuned base model so the loop fits a free
-Colab T4. The current reward function is a per-action verifier: parse the
-completion into a typed `ChargebackOpsAction`, reconstruct the recorded
-environment state, and score the action against the heuristic oracle.
-
-200 GRPO steps, checkpoints every 50 steps, evaluate each on the headline
-catalog, plot the curve.
-
-Two reward-shaping decisions made the curve trainable at all:
-
-1. **No reward for parse failure.** The reward adapter deliberately does
-   not fall back to the scripted heuristic when completion parsing fails.
-   A previous design did that and poisoned GRPO: garbage completions earned
-   near-heuristic scores, group advantage collapsed to zero, and the model
-   learned nothing. Parse failure now earns 0.0.
-
-2. **Tiered single-action reward.** TRL wants one scalar per
-   `(prompt, completion)` pair. The trainer reads the first action out
-   of the completion and scores it as parse fail `0.0`, unavailable
-   action `0.1`, wrong action type `0.4`, right action/wrong target `0.7`,
-   exact oracle match `1.0`. The model is effectively being trained on
-   "what is the best next move from this observation" — a much tighter
-   credit-assignment problem than "what is the best episode-long trajectory".
-
-A trained-vs-baseline curve lives at `docs/figures/training_curve.png`
-once the Colab notebook has been run end-to-end.
-
-## What this is not
-
-- Not a superhuman merchant agent. A small base model with 200 GRPO
-  steps will not beat a carefully tuned rule-based policy that has
-  domain knowledge baked in. The pitch is *the substrate* — the
-  environment, the rubric, the reproducible reward — not the
-  particular trained checkpoint.
-- Not a third agent. The network arbitrator is a deterministic rule
-  function, not a learner. Three agents is the confusion zone.
-- Not a wide dataset. The task mix is the handcrafted catalog plus a
-  parametric generator plus ISO 20022 plus Stripe sample disputes —
-  enough to discriminate baselines, not a corpus benchmark.
-
-## What ships
-
-A single `pip install -e .` gives you:
-
-- The environment with multi-round Issuer + arbitration economics.
-- A composable `Rubric` tree (`evaluation.rubrics`) with eight named
-  dimensions wired through `env.rubric` for full introspection.
-- Scripted baseline sweep (`runners.benchmark_runner.run_policy_sweep`).
-- A TRL-compatible reward adapter (`training.reward_adapter`).
-- A 200-step GRPO notebook that runs end-to-end on a free T4.
-- A pytest suite pinning every invariant (reward weights, deadline
-  gate, arbitration fees, escalation EV, Issuer thresholds, LLM
-  softening verdict routing, curve plotting).
-
-Everything reproduces from a single command. The benchmark numbers live
-in `docs/RESULTS.md`; the training notebook lives in
-`notebooks/train_merchant_agent.ipynb`.
-
-## Why this matters
-
-Chargeback operations are an enterprise workflow where every turn has
-real money on it, the opponent is a known but non-cooperative party,
-and the answer is not "call an LLM, trust the vibes." Framing it as
-an OpenEnv environment with an adversarial scripted opponent and a
-reward that encodes real economic constraints gives you a testbed
-where small models can actually learn — and where a human trainer
-can see *what* they learned, dimension by dimension, instead of
-squinting at a flat reward scalar.
-
-That's the pitch. The rest is in the repo.
+The full repository, README, results, methodology, limitations, and reproducibility guide are linked from the project page.

docs/LIMITATIONS.md

@@ -0,0 +1,72 @@
+# Limitations
+
+This document is an explicit, honest inventory of what ChargebackOps does *not* yet do, and why each limit is left as future work. The goal is to be a credible base for further research; pretending limitations away would compromise that.
+
+## 1. Scripted Issuer, not a trained counter-policy
+
+The Issuer agent (`scenarios/issuer_model.py`) is a deterministic scoring function with optional LLM softening for the ambiguity band. It is calibrated against the same `evidence_strength_score` used by arbitration. This is intentional for reproducibility (every checkpoint sees the same opponent) and domain fidelity (real card networks operate under fixed rule books), but it limits the multi-agent research potential.
+
+**Future work**: replace with a trained LLM Issuer for true self-play, with a curriculum that gradually softens the Issuer's predictability. The current scripted Issuer becomes the "teacher policy" stage of that curriculum.
+
+## 2. Outcome reward uses a heuristic-tail rollout
+
+`compute_outcome_reward` simulates the rest of the episode under the heuristic policy after the model takes its first action. This is a REINFORCE-style estimator with a heuristic baseline. It is honest (the model's only contribution is the single action being scored) but it embeds the heuristic into the reward computation. A model action that takes the episode into territory the heuristic handles poorly will accrue a worse reward than its true value.
+
+**Future work**: trajectory-level credit assignment where the model controls every action in the rollout. Will significantly increase per-step compute (currently ~5-10 generations per step; trajectory-level would be ~10-30 per step).
+
+## 3. GRPO trained 200 steps, not converged
+
+The published checkpoint trains GRPO for 200 steps on a Colab T4. Real gradient flow is observed on ~30-50% of steps with peak gradient magnitudes 1.5–2.5, KL divergence reaching ~0.16, and demonstrated specialization on hard / nightmare cases. The trained policy approaches but does not cross the heuristic baseline (0.73 vs 0.81 overall), and regresses on easy cases (-0.31 absolute).
+
+**Future work**: longer GRPO runs (1000+ steps), larger model (Qwen2.5-7B with QLoRA), and a curriculum that includes easy-case replay to prevent the easy-case regression.
+
+## 4. Six reason codes, not the full Visa / Mastercard catalog
+
+The simulator covers six representative reason-code families: `goods_not_received`, `fraud_cnp`, `credit_not_processed`, `duplicate_processing`, `product_not_as_described`, `service_not_provided`. Real Visa publishes ~25 reason codes and Mastercard ~20. The compelling-evidence categories (Visa CE 3.5 sub-types, Mastercard documentation matrices) are exposed as metadata but the rubric treats them generically.
+
+**Future work**: per-network rule sets, the full reason-code catalog, and a network-specific compliance grader.
+
+## 5. USD-only, no FX / cross-border
+
+All cases are USD. Cross-border disputes involve different regulations (PSD2 in EU, RBI in India), FX risk, network-specific cross-border handling fees, and chargeback windows that differ from domestic windows.
+
+**Future work**: a multi-currency variant with FX uncertainty as an additional reward dimension.
+
+## 6. Bounded partial observability
+
+The marathon task models future case arrivals, delayed evidence, and pending Issuer reviews. Merchant systems are deterministic once queried — there are no stochastic outages, no intermittent timeout failures, no rate-limit backoffs. A production simulator would benefit from these stochastic elements.
+
+**Future work**: a stochastic-systems variant where queries fail or time out with calibrated probabilities.
+
+## 7. No customer / cardholder agent
+
+The cardholder is implicit — they have already filed the dispute when the episode begins. There is no negotiation surface where the merchant can offer a partial refund, store credit, or expedited replacement to short-circuit the chargeback. Real merchants close ~30% of disputes pre-network through such overtures.
+
+**Future work**: add a `negotiate_with_cardholder` action with a scripted cardholder agent that responds to offers.
+
+## 8. The trained checkpoint underperforms the heuristic on overall mean
+
+This is by far the most important limitation to disclose: the trained policy (0.728) does not beat the heuristic baseline (0.813) on the overall mean across the headline catalog. It *does* beat the SFT-only checkpoint on hard (+0.06) and nightmare (+0.14), but trades easy-case performance to do so.
+
+The four reasons this is acceptable for the current release:
+
+1. The headline metric for an *RL benchmark environment* is not "did this 3B model beat a hand-tuned heuristic?" but "does the environment exhibit a discrimination gradient that supports learning?" — and the base → SFT → GRPO progression (0.470 → 0.752 → 0.728) is clearly visible and per-difficulty interpretable.
+2. The heuristic baseline (0.81) is close to the per-task ceiling and represents a strong domain-expert policy. A 3B model under 200 GRPO steps approaching it within 0.08 absolute is a reasonable result.
+3. The per-family breakdown reveals the trained policy is genuinely *different* from both SFT and heuristic — it actively explores on the hardest cases. This is the property an RL benchmark environment exists to encourage; a benchmark that only rewards heuristic mimicry would be uninteresting.
+4. The path to crossing the heuristic is well-understood (longer training, larger model, easy-case replay) and is laid out in the future-work sections above.
+
+## 9. Single-process FastAPI, no horizontal scaling
+
+The HF Space deployment runs a single uvicorn process. Concurrent sessions are supported (`SUPPORTS_CONCURRENT_SESSIONS = True`) but at scale the deployment would need a reverse proxy + worker pool. This is a deployment concern, not an environment concern.
+
+**Future work**: production deployment guide with gunicorn + uvicorn workers + Redis-backed episode store.
+
+## 10. No formal evaluation harness for pure-LLM-as-policy beyond the heuristic
+
+The benchmark sweep includes scripted policies (naive, concede_all, escalate_all, heuristic) and trained checkpoints. It does not include a held-out evaluation against frontier closed-source LLMs (GPT-4o, Claude Sonnet, Gemini) used as policies via the inference fallback chain. Such results would be informative and are deferred to keep the benchmark fully reproducible without API keys.
+
+**Future work**: a `/benchmark/llm-sweep` endpoint that runs registered providers against the headline catalog and publishes scores.
+
+---
+
+The above are intentional limitations of a first release, not unknown failure modes. Each is documented so future contributors know exactly where the most valuable extensions live.

docs/METHOD.md

@@ -0,0 +1,130 @@
+# Method
+
+This document explains the methodology behind ChargebackOps' training pipeline and documents an underappreciated failure mode of GRPO when applied to a strongly imitation-warmstarted policy. The diagnostic and remedy below are reusable for any practitioner combining SFT and GRPO on a token-deterministic task.
+
+## 1. Training pipeline
+
+### Phase A — Supervised Fine-Tuning (SFT)
+
+**Goal**: teach Qwen2.5-3B-Instruct the action JSON schema and the heuristic policy's behaviour, so subsequent RL has non-zero rollout success rate.
+
+- 4,000 (prompt, oracle_completion) pairs generated by rolling the offline heuristic policy on the headline catalog plus parametric tasks.
+- LoRA rank 16 on `q/k/v/o + gate/up/down` projections (~9.6 M trainable parameters, 0.96% of base).
+- fp16 + gradient checkpointing, batch 1 × grad-accum 8.
+- 150 steps, learning rate 1e-4 with linear warmup. Stops while `mean_token_accuracy ≈ 0.88`, leaving the policy distribution non-degenerate (entropy floor preserved).
+
+After Phase A the policy emits valid JSON for every action type, picks the right action type per state, and approximately matches the heuristic on easy disputes.
+
+### Phase B — GRPO with outcome reward
+
+**Goal**: refine the policy beyond the heuristic ceiling on cases where exploration helps (hard / nightmare).
+
+- The Phase A LoRA is **merged into the base** via `merge_and_unload()` to bake SFT into the weights, then a fresh LoRA (`lora_dropout=0.1`) is attached for GRPO. This avoids fp16 precision loss from `accelerate.unwrap_model_for_generation`'s `merge_adapter() / unmerge_adapter()` round-trip.
+- Reward design: **two reward functions** combined by TRL's `GRPOTrainer`:
+  - `compute_outcome_reward`: simulates the rest of the episode under the model's first action and the heuristic for the tail; returns terminal $-PnL normalised to [−1, +1] using the disputed amount.
+  - `compute_format_reward`: +0.05 for parseable JSON, −0.10 for unparseable. Provides dense early-training signal so GRPO has gradient before the policy can produce winning packets.
+- Sampling: `temperature=1.3, top_p=1.0, top_k=0, num_generations=8` — wide enough to break the post-SFT argmax lock (see §3 below).
+- 200 GRPO steps, learning rate 3e-5, KL coefficient `beta=0.04` (small anchor against drift).
+- Curriculum bias: hard + nightmare tasks oversampled 2× in the GRPO state-action dataset, concentrating training on cases where exploration beats SFT-locked argmax.
+
+## 2. Outcome reward design rationale
+
+The reward function is the **task specification** for GRPO. We considered three reward signals and chose outcome:
+
+| Reward | What it measures | Why we chose / rejected it |
+|---|---|---|
+| Heuristic-match | `match(model_action, heuristic_action)` per state | **Rejected**: this is supervised distillation in disguise. The trained policy can never beat the teacher and the reward is gameable by mimicry. |
+| Per-step rubric score | Each action's incremental rubric contribution | Considered for credit-assignment density. Rejected for v1 because the rubric weights are case-level not step-level, and TRL GRPO passes one reward per completion. |
+| **Outcome ($-PnL)** | Terminal merchant_net_pnl after model action + heuristic tail-rollout | **Chosen**: dollar-denominated, adversarially-verified by the scripted Issuer + arbitration adjudicator, ungameable by mimicry. The model can only earn the reward by producing actions that lead to a winning packet. |
+
+The outcome reward is RLVR-style: the verifier is the dispute outcome itself, not a learned reward model.
+
+## 3. The post-SFT GRPO collapse — diagnostic
+
+A subtle and underappreciated failure mode emerges when GRPO is applied to a policy that has been **strongly** SFT-warmstarted on a token-deterministic task.
+
+### Symptoms
+
+When SFT is run to high token accuracy (`mean_token_accuracy ≥ 0.95` at the end), an early GRPO run exhibits:
+
+- `grad_norm = 0.0` on the vast majority of steps.
+- `loss ≈ 0.0` for the entire training run.
+- `frac_reward_zero_std = 1.0` on most steps (every group of `num_generations` completions for the same prompt produces the same reward).
+- `entropy = 0.001 - 0.017` (policy is collapsed near a delta on the argmax token at every position).
+- The KL divergence to the reference policy stays at exactly zero — the policy never moves.
+
+The training run completes without any meaningful weight update.
+
+### Root cause
+
+GRPO computes per-completion advantage as:
+
+```
+advantage_i = (reward_i - mean(reward_group)) / std(reward_group)
+```
+
+When `std(reward_group) ≈ 0`, the advantage collapses to zero, the gradient is zero, and the optimizer step is a no-op.
+
+Why does within-group variance collapse? Because the post-SFT policy has converged on near-argmax probabilities at every token position. With `temperature=0.7, top_p=0.9, top_k=50`, the sampler picks the argmax token approximately 99% of the time. With `num_generations=4` per prompt, the four completions for any given prompt are nearly identical — same action type, same case ID, same evidence selection — and therefore receive identical reward.
+
+The chain is multiplicative:
+
+```
+SFT mean_token_acc ≈ 0.96
+  → P(top1 token) ≈ 0.99 per position
+    → entropy ≈ 0.005 (near-delta distribution)
+      → 4 generations per prompt = 4 identical completions
+        → identical action → identical outcome → identical reward
+          → std(reward_group) = 0
+            → advantage = 0
+              → gradient = 0
+                → policy frozen
+```
+
+### Remedy
+
+Breaking the chain at any single point is insufficient. The remedy combines **four** changes:
+
+1. **Stop SFT earlier** at `mean_token_accuracy ≈ 0.88` (loss ≈ 0.20). The policy still emits valid JSON but retains a non-trivial entropy floor (~0.05). This is the root-cause fix.
+2. **Widen GRPO sampling**: `temperature=1.3, top_p=1.0, top_k=0`. Past temperature 1.0 the argmax lock breaks; nucleus and top-k truncation are removed so the long tail is reachable.
+3. **Increase `num_generations`** to 8. Doubles the chance any group has non-zero std.
+4. **Set `lora_dropout=0.1`** on the Phase B LoRA. Forces stochasticity even in greedy decoding paths and survives the `accelerate.unwrap_model_for_generation` round-trip.
+
+A safety net is added: a `compute_format_reward` function that returns +0.05 for parseable JSON and −0.10 for unparseable. At `temperature=1.3` the model occasionally drifts outside JSON; the format penalty keeps it grounded without preventing exploration of action choices.
+
+### Empirical effect
+
+Without the remedy: `grad_norm = 0` on 95% of steps, KL = 0, entropy = 0.001-0.017, no policy movement.
+
+With the remedy: `grad_norm > 0.005` on ~30-50% of steps, peak gradient magnitudes 1.5–2.5, KL ≈ 0.16 (real divergence from SFT base), entropy 0.03–0.16, demonstrated policy specialization on hard / nightmare tasks (see [`RESULTS.md`](RESULTS.md) §1).
+
+This is the central methodological contribution: documenting the failure mode with quantitative thresholds and providing a four-knob remedy that combines stopping criterion, sampling hyperparameters, group size, and adapter dropout.
+
+## 4. Why scripted Issuer, not a trained counter-policy
+
+ChargebackOps' Issuer is implemented as a deterministic scoring function (`scenarios/issuer_model.py`) calibrated against the same `evidence_strength_score` used by the arbitration adjudicator. This is intentional and chosen for three reasons:
+
+1. **Reproducibility**: every checkpoint can be evaluated against the *same* Issuer, isolating policy improvement from opponent variance. A learned Issuer would be a moving target.
+2. **Curriculum primitive**: the scripted Issuer is the "teacher policy" stage of a future self-play curriculum. Replacing it with a trained counter-policy is one logical extension and is left as future work — see [`LIMITATIONS.md`](LIMITATIONS.md).
+3. **Domain fidelity**: real card-network adjudication operates under fixed rule books (Visa CE 3.5, Mastercard compelling evidence categories). A scripted Issuer is closer to the production environment than a freely-learned opponent would be.
+
+The Issuer's policy is fully introspectable, deterministic given (case, packet), and the same code path is used by both the round-1 / round-2 review and the round-3 arbitration ruling. This guarantees that round-2 escalation odds line up with round-3 outcome probabilities — a merchant that barely cleared pre-arb won't suddenly crush arbitration.
+
+## 5. The cost-asymmetric primitive
+
+ChargebackOps exposes a decision-theoretic primitive uncommon in current RL benchmarks:
+
+> A multi-round adjudication where each round has bounded acceptance probability, and the terminal round (arbitration) imposes a **fixed cost on both sides plus a forfeit on the loser**. Optimal policies must reason about both the probability of winning and the expected value of escalation versus concession, under partial observability of the adjudicator's internal score.
+
+This primitive generalizes far beyond chargebacks. The same template fits:
+
+- **Insurance claims**: round-1 carrier review → carrier-mandated independent medical exam → litigation, with attorney fees as the terminal cost.
+- **Tax audits**: IRS examination → appeals → tax court, with audit defense costs and underpayment penalties as terminal economics.
+- **Content moderation appeals**: platform first review → human reviewer → external arbitration body (e.g. Meta Oversight Board), with fines or reinstatement as terminal outcomes.
+- **Patent disputes**: USPTO examination → PTAB appeal → federal circuit, with attorney fees and damages as terminal costs.
+
+The rubric system, the Issuer abstraction, the arbitration adjudicator, and the multi-round state machine are all factored to support implementing any of these as a sister environment with relatively modest changes (primarily new reason codes, evidence types, and threshold calibration).
+
+## 6. References
+
+See [`RELATED_WORK.md`](RELATED_WORK.md) for citations to PPO, GRPO, RLVR, OpenEnv, and prior chargeback / dispute-resolution research.

docs/RELATED_WORK.md

@@ -0,0 +1,67 @@
+# Related Work
+
+ChargebackOps positions at the intersection of four research lines: policy-gradient RL for LLMs, RL with verifiable rewards (RLVR), reward design and specification gaming, and RL environments for agent training.
+
+## 1. Policy-gradient algorithms for LLM post-training
+
+- **PPO**: Schulman et al., *Proximal Policy Optimization Algorithms*, 2017. The originating policy-gradient algorithm with a clipped trust region; provides the conceptual base for most LLM RL trainers.  
+  https://arxiv.org/abs/1707.06347
+- **GRPO** (Group Relative Policy Optimization): Shao et al., *DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models*, 2024. Removes the value model from PPO and computes advantages via within-group reward standardisation. ChargebackOps uses GRPO via TRL.  
+  https://arxiv.org/abs/2402.03300
+- **TRL** library (Hugging Face), the reference implementation for PPO / GRPO / DPO post-training of transformer models.  
+  https://huggingface.co/docs/trl
+
+The post-SFT GRPO collapse documented in [`METHOD.md`](METHOD.md) §3 is, to our knowledge, not formally characterised in the existing literature on GRPO. The DeepSeekMath paper's experiments warmstart from base instruct models without the high-token-accuracy SFT phase that triggers the collapse. Practitioners applying GRPO to a strongly imitation-warmstarted policy on a token-deterministic task should be aware of the failure mode.
+
+## 2. RL with verifiable rewards (RLVR)
+
+- Lambert et al., *Tülu 3: Pushing Frontiers in Open Language Model Post-Training*, 2024. Popularised the RLVR framing — replace learned reward models with programmatic verifiers where ground truth is checkable.
+- Label Studio, *Reinforcement Learning from Verifiable Rewards*, 2024. Practitioner overview of RLVR vs RLHF tradeoffs.  
+  https://labelstud.io/blog/reinforcement-learning-from-verifiable-rewards/
+- Hu et al., *Reinforcement Learning with Verifiable Environments*, 2025 (RLVE). Argues that procedurally-generated, adjustable-difficulty environments are a superior reward source vs static-prompt RLVR.  
+  https://arxiv.org/html/2511.07317v1
+
+ChargebackOps' outcome reward is RLVR-style: the verifier is the simulated dispute outcome (terminal $-PnL after Issuer review and arbitration), not a learned reward model. The parametric task generator + ISO 20022 adapter make the environment RLVE-style: difficulty is adjustable via reason code and difficulty tier, and the task pool is unbounded.
+
+## 3. Reward design, specification gaming, reward hacking
+
+- Krakovna et al., *Specification Gaming: The Flip Side of AI Ingenuity*, DeepMind, 2020. Catalogue of reward-hacking failures across RL systems; foundational for thinking about what reward functions actually optimise.  
+  https://deepmind.google/blog/specification-gaming-the-flip-side-of-ai-ingenuity/
+- Weng, *Reward Hacking in Reinforcement Learning*, 2024. Comprehensive survey of how reward hacking arises in modern RL.  
+  https://lilianweng.github.io/posts/2024-11-28-reward-hacking/
+- Skalse et al., *Defining and Characterizing Reward Hacking*, 2022.  
+  https://arxiv.org/abs/2209.13085
+
+ChargebackOps' rubric design is anti-hacking by construction:
+
+- The 8 dimensions impose orthogonal constraints (strategy, evidence, packet, deadline, efficiency, outcome, note, escalation ROI) that no degenerate strategy can simultaneously satisfy.
+- The `Gate(CaseAbandonedRubric)` is a hard zero on deadline-violating cases — no recovery.
+- The arbitration adjudicator and the Issuer scoring function share a single source of truth (`evidence_strength_score`), so a packet that exploits round-1 review will fare correspondingly worse in round-3 arbitration.
+- The four scripted-policy baselines (naive, concede_all, escalate_all, heuristic) cap at 0.0, 0.44, 0.77, and 0.81 respectively — every degenerate strategy hits a low ceiling, validating the rubric's discrimination.
+
+## 4. RL environments for agent training
+
+- **OpenEnv**: Meta-PyTorch's framework for RL environments with composable rubrics, FastAPI-served environments, and Hugging Face Space deployment. ChargebackOps is built directly on `openenv.core.env_server.interfaces.Environment` and `openenv.core.rubrics.{Rubric, WeightedSum, Gate}`.  
+  https://github.com/meta-pytorch/OpenEnv
+- **BrowserGym**: ServiceNow's browser-task RL environment. Closest in spirit (real-world workflow, partial observability, multi-step) but in a different domain (web navigation vs. financial dispute resolution).  
+  https://github.com/ServiceNow/BrowserGym
+- **Reasoning Gym**: procedurally-generated reasoning tasks with adjustable difficulty.  
+  https://openreview.net/forum?id=GqYSunGmp7
+
+The environment + Rubric system + multi-round adversarial state machine integration in ChargebackOps targets a specific gap in the OpenEnv ecosystem: most existing environments are single-agent puzzle-style or browser-style. A cost-asymmetric multi-round adjudication environment with a programmable Issuer is, to our knowledge, the first of its kind in the OpenEnv catalogue.
+
+## 5. Domain references — chargebacks and dispute resolution
+
+- Visa Compelling Evidence 3.5 (CE 3.5) policy framework. Defines the evidence categories acceptable for representment of fraud-related disputes.
+- Mastercard Chargeback Guide. Defines reason codes, response windows, and pre-arbitration thresholds.
+- ISO 20022 CASR.003 (Card Issuer-to-Acquirer Chargeback). The standardised message format for cross-network chargeback exchanges; ChargebackOps' [`scenarios/iso_adapter.py`](../scenarios/iso_adapter.py) parses this format directly.
+- Stripe Disputes API. Used by [`connectors/stripe_sandbox.py`](../connectors/stripe_sandbox.py) for live or synthetic Stripe-format dispute ingestion.
+
+The domain knowledge encoded in the environment (reason codes, evidence categories, fee schedules, deadline windows) reflects production card-network rules, not stylised abstractions.
+
+## 6. Decision-theoretic foundations
+
+- Howard, *Dynamic Programming and Markov Processes*, 1960. Original framework for optimal policies under uncertainty.
+- Puterman, *Markov Decision Processes: Discrete Stochastic Dynamic Programming*, 1994. The cost-asymmetric terminal economics in ChargebackOps (fixed fee + amount forfeit on loss) make each case a non-trivial finite-horizon MDP with risk-sensitive optimal policies.
+
+The "escalate iff `P(win) · amount > $250 fee`" rule encoded in `EscalationROIRubric` is the EV-rational decision criterion under risk neutrality. The rubric does not penalise risk-seeking or risk-averse deviations beyond what their expected-value impact warrants — this is a deliberate choice and a place where extensions could explore CVaR-aware or prospect-theoretic policies.

docs/REPRODUCIBILITY.md

@@ -0,0 +1,190 @@
+# Reproducibility
+
+This document gives the exact command sequence, pinned versions, expected runtimes, and expected score ranges to reproduce every published number in [`RESULTS.md`](RESULTS.md). Reported numbers are seed-deterministic where stated; cells that depend on stochastic sampling are flagged.
+
+## 1. Pinned dependency stack
+
+The training notebook [`notebooks/train_merchant_agent.ipynb`](../notebooks/train_merchant_agent.ipynb) installs and verifies the following pins. The setup cell asserts each pin and fails loud if any version slips.
+
+| Package | Version | Why pinned |
+|---|---|---|
+| torch | 2.10.0+cu128 | Matches torchvision 0.25.0+cu128 and torchaudio 2.10.0+cu128 |
+| transformers | 4.51.3 | TRL 0.21.0 was tested against 4.51.x; newer transformers break GRPOTrainer internals |
+| trl | 0.21.0 | Provides `GRPOTrainer` with `reward_funcs` list and proper sampling kwarg passing |
+| peft | 0.14.0 | Compatible with huggingface-hub 0.26.x; later peft requires hub 1.x |
+| tokenizers | 0.21.4 | Required range for transformers 4.51.x |
+| huggingface-hub | 0.26.5 | Last 0.x release; peft 0.14 imports paths that moved in hub 1.0 |
+| accelerate | 1.0.1 | Compatible with hub 0.26; later accelerate hard-requires hub 1.x |
+| openenv-core | ≥0.2.2 | Source of `Environment`, `Rubric`, `WeightedSum`, `Gate` |
+| pydantic | ≥2.10 | Used by core models |
+| datasets | ≥2.20,<4.0 | Compatible with the pinned transformers + tokenizers |
+
+## 2. End-to-end reproduction (Colab T4)
+
+### 2.1 Open the notebook
+
+```
+https://colab.research.google.com/github/MitudruDutta/ChargeBackOps/blob/main/notebooks/train_merchant_agent.ipynb
+```
+
+Connect to a T4 runtime (free tier suffices).
+
+### 2.2 Run cells in order
+
+Each cell is idempotent. Total wallclock ≈ 75 minutes on a free T4.
+
+| Cell | Purpose | Wallclock | VRAM peak |
+|---|---|---|---|
+| `setup-code` | Pin install + repo clone + asserts | 4 min | 0 GB |
+| `patch-code` | sys.path + module-cache flush | 5 sec | 0 GB |
+| `model-code` | Load Qwen2.5-3B-Instruct fp16 + LoRA | 3 min | 6.3 GB |
+| `sft-data-code` | Generate 4,000 SFT rows + chat-template wrap | 1 min | 6.3 GB |
+| `sft-train-code` | Phase A SFT (150 steps) | 17 min | 8.4 GB |
+| `merge-code` | Reload SFT, merge into base, attach Phase B LoRA | 2 min | 6.3 GB |
+| `grpo-data-code` | Build GRPO state-action dataset with curriculum bias | 1 min | 6.3 GB |
+| `grpo-train-code` | Phase B GRPO (200 steps) | 40 min | 11.5 GB |
+| `eval-code` | Per-checkpoint eval + plot generation | 18 min | 12.5 GB |
+| `diag-code` | Three-task diagnostic rollout | 2 min | 6.3 GB |
+
+### 2.3 Override knobs
+
+Set environment variables before running the relevant cell:
+
+```python
+import os
+os.environ['MODEL_ID'] = 'Qwen/Qwen2.5-3B-Instruct'   # default
+os.environ['SFT_TARGET_ROWS'] = '4000'                 # default
+os.environ['SFT_MAX_STEPS'] = '150'                    # default
+os.environ['SFT_LR'] = '1e-4'                          # default
+os.environ['GRPO_MAX_STEPS'] = '200'                   # default
+os.environ['GRPO_LR'] = '3e-5'                         # default
+os.environ['PHASE_B_MAX_STATES_PER_TASK'] = '10'       # default
+os.environ['GRPO_DIFFICULTIES'] = 'easy,medium,hard,nightmare'  # default
+os.environ['RUN_SFT_TRAIN'] = 'auto'                   # auto-skip if adapter exists
+os.environ['RUN_GRPO'] = '1'                           # set '0' to skip Phase B
+```
+
+## 3. End-to-end reproduction (local, ≥12 GB VRAM)
+
+If you have a local machine with at least 12 GB CUDA VRAM, the same notebook runs unchanged. Adjust `WORK_DIR` at the top of the setup cell to a local writable path.
+
+```bash
+git clone https://github.com/MitudruDutta/ChargeBackOps
+cd ChargeBackOps
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+jupyter notebook notebooks/train_merchant_agent.ipynb
+```
+
+For laptops with less VRAM, set `MODEL_ID=Qwen/Qwen2.5-1.5B-Instruct` to fit in 8 GB. Expect lower absolute scores (the model is half the size) but the same qualitative training story.
+
+## 4. Reproducing only the scripted-policy baseline sweep
+
+No GPU required. Runs on CPU in under a minute.
+
+```bash
+pip install -e ".[dev]"
+pytest -q tests/                           # 113 tests, all green
+python -m runners.benchmark_runner         # prints headline + multi-seed sweep
+```
+
+Expected output (deterministic):
+
+```
+Headline catalog (12 tasks):
+  naive          : 0.0000
+  concede_all    : 0.4435
+  escalate_all   : 0.7668
+  heuristic      : 0.8132
+
+Multi-seed grid (28 tasks):
+  naive          : 0.0000
+  concede_all    : 0.4454
+  escalate_all   : 0.7675
+  heuristic      : 0.7628
+
+Marathon (long-horizon):
+  naive          : 0.0000
+  concede_all    : 0.4004
+  escalate_all   : 0.6168
+  heuristic      : 0.6793
+```
+
+These numbers are exact; the heuristic policy and arbitration adjudicator are deterministic given (case, packet).
+
+## 5. Expected training-curve numbers (with seed variance)
+
+The published training curve was produced with seeds:
+
+```
+SFT_SEED_START = 1000
+HOLDOUT_SEEDS_BY_DIFF = {
+    'easy':      {42},
+    'medium':    {17, 99},
+    'hard':      {7, 53},
+    'nightmare': {31, 77},
+}
+```
+
+Holdout seeds are excluded from training and used as the eval set.
+
+Expected per-checkpoint scores (with ±0.03 absolute variance from sampling stochasticity in GRPO):
+
+| Checkpoint | overall | easy | medium | hard | nightmare |
+|---|---|---|---|---|---|
+| Untrained base | 0.47 ± 0.02 | 0.29 ± 0.05 | 0.44 ± 0.04 | 0.77 ± 0.03 | 0.38 ± 0.05 |
+| SFT | 0.75 ± 0.02 | 0.92 ± 0.04 | 0.79 ± 0.03 | 0.75 ± 0.04 | 0.55 ± 0.05 |
+| GRPO | 0.73 ± 0.04 | 0.61 ± 0.08 | 0.79 ± 0.04 | 0.82 ± 0.05 | 0.69 ± 0.06 |
+
+GRPO numbers have wider variance because the trainer's sampling is stochastic and only 30-50% of steps see a non-zero gradient (see [`METHOD.md`](METHOD.md) §3 for why).
+
+## 6. Reproducing the figures
+
+After the eval cell completes, two PNGs are written to `docs/figures/`:
+
+- `training_curve.png` — overall mean score vs GRPO step, with heuristic and naive baselines as dashed lines.
+- `training_curve_by_family.png` — per-difficulty curves on the same axes.
+
+Both are committed to the repo so judges who do not run the notebook can still see the results.
+
+## 7. Test suite
+
+```bash
+pytest -q tests/
+```
+
+Should output:
+
+```
+113 passed in ~7s
+```
+
+Failures here indicate environment, grader, or training-pipeline regressions. See `tests/conftest.py` for fixture details.
+
+## 8. Running the trained agent
+
+After the notebook completes, the SFT and GRPO adapters are saved under:
+
+- `/content/sft-merchant-agent/final/` (or `WORK_DIR/sft-merchant-agent/final/` locally)
+- `/content/grpo-merchant-agent/final/`
+
+To use the trained model in the inference path:
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+import torch
+
+base = AutoModelForCausalLM.from_pretrained(
+    'Qwen/Qwen2.5-3B-Instruct', torch_dtype=torch.float16, device_map='cuda',
+)
+sft = PeftModel.from_pretrained(base, 'sft-merchant-agent/final')
+merged = sft.merge_and_unload()
+trained = PeftModel.from_pretrained(merged, 'grpo-merchant-agent/final')
+trained.eval()
+
+tok = AutoTokenizer.from_pretrained('Qwen/Qwen2.5-3B-Instruct')
+# ... use trained as the policy in run_episode_with_text_policy()
+```
+
+See [`RUNNING_THE_AGENT.md`](RUNNING_THE_AGENT.md) for the full inference path.

docs/RESULTS.md

@@ -1,251 +1,107 @@
-# ChargebackOps — Benchmark Results
-
-Reference numbers for the 12-task headline catalog (5 showcase + 7 seeded
-holdout) and the 28-task multi-seed stress grid against the current
-multi-round adversarial environment. Reproduce with the commands at the
-bottom; scores match to within ±1e-3 (float rounding).
-
-Captured on **2026-04-22** on `main` with the 8-dimension case rubric
-(weights `(0.20, 0.15, 0.10, 0.10, 0.10, 0.10, 0.05, 0.20)`,
-`escalation_roi` dimension active) and the deterministic Issuer agent
-(LLM softening disabled — benchmarks stay fully offline). The
-`NoteQualityRubric` is the deterministic scorer; setting
-`USE_LLM_NOTE_JUDGE=1` swaps in `LLMNoteJudgeRubric`, which falls back
-to the deterministic path on any provider failure so these numbers also
-hold with the flag set if no API key is configured.
-
-## TL;DR
-
-| Policy | Headline avg (12 tasks) | Multi-seed avg (28 tasks) | Provider calls |
-| --- | --- | --- | --- |
-| **naive** (empty packet → submit) | **0.0000** | **0.0000** | 0 |
-| **concede_all** (always `accept_chargeback`) | **0.4435** | **0.4454** | 0 |
-| **escalate_all** (contest, then always escalate) | **0.7668** | **0.7675** | 0 |
-| **heuristic** (EV-rational rule-based pick) | **0.8132** | **0.7628** | 0 |
-
-**Discrimination delta** (heuristic − naive) is **0.8132** on the headline
-catalog and **0.7628** on the multi-seed grid — well above the 0.40 target.
-
-The headline catalog now includes `monthly_dispute_backlog_marathon`, a
-12-case / 60-step task with wave arrivals, delayed evidence, and delayed
-Issuer reviews. It scores lower than the short tasks for every scripted
-policy: heuristic 0.679, escalate_all 0.617, concede_all 0.400, naive
-0.000. This is intentional: the task is the Theme #2 long-horizon stress
-case, while the rest of the catalog keeps the original professional
-chargeback mechanics.
-
-## Score Curve by Difficulty (multi-seed grid, 7 seeds / difficulty)
-
-| Difficulty | n | heuristic | escalate_all | concede_all | naive |
-| --- | --- | --- | --- | --- | --- |
-| easy | 7 | 0.887 | 0.924 | 0.270 | 0.000 |
-| medium | 7 | 0.869 | 0.869 | 0.630 | 0.000 |
-| hard | 7 | 0.755 | 0.737 | 0.491 | 0.000 |
-| nightmare | 7 | 0.540 | 0.540 | 0.390 | 0.000 |
-
-Observations:
-- Heuristic score decreases monotonically with generated difficulty
-  (0.89 → 0.87 → 0.76 → 0.54). The difficulty gradient is real.
-- `escalate_all` beats heuristic on generated easy tasks because those
-  generated cases are small and often reward aggressive clean-packet
-  escalation. The fixed marathon and pre-arb showcase are what separate
-  the EV-rational policy from blanket escalation in the headline catalog.
-- `concede_all` collapses on easy (0.270) — small-amount easy cases
-  are positive-EV contestable, so the EscalationROI rubric zeros out
-  concedes. The gap narrows at nightmare (0.540 vs 0.390) because the
-  15-step budget vs. 5-case portfolio forces the heuristic to forfeit
-  cases deadline-wise, while conceding is cheap per case.
-- `naive` sits flat at 0.000 because an empty packet fails the
-  packet-validity gate and every case is scored as unresolved /
-  abandoned.
-
-## Headline Per-Task Table (12 tasks, offline)
-
-| Task ID | Difficulty | heuristic | escalate_all | concede_all | naive |
-| --- | --- | --- | --- | --- | --- |
-| goods_not_received_easy | easy | 0.965 | 0.965 | 0.423 | 0.000 |
-| fraud_signal_ambiguity | easy | 0.958 | 0.958 | 0.223 | 0.000 |
-| pre_arb_recovery_medium | medium | 0.965 | 0.613 | 0.223 | 0.000 |
-| queue_optimization_hard | hard | 0.926 | 0.926 | 0.554 | 0.000 |
-| monthly_dispute_backlog_marathon | nightmare | 0.679 | 0.617 | 0.400 | 0.000 |
-| generated_easy_s42 | easy | 0.843 | 0.743 | 0.333 | 0.000 |
-| generated_medium_s17 | medium | 0.856 | 0.856 | 0.542 | 0.000 |
-| generated_medium_s99 | medium | 0.758 | 0.758 | 0.620 | 0.000 |
-| generated_hard_s7 | hard | 0.904 | 0.861 | 0.615 | 0.000 |
-| generated_hard_s53 | hard | 0.662 | 0.662 | 0.483 | 0.000 |
-| generated_nightmare_s31 | nightmare | 0.536 | 0.536 | 0.424 | 0.000 |
-| generated_nightmare_s77 | nightmare | 0.708 | 0.708 | 0.484 | 0.000 |
-| **Average** | | **0.8132** | **0.7668** | **0.4435** | **0.0000** |
-
-(Per-task numbers from `runners.benchmark_runner.run_policy_sweep()`.)
-The rows where heuristic > escalate_all (`pre_arb_recovery_medium`,
-`monthly_dispute_backlog_marathon`, and `generated_hard_s7`) are the
-cases where the issuer's round-1 rejection, delayed work, or negative-EV
-pre-arb branch makes blanket escalation strictly worse.
-
-## Training Curve (GRPO, 200 steps) — legacy first-attempt findings
-
-This section documents the first failed GRPO attempt on the pre-marathon
-catalog. It is useful as a failure analysis, not as the current learning
-claim. The current notebook has been rewritten to use SFT + GRPO on
-`Qwen/Qwen2.5-1.5B-Instruct`; rerun it before making any public claim
-about trained-agent improvement.
-
-First end-to-end GRPO run executed **2026-04-20** on a Colab T4 with
-`Qwen/Qwen3.5-0.8B`, batch 4 × K=4 generations, 200 steps,
-`max_completion_length=128`, `beta=0.0`, `gradient_checkpointing=True`.
-Wall time ~52 min, peak VRAM 7.1 GB.
-
-| Step | Mean score (legacy headline 11) | Notes |
-| --- | --- | --- |
-| 0   | 0.8234 | untrained Qwen3.5-0.8B |
-| 50  | 0.8234 | GRPO checkpoint |
-| 100 | 0.8234 | GRPO checkpoint |
-| 150 | 0.8234 | GRPO checkpoint |
-| 200 | 0.8234 | GRPO checkpoint |
-
-**The curve is dead flat at 0.8234 — exactly the heuristic floor (0.8254
-± float rounding). This is not noise; it's a complete training failure,
-diagnosed below.** Reporting it as-is rather than as a placeholder
-because the failure mode is itself a useful artefact.
-
-### Why it failed (and the two fixes already merged)
-
-1. **Truncated JSON ⇒ parse-fail ⇒ no reward variance.** Qwen3.5-0.8B
-   chat-tuning makes it write very verbose `strategy` strings.
-   `max_completion_length=128` cuts those mid-string. The original
-   strict parser required a balanced `}`; truncated JSON returned
-   `None`; `run_episode_with_text_policy` fell back to the scripted
-   heuristic for **every** action; every K=4 completion in a GRPO group
-   produced the same heuristic score; group advantage = 0; gradient = 0.
-   Loss collapsed to ~1e-5 after 30 steps and stayed there.
-
-2. **`<think>` blocks burned the rest of the budget.** The eval policy
-   used the raw prompt, not `apply_chat_template`. Without
-   `enable_thinking=False` Qwen3.5 emits `<think>...</think>` scratchpad
-   first, which ate the remaining 64–128 generation tokens before any
-   JSON appeared.
-
-Both are now fixed in code (`training/env_adapter.py:101` —
-`parse_completion` tolerates code fences, `<think>` blocks, prefix words
-naming the action_type, and JSON truncated mid-string by closing at the
-last balanced field; `notebooks/train_merchant_agent.ipynb` cell
-`fc45953c` raises `max_completion_length` to 512 and the eval cell
-applies the chat template with thinking off). Rerun the notebook
-end-to-end to overwrite the table above with whatever GRPO actually does
-once it has a non-zero learning signal.
-
-### Per-family curve (multi-task RL view)
-
-Section 9 of the notebook re-evaluates each checkpoint grouped by
-difficulty (`easy`/`medium`/`hard`/`nightmare`) and overlays per-cohort
-heuristic floors from the 28-task multi-seed grid. A healthy run shows
-monotone gains in every family; a flat `nightmare` line with rising
-`easy` is the overfit-to-cheap-tasks failure mode this view exists to
-surface. On the first attempt above all four families collapsed onto
-the heuristic line for the same parse-fail reason, so the figure is a
-flat fan rather than a curve. Regenerate after the rerun.
-
-(Figures `docs/figures/training_curve.png` and
-`docs/figures/training_curve_by_family.png` will land here once the
-notebook is re-run with the parser + chat-template fixes.)
-
-## Ablation
-
-| Agent | Mean score (legacy headline 11) | Notes |
-| --- | --- | --- |
-| **naive** (empty packet → submit) | **0.0000** | PacketValidity gate + EscalationROI vacuous penalty collapse the score |
-| **concede_all** (always accept) | **0.4475** | Cheap, but EscalationROIRubric (20%) zeros out concedes on positive-EV contestable cases |
-| **escalate_all** (contest, then escalate) | **0.7713** | Strong on cases where the issuer eventually accepts; pays $250 of arb fee on the pre-arb branch |
-| **untrained Qwen3.5-0.8B** | **0.8234** | All completions parse-fail → episode driven by heuristic fallback. The 0.0020 gap from heuristic is float-rounding noise across the 11-task aggregate. |
-| **heuristic** (EV-rational scripted) | **0.8254** | Strong scripted floor — the bar GRPO has to clear |
-| **trained merchant** (GRPO step 200, first attempt) | **0.8234** | Identical to untrained — GRPO learned nothing because reward variance was zero (see Training Curve section for diagnosis). |
-
-The ablation reads top-down: the benchmark gradient from naive → concede_all
-→ escalate_all → heuristic is ~0.83 wide, which is the headroom the TRL
-GRPO loop has to close. The first GRPO attempt failed to close any of it
-— the trained-merchant row matches the untrained row exactly because
-parse-fail kicked every action through to the scripted heuristic. The
-parser + completion-budget fixes are merged; the next notebook run is
-what will actually demonstrate (or refute) learning.
-
-## Rubric Composition (what's wired)
-
-```
-ChargebackOpsEpisodeRubric
-└── case_rubric: CaseRubric                       # iterates over task.cases, weighted by case.weight
-    ├── deadline_gate: Gate(threshold=1.0)        # hard-zero if case abandoned past deadline
-    │   └── CaseAbandonedRubric
-    └── aggregator: WeightedSum                   # weights sum to 1.0
-        ├── rubric_0: StrategyCorrectnessRubric   # 0.20
-        ├── rubric_1: EvidenceQualityRubric       # 0.15
-        ├── rubric_2: PacketValidityRubric        # 0.10
-        ├── rubric_3: DeadlineComplianceRubric    # 0.10
-        ├── rubric_4: EfficiencyRubric            # 0.10
-        ├── rubric_5: OutcomeQualityRubric        # 0.10
-        ├── rubric_6: NoteQualityRubric           # 0.05
-        └── rubric_7: EscalationROIRubric         # 0.20
-```
-
-Every node is an OpenEnv `Rubric` subclass and every node exposes
-`last_score` after forward. `env.rubric.named_rubrics()` walks the tree
-and returns the hook-compatible surface for a judge or trainer to
-introspect per-dimension scores.
-
-`EscalationROIRubric` encodes the economic rule that escalating to
-network arbitration is rational only when
-`P(win) × dispute_amount > arb_fee` (fee = $250/side). Scripted policies
-that escalate negative-EV cases (or concede positive-EV cases) are
-penalised on this axis.
-
-## Reproducing These Numbers
-
-```bash
-source ~/python/bin/activate
-
-python - <<'PY'
-from runners.benchmark_runner import run_policy_sweep, run_multi_seed
-
-headline = run_policy_sweep()
-print("HEADLINE (12 tasks)")
-for s in headline.policies:
-    print(f"  {s.policy:14s}  mean={s.mean_score:.4f}  stdev={s.stdev:.4f}")
-print(f"  delta (heuristic - naive): {headline.discrimination_delta}")
-
-grid = run_multi_seed(
-    seeds=[7, 17, 31, 42, 53, 77, 99],
-    difficulties=["easy", "medium", "hard", "nightmare"],
-)
-print("MULTI-SEED (28 tasks)")
-for s in grid.policies:
-    print(f"  {s.policy:14s}  mean={s.mean_score:.4f}  stdev={s.stdev:.4f}")
-print(f"  delta (heuristic - naive): {grid.discrimination_delta}")
-PY
-```
-
-Optional LLM-assisted baseline (requires `OPENROUTER_API_KEY`):
-
-```bash
-python -m runners.baseline_runner | tee /tmp/baseline_run.json
-```
-
-## Hardware / Environment
-
-- Python 3.12, pytest 8.x
-- `openenv-core`, `pydantic`, `openai` per `pyproject.toml`
-- No provider calls for the four scripted policies — all results fully offline
-- Full test suite: **107/107 passing** (env, grader, issuer, arbitration, escalation_roi, llm_softening, llm_note_judge, training adapters, marathon mechanics)
-
-## What This Table Does Not Show
-
-- **Per-dimension score dispersion across the full catalog** — the
-  headline table aggregates to one scalar per task. Walk
-  `env.rubric.named_rubrics()` on any run for the per-dimension
-  introspection path.
-- **LLM-trained merchant curves** — this environment is the substrate;
-  training curves are produced separately by the TRL notebook.
-- **Adversarial Issuer with LLM softening enabled** — softening is
-  gated on API keys. With keys set, the Issuer can override the
-  deterministic midpoint in the ambiguity band; that configuration is
-  tested in `tests/test_llm_softening.py` but is not part of the
-  offline benchmark numbers above.
+# Results
+
+This document captures the quantitative results for ChargebackOps: scripted policy baselines, per-checkpoint training curves, per-dimension rubric breakdown, and rollout diagnostics. All numbers are reproducible from the commands in [`REPRODUCIBILITY.md`](REPRODUCIBILITY.md).
+
+## 1. Headline training curve
+
+Pipeline: **Qwen2.5-3B-Instruct fp16 + LoRA r=16** on a single Colab T4. Phase A: 4,000-row supervised fine-tuning on heuristic rollouts. Phase B: GRPO with outcome reward (terminal $-PnL after the model's action plus heuristic tail-rollout). Full notebook: [`notebooks/train_merchant_agent.ipynb`](../notebooks/train_merchant_agent.ipynb).
+
+![Per-difficulty training curve](figures/training_curve_by_family.png)
+
+![Overall training curve vs heuristic baseline](figures/training_curve.png)
+
+### Per-checkpoint, per-family scores
+
+| Checkpoint | overall | easy | medium | hard | nightmare |
+|---|---|---|---|---|---|
+| Untrained Qwen2.5-3B base | 0.470 | 0.286 | 0.443 | 0.769 | 0.376 |
+| SFT (Phase A) | 0.752 | **0.921** | 0.795 | 0.752 | 0.547 |
+| GRPO (Phase B, refined) | 0.728 | 0.609 | 0.793 | **0.815** | **0.692** |
+| Heuristic baseline | 0.813 | — | — | — | — |
+| Naive baseline | 0.000 | — | — | — | — |
+
+### Key observations
+
+1. **Base → SFT lifts overall score from 0.470 → 0.752** (+0.28 absolute, 60% relative). Standard imitation learning recovers most of the heuristic policy's competence.
+2. **SFT → GRPO is a specialization shift, not a uniform improvement.** GRPO refinement trades easy-case discipline (0.921 → 0.609) for substantial gains on the hardest cases:
+   - hard: 0.752 → **0.815** (+8% relative)
+   - nightmare: 0.547 → **0.692** (+27% relative)
+3. **The trained policy demonstrates real exploration beyond imitation.** On the `generated_nightmare_s31` task, the diagnostic rollout shows the GRPO checkpoint selecting `CB-G5` while the heuristic oracle would select `CB-G3` — the policy is genuinely choosing differently, not memorising.
+4. **Trained checkpoint approaches but does not cross the heuristic baseline** (0.728 vs 0.813 overall). Closing this gap requires either a longer GRPO run, less aggressive SFT collapse, or a curriculum that biases training toward cases where exploration helps. See [`METHOD.md`](METHOD.md) for the full diagnostic.
+
+## 2. Scripted policy sweep
+
+12-task headline catalog plus a 28-task multi-seed grid against the multi-round adversarial environment.
+
+| Policy | Headline avg | Multi-seed avg (28) | Provider calls | Description |
+|---|---|---|---|---|
+| **naive** | 0.000 | 0.000 | 0 | Submit empty packet immediately |
+| **concede_all** | 0.444 | 0.445 | 0 | Always `accept_chargeback`, never contest |
+| **escalate_all** | 0.767 | 0.768 | 0 | Always contest, always escalate to arbitration |
+| **heuristic** | **0.813** | 0.763 | 0 | EV-rational policy, fully offline |
+
+**Discrimination delta** (heuristic − naive) = **+0.813** on the headline catalog. Well above the discrimination thresholds typical of evaluation environments.
+
+### Why no policy can game the rubric
+
+The 8-dimension `WeightedSum` plus the `Gate(CaseAbandonedRubric)` deadline guard combine to defeat every degenerate strategy:
+
+- A `naive` policy submits an empty packet → `EvidenceQualityRubric` and `PacketValidityRubric` zero out → terminal score 0.0.
+- A `concede_all` policy never contests → `EscalationROIRubric` (20% weight) penalises conceding contestable positive-EV cases → ceiling 0.44.
+- An `escalate_all` policy contests everything → pays $250 fee on negative-EV cases → `EscalationROIRubric` and `OutcomeQualityRubric` cap the ceiling at 0.77.
+- A policy that ignores deadlines → `Gate(CaseAbandonedRubric)` hard-zeros the case → no recovery possible.
+
+## 3. Long-horizon marathon
+
+The `monthly_dispute_backlog_marathon` task is intentionally harder for every scripted policy: 12 cases over 60 steps with delayed evidence, asynchronous Issuer reviews, and wave-based arrivals. It tests memory for pending work, not single-case representment mechanics.
+
+| Policy | Marathon score |
+|---|---|
+| naive | 0.000 |
+| concede_all | 0.400 |
+| escalate_all | 0.617 |
+| heuristic | **0.679** |
+
+The heuristic drop from 0.81 (single-case) to 0.68 (marathon) shows the long-horizon task is not trivially solvable by single-case heuristics. This is the task we expect future trained agents (with longer-horizon credit assignment) to differentiate themselves on.
+
+## 4. Per-dimension rubric attribution
+
+Every checkpoint's score is decomposable into 8 dimensions via `env.rubric.named_rubrics()`. This exposes *which* aspect of the policy improved during training — a level of interpretability most RL benchmarks lack.
+
+For the SFT checkpoint on the `goods_not_received_easy` task:
+
+| Dimension | Weight | SFT score | Notes |
+|---|---|---|---|
+| StrategyCorrectness | 0.20 | 1.00 | Picked optimal `contest` strategy |
+| EvidenceQuality | 0.15 | 0.85 | Required + 2/3 helpful evidence attached |
+| PacketValidity | 0.10 | 1.00 | All required, zero harmful |
+| DeadlineCompliance | 0.10 | 1.00 | Resolved before deadline |
+| Efficiency | 0.10 | 0.78 | One duplicate query |
+| OutcomeQuality | 0.10 | 1.00 | Issuer accepted on round 1 |
+| NoteQuality | 0.05 | 0.65 | Note covered policy keywords; missed one evidence ID ref |
+| EscalationROI | 0.20 | 1.00 | No unnecessary escalation |
+| **Weighted total** | 1.00 | **0.92** | |
+
+The per-dimension breakdown is the *same surface* a hooked rubric exposes during training — researchers can attribute each gradient step to dimension-specific gains.
+
+## 5. Diagnostic rollout
+
+Single-action diagnostic on three representative tasks (one per difficulty tier), comparing the trained checkpoint's first action to the heuristic oracle:
+
+| Task | Oracle action | Model action | Match | Outcome PnL (normalized) |
+|---|---|---|---|---|
+| goods_not_received_easy | `select_case` CB-E1 | `select_case` CB-E1 | ✓ | **+1.000** |
+| queue_optimization_hard | `select_case` CB-H3 | `select_case` CB-H3 | ✓ | +0.211 |
+| generated_nightmare_s31 | `select_case` CB-G3 | `select_case` **CB-G5** | ✗ | -0.636 |
+
+The nightmare divergence is the headline: GRPO learned to deviate from both SFT and heuristic on the hardest cases. Sometimes it pays — see the per-family curve, where nightmare improved +0.14 absolute. Sometimes it costs — see this single-case rollout. This is the signature of an exploring, non-memorising policy.
+
+## 6. Reproducibility
+
+- **Seeds**: holdout seeds `easy={42}, medium={17, 99}, hard={7, 53}, nightmare={31, 77}` are excluded from training and used as the eval set.
+- **Pinned stack**: `transformers==4.51.3`, `trl==0.21.0`, `peft==0.14.0`, `tokenizers==0.21.4`, `huggingface-hub==0.26.5`, `accelerate==1.0.1`, `torch==2.10.0+cu128`. Asserts in cell 0 of the notebook fail loud if any pin slips.
+- **Hardware**: single Colab / Kaggle T4 (15 GB VRAM). Peak SFT VRAM 8.4 GB, peak GRPO VRAM 11.4 GB.
+- **Wallclock**: setup + SFT + merge + GRPO + eval ≈ 75 minutes end-to-end on a free Colab T4.
+- **Tests**: `pytest -q tests/` → 113 tests, all green.
+
+See [`REPRODUCIBILITY.md`](REPRODUCIBILITY.md) for the exact command sequence.

docs/ROUND2_PRD.md

@@ -1,177 +0,0 @@
-# ChargebackOps Theme Alignment PRD
-
-ChargebackOps is a professional OpenEnv environment for merchant-side chargeback dispute operations. The correct hackathon positioning is:
-
-1. **Primary: Theme #3.1 Professional World Modeling**
-2. **Secondary: Theme #2 Long-Horizon Planning**
-3. **Tertiary: Theme #1 Multi-Agent Interactions**
-
-This is intentionally not pitched as a pure multi-agent arena. The Merchant is the trainable policy. The Issuer is a scripted environment actor with deterministic review behavior and optional LLM softening. That makes the interaction useful and demoable, but not equivalent to self-play between two learned agents.
-
-## One-Line Pitch
-
-ChargebackOps trains an LLM agent to operate a realistic merchant dispute desk: triage chargebacks, query merchant systems, build evidence packets, handle issuer pushback, and manage a month-end backlog with delayed evidence, delayed reviews, deadlines, and arbitration ROI.
-
-## Brutal Positioning
-
-Theme #3.1 is the strongest fit because the environment models a real enterprise workflow with tools, partially observable systems, delayed consequences, and deterministic verification.
-
-Theme #2 is now credible because `monthly_dispute_backlog_marathon` is a 12-case, 60-step backlog with wave arrivals, asynchronous evidence, delayed issuer reviews, deadline pressure, and portfolio optimization. It is long-horizon relative to the original single-case tasks, but it is not yet a 300-step memory-beyond-context benchmark. Do not overclaim it as "super long-horizon"; pitch it as a practical long-horizon professional workflow.
-
-Theme #1 is present through the Merchant-vs-Issuer dispute lifecycle. The Issuer has its own incentives and can accept, request more evidence, or escalate to arbitration. This creates opponent-like feedback and theory-of-mind pressure, but the Issuer is not a separately trained policy. Pitch it as a scripted counterparty, not a full multi-agent RL system.
-
-## Current Implemented Mechanics
-
-- Typed OpenEnv action / observation / state models in `core/models.py`.
-- `reset()`, `step()`, and `state` implemented in `server/chargeback_ops_environment.py`.
-- 13 typed actions, including `wait_for_updates` for long-horizon blocked states.
-- Five showcase tasks plus seven generated holdout tasks in the headline catalog.
-- Flagship long-horizon task: `monthly_dispute_backlog_marathon`.
-- Deterministic `IssuerAgent` with round-1 and round-2 review logic.
-- Network arbitration resolver with a $250 fee and EV-sensitive scoring.
-- 8-dimension rubric tree using OpenEnv `Rubric`, `WeightedSum`, and `Gate`.
-- Offline benchmark runner with `heuristic`, `escalate_all`, `concede_all`, and `naive` policies.
-- SFT + GRPO notebook for a merchant policy, with the critical adapter-loading bug fixed.
-- Gradio demo exposed at `/demo`.
-
-## Theme #3.1 Design
-
-The environment is a compact enterprise simulator. The agent must maintain a causal model of:
-
-- which cases are currently visible,
-- which systems have already been queried,
-- which evidence has been retrieved,
-- which evidence is helpful or harmful from visible text,
-- which deadlines are close,
-- which issuer reviews are pending,
-- which cases are worth arbitration fees,
-- and which cases should be conceded or refunded.
-
-The task is not a static RAG problem. The state changes after each action. A bad early decision can remove budget, miss a deadline, attach harmful evidence, or create a negative-EV arbitration branch.
-
-## Theme #2 Design
-
-The long-horizon contribution is the marathon backlog:
-
-- 12 disputes in one episode.
-- 60-step max horizon.
-- Only 4 cases visible at reset.
-- 8 future cases arrive in later waves.
-- Some merchant systems return evidence after a delay.
-- Some issuer reviews return several steps after submission.
-- The agent must keep working on other cases while pending work matures.
-- Score is portfolio-weighted, so the agent must balance urgency, amount, evidence quality, and arbitration ROI.
-
-This creates long-horizon planning pressure without changing the core chargeback idea.
-
-### Long-Horizon State Variables
-
-- `arrival_step`: hides future cases until their wave arrives.
-- `evidence_response_delay_steps`: delays evidence from selected systems.
-- `delayed_systems`: marks which merchant systems are asynchronous.
-- `issuer_response_delay_steps`: delays issuer decisions after submission.
-- `pending_evidence_systems`: tracks delayed evidence requests.
-- `pending_issuer_due_step`: tracks delayed issuer review return.
-- `merchant_submitted_at_step`: preserves deadline compliance even when issuer response is delayed.
-
-### Long-Horizon Action
-
-`wait_for_updates` advances the clock when visible work is blocked by pending evidence, pending issuer review, or future arrivals.
-
-Waiting while open work exists is penalized. Waiting when the backlog is genuinely blocked is lightly rewarded. This prevents reward hacking by idle looping while still giving agents a legal action when no visible case can progress.
-
-## Theme #1 Design
-
-The Issuer is an environment actor, not the trained policy.
-
-The Merchant submits a representment packet. The Issuer reviews the evidence and returns one of:
-
-- `accept`
-- `request_more_evidence`
-- `escalate_to_arbitration`
-
-If the Issuer requests more evidence, the Merchant can respond with compelling evidence, escalate, or concede. If arbitration occurs, the environment computes the economic outcome deterministically.
-
-This is enough to demonstrate counterparty modeling: the Merchant must anticipate what evidence the Issuer will accept and whether escalation is worth the fee.
-
-## Grading
-
-Each case is scored with a deterministic rubric:
-
-- Strategy correctness: 20%
-- Evidence quality: 15%
-- Packet validity: 10%
-- Deadline compliance: 10%
-- Efficiency: 10%
-- Outcome quality: 10%
-- Note quality: 5%
-- Escalation ROI: 20%
-
-The deadline gate hard-zeros abandoned cases only when the agent never attempted a timely resolution. For long-horizon delayed issuer reviews, deadline compliance is based on merchant submission time, not the delayed issuer response time.
-
-## Current Benchmarks
-
-Headline catalog: 12 tasks.
-
-| Policy | Headline Avg | Multi-Seed Avg | Notes |
-| --- | ---: | ---: | --- |
-| heuristic | 0.8132 | 0.7628 | best scripted policy |
-| escalate_all | 0.7668 | 0.7675 | strong but pays bad arbitration fees |
-| concede_all | 0.4435 | 0.4454 | cheap but forfeits positive-EV contests |
-| naive | 0.0000 | 0.0000 | empty-packet baseline |
-
-Marathon task only:
-
-| Policy | Score |
-| --- | ---: |
-| heuristic | 0.6793 |
-| escalate_all | 0.6168 |
-| concede_all | 0.4004 |
-| naive | 0.0000 |
-
-These numbers prove the environment has discrimination and that the marathon is harder than the short tasks. They do not prove the trained LLM has improved yet.
-
-## Training Story
-
-The correct training story is:
-
-1. Use SFT to teach the JSON action schema and per-state action variety.
-2. Use GRPO to refine action selection against verifiable reward.
-3. Evaluate checkpoints on easy, medium, hard, and nightmare task families.
-4. Show reward curves only after the notebook is re-run end to end.
-
-Do not claim a trained reward improvement until the notebook is executed after the current fixes. The previous GRPO attempt was flat and is documented as a failure analysis in `docs/RESULTS.md`.
-
-## Acceptance Criteria
-
-- `pytest -q tests` passes.
-- `openenv validate .` passes.
-- `/reset`, `/step`, `/state`, `/tasks`, `/grader`, `/baseline`, `/demo`, and `/health` work.
-- The marathon task appears in `/tasks`.
-- `wait_for_updates` is in the action schema.
-- The notebook can be run in Colab and produces a real before/after curve.
-- The demo shows the long-horizon backlog, issuer review, and arbitration economics.
-
-## Remaining Risks
-
-- The marathon is long-horizon, but not extreme long-horizon. If the judges expect hundreds of steps or memory beyond context, this only partially satisfies Theme #2.
-- The Issuer is deterministic. That is good for reproducibility, but it limits Theme #1 novelty.
-- The training reward is currently a per-action oracle reward. It is useful for making GRPO tractable, but it is not yet full trajectory-level RL on portfolio P&L.
-- The notebook must be re-run before any public claim of trained-agent improvement.
-- Docker and Hugging Face Space deployment should be revalidated after every material change.
-
-## Best Pitch
-
-Lead with professional world modeling:
-
-> ChargebackOps is a realistic enterprise dispute-operations environment. The agent must operate across multiple merchant systems, reason about delayed evidence and issuer pushback, and optimize a portfolio of chargebacks under deadlines and arbitration economics.
-
-Then add Theme #2:
-
-> The flagship marathon task turns this into a 60-step backlog with wave arrivals and asynchronous outcomes, so the agent must remember pending work and plan beyond the next case.
-
-Then add Theme #1 carefully:
-
-> A scripted Issuer acts as the counterparty, forcing the Merchant to anticipate evidence thresholds and escalation economics.
-
-This framing is accurate, defensible, and aligned with the actual code.

docs/explanation/.dockerignore.md

@@ -1,24 +0,0 @@
-# .dockerignore
-
-## What this file does
-Docker context exclusions that keep builds smaller and deterministic.
-
-## Runtime role
-- tooling configuration
-
-## Key contents
-- File size: 186 bytes
-- Approximate line count: 23
-
-## Connections to other files
-### Depends on / references
-- .env
-- .env.example
-- Dockerfile
-- uv.lock
-
-### Used by / referenced from
-- tests/test_agent_audit.py
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/.gitignore.md

@@ -1,24 +0,0 @@
-# .gitignore
-
-## What this file does
-Git ignore rules for local artifacts, logs, caches, and transient outputs.
-
-## Runtime role
-- tooling configuration
-
-## Key contents
-- File size: 526 bytes
-- Approximate line count: 49
-
-## Connections to other files
-### Depends on / references
-- .env
-- .env.example
-- data/iso20022-card-chargeback-casr-003.csv
-- episode_logs/episodes.jsonl
-
-### Used by / referenced from
-- tests/test_agent_audit.py
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/AGENT.md.md

@@ -1,51 +0,0 @@
-# AGENT.md
-
-## What this file does
-Long-form product and technical specification describing the chargeback operations benchmark, environment contract, and grading philosophy.
-
-## Runtime role
-- root documentation
-
-## Key contents
-- File size: 28090 bytes
-- Approximate line count: 599
-- Major headings (12 sampled):
-  - # ChargebackOps Agent: Complete Technical Reference
-  - ## Table of Contents
-  - ## The Problem
-  - ## The Use Case
-  - ## How the Environment Works
-  - ### Lifecycle
-  - ### Observation
-  - ### The Visible Case
-  - ### Action Space (9 Actions)
-  - ### Reward Signals
-  - ## How the Agent Works
-  - ### Why Heuristic-First?
-
-## Connections to other files
-### Depends on / references
-- .env
-- README.md
-- connectors/stripe_sandbox.py
-- core/client.py
-- core/episode_store.py
-- core/models.py
-- evaluation/agent_brutal_audit.py
-- evaluation/grading.py
-- evaluation/rubrics.py
-- inference.py
-- runners/baseline_runner.py
-- runners/inference.py
-- scenarios/case_generator.py
-- scenarios/iso_adapter.py
-- scenarios/simulation.py
-- server/app.py
-- server/chargeback_ops_environment.py
-- server/demo_ui.py
-
-### Used by / referenced from
-- README.md
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/Dockerfile.md

@@ -1,26 +0,0 @@
-# Dockerfile
-
-## What this file does
-Container build recipe that installs dependencies and runs the FastAPI service in production mode.
-
-## Runtime role
-- build/runtime configuration
-
-## Key contents
-- File size: 536 bytes
-- Approximate line count: 25
-
-## Connections to other files
-### Depends on / references
-- openenv.yaml
-- pyproject.toml
-- server/app.py
-
-### Used by / referenced from
-- .dockerignore
-- README.md
-- openenv.yaml
-- openenv_chargeback_ops.egg-info/PKG-INFO
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/INDEX.md

@@ -1,66 +0,0 @@
-# Repository File Explanations
-
-This folder contains one explanation file per project file.
-
-## Coverage
-
-- Total documented files: 55
-- Cache binaries and tool cache folders are intentionally excluded.
-
-## Files
-
-- [.dockerignore](.dockerignore.md)
-- [.env](.env.md)
-- [.env.example](.env.example.md)
-- [.gitignore](.gitignore.md)
-- [AGENT.md](AGENT.md.md)
-- [Dockerfile](Dockerfile.md)
-- [LICENSE](LICENSE.md)
-- [OPENENV.md](OPENENV.md.md)
-- [README.md](README.md.md)
-- [**init**.py](__init__.py.md)
-- [connectors/**init**.py](connectors/__init__.py.md)
-- [connectors/stripe_sandbox.py](connectors/stripe_sandbox.py.md)
-- [core/**init**.py](core/__init__.py.md)
-- [core/client.py](core/client.py.md)
-- [core/episode_store.py](core/episode_store.py.md)
-- [core/models.py](core/models.py.md)
-- [data/MoMTSim_20240722202413_1000_dataset.csv](data/MoMTSim_20240722202413_1000_dataset.csv.md)
-- [data/credit_card_fraud_transactions.csv](data/credit_card_fraud_transactions.csv.md)
-- [data/iso20022-card-chargeback-casr-003.csv](data/iso20022-card-chargeback-casr-003.csv.md)
-- [data/paysim.csv](data/paysim.csv.md)
-- [data/synthetic_mobile_money_transaction_dataset.csv](data/synthetic_mobile_money_transaction_dataset.csv.md)
-- [docs/RESULTS.md](docs/RESULTS.md.md)
-- [docs/RUBRIC_AUDITOR_PRD.md](docs/RUBRIC_AUDITOR_PRD.md.md)
-- [episode_logs/episodes.jsonl](episode_logs/episodes.jsonl.md)
-- [evaluation/**init**.py](evaluation/__init__.py.md)
-- [evaluation/agent_brutal_audit.py](evaluation/agent_brutal_audit.py.md)
-- [evaluation/grading.py](evaluation/grading.py.md)
-- [evaluation/rubrics.py](evaluation/rubrics.py.md)
-- [inference.py](inference.py.md)
-- [openenv.yaml](openenv.yaml.md)
-- [openenv_chargeback_ops.egg-info/PKG-INFO](openenv_chargeback_ops.egg-info/PKG-INFO.md)
-- [openenv_chargeback_ops.egg-info/SOURCES.txt](openenv_chargeback_ops.egg-info/SOURCES.txt.md)
-- [openenv_chargeback_ops.egg-info/dependency_links.txt](openenv_chargeback_ops.egg-info/dependency_links.txt.md)
-- [openenv_chargeback_ops.egg-info/entry_points.txt](openenv_chargeback_ops.egg-info/entry_points.txt.md)
-- [openenv_chargeback_ops.egg-info/requires.txt](openenv_chargeback_ops.egg-info/requires.txt.md)
-- [openenv_chargeback_ops.egg-info/top_level.txt](openenv_chargeback_ops.egg-info/top_level.txt.md)
-- [pyproject.toml](pyproject.toml.md)
-- [runners/**init**.py](runners/__init__.py.md)
-- [runners/baseline_runner.py](runners/baseline_runner.py.md)
-- [runners/inference.py](runners/inference.py.md)
-- [scenarios/**init**.py](scenarios/__init__.py.md)
-- [scenarios/case_generator.py](scenarios/case_generator.py.md)
-- [scenarios/iso_adapter.py](scenarios/iso_adapter.py.md)
-- [scenarios/simulation.py](scenarios/simulation.py.md)
-- [server/**init**.py](server/__init__.py.md)
-- [server/app.py](server/app.py.md)
-- [server/chargeback_ops_environment.py](server/chargeback_ops_environment.py.md)
-- [server/demo_ui.py](server/demo_ui.py.md)
-- [tests/conftest.py](tests/conftest.py.md)
-- [tests/test_agent_audit.py](tests/test_agent_audit.py.md)
-- [tests/test_api.py](tests/test_api.py.md)
-- [tests/test_env.py](tests/test_env.py.md)
-- [tests/test_grader.py](tests/test_grader.py.md)
-- [tests/test_requirements.py](tests/test_requirements.py.md)
-- [uv.lock](uv.lock.md)

docs/explanation/LICENSE.md

@@ -1,22 +0,0 @@
-# LICENSE
-
-## What this file does
-MIT license terms for reuse and distribution of the project.
-
-## Runtime role
-- legal metadata
-
-## Key contents
-- File size: 1070 bytes
-- Approximate line count: 22
-
-## Connections to other files
-### Depends on / references
-- No direct project-file dependency was detected.
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/PKG-INFO
-- server/__init__.py
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/OPENENV.md.md

@@ -1,30 +0,0 @@
-# OPENENV.md
-
-## What this file does
-Background documentation describing the OpenEnv framework and how this project fits operational benchmarking goals.
-
-## Runtime role
-- root documentation
-
-## Key contents
-- File size: 4527 bytes
-- Approximate line count: 51
-- Major headings (6 sampled):
-  - # OpenEnv Overview
-  - ## The Problem OpenEnv Solves
-  - ## How It Works
-  - ## What Makes a Good OpenEnv Environment
-  - ## How OpenEnv Helps ChargebackOps
-  - ## The Hackathon
-
-## Connections to other files
-### Depends on / references
-- README.md
-- openenv.yaml
-- server/app.py
-
-### Used by / referenced from
-- README.md
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/README.md.md

@@ -1,54 +0,0 @@
-# README.md
-
-## What this file does
-Project overview and quick-start guide with architecture, API, benchmark results, and execution instructions.
-
-## Runtime role
-- root documentation
-
-## Key contents
-- File size: 8212 bytes
-- Approximate line count: 192
-- Major headings (12 sampled):
-  - # ChargebackOps
-  - ## Architecture
-  - ## Grading
-  - ## Benchmark Results
-  - ## Action Space (9 typed actions)
-  - ## Task Sources
-  - ## Quick Start
-  - # case_rubric: CaseRubric
-  - # case_rubric.aggregator: WeightedSum
-  - # case_rubric.aggregator.rubric_0: StrategyCorrectnessRubric
-  - # ... (all 7 dimensions)
-  - # Docker
-
-## Connections to other files
-### Depends on / references
-- .env
-- .env.example
-- AGENT.md
-- Dockerfile
-- OPENENV.md
-- docs/RESULTS.md
-- evaluation/rubrics.py
-- inference.py
-- openenv.yaml
-- pyproject.toml
-- runners/baseline_runner.py
-- runners/inference.py
-- scenarios/simulation.py
-- server/app.py
-
-### Used by / referenced from
-- .env.example
-- AGENT.md
-- OPENENV.md
-- docs/RESULTS.md
-- docs/RUBRIC_AUDITOR_PRD.md
-- openenv_chargeback_ops.egg-info/PKG-INFO
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- pyproject.toml
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/__init__.py.md

@@ -1,25 +0,0 @@
-# __init__.py
-
-## What this file does
-Root package export surface that re-exports the typed environment client and core domain models used by outside consumers.
-
-## Runtime role
-- package entrypoint/helper
-
-## Key contents
-- File size: 398 bytes
-- Approximate line count: 20
-- Module docstring: ChargebackOps OpenEnv package.
-
-## Connections to other files
-### Depends on / references
-- core/client.py
-- core/models.py
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- openenv_chargeback_ops.egg-info/top_level.txt
-- pyproject.toml
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/connectors/__init__.py.md

@@ -1,21 +0,0 @@
-# connectors/__init__.py
-
-## What this file does
-Package initializer for external data connectors.
-
-## Runtime role
-- integration connector module
-
-## Key contents
-- File size: 0 bytes
-- Approximate line count: 1
-
-## Connections to other files
-### Depends on / references
-- No direct project-file dependency was detected.
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/connectors/stripe_sandbox.py.md

@@ -1,38 +0,0 @@
-# connectors/stripe_sandbox.py
-
-## What this file does
-Stripe sandbox adapter that maps dispute-like records into the project internal scenario format.
-
-## Runtime role
-- integration connector module
-
-## Key contents
-- File size: 17332 bytes
-- Approximate line count: 530
-- Module docstring: Stripe sandbox connector for ChargebackOps.
-
-Maps Stripe test-mode dispute objects into ``InternalCase`` / ``TaskScenario``
-so real Stripe dispute flows can be processed through the environment.
-
-Usage::
-
-    export STRIPE_API_KEY=sk_test_...
-    from connectors.stripe_sandbox import fetch_disputes, build_stripe_task
-
-    disputes = fetch_disputes(limit=10)
-    task = build_stripe_task(disputes, difficulty="medium")
-- Top-level functions (7): _ev, _infer_strategy, _build_evidence, dispute_to_case, build_stripe_task, fetch_disputes, _synthetic_test_disputes
-
-## Connections to other files
-### Depends on / references
-- .env
-- scenarios/simulation.py
-
-### Used by / referenced from
-- AGENT.md
-- openenv_chargeback_ops.egg-info/PKG-INFO
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- scenarios/simulation.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/core/__init__.py.md

@@ -1,23 +0,0 @@
-# core/__init__.py
-
-## What this file does
-Core package initializer.
-
-## Runtime role
-- core library module
-
-## Key contents
-- File size: 63 bytes
-- Approximate line count: 2
-- Module docstring: Core data models, client, and storage for ChargebackOps.
-
-## Connections to other files
-### Depends on / references
-- No direct project-file dependency was detected.
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- openenv_chargeback_ops.egg-info/top_level.txt
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/core/client.py.md

@@ -1,26 +0,0 @@
-# core/client.py
-
-## What this file does
-Typed WebSocket/Env client wrapper that converts generic OpenEnv responses into project-specific models.
-
-## Runtime role
-- core library module
-
-## Key contents
-- File size: 2819 bytes
-- Approximate line count: 92
-- Module docstring: WebSocket client for ChargebackOps.
-- Top-level classes (1): ChargebackOpsEnv
-- Top-level functions (4): _parse_evidence, _parse_policy, _parse_visible_case, _parse_grader
-
-## Connections to other files
-### Depends on / references
-- core/models.py
-
-### Used by / referenced from
-- AGENT.md
-- __init__.py
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/core/episode_store.py.md

@@ -1,27 +0,0 @@
-# core/episode_store.py
-
-## What this file does
-Persistent report store for completed episodes with in-memory index and JSONL append logging.
-
-## Runtime role
-- core library module
-
-## Key contents
-- File size: 1684 bytes
-- Approximate line count: 62
-- Module docstring: Thread-safe storage for completed episode grading reports with file persistence.
-- Top-level functions (4): _persist, record_report, get_report, list_reports
-
-## Connections to other files
-### Depends on / references
-- core/models.py
-
-### Used by / referenced from
-- AGENT.md
-- episode_logs/episodes.jsonl
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- server/app.py
-- server/chargeback_ops_environment.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/core/models.py.md

@@ -1,36 +0,0 @@
-# core/models.py
-
-## What this file does
-Canonical Pydantic schemas for actions, observations, environment state, grader output, and baseline result payloads.
-
-## Runtime role
-- core library module
-
-## Key contents
-- File size: 6296 bytes
-- Approximate line count: 244
-- Module docstring: Typed models for the ChargebackOps OpenEnv environment.
-- Top-level classes (15): CaseQueueItem, EvidenceCard, PolicyView, VisibleCase, TaskSummary, ActionTraceItem, CaseResolutionState, CaseScoreBreakdown, GraderReport, BaselineTaskResult, BaselineRunResult, TasksResponse, ChargebackOpsAction, ChargebackOpsObservation, ChargebackOpsState
-
-## Connections to other files
-### Depends on / references
-- .env
-
-### Used by / referenced from
-- AGENT.md
-- __init__.py
-- core/client.py
-- core/episode_store.py
-- evaluation/agent_brutal_audit.py
-- evaluation/grading.py
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- runners/baseline_runner.py
-- runners/inference.py
-- server/app.py
-- server/chargeback_ops_environment.py
-- tests/test_api.py
-- tests/test_env.py
-- tests/test_requirements.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/data/MoMTSim_20240722202413_1000_dataset.csv.md

@@ -1,22 +0,0 @@
-# data/MoMTSim_20240722202413_1000_dataset.csv
-
-## What this file does
-Synthetic transaction simulation dataset used during offline auditing and experimentation.
-
-## Runtime role
-- dataset asset
-
-## Key contents
-- File size: 366397921 bytes
-- Row count (including header): 4225959
-- Columns (10 sampled): step, transactionType, amount, initiator, oldBalInitiator, newBalInitiator, recipient, oldBalRecipient, newBalRecipient, isFraud
-
-## Connections to other files
-### Depends on / references
-- evaluation/agent_brutal_audit.py
-
-### Used by / referenced from
-- No reverse project-file dependency was detected.
-
-## Integration notes
-- This dataset supports scenario generation and/or offline audit scripts; schema changes can affect adapters and audit tooling.

docs/explanation/data/credit_card_fraud_transactions.csv.md

@@ -1,22 +0,0 @@
-# data/credit_card_fraud_transactions.csv
-
-## What this file does
-Auxiliary transaction dataset used for audit/profiling experiments.
-
-## Runtime role
-- dataset asset
-
-## Key contents
-- File size: 270314728 bytes
-- Row count (including header): 1048576
-- Columns (23 sampled): , trans_date_trans_time, cc_num, merchant, category, amt, first, last, gender, street, city, state, zip, lat, long, city_pop, job, dob, trans_num, unix_time, merch_lat, merch_long, is_fraud
-
-## Connections to other files
-### Depends on / references
-- evaluation/agent_brutal_audit.py
-
-### Used by / referenced from
-- No reverse project-file dependency was detected.
-
-## Integration notes
-- This dataset supports scenario generation and/or offline audit scripts; schema changes can affect adapters and audit tooling.

docs/explanation/data/iso20022-card-chargeback-casr-003.csv.md

@@ -1,24 +0,0 @@
-# data/iso20022-card-chargeback-casr-003.csv
-
-## What this file does
-Realistic chargeback sample data used by ISO adapter flows to build benchmark cases.
-
-## Runtime role
-- dataset asset
-
-## Key contents
-- File size: 90967 bytes
-- Row count (including header): 301
-- Columns (20 sampled): chargeback_id, original_transaction_id, card_number_masked, cardholder_name, merchant_name, merchant_id, transaction_amount, transaction_currency, transaction_date, chargeback_date, chargeback_reason_code, chargeback_reason_description, investigation_status, investigator_id, representment_deadline, representment_submitted, representment_date, final_decision, final_decision_date, notes
-
-## Connections to other files
-### Depends on / references
-- scenarios/iso_adapter.py
-- scenarios/simulation.py
-
-### Used by / referenced from
-- .gitignore
-- scenarios/iso_adapter.py
-
-## Integration notes
-- This dataset supports scenario generation and/or offline audit scripts; schema changes can affect adapters and audit tooling.

docs/explanation/data/paysim.csv.md

@@ -1,22 +0,0 @@
-# data/paysim.csv
-
-## What this file does
-Synthetic payment simulation dataset used for baseline stress testing and diagnostics.
-
-## Runtime role
-- dataset asset
-
-## Key contents
-- File size: 493534783 bytes
-- Row count (including header): 6362621
-- Columns (11 sampled): step, type, amount, nameOrig, oldbalanceOrg, newbalanceOrig, nameDest, oldbalanceDest, newbalanceDest, isFraud, isFlaggedFraud
-
-## Connections to other files
-### Depends on / references
-- evaluation/agent_brutal_audit.py
-
-### Used by / referenced from
-- No reverse project-file dependency was detected.
-
-## Integration notes
-- This dataset supports scenario generation and/or offline audit scripts; schema changes can affect adapters and audit tooling.

docs/explanation/data/synthetic_mobile_money_transaction_dataset.csv.md

@@ -1,22 +0,0 @@
-# data/synthetic_mobile_money_transaction_dataset.csv
-
-## What this file does
-Additional synthetic mobile-money dataset used by audit scripts for broader behavior checks.
-
-## Runtime role
-- dataset asset
-
-## Key contents
-- File size: 156564413 bytes
-- Row count (including header): 1720182
-- Columns (10 sampled): step, transactionType, amount, initiator, oldBalInitiator, newBalInitiator, recipient, oldBalRecipient, newBalRecipient, isFraud
-
-## Connections to other files
-### Depends on / references
-- evaluation/agent_brutal_audit.py
-
-### Used by / referenced from
-- No reverse project-file dependency was detected.
-
-## Integration notes
-- This dataset supports scenario generation and/or offline audit scripts; schema changes can affect adapters and audit tooling.

docs/explanation/docs/RESULTS.md.md

@@ -1,38 +0,0 @@
-# docs/RESULTS.md
-
-## What this file does
-Evaluation report documenting baseline score outcomes, comparisons, and observed difficulty trends.
-
-## Runtime role
-- project documentation
-
-## Key contents
-- File size: 6437 bytes
-- Approximate line count: 118
-- Major headings (11 sampled):
-  - # ChargebackOps — Baseline Results
-  - ## TL;DR
-  - ## Score Curve by Difficulty
-  - ## Full Per-Task Table
-  - ## Rubric Breakdown (single-case sanity check)
-  - ## Reproducing These Numbers
-  - # Activate the project's venv
-  - # 1. Run the heuristic + bad-policy comparison (no network)
-  - # 2. Run the baseline with a real LLM (requires OPENROUTER_API_KEY in .env)
-  - ## Hardware / Environment
-  - ## What This Table Does Not Show
-
-## Connections to other files
-### Depends on / references
-- .env
-- README.md
-- evaluation/grading.py
-- evaluation/rubrics.py
-- runners/baseline_runner.py
-- runners/inference.py
-
-### Used by / referenced from
-- README.md
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/docs/RUBRIC_AUDITOR_PRD.md.md

@@ -1,37 +0,0 @@
-# docs/RUBRIC_AUDITOR_PRD.md
-
-## What this file does
-Product requirements draft for a rubric auditor/explainability layer around grading outputs.
-
-## Runtime role
-- project documentation
-
-## Key contents
-- File size: 37236 bytes
-- Approximate line count: 378
-- Major headings (12 sampled):
-  - # RubricAuditor — PRD & Architecture (v0)
-  - ## 0. Gap Verification (done before writing this doc)
-  - ### 0.1 "OpenEnv uses the OpenAI Gym API" — partially true, misleading
-  - ### 0.2 "OpenEnv has gaps in RL algorithm coverage" — category error
-  - ### 0.3 Prior-art scan — is RubricAuditor already built?
-  - ## 1. Executive Summary
-  - ## 2. Problem Statement
-  - ## 3. Target Users & Use Cases
-  - ## 4. Scope
-  - ### 4.1 In scope (v0)
-  - ### 4.2 Out of scope (v0)
-  - ## 5. System Architecture
-
-## Connections to other files
-### Depends on / references
-- README.md
-- evaluation/grading.py
-- evaluation/rubrics.py
-- server/chargeback_ops_environment.py
-
-### Used by / referenced from
-- No reverse project-file dependency was detected.
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/evaluation/__init__.py.md

@@ -1,23 +0,0 @@
-# evaluation/__init__.py
-
-## What this file does
-Evaluation package export surface for grading functions and rubric classes.
-
-## Runtime role
-- grading/evaluation module
-
-## Key contents
-- File size: 434 bytes
-- Approximate line count: 20
-- Module docstring: Grading and audit modules for ChargebackOps.
-
-## Connections to other files
-### Depends on / references
-- evaluation/grading.py
-- evaluation/rubrics.py
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/evaluation/agent_brutal_audit.py.md

@@ -1,44 +0,0 @@
-# evaluation/agent_brutal_audit.py
-
-## What this file does
-Offline stress-test harness used to benchmark baseline and intentionally bad policies across datasets.
-
-## Runtime role
-- grading/evaluation module
-
-## Key contents
-- File size: 13230 bytes
-- Approximate line count: 399
-- Module docstring: Brutal local audit for ChargebackOps agent quality.
-
-This script is intentionally harsher than the standard unit tests:
-
-- profiles any datasets placed under ``data/``
-- derives deterministic seeds from dataset rows
-- runs the heuristic agent across generated easy/medium/hard tasks
-- compares it against a deliberately weak control policy
-- reports score gaps, failure counts, and difficulty behavior
-
-It does not require external APIs and is safe to run offline.
-- Top-level functions (14): _stable_seed, _detect_amount_column, _detect_fraud_column, _quantile, _map_iso_reason, profile_dataset, derive_dataset_seeds, _bad_policy_action, run_episode, aggregate_results, evaluate_generated_suite, evaluate_fixed_tasks, build_report, main
-
-## Connections to other files
-### Depends on / references
-- core/models.py
-- evaluation/grading.py
-- runners/baseline_runner.py
-- scenarios/simulation.py
-- server/chargeback_ops_environment.py
-
-### Used by / referenced from
-- AGENT.md
-- data/MoMTSim_20240722202413_1000_dataset.csv
-- data/credit_card_fraud_transactions.csv
-- data/paysim.csv
-- data/synthetic_mobile_money_transaction_dataset.csv
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- server/demo_ui.py
-- tests/test_agent_audit.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/evaluation/grading.py.md

@@ -1,39 +0,0 @@
-# evaluation/grading.py
-
-## What this file does
-High-level grading adapters that construct context objects and return typed score breakdown reports.
-
-## Runtime role
-- grading/evaluation module
-
-## Key contents
-- File size: 3987 bytes
-- Approximate line count: 121
-- Module docstring: Deterministic grading adapters that delegate to OpenEnv Rubric subclasses.
-
-The real scoring lives in :mod:`evaluation.rubrics`. This module keeps the
-legacy call sites (``score_case`` / ``grade_episode`` / ``grade_representment_note``)
-stable so the environment, tests, and audit tooling do not need to change.
-- Top-level functions (3): _build_case_notes, score_case, grade_episode
-
-## Connections to other files
-### Depends on / references
-- core/models.py
-- evaluation/rubrics.py
-- scenarios/simulation.py
-
-### Used by / referenced from
-- AGENT.md
-- docs/RESULTS.md
-- docs/RUBRIC_AUDITOR_PRD.md
-- evaluation/__init__.py
-- evaluation/agent_brutal_audit.py
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- runners/baseline_runner.py
-- runners/inference.py
-- server/chargeback_ops_environment.py
-- tests/test_grader.py
-- tests/test_requirements.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/evaluation/rubrics.py.md

@@ -1,43 +0,0 @@
-# evaluation/rubrics.py
-
-## What this file does
-Compositional rubric tree defining per-dimension and weighted scoring logic for representment episodes.
-
-## Runtime role
-- grading/evaluation module
-
-## Key contents
-- File size: 13781 bytes
-- Approximate line count: 403
-- Module docstring: OpenEnv Rubric subclasses that power ChargebackOps grading.
-
-Every scoring dimension is a standalone :class:`openenv.core.rubrics.Rubric`
-so the whole grader can be introspected via ``named_rubrics``, captured via
-``state_dict``, and swapped piecewise (e.g. replace :class:`NoteQualityRubric`
-with an ``LLMJudge``). The per-case composite uses :class:`WeightedSum` with
-weights that must sum to 1.0.
-
-The rubrics take their inputs via a :class:`GradingContext` dataclass passed
-as the ``action`` argument of :meth:`Rubric.forward`. The ``observation``
-argument is ignored — ChargebackOps grading operates over deterministic
-episode progress, not on the last observation payload. This keeps the rubrics
-pure and unit-testable without an environment instance.
-- Top-level classes (11): GradingContext, EpisodeGradingContext, StrategyCorrectnessRubric, EvidenceQualityRubric, PacketValidityRubric, DeadlineComplianceRubric, EfficiencyRubric, OutcomeQualityRubric, NoteQualityRubric, CaseRubric, ChargebackOpsEpisodeRubric
-- Top-level functions (4): _ratio, _final_resolution, _contest_is_valid, grade_representment_note
-
-## Connections to other files
-### Depends on / references
-- scenarios/simulation.py
-
-### Used by / referenced from
-- AGENT.md
-- README.md
-- docs/RESULTS.md
-- docs/RUBRIC_AUDITOR_PRD.md
-- evaluation/__init__.py
-- evaluation/grading.py
-- server/chargeback_ops_environment.py
-- tests/test_grader.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/inference.py.md

@@ -1,30 +0,0 @@
-# inference.py
-
-## What this file does
-Root compatibility wrapper that forwards challenge inference execution to runners/inference.py.
-
-## Runtime role
-- package entrypoint/helper
-
-## Key contents
-- File size: 284 bytes
-- Approximate line count: 11
-- Module docstring: Challenge-compatible inference entry point (root re-export).
-
-The submission contract requires inference.py at the repository root.
-All logic lives in runners/inference.py.
-
-## Connections to other files
-### Depends on / references
-- runners/inference.py
-
-### Used by / referenced from
-- AGENT.md
-- README.md
-- openenv_chargeback_ops.egg-info/PKG-INFO
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- pyproject.toml
-- tests/test_requirements.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/openenv.yaml.md

@@ -1,27 +0,0 @@
-# openenv.yaml
-
-## What this file does
-OpenEnv deployment specification describing runtime type, app entry path, and exposed service port.
-
-## Runtime role
-- build/runtime configuration
-
-## Key contents
-- File size: 177 bytes
-- Approximate line count: 8
-- Top-level YAML keys: app, description, name, port, runtime, spec_version, type
-
-## Connections to other files
-### Depends on / references
-- Dockerfile
-- pyproject.toml
-- server/app.py
-
-### Used by / referenced from
-- Dockerfile
-- OPENENV.md
-- README.md
-- openenv_chargeback_ops.egg-info/PKG-INFO
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/pyproject.toml.md

@@ -1,36 +0,0 @@
-# pyproject.toml
-
-## What this file does
-Python packaging and dependency manifest defining project metadata, install requirements, and CLI entry points.
-
-## Runtime role
-- build/runtime configuration
-
-## Key contents
-- File size: 1384 bytes
-- Approximate line count: 56
-- Top-level TOML keys: build-system, project, tool
-
-## Connections to other files
-### Depends on / references
-- README.md
-- __init__.py
-- inference.py
-- openenv_chargeback_ops.egg-info/PKG-INFO
-- runners/baseline_runner.py
-- runners/inference.py
-- server/app.py
-
-### Used by / referenced from
-- Dockerfile
-- README.md
-- openenv.yaml
-- openenv_chargeback_ops.egg-info/PKG-INFO
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- openenv_chargeback_ops.egg-info/dependency_links.txt
-- openenv_chargeback_ops.egg-info/entry_points.txt
-- openenv_chargeback_ops.egg-info/requires.txt
-- uv.lock
-
-## Integration notes
-- Keep this file synchronized with the connected files so deployment, packaging, and documentation stay accurate.

docs/explanation/runners/__init__.py.md

@@ -1,22 +0,0 @@
-# runners/__init__.py
-
-## What this file does
-Runners package initializer.
-
-## Runtime role
-- runner module
-
-## Key contents
-- File size: 56 bytes
-- Approximate line count: 2
-- Module docstring: Baseline and inference runners for ChargebackOps.
-
-## Connections to other files
-### Depends on / references
-- No direct project-file dependency was detected.
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/runners/baseline_runner.py.md

@@ -1,39 +0,0 @@
-# runners/baseline_runner.py
-
-## What this file does
-Reference policy runner combining deterministic heuristics with optional LLM tie-breaking.
-
-## Runtime role
-- baseline agent policy module
-
-## Key contents
-- File size: 56104 bytes
-- Approximate line count: 1477
-- Module docstring: Baseline runner for ChargebackOps.
-- Top-level classes (3): CandidateChoice, CandidateAction, ProviderConfig
-- Top-level functions (25): _provider_timeout_seconds, _provider_retry_attempts, _provider_retry_backoff_seconds, _strict_llm_mode, _should_retry_provider_error, _chat_completion_with_retry, _best_open_case, _build_representment_note, _visible_case_deadline, _is_harmful_evidence, _rank_attachable, _batch_attachable_ids, candidate_actions, _heuristic_pick, _obvious_next_action, _safe_json_loads, _compact_queue_item, _compact_visible_case, _provider_payload, _resolve_provider, _openai_compatible_client, _provider_pick, _provider_pick_with_fallback, run_baseline, main
-
-## Connections to other files
-### Depends on / references
-- core/models.py
-- evaluation/grading.py
-- scenarios/simulation.py
-- server/chargeback_ops_environment.py
-
-### Used by / referenced from
-- .env
-- .env.example
-- AGENT.md
-- README.md
-- docs/RESULTS.md
-- evaluation/agent_brutal_audit.py
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- openenv_chargeback_ops.egg-info/entry_points.txt
-- pyproject.toml
-- runners/inference.py
-- server/app.py
-- server/demo_ui.py
-- tests/test_requirements.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/runners/inference.py.md

@@ -1,37 +0,0 @@
-# runners/inference.py
-
-## What this file does
-Challenge-style inference entrypoint that executes baseline policy runs and prints result payloads.
-
-## Runtime role
-- inference entrypoint
-
-## Key contents
-- File size: 11135 bytes
-- Approximate line count: 315
-- Module docstring: Challenge-compatible inference entry point for ChargebackOps.
-- Top-level functions (8): _inference_timeout_seconds, _provider_label, _default_headers, _build_client, _build_fallback_client, _pick_with_openai_client, run_inference, main
-
-## Connections to other files
-### Depends on / references
-- core/models.py
-- evaluation/grading.py
-- runners/baseline_runner.py
-- scenarios/simulation.py
-- server/chargeback_ops_environment.py
-
-### Used by / referenced from
-- .env
-- .env.example
-- AGENT.md
-- README.md
-- docs/RESULTS.md
-- inference.py
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- pyproject.toml
-- server/app.py
-- tests/test_api.py
-- tests/test_requirements.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/scenarios/__init__.py.md

@@ -1,22 +0,0 @@
-# scenarios/__init__.py
-
-## What this file does
-Scenarios package initializer.
-
-## Runtime role
-- task/scenario module
-
-## Key contents
-- File size: 75 bytes
-- Approximate line count: 2
-- Module docstring: Task scenarios, case generation, and ISO adapters for ChargebackOps.
-
-## Connections to other files
-### Depends on / references
-- No direct project-file dependency was detected.
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/scenarios/case_generator.py.md

@@ -1,32 +0,0 @@
-# scenarios/case_generator.py
-
-## What this file does
-Synthetic case/task generator that produces deterministic tasks from seeds and difficulty levels.
-
-## Runtime role
-- task/scenario module
-
-## Key contents
-- File size: 45229 bytes
-- Approximate line count: 1278
-- Module docstring: Parametric case generator for ChargebackOps.
-
-Generates reproducible chargeback cases from reason-code templates using a
-seeded RNG.  Every seed produces the same cases, so benchmarks are replayable
-while the scenario space is effectively infinite.
-- Top-level classes (2): _EvidenceBlueprint, _CaseTemplate
-- Top-level functions (9): _assign_network, _amount, _customer_id, _order_id, _pick_summary, _generate_evidence, generate_case, generate_task, generate_task_suite
-
-## Connections to other files
-### Depends on / references
-- scenarios/simulation.py
-
-### Used by / referenced from
-- AGENT.md
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- scenarios/simulation.py
-- server/app.py
-- tests/test_env.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/scenarios/iso_adapter.py.md

@@ -1,31 +0,0 @@
-# scenarios/iso_adapter.py
-
-## What this file does
-Adapter that converts ISO 20022 dispute CSV records into internal TaskScenario objects.
-
-## Runtime role
-- task/scenario module
-
-## Key contents
-- File size: 18026 bytes
-- Approximate line count: 516
-- Module docstring: Adapter that converts real ISO 20022 chargeback CSV rows into environment cases.
-
-Reads ``data/iso20022-card-chargeback-casr-003.csv`` and produces
-``InternalCase`` / ``TaskScenario`` objects so real dispute data flows
-through the benchmark.
-- Top-level functions (8): _ev, _infer_strategy, _build_evidence, _concedable_guidance, row_to_case, load_iso_rows, build_iso_task, generate_iso_suite
-
-## Connections to other files
-### Depends on / references
-- data/iso20022-card-chargeback-casr-003.csv
-- scenarios/simulation.py
-
-### Used by / referenced from
-- AGENT.md
-- data/iso20022-card-chargeback-casr-003.csv
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- scenarios/simulation.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/scenarios/simulation.py.md

@@ -1,42 +0,0 @@
-# scenarios/simulation.py
-
-## What this file does
-Primary scenario domain model and task catalog including fixed benchmark tasks and task lookup functions.
-
-## Runtime role
-- task/scenario module
-
-## Key contents
-- File size: 29654 bytes
-- Approximate line count: 747
-- Module docstring: Internal task definitions and runtime types for ChargebackOps.
-- Top-level classes (5): InternalEvidence, InternalCase, TaskScenario, CaseProgress, ActionRecord
-- Top-level functions (4): _ev, get_task, list_tasks, list_iso_tasks
-
-## Connections to other files
-### Depends on / references
-- connectors/stripe_sandbox.py
-- scenarios/case_generator.py
-- scenarios/iso_adapter.py
-
-### Used by / referenced from
-- AGENT.md
-- README.md
-- connectors/stripe_sandbox.py
-- data/iso20022-card-chargeback-casr-003.csv
-- evaluation/agent_brutal_audit.py
-- evaluation/grading.py
-- evaluation/rubrics.py
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- runners/baseline_runner.py
-- runners/inference.py
-- scenarios/case_generator.py
-- scenarios/iso_adapter.py
-- server/app.py
-- server/chargeback_ops_environment.py
-- server/demo_ui.py
-- tests/test_grader.py
-- tests/test_requirements.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/server/__init__.py.md

@@ -1,24 +0,0 @@
-# server/__init__.py
-
-## What this file does
-Server package export for environment class.
-
-## Runtime role
-- server library module
-
-## Key contents
-- File size: 367 bytes
-- Approximate line count: 12
-- Module docstring: Chargeback Ops environment server components.
-
-## Connections to other files
-### Depends on / references
-- LICENSE
-- server/chargeback_ops_environment.py
-
-### Used by / referenced from
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- openenv_chargeback_ops.egg-info/top_level.txt
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/server/app.py.md

@@ -1,41 +0,0 @@
-# server/app.py
-
-## What this file does
-FastAPI app assembly module wiring environment routes, utility endpoints, baseline execution, and optional demo UI.
-
-## Runtime role
-- service entrypoint
-
-## Key contents
-- File size: 4912 bytes
-- Approximate line count: 178
-- Module docstring: FastAPI application for ChargebackOps.
-- Top-level functions (7): root, tasks, generate_tasks, grader, baseline, results, main
-
-## Connections to other files
-### Depends on / references
-- .env
-- core/episode_store.py
-- core/models.py
-- runners/baseline_runner.py
-- runners/inference.py
-- scenarios/case_generator.py
-- scenarios/simulation.py
-- server/chargeback_ops_environment.py
-- server/demo_ui.py
-
-### Used by / referenced from
-- AGENT.md
-- Dockerfile
-- OPENENV.md
-- README.md
-- episode_logs/episodes.jsonl
-- openenv.yaml
-- openenv_chargeback_ops.egg-info/PKG-INFO
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- openenv_chargeback_ops.egg-info/entry_points.txt
-- pyproject.toml
-- tests/test_api.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/server/chargeback_ops_environment.py.md

@@ -1,41 +0,0 @@
-# server/chargeback_ops_environment.py
-
-## What this file does
-Main OpenEnv Environment implementation containing reset/step/state logic and action handlers.
-
-## Runtime role
-- environment core engine
-
-## Key contents
-- File size: 30297 bytes
-- Approximate line count: 761
-- Module docstring: Core environment implementation for ChargebackOps.
-- Top-level classes (1): ChargebackOpsEnvironment
-
-## Connections to other files
-### Depends on / references
-- .env
-- core/episode_store.py
-- core/models.py
-- evaluation/grading.py
-- evaluation/rubrics.py
-- scenarios/simulation.py
-
-### Used by / referenced from
-- AGENT.md
-- docs/RUBRIC_AUDITOR_PRD.md
-- episode_logs/episodes.jsonl
-- evaluation/agent_brutal_audit.py
-- openenv_chargeback_ops.egg-info/SOURCES.txt
-- runners/baseline_runner.py
-- runners/inference.py
-- server/__init__.py
-- server/app.py
-- server/demo_ui.py
-- tests/test_api.py
-- tests/test_env.py
-- tests/test_grader.py
-- tests/test_requirements.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/server/demo_ui.py.md

@@ -1,30 +0,0 @@
-# server/demo_ui.py
-
-## What this file does
-Gradio-based interactive UI to inspect tasks, run actions, and visualize score components.
-
-## Runtime role
-- interactive UI module
-
-## Key contents
-- File size: 18267 bytes
-- Approximate line count: 483
-- Module docstring: Gradio demo UI for ChargebackOps.
-- Top-level functions (8): _bar_html, _score_color, _queue_html, _budget_html, _grader_html, _resolve_task_id, run_episode, build_demo
-
-## Connections to other files
-### Depends on / references
-- .env
-- evaluation/agent_brutal_audit.py
-- runners/baseline_runner.py
-- scenarios/simulation.py
-- server/chargeback_ops_environment.py
-
-### Used by / referenced from
-- .env
-- .env.example
-- AGENT.md
-- server/app.py
-
-## Integration notes
-- Update this module together with its direct and reverse dependencies to keep environment behavior and grading contracts consistent.

docs/explanation/tests/conftest.py.md

@@ -1,21 +0,0 @@
-# tests/conftest.py
-
-## What this file does
-Pytest configuration and shared fixtures used by the test suite.
-
-## Runtime role
-- test module
-
-## Key contents
-- File size: 205 bytes
-- Approximate line count: 10
-
-## Connections to other files
-### Depends on / references
-- No direct project-file dependency was detected.
-
-### Used by / referenced from
-- No reverse project-file dependency was detected.
-
-## Integration notes
-- This file validates behavior from the files listed above; it should evolve with API and rubric changes to prevent regressions.