diff --git a/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md b/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md index 8b40e3e3..9fe1cd88 100644 --- a/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md +++ b/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md @@ -558,3 +558,158 @@ Post-launch upgrade policy: monthly review, upgrade in lockstep, regression-test --- **End of RFC.** + +--- + +## Amendment 2026-05-10: TEST-INFRA-001 inserted before F2 + +| Field | Value | +|---|---| +| **Amendment ID** | A-1 | +| **Status** | Approved | +| **Date** | 2026-05-10 | +| **Author** | Architecture (Claude Chat) | +| **Trigger** | Timetable stabilization sprint (PR #18, #19) surfaced three diagnostic incidents that the RFC v1.0 sequencing did not anticipate | +| **Scope of change** | Sequencing addition + F5 scope extension + Risk register + DoD. **No changes to F2–F6 internal architecture, no changes to Aura preset, no changes to `` API, no changes to Tailwind v4, no changes to bundle size targets.** | + +### A.1 Background + +This RFC v1.0 was approved on 2026-05-10. On the same day, the closing PR of the timetable stabilization sprint (`fix/timetable-stabilization`, PR #19) merged to main. That sprint formalized a new project principle in `CLAUDE.md` titled "Diagnostic discipline: audit before assume", anchored to three empirical incidents: + +- **B1** — controller assumed buggy; schema-verify gate against `SCHEMA.md:1285` proved the seeder was wrong, controllers correct +- **B5** — enum-shape assumed drifted; field-by-field response audit proved decimal-as-string was the actual drift +- **UX divergence** — 397 jsdom-tests green, but manual browser test against the prototype revealed substantial divergence (PerformanceBlock missing genre tag, drag broken, resize handles missing, etc.) — tracked as `ART-S4-UX-PARITY` in BACKLOG.md + +The common pattern across all three: **the existing Vitest+jsdom test layer did not detect what the product actually does in a real browser**. Tests asserted against mocks that agreed with schemas; schemas didn't agree with the backend wire format; layouts didn't match the prototype; jsdom couldn't compute layout cascade, sticky positioning, or visual regressions. + +This RFC's F4 sub-packages (a/b/c/d) constitute a structurally larger refactor than the timetable module — every `.vue` page in the SPA changes, 75 distinct Vuetify components are replaced, 38 form-bearing components migrate to ``. The probability that the same pattern of incidents will recur during F4 — without test infrastructure capable of detecting them — is high enough to warrant addressing pre-emptively. + +The RFC v1.0 author did not have access to the timetable-stabilization context (the work was done in a separate Claude Chat that focused exclusively on the migration audit). Hence this amendment, not a v1.1 rewrite. + +### A.2 What changes + +| Aspect | RFC v1.0 | After amendment | +|---|---|---| +| Sequence | F1 → F2 → F3 → F4 → F5 → F6 | F1 → **TEST-INFRA-001** → F2 → F3 → F4 → F5 → F6 | +| F5 scope | axe-core + 22 mount-tests + perf benchmark | All of v1.0 **plus visual regression baselines (intermediate for Artist Management, first-capture for other surfaces)** | +| Risk register | 10 risks (R-1 through R-10) | 10 + **R-11** (visual regression coverage gap) | +| Definition of Done | 15 items | 15 + **5 new items** (DoD-16 through DoD-20) | +| Sprint effort | 10–12 working days | **15–19 working days** (+5–7 for TEST-INFRA-001) | +| Concurrent Artist Management work | Continues on Vuetify until F4b absorbs it | Same — TEST-INFRA-001 does not modify application code, only test infrastructure | + +### A.3 New sprint: TEST-INFRA-001 (5–7 working days) + +This sprint is **prerequisite to F2**. F2 cannot begin until TEST-INFRA-001 closes. Sprint scope at high level — full sprint prompt is authored separately and is the next concrete action after this amendment is committed. + +**Goals:** + +1. **Playwright Component Testing foundation**: install `@playwright/test` + `@playwright/experimental-ct-vue` + axe-core dependencies. Configure component-test runner with Vuetify+Pinia+TanStack+router providers. Demonstrate one working component test that mounts a current Vuetify component (proves the foundation) and one that mounts a prototype HTML region (proves visual baseline pipeline). + +2. **Visual regression infrastructure**: pixel-diff tooling, baseline storage in Git LFS (self-hosted per Bert's preference), prototype-HTML rendering pipeline (the prototype at `./resources/Crewli - Artist Timetable Management/` is React+Babel via unpkg — Playwright renders it once, captures baselines, stores them as authoritative). CI integration with PR-comment diff visibility. + +3. **Real-backend e2e setup**: Playwright e2e configuration that spins up Laravel test-server, authenticates via Sanctum, runs against seeded fixtures. First flow: the 409 conflict contract test from `TEST-CONTRACT-001`. + +4. **Architecture documentation**: `dev-docs/ARCH-TESTING.md` codifying the test pyramid (unit / component / integration / e2e / visual), scope per layer, when something belongs in which layer, conventions for mock-vs-real-backend choices, baseline update workflow. + +5. **No migration of existing Vitest tests**. Existing 402 Vitest+jsdom tests remain unchanged. They will be naturally replaced during F4 component migration (each migrated component gets a fresh Playwright Component Test, the corresponding Vitest+jsdom test is removed at that point). This is a deliberate scope decision — migrating tests now and again during F4 is duplicate work. + +**Baseline scope:** + +Visual regression baselines in this sprint are limited to **Artist Management surfaces** (PerformanceBlock, PerformancePopover, AddPerformanceDialog, Wachtrij, StageRow, plus the timetable canvas at three states: empty / partial / full). Reason: these are the only surfaces with a canonical prototype to baseline against. Other modules (Volunteers, Events, Forms, Platform Admin) get baselines progressively as they're migrated through F4 — and those baselines are taken against the **PrimeVue implementation post-migration**, not against the current Vuetify implementation that we are about to discard. + +**Definition of Done:** + +- All five goals delivered, branch merged to main, `.claude-sync/` re-uploaded +- Existing 402 Vitest+jsdom tests still pass unchanged +- At least one Playwright component test passing in CI (smoke proof) +- At least one visual regression baseline committed (smoke proof) +- One real-backend e2e test passing (TEST-CONTRACT-001 first flow) +- `ARCH-TESTING.md` reviewed and committed + +**BACKLOG consolidation:** + +This sprint consumes and closes three pre-existing BACKLOG entries from the timetable-stabilization PR: + +- `TEST-INFRA-001` — closed by goal 1+2 above +- `TEST-CONTRACT-001` — closed by goal 3 above +- `TEST-VISUAL-001` — closed by goal 2 above (with explicit prototype-HTML baseline source) + +### A.4 Updated sequencing +F1 ─► TEST-INFRA-001 ─► F2 ─► F3 ─► F4a ─► F4b ─► F4c ─► F4d ─► F5 ─► F6 +╰──── 5-7 d ────╯ ╰1d╯ ╰2d╯ ╰1d╯ ╰3d╯ ╰1d╯ ╰1.5d╯ ╰1.5d╯ ╰0.5d╯ +╰── visual & e2e ──╯ +╰── infra only ────╯ +After F6: ART-S4-UX-PARITY (Artist Management UX parity on PrimeVue, with visual regression baselines as objective measure) +After ART-S4-UX-PARITY: Sessie 5 (Engagement Detail), Accreditation Engine, etc. + +Total estimated effort: 15–19 working days for TEST-INFRA-001 + F2–F6. + +### A.5 F5 scope extension + +RFC v1.0 §6, F5 (Tests, accessibility, performance) is extended with one additional output. The handling depends on whether a prototype-baseline exists for the surface being validated: + +**Artist Management surfaces** (PerformanceBlock, PerformancePopover, AddPerformanceDialog, Wachtrij, StageRow, timetable canvas — originally baselined against prototype HTML in TEST-INFRA-001): + +- F5 captures the PrimeVue-implementation baselines as a **separate intermediate baseline set**. These are explicitly NOT expected to match the prototype baselines. +- Reason: UX parity with the prototype is out of scope for F4 (F4b absorbs the Artist Management module "as it stands at F4b start" per RFC §6, which is its current Vuetify implementation including all gaps documented in `ART-S4-UX-PARITY`). PrimeVue migration converts those Vuetify components to PrimeVue equivalents but does not close the UX gaps. +- F5 acceptance for these surfaces requires only that the PrimeVue implementations render **structurally correctly** (no missing components, no broken layouts, no console errors, no a11y blockers) — not pixel-equivalence with the prototype. +- `ART-S4-UX-PARITY` (post-F6 sprint) closes the gap by refactoring the PrimeVue Artist Management surfaces to match the prototype, and at that point updates the intermediate baselines to align with the prototype baselines. + +**Surfaces outside Artist Management** (Volunteers, Events, Forms, Platform Admin, etc. — no prototype baseline exists): + +- F5 captures the **first PrimeVue-implementation baseline** for each surface. This becomes the regression anchor going forward. +- F5 acceptance requires the baseline to be reproducible (re-running the capture produces an identical baseline within configured pixel tolerance). + +The existing F5 outputs (axe-core audit, mount-test verification, perf benchmark) are unchanged. + +### A.6 Risk register addition + +| ID | Risk | Probability | Impact | Mitigation | +|---|---|---|---|---| +| R-11 | F4 component migration introduces visual regressions that jsdom-tests do not detect, mirroring the timetable-stabilization pattern | High (without TEST-INFRA-001) / Low (with) | High | TEST-INFRA-001 sprint inserted before F2 establishes Playwright + visual regression baselines against prototype HTML. F4 sub-packages must show passing baselines before sub-package closure. F5 re-validates all baselines against PrimeVue final state with the dual-tier scope defined in §A.5. | + +### A.7 Definition of Done — additional items + +The sprint-level DoD in RFC v1.0 §10 is extended with: + +16. `dev-docs/ARCH-TESTING.md` exists and is referenced from `CLAUDE.md`. +17. Playwright Component Testing infrastructure is operational; `pnpm test:component` (or equivalent) runs in CI. +18. Visual regression baselines exist for all Artist Management surfaces; `pnpm test:visual` (or equivalent) passes against them. +19. At least one real-backend e2e test (the 409 conflict contract test from TEST-CONTRACT-001) passes against a Laravel test-server in CI. +20. BACKLOG entries `TEST-INFRA-001`, `TEST-CONTRACT-001`, and `TEST-VISUAL-001` are marked closed in `BACKLOG.md`, with references to the sprint commits. + +### A.8 Effort impact + +| Phase | RFC v1.0 estimate | After amendment | +|---|---|---| +| F1 | already complete | already complete | +| **TEST-INFRA-001** | – | **5–7 days** (new) | +| F2 | 1 day | 1 day | +| F3 | 2 days | 2 days | +| F4a | 1 day | 1 day | +| F4b | 3 days | 3 days | +| F4c | 1 day | 1 day | +| F4d | 1.5 days | 1.5 days | +| F5 | 1 day | 1.5 days (visual regression validation extends scope per §A.5) | +| F6 | 0.5 day | 0.5 day | +| **Total** | **10–12 days** | **15–19 days** | + +No launch-pressure exists per current planning (Bert confirmation 2026-05-10: minimum 6 months). The 5–7 day investment is justified against the high probability that R-11 materializes during F4 without it. + +### A.9 What this amendment does NOT change + +To prevent ambiguity in future review: + +- **F2 documentation rewrite scope** is unchanged (`PRIMEVUE_COMPONENTS.md`, CLAUDE.md update, `.cursorrules` update, `VUEXY_COMPONENTS.md` deletion). +- **F3 foundation outputs** are unchanged. Tailwind v4 still installs, `` wrapper still gets built per Appendix A, layout shells still get rewritten, Aura preset still gets configured with Crewli teal. +- **F4 sub-package boundaries and order** are unchanged. F4a (`/portal/*`) → F4b (organizer root + Artist Management) → F4c (`/platform/*`) → F4d (public registration + Form Builder). +- **F6 cleanup deletions** are unchanged. +- **Bundle size targets** in §11 are unchanged. +- **Architectural decisions** AD-1 through AD-12 are unchanged. +- **`` API specification** in Appendix A is unchanged. + +### A.10 Approval & next action + +This amendment is approved on **2026-05-10**. The next concrete action is to commit this amendment to `dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md` on the `audit/primevue-migration` branch, regenerate the sync manifest, upload `.claude-sync/` to Project Knowledge, then issue the **TEST-INFRA-001 sprint prompt** (authored separately). + +After TEST-INFRA-001 closes and merges to main, F2 begins per RFC v1.0 §6.