PLAN — GatewayPrismaQR build (uscha-devloop)¶
Inputs: SPEC.md, CONSTITUTION.md (INV-01..11), ACCEPTANCE.md (AC-01..32, all confirmed), docs/adr/ADR-001..004, HANDOFF.md.
Policy¶
| Item | Value |
|---|---|
| Risk profile | C (greenfield payments core): QA tools code-review → judgment-day → improve, operability gate on (CI test workflow, release workflow, RUNBOOK, seed) |
| Severity gate | BLOCKER / CRITICAL / HIGH block; the rest goes to ISSUES-DEFERRED.md |
| Coverage | ≥ 90 % line (domain), ≥ 80 % rest; PIT ≥ 80 % domain (SPEC §3.2) |
| Max QA iterations | 5 per slice |
| TDD | Strict: a failing test first; test names carry the AC id (ac07_...) |
| Fast path | Not applicable (greenfield, no fast_path config) |
Test database¶
| Environment | Database | How |
|---|---|---|
| Local (no Docker) | SQL Server 2022 at localhost, database GatewayPrismaQR_IT (SCR-001; clean refused unless the name ends in _IT) |
Credentials from GPQR_DB_USER / GPQR_DB_PASSWORD (or config/application-local.yml, gitignored) |
| CI (GitHub Actions, ubuntu) | mcr.microsoft.com/mssql/server:2022 container, database GatewayPrismaQR_IT, random SA password per run |
Same environment variables |
One datasource configuration, no Testcontainers.
Slices (vertical, one branch and one review each)¶
| Slice | Content | Acceptance |
|---|---|---|
| S0 Skeleton | Maven project (Spring Boot 4.1, Java 25), hexagonal packages + ArchUnit, Flyway V1 with the full schema (configuration aggregates, payment, intention, snapshots, reversal with one-active constraint, compensation_task, inbound_notification, wire_log, terminal sequences), two listeners (POS on VPN-side address, Prisma callbacks on separate HTTPS port), JaCoCo + PIT, CI test + release workflows, seed SQL at db/seed/seed-dev.sql, .nvmrc = 24, RUNBOOK update |
AC-28 |
| S1 POS contract | PosRequestNormalizer (POS-native + RouterQR shapes), trxid, estado mapping, payment state machine (pure domain), status endpoint; fixtures from the real POS E2E log |
AC-01, AC-02, AC-05 |
| S2 Prisma adapter + emulator v0 | Create intention, callbacks fail-closed, BINs → complete intention, notification → POS answer, wire log | AC-03, AC-04, AC-06..AC-10, AC-27 |
| S3 Plans | PlanSource A/B, BinMatcher, POS rounding, TNA/CFT, MiPyME, cashback |
AC-11..AC-18 |
| S4 Timeout, compensation, reversals | Leased compensation job, DELETE / forced annulment / forced refund, idempotent trxanulacion, late notifications, supersede, cashier cancel, atomic numbering, node kill |
AC-19..AC-26, AC-31, AC-32 |
| S5 Console + emulator scenarios | React console (CRUD, plan simulator, payment search, dashboard), emulator scenario catalog | AC-29, AC-30 |
Status (2026-10-28)¶
Slices S0 to S5 are integrated. ACCEPTANCE.md has 28 of the 30 applicable criteria closed (32 were confirmed; AC-11 and AC-12 were withdrawn with Mode A). AC-06, AC-09 and AC-27 are no longer open: the integration QA closed them with end-to-end tests on 2026-10-28. AC-14 was closed on 2026-10-29 by measurement on the real POS. Open: AC-15 and AC-16, which wait for the answers of Prisma (docs/PRISMA-PREGUNTAS.md).
Formal verification (2026-10-31): the payment lifecycle is modelled in TLA+ and checked exhaustively with TLC (docs/modelo/). Within its scope the at-most-one-reversal-per-charge rule, deadlock freedom and the INV-02 liveness rule hold; it found D-134 (INV-01, money; corrected in PR #7, run 8 of the model confirms it), D-132 (depends on Prisma question 17g) and D-135 (deferred). D-136 (a query-only sweep of given-up reversals) is deferred. Rerun the model when code behind a modelled action changes.
Migrations¶
V1__baseline.sql stays editable until the first release is deployed anywhere outside development (decided 2026-10-02 by the agent with the human's full-system scope; every edit requires resetting development databases, as RUNBOOK §6 explains). From the first release on, V1 is frozen and changes go to V2+.
Per-slice loop¶
- Writer sub-agent implements the slice test-first, conventional commits per work unit, no attribution lines.
- Fresh-context review → fixes at/above the gate.
log-step,gate-check --from-git,snapshot --phase post,readiness --record.- Converged → next slice. Nothing is pushed without the human's approval.