Workflow

Review the full financial lifecycle: preview -> lock bill -> capture or finalize -> refund -> refund cancel -> reconciliation.
Verify duplicate or replay handling, branch scope, refund lineage, stale write protection, and payment session ordering before patching.
Keep settlement math, capture rules, and refund planning in service code rather than controllers.
If provider or webhook behavior changes, update both runtime tests and contract or operational checks in the same batch.
Add focused regression coverage for race conditions and financial invariants.

Guardrails

Do not bypass bill locks or refund source checks to unblock a path.
Preserve financial auditability and traceability across settlement and refund events.
Treat webhook duplicate delivery and stale ordering as first-class cases, not edge cases.
Keep API contract stable unless docs and contract tests move together.

Read AGENTS.md, .codex/AGENTS.md, and references/paths.md before editing.

Review the full financial lifecycle: preview -> lock bill -> capture or finalize -> refund -> refund cancel -> reconciliation.
Verify duplicate or replay handling, branch scope, refund lineage, stale write protection, and payment session ordering before patching.
Keep settlement math, capture rules, and refund planning in service code rather than controllers.
If provider or webhook behavior changes, update both runtime tests and contract or operational checks in the same batch.
Add focused regression coverage for race conditions and financial invariants.

Do not bypass bill locks or refund source checks to unblock a path.
Preserve financial auditability and traceability across settlement and refund events.
Treat webhook duplicate delivery and stale ordering as first-class cases, not edge cases.
Keep API contract stable unless docs and contract tests move together.