From c7dd3299d77a0ba1078e2192611c95b9404d8181 Mon Sep 17 00:00:00 2001 From: Sisyphus Executor Date: Tue, 3 Mar 2026 14:02:37 +0100 Subject: [PATCH] chore(scaffold): initialize git repo and monorepo with .NET solution --- .editorconfig | 79 + .gitignore | 47 + .sisyphus/boulder.json | 10 + .sisyphus/drafts/club-work-manager.md | 59 + .../notepads/club-work-manager/decisions.md | 5 + .../notepads/club-work-manager/issues.md | 5 + .../notepads/club-work-manager/learnings.md | 5 + .../notepads/club-work-manager/problems.md | 5 + .sisyphus/plans/club-work-manager.md | 2611 +++++++++++++++++ backend/WorkClub.Api/Program.cs | 41 + backend/WorkClub.Api/WorkClub.Api.csproj | 19 + backend/WorkClub.Api/WorkClub.Api.http | 6 + .../WorkClub.Api/appsettings.Development.json | 8 + backend/WorkClub.Api/appsettings.json | 9 + backend/WorkClub.Application/Class1.cs | 6 + .../WorkClub.Application.csproj | 18 + backend/WorkClub.Domain/Class1.cs | 6 + .../WorkClub.Domain/WorkClub.Domain.csproj | 9 + backend/WorkClub.Infrastructure/Class1.cs | 6 + .../WorkClub.Infrastructure.csproj | 17 + .../WorkClub.Tests.Integration/UnitTest1.cs | 10 + .../WorkClub.Tests.Integration.csproj | 30 + backend/WorkClub.Tests.Unit/UnitTest1.cs | 10 + .../WorkClub.Tests.Unit.csproj | 28 + backend/WorkClub.slnx | 8 + backend/global.json | 6 + 26 files changed, 3063 insertions(+) create mode 100644 .editorconfig create mode 100644 .gitignore create mode 100644 .sisyphus/boulder.json create mode 100644 .sisyphus/drafts/club-work-manager.md create mode 100644 .sisyphus/notepads/club-work-manager/decisions.md create mode 100644 .sisyphus/notepads/club-work-manager/issues.md create mode 100644 .sisyphus/notepads/club-work-manager/learnings.md create mode 100644 .sisyphus/notepads/club-work-manager/problems.md create mode 100644 .sisyphus/plans/club-work-manager.md create mode 100644 backend/WorkClub.Api/Program.cs create mode 100644 backend/WorkClub.Api/WorkClub.Api.csproj create mode 100644 backend/WorkClub.Api/WorkClub.Api.http create mode 100644 backend/WorkClub.Api/appsettings.Development.json create mode 100644 backend/WorkClub.Api/appsettings.json create mode 100644 backend/WorkClub.Application/Class1.cs create mode 100644 backend/WorkClub.Application/WorkClub.Application.csproj create mode 100644 backend/WorkClub.Domain/Class1.cs create mode 100644 backend/WorkClub.Domain/WorkClub.Domain.csproj create mode 100644 backend/WorkClub.Infrastructure/Class1.cs create mode 100644 backend/WorkClub.Infrastructure/WorkClub.Infrastructure.csproj create mode 100644 backend/WorkClub.Tests.Integration/UnitTest1.cs create mode 100644 backend/WorkClub.Tests.Integration/WorkClub.Tests.Integration.csproj create mode 100644 backend/WorkClub.Tests.Unit/UnitTest1.cs create mode 100644 backend/WorkClub.Tests.Unit/WorkClub.Tests.Unit.csproj create mode 100644 backend/WorkClub.slnx create mode 100644 backend/global.json diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..8796a81 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,79 @@ +# EditorConfig for C# and Web projects +root = true + +# All files +[*] +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true +insert_final_newline = true +charset = utf-8 + +# C# files +[*.cs] +indent_size = 4 + +# Code style rules +[*.cs] +# Indentation preferences +csharp_indent_case_contents = true +csharp_indent_switch_labels = true +csharp_indent_labels = flush_left + +# New line preferences +csharp_new_line_before_catch = true +csharp_new_line_before_else = true +csharp_new_line_before_finally = true +csharp_new_line_before_members_in_anonymous_types = true +csharp_new_line_before_members_in_object_initializers = true +csharp_new_line_before_open_brace = all +csharp_new_line_between_query_expression_clauses = true + +# Space preferences +csharp_space_after_cast = false +csharp_space_after_keywords_in_control_flow_statements = true +csharp_space_between_method_call_parameter_list_parentheses = false +csharp_space_between_parentheses = false +csharp_space_before_colon_in_inheritance_clause = true +csharp_space_before_comma = false +csharp_space_before_dot = false +csharp_space_before_open_square_brackets = false +csharp_space_before_semicolon_in_for_statement = false +csharp_space_around_binary_operators = before_and_after +csharp_space_around_declaration_statements = false +csharp_space_before_open_brace = true +csharp_space_between_empty_square_brackets = false +csharp_space_between_method_declaration_parameter_list_parentheses = false + +# Wrapping preferences +csharp_preserve_single_line_blocks = true +csharp_preserve_single_line_statements = false + +# Naming conventions +[*.cs] +# Style Definitions +dotnet_naming_style.pascal_case_style.required_prefix = +dotnet_naming_style.pascal_case_style.required_suffix = +dotnet_naming_style.pascal_case_style.word_separator = +dotnet_naming_style.pascal_case_style.capitalization = pascal_case + +dotnet_naming_style.camel_case_style.required_prefix = +dotnet_naming_style.camel_case_style.required_suffix = +dotnet_naming_style.camel_case_style.word_separator = +dotnet_naming_style.camel_case_style.capitalization = camel_case + +# Use PascalCase for public members +dotnet_naming_rule.public_members_pascal_case.symbols = public_symbols +dotnet_naming_rule.public_members_pascal_case.style = pascal_case_style +dotnet_naming_rule.public_members_pascal_case.severity = suggestion + +dotnet_naming_symbols.public_symbols.applicable_kinds = property,method,field,event,delegate +dotnet_naming_symbols.public_symbols.applicable_accessibilities = public + +# Use camelCase for private members +dotnet_naming_rule.private_members_camel_case.symbols = private_symbols +dotnet_naming_rule.private_members_camel_case.style = camel_case_style +dotnet_naming_rule.private_members_camel_case.severity = suggestion + +dotnet_naming_symbols.private_symbols.applicable_kinds = property,method,field,event,delegate +dotnet_naming_symbols.private_symbols.applicable_accessibilities = private,protected diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..03307d5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,47 @@ +# .NET +bin/ +obj/ +*.dll +*.exe +*.pdb +*.user +*.suo +*.sln.docstates +.vs/ +.vscode/ +launchSettings.json + +# Node +node_modules/ +.next/ +.cache/ +dist/ +build/ +coverage/ +.npm +.eslintcache + +# IDE +.idea/ +*.swp +*.swo +*~ +.DS_Store +*.iml +*.sublime-workspace + +# Environment +.env +.env.local +.env.*.local + +# Logs +logs/ +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Testing +.nyc_output/ +.coverage/ diff --git a/.sisyphus/boulder.json b/.sisyphus/boulder.json new file mode 100644 index 0000000..f549515 --- /dev/null +++ b/.sisyphus/boulder.json @@ -0,0 +1,10 @@ +{ + "active_plan": "/Users/mastermito/Dev/opencode/.sisyphus/plans/club-work-manager.md", + "started_at": "2026-03-03T13:00:10.030Z", + "session_ids": [ + "ses_3508d46e8ffeZdkOZ6IqCCwAJg" + ], + "plan_name": "club-work-manager", + "agent": "atlas", + "worktree_path": "/Users/mastermito/Dev/opencode" +} \ No newline at end of file diff --git a/.sisyphus/drafts/club-work-manager.md b/.sisyphus/drafts/club-work-manager.md new file mode 100644 index 0000000..94304ad --- /dev/null +++ b/.sisyphus/drafts/club-work-manager.md @@ -0,0 +1,59 @@ +# Draft: Multi-Tenant Club Work Manager + +## Requirements (confirmed) +- **Multi-tenant**: Multiple clubs (tennis, cycling, etc.) share one application +- **Tenant identification**: Credential-based — user logs in, system resolves which club(s) they belong to. No subdomains or URL paths for tenant routing. +- **Data isolation**: PostgreSQL Row-Level Security (RLS) — shared database, tenant isolation via RLS policies +- **Work items**: Hybrid — both task-based (title, desc, assignee, status) AND schedule/shift-based (time slots, sign-ups, assignments) +- **Authentication**: External provider (Auth0, Clerk, or Keycloak) +- **Target scale**: MVP / Proof of concept (1-5 clubs, <100 users) +- **Backend**: .NET (ASP.NET Core) with PostgreSQL +- **Frontend**: Next.js with Bun +- **Deployment (prod)**: Kubernetes cluster +- **Deployment (local)**: Docker Compose + +## Technical Decisions +- **Multi-tenancy strategy**: RLS + EF Core global query filters (defense-in-depth) +- **Tenant resolution**: NOT subdomain-based. Tenant derived from authenticated user's JWT claims (club membership) +- **Bun runtime**: Research shows Bun has P99 latency issues with Next.js SSR in production (March 2026). Use Bun for local dev / package management, Node.js for production runtime. +- **Infrastructure**: Kustomize (simpler for MVP, no Helm complexity needed yet) + +## Research Findings +- **Finbuckle.MultiTenant**: Industry-standard .NET multi-tenancy library. Supports header strategy — good fit for credential-based tenant resolution. +- **EF Core Global Query Filters**: Auto-filter all queries by tenant_id. Combined with RLS for defense-in-depth. +- **PostgreSQL RLS**: SET app.current_tenant per connection. Must reset when returning connections to pool. +- **Next.js + Bun**: Bun has 340ms P99 latency vs 120ms for Node.js (Platformatic benchmarks Jan 2026). Recommendation: Bun for dev, Node.js for prod Docker image. +- **K8s deployment**: Kustomize with base + overlays (dev/staging/prod). PostgreSQL as StatefulSet for dev, managed DB for prod. +- **Docker Compose**: Hot reload via `dotnet watch` for .NET, standard Next.js dev server. + +## Decisions (Round 2) +- **Auth provider**: Keycloak — self-hosted in K8s cluster, runs alongside the app +- **Multi-club membership**: YES — a user can belong to multiple clubs, needs a club-switcher/selector after login +- **Member roles**: 4-tier — Admin, Manager, Member, Viewer (per club, since user can be Admin in one club and Member in another) +- **Shift model**: Time-slot with sign-up — date, time range, location, description, required headcount. Members sign up or get assigned. +- **Repo structure**: Monorepo — /backend, /frontend, /infra in one repo +- **Notifications**: None for MVP — simplest approach, users check the app + +## Decisions (Round 3) +- **.NET version**: .NET 10 (user explicitly requested) +- **Work item statuses**: 5-state — Open → Assigned → In Progress → Review → Done +- **Project type**: Greenfield — starting from scratch, empty repo +- **UI framework**: Tailwind CSS + shadcn/ui component library + +## Test Strategy Decision +- **Infrastructure exists**: NO (greenfield) +- **Automated tests**: YES (TDD — tests first) +- **Backend framework**: xUnit + Testcontainers (PostgreSQL) for .NET 10 +- **Frontend framework**: bun test / Vitest + React Testing Library for Next.js +- **Agent-Executed QA**: ALWAYS (mandatory — Playwright for UI, curl for API) +- **Test infrastructure setup**: Must be part of Wave 1 scaffolding tasks + +## Decisions (Round 4) +- **Git repository**: Initialize git repo as first step in Task 1 — `git init` + comprehensive `.gitignore` (dotnet + node + IDE) + initial commit + +## Open Questions +- (none remaining — all critical decisions made, ready for plan generation) + +## Scope Boundaries +- INCLUDE: Full backend API, frontend app, Docker Compose, Kubernetes manifests (Kustomize), database schema + EF Core migrations, Keycloak integration, work item CRUD, time-slot shift management with sign-up, club-switcher, role-based access control (4 roles), PostgreSQL RLS +- EXCLUDE: Billing/subscriptions, email/push notifications, mobile app, recurring shift patterns (future), custom roles, reporting/analytics dashboard diff --git a/.sisyphus/notepads/club-work-manager/decisions.md b/.sisyphus/notepads/club-work-manager/decisions.md new file mode 100644 index 0000000..189345a --- /dev/null +++ b/.sisyphus/notepads/club-work-manager/decisions.md @@ -0,0 +1,5 @@ +# Decisions — Club Work Manager + +_Architectural choices and technical decisions made during implementation_ + +--- diff --git a/.sisyphus/notepads/club-work-manager/issues.md b/.sisyphus/notepads/club-work-manager/issues.md new file mode 100644 index 0000000..87561ab --- /dev/null +++ b/.sisyphus/notepads/club-work-manager/issues.md @@ -0,0 +1,5 @@ +# Issues — Club Work Manager + +_Problems, gotchas, and edge cases discovered during implementation_ + +--- diff --git a/.sisyphus/notepads/club-work-manager/learnings.md b/.sisyphus/notepads/club-work-manager/learnings.md new file mode 100644 index 0000000..9462916 --- /dev/null +++ b/.sisyphus/notepads/club-work-manager/learnings.md @@ -0,0 +1,5 @@ +# Learnings — Club Work Manager + +_Conventions, patterns, and accumulated wisdom from task execution_ + +--- diff --git a/.sisyphus/notepads/club-work-manager/problems.md b/.sisyphus/notepads/club-work-manager/problems.md new file mode 100644 index 0000000..0fbc23a --- /dev/null +++ b/.sisyphus/notepads/club-work-manager/problems.md @@ -0,0 +1,5 @@ +# Problems — Club Work Manager + +_Unresolved blockers requiring attention_ + +--- diff --git a/.sisyphus/plans/club-work-manager.md b/.sisyphus/plans/club-work-manager.md new file mode 100644 index 0000000..3d3187a --- /dev/null +++ b/.sisyphus/plans/club-work-manager.md @@ -0,0 +1,2611 @@ +# Multi-Tenant Club Work Manager + +## TL;DR + +> **Quick Summary**: Build a greenfield multi-tenant SaaS application for clubs (tennis, cycling, etc.) to manage work items (tasks + time-slot shifts) across their members. Credential-based multi-tenancy with PostgreSQL RLS, Keycloak auth, .NET 10 backend, Next.js frontend, deployed to Kubernetes. +> +> **Deliverables**: +> - .NET 10 REST API with multi-tenant data isolation (RLS + Finbuckle) +> - Next.js frontend with Tailwind + shadcn/ui, club-switcher, task & shift management +> - Keycloak integration for authentication with multi-club membership +> - PostgreSQL schema with RLS policies and EF Core migrations +> - Docker Compose for local development (hot reload, Keycloak, PostgreSQL) +> - Kubernetes manifests (Kustomize base + dev overlay) +> - Comprehensive TDD test suite (xUnit + Testcontainers, Vitest + RTL, Playwright E2E) +> - Seed data for development (2 clubs, 5 users, sample tasks + shifts) +> +> **Estimated Effort**: Large +> **Parallel Execution**: YES — 7 waves +> **Critical Path**: Monorepo scaffold → Auth pipeline → Multi-tenancy layer → Domain model → API endpoints → Frontend → K8s manifests + +--- + +## Context + +### Original Request +Build a multi-tenant internet application for managing work items over several members of a club (e.g. Tennis club, cycling club). Backend in .NET + PostgreSQL, frontend in Next.js + Bun, deployed to Kubernetes with local Docker Compose for development. + +### Interview Summary +**Key Discussions**: +- **Tenant identification**: Credential-based (not subdomain). User logs in, JWT claims identify club memberships. Active club selected via X-Tenant-Id header. +- **Work items**: Hybrid — task-based (5-state: Open → Assigned → In Progress → Review → Done) AND time-slot shift scheduling with member sign-up. +- **Auth**: Keycloak (self-hosted), single realm, user attributes for club membership, custom protocol mapper for JWT claims. +- **Multi-club**: Users can belong to multiple clubs with different roles (Admin/Manager/Member/Viewer per club). +- **Scale**: MVP — 1-5 clubs, <100 users. +- **Testing**: TDD approach (tests first). +- **Notifications**: None for MVP. + +**Research Findings**: +- **Finbuckle.MultiTenant**: ClaimStrategy + HeaderStrategy fallback is production-proven (fullstackhero/dotnet-starter-kit pattern). +- **Middleware order**: `UseAuthentication()` → `UseMultiTenant()` → `UseAuthorization()` (single Keycloak realm, ClaimStrategy needs claims). +- **RLS safety**: Use `SET LOCAL` (transaction-scoped) not `SET` to prevent stale tenant context in pooled connections. +- **EF Core + RLS**: Do NOT use Finbuckle's `IsMultiTenant()` shadow property — use explicit `TenantId` column + RLS only (avoids double-filtering). +- **Bun**: P99 latency issues with Next.js SSR (340ms vs 120ms Node.js). Use Bun for dev/package management, Node.js for production. +- **.NET 10**: Built-in `AddOpenApi()` (no Swashbuckle). 49% faster than .NET 8. +- **Keycloak**: Use `--import-realm` for dev bootstrapping. User attributes + custom protocol mapper for club claims. +- **Kustomize**: Simpler than Helm for MVP. Base + overlays structure. + +### Metis Review +**Identified Gaps** (all resolved): +- **Club data model**: Club is both tenant container AND domain entity (name, sport type). Provisioned via Keycloak admin + seed script. +- **User-Club DB relationship**: `UserClubMembership` junction table needed for assignment queries. Synced from Keycloak on first login. +- **Task workflow rules**: Admin/Manager assigns. Assignee transitions through states. Only backward: Review → In Progress. Concurrency via EF Core `RowVersion`. +- **Shift semantics**: First-come-first-served sign-up. Cancel anytime before start. No waitlist. Optimistic concurrency for last-slot race. +- **Seed data**: 2 clubs, 5 users (1 admin, 1 manager, 2 members, 1 viewer), sample tasks + shifts. +- **API style**: REST + OpenAPI (built-in). URL: `/api/tasks` with tenant from header, not path. +- **Data fetching**: TanStack Query (client) + Server Components (initial load). +- **First login UX**: 1 club → auto-select. Multiple → picker. Zero → "Contact admin". +- **RLS migration safety**: `bypass_rls_policy` on all RLS-enabled tables for migrations. + +--- + +## Work Objectives + +### Core Objective +Deliver a working multi-tenant club work management application where authenticated members can manage tasks and sign up for shifts within their club context, with full data isolation between tenants. + +### Concrete Deliverables +- `/backend/WorkClub.sln` — .NET 10 solution (Api, Application, Domain, Infrastructure, Tests.Unit, Tests.Integration) +- `/frontend/` — Next.js 15 App Router project with Tailwind + shadcn/ui +- `/docker-compose.yml` — Local dev stack (PostgreSQL, Keycloak, .NET API, Next.js) +- `/infra/k8s/` — Kustomize manifests (base + dev overlay) +- PostgreSQL database with RLS policies on all tenant-scoped tables +- Keycloak realm configuration with test users and club memberships +- Seed data for development + +### Definition of Done +- [ ] `docker compose up` starts all 4 services healthy within 90s +- [ ] Keycloak login returns JWT with club claims +- [ ] API enforces tenant isolation (cross-tenant requests return 403) +- [ ] RLS blocks data access at DB level without tenant context +- [ ] Tasks follow 5-state workflow with invalid transitions rejected (422) +- [ ] Shifts support sign-up with capacity enforcement (409 when full) +- [ ] Frontend shows club-switcher, task list, shift list +- [ ] `dotnet test` passes all unit + integration tests +- [ ] `bun run test` passes all frontend tests +- [ ] `kustomize build infra/k8s/overlays/dev` produces valid YAML + +### Must Have +- Credential-based multi-tenancy (JWT claims + X-Tenant-Id header) +- PostgreSQL RLS with `SET LOCAL` for connection pooling safety +- Finbuckle.MultiTenant with ClaimStrategy + HeaderStrategy fallback +- Backend validates JWT `clubs` claim against X-Tenant-Id → 403 on mismatch +- 4-role authorization per club (Admin, Manager, Member, Viewer) +- 5-state task workflow with state machine validation +- Time-slot shift scheduling with capacity and first-come-first-served sign-up +- Club-switcher in frontend for multi-club users +- EF Core concurrency tokens on Task and Shift entities +- Seed data: 2 clubs, 5 users, sample tasks + shifts +- Docker Compose with hot reload for .NET and Next.js +- Kubernetes Kustomize manifests (base + dev overlay) +- TDD: all backend features have tests BEFORE implementation + +### Must NOT Have (Guardrails) +- **No CQRS/MediatR** — Direct service injection from controllers/endpoints +- **No generic repository pattern** — Use DbContext directly (EF Core IS the unit of work) +- **No event sourcing** — Enum column + domain validation for task states +- **No Finbuckle `IsMultiTenant()` shadow property** — Explicit `TenantId` column + RLS only +- **No Swashbuckle** — Use .NET 10 built-in `AddOpenApi()` +- **No abstraction over shadcn/ui** — Use components as-is +- **No custom HTTP client wrapper** — Use `fetch` with auth headers +- **No database-per-tenant or schema-per-tenant** — Single DB, shared schema, RLS +- **No social login, self-registration, custom Keycloak themes, or 2FA** +- **No recurring shifts, waitlists, swap requests, or approval flows** +- **No custom roles or field-level permissions** — 4 fixed roles +- **No notifications (email/push)** — Users check the app +- **No API versioning, rate limiting, or HATEOAS** — MVP scope +- **No in-memory database for tests** — Real PostgreSQL via Testcontainers +- **No billing, subscriptions, or analytics dashboard** +- **No mobile app** + +--- + +## Verification Strategy + +> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed. No exceptions. +> Acceptance criteria requiring "user manually tests/confirms" are FORBIDDEN. + +### Test Decision +- **Infrastructure exists**: NO (greenfield) +- **Automated tests**: YES (TDD — tests first) +- **Backend framework**: xUnit + Testcontainers (postgres:16-alpine) + WebApplicationFactory +- **Frontend framework**: Vitest + React Testing Library +- **E2E framework**: Playwright +- **If TDD**: Each task follows RED (failing test) → GREEN (minimal impl) → REFACTOR + +### QA Policy +Every task MUST include agent-executed QA scenarios (see TODO template below). +Evidence saved to `.sisyphus/evidence/task-{N}-{scenario-slug}.{ext}`. + +- **Frontend/UI**: Use Playwright (playwright skill) — Navigate, interact, assert DOM, screenshot +- **TUI/CLI**: Use interactive_bash (tmux) — Run command, send keystrokes, validate output +- **API/Backend**: Use Bash (curl) — Send requests, assert status + response fields +- **Library/Module**: Use Bash (dotnet test / bun test) — Run tests, compare output +- **Infrastructure**: Use Bash (docker compose / kustomize build) — Validate configs + +--- + +## Execution Strategy + +### Parallel Execution Waves + +``` +Wave 1 (Start Immediately — scaffolding + infrastructure): +├── Task 1: Monorepo structure + git init + solution scaffold [quick] +├── Task 2: Docker Compose (PostgreSQL + Keycloak) [quick] +├── Task 3: Keycloak realm configuration + test users [unspecified-high] +├── Task 4: Domain entities + value objects [quick] +├── Task 5: Next.js project scaffold + Tailwind + shadcn/ui [quick] +└── Task 6: Kustomize base manifests [quick] + +Wave 2 (After Wave 1 — data layer + auth): +├── Task 7: PostgreSQL schema + EF Core migrations + RLS policies (depends: 1, 2, 4) [deep] +├── Task 8: Finbuckle multi-tenant middleware + tenant validation (depends: 1, 3) [deep] +├── Task 9: Keycloak JWT auth in .NET + role-based authorization (depends: 1, 3) [deep] +├── Task 10: NextAuth.js Keycloak integration (depends: 3, 5) [unspecified-high] +├── Task 11: Seed data script (depends: 2, 3, 4) [quick] +└── Task 12: Backend test infrastructure (xUnit + Testcontainers + WebApplicationFactory) (depends: 1) [unspecified-high] + +Wave 3 (After Wave 2 — core API): +├── Task 13: RLS integration tests — multi-tenant isolation proof (depends: 7, 8, 12) [deep] +├── Task 14: Task CRUD API endpoints + 5-state workflow (depends: 7, 8, 9) [deep] +├── Task 15: Shift CRUD API + sign-up/cancel endpoints (depends: 7, 8, 9) [deep] +├── Task 16: Club + Member API endpoints (depends: 7, 8, 9) [unspecified-high] +└── Task 17: Frontend test infrastructure (Vitest + RTL + Playwright) (depends: 5) [quick] + +Wave 4 (After Wave 3 — frontend pages): +├── Task 18: App layout + club-switcher + auth guard (depends: 10, 16, 17) [visual-engineering] +├── Task 19: Task list + task detail + status transitions UI (depends: 14, 17, 18) [visual-engineering] +├── Task 20: Shift list + shift detail + sign-up UI (depends: 15, 17, 18) [visual-engineering] +└── Task 21: Login page + first-login club picker (depends: 10, 17) [visual-engineering] + +Wave 5 (After Wave 4 — polish + Docker): +├── Task 22: Docker Compose full stack (backend + frontend + hot reload) (depends: 14, 15, 18) [unspecified-high] +├── Task 23: Backend Dockerfiles (dev + prod multi-stage) (depends: 14) [quick] +├── Task 24: Frontend Dockerfiles (dev + prod standalone) (depends: 18) [quick] +└── Task 25: Kustomize dev overlay + resource limits + health checks (depends: 6, 23, 24) [unspecified-high] + +Wave 6 (After Wave 5 — E2E + integration): +├── Task 26: Playwright E2E tests — auth flow + club switching (depends: 21, 22) [unspecified-high] +├── Task 27: Playwright E2E tests — task management flow (depends: 19, 22) [unspecified-high] +└── Task 28: Playwright E2E tests — shift sign-up flow (depends: 20, 22) [unspecified-high] + +Wave FINAL (After ALL tasks — independent review, 4 parallel): +├── Task F1: Plan compliance audit (oracle) +├── Task F2: Code quality review (unspecified-high) +├── Task F3: Real manual QA (unspecified-high) +└── Task F4: Scope fidelity check (deep) + +Critical Path: Task 1 → Task 7 → Task 8 → Task 13 → Task 14 → Task 18 → Task 22 → Task 26 → F1-F4 +Parallel Speedup: ~65% faster than sequential +Max Concurrent: 6 (Wave 1) +``` + +### Dependency Matrix + +| Task | Depends On | Blocks | Wave | +|------|-----------|--------|------| +| 1 | — | 7, 8, 9, 12 | 1 | +| 2 | — | 7, 11, 22 | 1 | +| 3 | — | 8, 9, 10, 11 | 1 | +| 4 | — | 7, 11 | 1 | +| 5 | — | 10, 17 | 1 | +| 6 | — | 25 | 1 | +| 7 | 1, 2, 4 | 13, 14, 15, 16 | 2 | +| 8 | 1, 3 | 13, 14, 15, 16 | 2 | +| 9 | 1, 3 | 14, 15, 16 | 2 | +| 10 | 3, 5 | 18, 21 | 2 | +| 11 | 2, 3, 4 | 22 | 2 | +| 12 | 1 | 13 | 2 | +| 13 | 7, 8, 12 | 14, 15 | 3 | +| 14 | 7, 8, 9 | 19, 22, 23 | 3 | +| 15 | 7, 8, 9 | 20, 22 | 3 | +| 16 | 7, 8, 9 | 18 | 3 | +| 17 | 5 | 18, 19, 20, 21 | 3 | +| 18 | 10, 16, 17 | 19, 20, 22 | 4 | +| 19 | 14, 17, 18 | 27 | 4 | +| 20 | 15, 17, 18 | 28 | 4 | +| 21 | 10, 17 | 26 | 4 | +| 22 | 14, 15, 18 | 26, 27, 28 | 5 | +| 23 | 14 | 25 | 5 | +| 24 | 18 | 25 | 5 | +| 25 | 6, 23, 24 | — | 5 | +| 26 | 21, 22 | — | 6 | +| 27 | 19, 22 | — | 6 | +| 28 | 20, 22 | — | 6 | +| F1-F4 | ALL | — | FINAL | + +### Agent Dispatch Summary + +- **Wave 1 (6 tasks)**: T1 → `quick`, T2 → `quick`, T3 → `unspecified-high`, T4 → `quick`, T5 → `quick`, T6 → `quick` +- **Wave 2 (6 tasks)**: T7 → `deep`, T8 → `deep`, T9 → `deep`, T10 → `unspecified-high`, T11 → `quick`, T12 → `unspecified-high` +- **Wave 3 (5 tasks)**: T13 → `deep`, T14 → `deep`, T15 → `deep`, T16 → `unspecified-high`, T17 → `quick` +- **Wave 4 (4 tasks)**: T18 → `visual-engineering`, T19 → `visual-engineering`, T20 → `visual-engineering`, T21 → `visual-engineering` +- **Wave 5 (4 tasks)**: T22 → `unspecified-high`, T23 → `quick`, T24 → `quick`, T25 → `unspecified-high` +- **Wave 6 (3 tasks)**: T26 → `unspecified-high`, T27 → `unspecified-high`, T28 → `unspecified-high` +- **FINAL (4 tasks)**: F1 → `oracle`, F2 → `unspecified-high`, F3 → `unspecified-high`, F4 → `deep` + +--- + +## TODOs + +- [ ] 1. Monorepo Structure + Git Repository + .NET Solution Scaffold + + **What to do**: + - Initialize git repository: `git init` at repo root + - Create monorepo directory structure: `/backend/`, `/frontend/`, `/infra/` + - Initialize .NET 10 solution at `/backend/WorkClub.sln` + - Create projects: `WorkClub.Api` (web), `WorkClub.Application` (classlib), `WorkClub.Domain` (classlib), `WorkClub.Infrastructure` (classlib), `WorkClub.Tests.Unit` (xunit), `WorkClub.Tests.Integration` (xunit) + - Configure project references: Api → Application → Domain ← Infrastructure. Tests → all. + - Add `.gitignore` (combined dotnet + node + IDE entries), `.editorconfig` (C# conventions), `global.json` (pin .NET 10 SDK) + - Create initial commit with repo structure and configuration files + - Add NuGet packages to Api: `Npgsql.EntityFrameworkCore.PostgreSQL`, `Finbuckle.MultiTenant`, `Microsoft.AspNetCore.Authentication.JwtBearer` + - Add NuGet packages to Infrastructure: `Npgsql.EntityFrameworkCore.PostgreSQL`, `Microsoft.EntityFrameworkCore.Design` + - Add NuGet packages to Tests.Integration: `Testcontainers.PostgreSql`, `Microsoft.AspNetCore.Mvc.Testing` + - Verify `dotnet build` compiles with zero errors + + **Must NOT do**: + - Do NOT add MediatR, AutoMapper, or FluentValidation + - Do NOT create generic repository interfaces + - Do NOT add Swashbuckle — will use built-in `AddOpenApi()` later + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Straightforward scaffolding with well-known dotnet CLI commands + - **Skills**: [] + - No special skills needed — standard dotnet CLI operations + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 2, 3, 4, 5, 6) + - **Blocks**: Tasks 7, 8, 9, 12 + - **Blocked By**: None + + **References**: + + **Pattern References**: + - None (greenfield — no existing code) + + **External References**: + - .NET 10 SDK: `dotnet new sln`, `dotnet new webapi`, `dotnet new classlib`, `dotnet new xunit` + - Clean Architecture layout: Api → Application → Domain ← Infrastructure (standard .NET layering) + - `global.json` format: `{ "sdk": { "version": "10.0.100", "rollForward": "latestFeature" } }` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Git repository initialized + Tool: Bash + Preconditions: Repo root exists + Steps: + 1. Run `git rev-parse --is-inside-work-tree` + 2. Assert output is "true" + 3. Run `git log --oneline -1` + 4. Assert initial commit exists + 5. Run `cat .gitignore` + 6. Assert contains "bin/", "obj/", "node_modules/", ".next/" + Expected Result: Git repo initialized with comprehensive .gitignore + Failure Indicators: Not a git repo, missing .gitignore entries + Evidence: .sisyphus/evidence/task-1-git-init.txt + + Scenario: Solution builds successfully + Tool: Bash + Preconditions: .NET 10 SDK installed + Steps: + 1. Run `dotnet build backend/WorkClub.sln --configuration Release` + 2. Check exit code is 0 + 3. Verify all 6 projects are listed in build output + Expected Result: Exit code 0, output contains "6 succeeded, 0 failed" + Failure Indicators: Any "error" or non-zero exit code + Evidence: .sisyphus/evidence/task-1-solution-build.txt + + Scenario: Project references are correct + Tool: Bash + Preconditions: Solution exists + Steps: + 1. Run `dotnet list backend/src/WorkClub.Api/WorkClub.Api.csproj reference` + 2. Assert output contains "WorkClub.Application" and "WorkClub.Infrastructure" + 3. Run `dotnet list backend/src/WorkClub.Application/WorkClub.Application.csproj reference` + 4. Assert output contains "WorkClub.Domain" + 5. Run `dotnet list backend/src/WorkClub.Infrastructure/WorkClub.Infrastructure.csproj reference` + 6. Assert output contains "WorkClub.Domain" + Expected Result: All project references match Clean Architecture dependency graph + Failure Indicators: Missing references or circular dependencies + Evidence: .sisyphus/evidence/task-1-project-refs.txt + ``` + + **Commit**: YES + - Message: `chore(scaffold): initialize git repo and monorepo with .NET solution` + - Files: `backend/**/*.csproj`, `backend/WorkClub.sln`, `.gitignore`, `.editorconfig`, `global.json` + - Pre-commit: `dotnet build backend/WorkClub.sln` + +- [ ] 2. Docker Compose — PostgreSQL + Keycloak + + **What to do**: + - Create `/docker-compose.yml` at repo root with services: + - `postgres`: PostgreSQL 16 Alpine, port 5432, volume `postgres-data`, healthcheck via `pg_isready` + - `keycloak`: Keycloak 26.x (quay.io/keycloak/keycloak:26.1), port 8080, depends on postgres, `--import-realm` flag with volume mount to `/opt/keycloak/data/import` + - Configure PostgreSQL: database `workclub`, user `app`, password `devpass` (dev only) + - Configure Keycloak: admin user `admin`/`admin`, PostgreSQL as Keycloak's own database (separate DB `keycloak`) + - Create placeholder realm file at `/infra/keycloak/realm-export.json` (will be populated in Task 3) + - Add `app-network` bridge network connecting all services + - Verify both services start and pass health checks + + **Must NOT do**: + - Do NOT add backend or frontend services yet (Task 22) + - Do NOT use deprecated `KEYCLOAK_IMPORT` env var — use `--import-realm` CLI flag + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Standard Docker Compose YAML, well-documented services + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 1, 3, 4, 5, 6) + - **Blocks**: Tasks 7, 11, 22 + - **Blocked By**: None + + **References**: + + **External References**: + - Keycloak Docker: `quay.io/keycloak/keycloak:26.1` with `start-dev` command for local + - Keycloak realm import: `--import-realm` flag + volume `/opt/keycloak/data/import` + - PostgreSQL healthcheck: `pg_isready -U app -d workclub` + - Keycloak healthcheck: `curl -sf http://localhost:8080/health/ready || exit 1` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: PostgreSQL starts and accepts connections + Tool: Bash + Preconditions: Docker installed, no conflicting port 5432 + Steps: + 1. Run `docker compose up -d postgres` + 2. Wait up to 30s: `docker compose exec postgres pg_isready -U app -d workclub` + 3. Assert exit code 0 + 4. Run `docker compose exec postgres psql -U app -d workclub -c "SELECT 1"` + 5. Assert output contains "1" + Expected Result: PostgreSQL healthy and accepting queries + Failure Indicators: pg_isready fails, connection refused + Evidence: .sisyphus/evidence/task-2-postgres-health.txt + + Scenario: Keycloak starts and serves OIDC discovery + Tool: Bash + Preconditions: docker compose up -d (postgres + keycloak) + Steps: + 1. Run `docker compose up -d` + 2. Wait up to 120s for Keycloak health: poll `curl -sf http://localhost:8080/health/ready` + 3. Curl `http://localhost:8080/realms/master/.well-known/openid-configuration` + 4. Assert HTTP 200 and JSON contains "issuer" field + Expected Result: Keycloak healthy, OIDC endpoint responding + Failure Indicators: Keycloak fails to start, OIDC endpoint returns non-200 + Evidence: .sisyphus/evidence/task-2-keycloak-health.txt + ``` + + **Commit**: YES + - Message: `infra(docker): add Docker Compose with PostgreSQL and Keycloak` + - Files: `docker-compose.yml`, `infra/keycloak/realm-export.json` + - Pre-commit: `docker compose config` + +- [ ] 3. Keycloak Realm Configuration + Test Users + + **What to do**: + - Create Keycloak realm `workclub` with: + - Client `workclub-api` (confidential, service account enabled) for backend + - Client `workclub-app` (public, PKCE) for frontend — redirect URIs: `http://localhost:3000/*` + - Custom user attribute `clubs` (JSON string: `{"club-1-uuid": "admin", "club-2-uuid": "member"}`) + - Custom protocol mapper `club-membership` (type: `Script Mapper` or `User Attribute` → JWT claim `clubs`) + - Create 5 test users: + - `admin@test.com` / `testpass123` — Admin of club-1, Member of club-2 + - `manager@test.com` / `testpass123` — Manager of club-1 + - `member1@test.com` / `testpass123` — Member of club-1, Member of club-2 + - `member2@test.com` / `testpass123` — Member of club-1 + - `viewer@test.com` / `testpass123` — Viewer of club-1 + - Export realm to `/infra/keycloak/realm-export.json` including users (with hashed passwords) + - Test: obtain token for admin@test.com, decode JWT, verify `clubs` claim is present + + **Must NOT do**: + - Do NOT add social login providers + - Do NOT add self-registration flow + - Do NOT customize Keycloak login theme + - Do NOT use Keycloak Organizations feature (too new for MVP) + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: Keycloak realm configuration requires understanding OIDC flows, custom mappers, and realm export format + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 1, 2, 4, 5, 6) + - **Blocks**: Tasks 8, 9, 10, 11 + - **Blocked By**: None (creates realm export JSON file; Docker Compose from Task 2 will use it, but the file can be created independently) + + **References**: + + **External References**: + - Keycloak Admin REST API: `https://www.keycloak.org/docs-api/latest/rest-api/` — for programmatic realm creation + - Keycloak realm export format: JSON with `realm`, `clients`, `users`, `protocolMappers` arrays + - Custom protocol mapper: `oidc-usermodel-attribute-mapper` type with `claim.name: clubs`, `user.attribute: clubs` + - PKCE client config: `publicClient: true`, `standardFlowEnabled: true`, `directAccessGrantsEnabled: true` (for dev token testing) + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Token contains club membership claims + Tool: Bash + Preconditions: docker compose up -d (with realm imported) + Steps: + 1. Obtain token: `curl -sf -X POST http://localhost:8080/realms/workclub/protocol/openid-connect/token -d "client_id=workclub-app&username=admin@test.com&password=testpass123&grant_type=password"` + 2. Extract access_token from JSON response + 3. Decode JWT payload: `echo $TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | jq '.clubs'` + 4. Assert clubs claim contains `{"club-1-uuid": "admin", "club-2-uuid": "member"}` + Expected Result: JWT has `clubs` claim with correct role mappings + Failure Indicators: Missing `clubs` claim, wrong roles, token request fails + Evidence: .sisyphus/evidence/task-3-jwt-claims.txt + + Scenario: All 5 test users can authenticate + Tool: Bash + Preconditions: Keycloak running with realm imported + Steps: + 1. For each user (admin@test.com, manager@test.com, member1@test.com, member2@test.com, viewer@test.com): + curl token endpoint with username/password + 2. Assert HTTP 200 for all 5 users + 3. Assert each response contains "access_token" field + Expected Result: All 5 users authenticate successfully + Failure Indicators: Any user returns non-200, missing access_token + Evidence: .sisyphus/evidence/task-3-user-auth.txt + ``` + + **Commit**: YES + - Message: `infra(keycloak): configure realm with test users and club memberships` + - Files: `infra/keycloak/realm-export.json` + - Pre-commit: — + +--- + +- [ ] 4. Domain Entities + Value Objects + + **What to do**: + - Create domain entities in `WorkClub.Domain/Entities/`: + - `Club`: Id (Guid), TenantId (string), Name, SportType (enum), Description, CreatedAt, UpdatedAt + - `Member`: Id (Guid), TenantId (string), ExternalUserId (string — Keycloak sub), DisplayName, Email, Role (enum: Admin/Manager/Member/Viewer), ClubId (FK), CreatedAt, UpdatedAt + - `WorkItem` (Task): Id (Guid), TenantId (string), Title, Description, Status (enum: Open/Assigned/InProgress/Review/Done), AssigneeId (FK? nullable), CreatedById (FK), ClubId (FK), DueDate (DateTimeOffset?), CreatedAt, UpdatedAt, RowVersion (byte[] — concurrency token) + - `Shift`: Id (Guid), TenantId (string), Title, Description, Location (string?), StartTime (DateTimeOffset), EndTime (DateTimeOffset), Capacity (int, default 1), ClubId (FK), CreatedById (FK), CreatedAt, UpdatedAt, RowVersion (byte[]) + - `ShiftSignup`: Id (Guid), ShiftId (FK), MemberId (FK), SignedUpAt (DateTimeOffset) + - Create enums in `WorkClub.Domain/Enums/`: + - `SportType`: Tennis, Cycling, Swimming, Football, Other + - `ClubRole`: Admin, Manager, Member, Viewer + - `WorkItemStatus`: Open, Assigned, InProgress, Review, Done + - Create `ITenantEntity` marker interface: `string TenantId { get; set; }` + - Create `WorkItemStatus` state machine validation method on `WorkItem` entity: + - Valid transitions: Open→Assigned, Assigned→InProgress, InProgress→Review, Review→Done, Review→InProgress + - Method: `bool CanTransitionTo(WorkItemStatus newStatus)` + `void TransitionTo(WorkItemStatus newStatus)` (throws on invalid) + - Write unit tests FIRST (TDD): test state machine — valid transitions succeed, invalid transitions throw + + **Must NOT do**: + - Do NOT add event sourcing or domain events + - Do NOT create repository interfaces — will use DbContext directly + - Do NOT add navigation properties yet (EF Core configuration is Task 7) + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Simple POCO classes and enum definitions with straightforward unit tests + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 1, 2, 3, 5, 6) + - **Blocks**: Tasks 7, 11 + - **Blocked By**: None + + **References**: + + **External References**: + - C# 14 record types for value objects: `public record SportType(string Value)` + - State machine pattern: simple `switch` expression in entity method — no external library needed + - `ITenantEntity` interface pattern from Metis research: explicit TenantId property (not Finbuckle shadow) + + **Acceptance Criteria**: + + **If TDD:** + - [ ] Test file created: `backend/tests/WorkClub.Tests.Unit/Domain/WorkItemStatusTests.cs` + - [ ] `dotnet test backend/tests/WorkClub.Tests.Unit` → PASS (all state machine tests) + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Valid state transitions succeed + Tool: Bash + Preconditions: Unit test project compiles + Steps: + 1. Run `dotnet test backend/tests/WorkClub.Tests.Unit --filter "WorkItemStatus" --verbosity normal` + 2. Assert tests cover: Open→Assigned, Assigned→InProgress, InProgress→Review, Review→Done, Review→InProgress + 3. Assert all pass + Expected Result: 5 valid transition tests pass + Failure Indicators: Any test fails, missing test cases + Evidence: .sisyphus/evidence/task-4-state-machine-valid.txt + + Scenario: Invalid state transitions throw + Tool: Bash + Preconditions: Unit test project compiles + Steps: + 1. Run `dotnet test backend/tests/WorkClub.Tests.Unit --filter "InvalidTransition" --verbosity normal` + 2. Assert tests cover: Open→Done, Open→InProgress, Assigned→Done, InProgress→Open, Done→anything + 3. Assert all pass (each asserts exception thrown) + Expected Result: Invalid transition tests pass (exceptions correctly thrown) + Failure Indicators: Missing invalid transition tests, test failures + Evidence: .sisyphus/evidence/task-4-state-machine-invalid.txt + ``` + + **Commit**: YES + - Message: `feat(domain): add core entities — Club, Member, WorkItem, Shift with state machine` + - Files: `backend/src/WorkClub.Domain/**/*.cs`, `backend/tests/WorkClub.Tests.Unit/Domain/*.cs` + - Pre-commit: `dotnet test backend/tests/WorkClub.Tests.Unit` + +- [ ] 5. Next.js Project Scaffold + Tailwind + shadcn/ui + + **What to do**: + - Initialize Next.js 15 project in `/frontend/` using `bunx create-next-app@latest` with: + - App Router (not Pages), TypeScript, Tailwind CSS, ESLint, `src/` directory + - `output: 'standalone'` in `next.config.ts` + - Install and configure shadcn/ui: `bunx shadcn@latest init` + - Install initial components: Button, Card, Badge, Input, Label, Select, Dialog, DropdownMenu, Table, Toast + - Configure path aliases in `tsconfig.json`: `@/*` → `src/*` + - Create directory structure: + - `src/app/` — App Router pages + - `src/components/` — shared components + - `src/lib/` — utilities + - `src/hooks/` — custom hooks + - `src/types/` — TypeScript types + - Add environment variables to `.env.local.example`: + - `NEXT_PUBLIC_API_URL=http://localhost:5000` + - `NEXTAUTH_URL=http://localhost:3000` + - `NEXTAUTH_SECRET=dev-secret-change-me` + - `KEYCLOAK_ISSUER=http://localhost:8080/realms/workclub` + - `KEYCLOAK_CLIENT_ID=workclub-app` + - `KEYCLOAK_CLIENT_SECRET=` + - Verify `bun run build` succeeds + + **Must NOT do**: + - Do NOT install Bun-specific Next.js plugins — use standard Next.js + - Do NOT create custom component wrappers over shadcn/ui + - Do NOT add auth pages yet (Task 21) + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Standard Next.js scaffolding with well-known CLI tools + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 1, 2, 3, 4, 6) + - **Blocks**: Tasks 10, 17 + - **Blocked By**: None + + **References**: + + **External References**: + - Next.js create-next-app: `bunx create-next-app@latest frontend --typescript --tailwind --eslint --app --src-dir --use-bun` + - shadcn/ui init: `bunx shadcn@latest init` then `bunx shadcn@latest add button card badge input label select dialog dropdown-menu table toast` + - `next.config.ts`: `{ output: 'standalone' }` for Docker deployment + - Standalone output: copies only needed `node_modules`, creates `server.js` entry point + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Next.js builds successfully + Tool: Bash + Preconditions: Bun installed, frontend/ directory exists + Steps: + 1. Run `bun run build` in frontend/ + 2. Assert exit code 0 + 3. Verify `.next/standalone/server.js` exists + Expected Result: Build succeeds with standalone output + Failure Indicators: TypeScript errors, build failure, missing standalone + Evidence: .sisyphus/evidence/task-5-nextjs-build.txt + + Scenario: Dev server starts + Tool: Bash + Preconditions: frontend/ exists with dependencies installed + Steps: + 1. Start `bun run dev` in background + 2. Wait 10s, then curl `http://localhost:3000` + 3. Assert HTTP 200 + 4. Kill dev server + Expected Result: Dev server responds on port 3000 + Failure Indicators: Server fails to start, non-200 response + Evidence: .sisyphus/evidence/task-5-dev-server.txt + ``` + + **Commit**: YES + - Message: `chore(frontend): initialize Next.js project with Tailwind and shadcn/ui` + - Files: `frontend/**` + - Pre-commit: `bun run build` (in frontend/) + +- [ ] 6. Kustomize Base Manifests + + **What to do**: + - Create `/infra/k8s/base/kustomization.yaml` referencing all base resources + - Create base manifests: + - `backend-deployment.yaml`: Deployment for dotnet-api (1 replica, port 8080, health probes at `/health/live`, `/health/ready`, `/health/startup`) + - `backend-service.yaml`: ClusterIP Service (port 80 → 8080) + - `frontend-deployment.yaml`: Deployment for nextjs (1 replica, port 3000, health probe at `/api/health`) + - `frontend-service.yaml`: ClusterIP Service (port 80 → 3000) + - `postgres-statefulset.yaml`: StatefulSet (1 replica, port 5432, PVC 10Gi, healthcheck via `pg_isready`) + - `postgres-service.yaml`: Headless + primary ClusterIP service + - `keycloak-deployment.yaml`: Deployment (1 replica, port 8080) + - `keycloak-service.yaml`: ClusterIP Service + - `configmap.yaml`: App configuration (non-sensitive: log level, CORS origins, API URLs) + - `ingress.yaml`: Basic Ingress for single-domain routing (frontend on `/`, backend on `/api`) + - Use resource requests/limits placeholders (overridden per environment in overlays) + - Use image tag placeholder `latest` (overridden per environment) + - Verify `kustomize build infra/k8s/base` produces valid YAML + + **Must NOT do**: + - Do NOT create Helm charts + - Do NOT add wildcard TLS/cert-manager (single domain, no subdomains) + - Do NOT add HPA, PDB, or NetworkPolicies (production concerns, not MVP) + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Standard Kubernetes YAML manifests with well-known patterns + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 1, 2, 3, 4, 5) + - **Blocks**: Task 25 + - **Blocked By**: None + + **References**: + + **External References**: + - Kustomize: `kustomization.yaml` with `resources:` list + - .NET health probes: `/health/startup` (startupProbe), `/health/live` (livenessProbe), `/health/ready` (readinessProbe) + - Next.js health: `/api/health` (custom route handler) + - PostgreSQL StatefulSet: headless Service + volumeClaimTemplates + - Ingress single-domain: path-based routing (`/` → frontend, `/api` → backend) + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Kustomize base builds valid YAML + Tool: Bash + Preconditions: kustomize CLI installed + Steps: + 1. Run `kustomize build infra/k8s/base` + 2. Assert exit code 0 + 3. Pipe output to `grep "kind:" | sort -u` + 4. Assert contains: ConfigMap, Deployment (x3), Ingress, Service (x4), StatefulSet + Expected Result: Valid YAML with all expected resource kinds + Failure Indicators: kustomize build fails, missing resource kinds + Evidence: .sisyphus/evidence/task-6-kustomize-base.txt + + Scenario: Resource names are consistent + Tool: Bash + Preconditions: kustomize build succeeds + Steps: + 1. Run `kustomize build infra/k8s/base | grep "name:" | head -20` + 2. Verify naming convention is consistent (e.g., workclub-api, workclub-frontend, workclub-postgres) + Expected Result: All resources follow consistent naming pattern + Failure Indicators: Inconsistent or missing names + Evidence: .sisyphus/evidence/task-6-resource-names.txt + ``` + + **Commit**: YES + - Message: `infra(k8s): add Kustomize base manifests for all services` + - Files: `infra/k8s/base/**/*.yaml` + - Pre-commit: `kustomize build infra/k8s/base` + +--- + +- [ ] 7. PostgreSQL Schema + EF Core Migrations + RLS Policies + + **What to do**: + - Create `AppDbContext` in `WorkClub.Infrastructure/Data/`: + - DbSets: Clubs, Members, WorkItems, Shifts, ShiftSignups + - Configure entity mappings via `IEntityTypeConfiguration` classes + - Configure `RowVersion` as concurrency token on WorkItem and Shift (`UseXminAsConcurrencyToken()`) + - Configure indexes: `TenantId` on all tenant-scoped tables, `ClubId` on Member/WorkItem/Shift, `Status` on WorkItem + - Configure relationships: Club → Members, Club → WorkItems, Club → Shifts, Shift → ShiftSignups, Member → ShiftSignups + - Create initial EF Core migration + - Create SQL migration script for RLS policies (run after EF migration): + - `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` on: clubs, members, work_items, shifts, shift_signups + - Create `tenant_isolation` policy on each table: `USING (tenant_id = current_setting('app.current_tenant_id', true)::text)` + - Create `bypass_rls_policy` on each table for migrations role: `USING (true)` for role `app_admin` + - Create `app_user` role (used by application) — RLS applies + - Create `app_admin` role (used by migrations) — RLS bypassed + - Create `TenantDbConnectionInterceptor` (implements `DbConnectionInterceptor`): + - On `ConnectionOpenedAsync`: execute `SET LOCAL app.current_tenant_id = '{tenantId}'` + - Get tenant ID from `IHttpContextAccessor` → `ITenantInfo` (Finbuckle) + - Create `SaveChangesInterceptor` for automatic TenantId assignment on new entities (implements `ITenantEntity`) + - Write integration tests FIRST (TDD): + - Test: migration applies cleanly to fresh PostgreSQL + - Test: RLS blocks queries without `SET LOCAL` context + - Test: RLS allows queries with correct tenant context + + **Must NOT do**: + - Do NOT use Finbuckle's `IsMultiTenant()` fluent API — use explicit `TenantId` property + - Do NOT use `SET` — MUST use `SET LOCAL` for transaction-scoped tenant context + - Do NOT use in-memory database provider for tests + - Do NOT create generic repository pattern + + **Recommended Agent Profile**: + - **Category**: `deep` + - Reason: Complex EF Core configuration with RLS policies, connection interceptors, and concurrent connection pooling safety — highest-risk task in the project + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 2 (with Tasks 8, 9, 10, 11, 12) + - **Blocks**: Tasks 13, 14, 15, 16 + - **Blocked By**: Tasks 1 (solution), 2 (Docker Compose for PostgreSQL), 4 (domain entities) + + **References**: + + **External References**: + - EF Core Npgsql: `UseXminAsConcurrencyToken()` for PostgreSQL optimistic concurrency + - PostgreSQL RLS: `ALTER TABLE x ENABLE ROW LEVEL SECURITY; CREATE POLICY ... USING (...)` + - `SET LOCAL`: Transaction-scoped session variable — safe with connection pooling + - `current_setting('app.current_tenant_id', true)`: Second param `true` returns NULL instead of error when unset + - `DbConnectionInterceptor`: `ConnectionOpenedAsync(DbConnection, ConnectionEndEventData, CancellationToken)` — execute SQL after connection opened + - `bypass_rls_policy`: `CREATE POLICY bypass ON table FOR ALL TO app_admin USING (true)` — allows migrations + - Finbuckle `ITenantInfo.Id`: Access current tenant from DI + + **Acceptance Criteria**: + + **If TDD:** + - [ ] Test file: `backend/tests/WorkClub.Tests.Integration/Data/MigrationTests.cs` + - [ ] Test file: `backend/tests/WorkClub.Tests.Integration/Data/RlsTests.cs` + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Migration applies to fresh PostgreSQL + Tool: Bash (Testcontainers in test) + Preconditions: Testcontainers, Docker running + Steps: + 1. Run `dotnet test backend/tests/WorkClub.Tests.Integration --filter "Migration" --verbosity normal` + 2. Test spins up PostgreSQL container, applies migration, verifies all tables exist + Expected Result: All tables created (clubs, members, work_items, shifts, shift_signups) + Failure Indicators: Migration fails, missing tables + Evidence: .sisyphus/evidence/task-7-migration.txt + + Scenario: RLS blocks access without tenant context + Tool: Bash (integration test) + Preconditions: Migration applied, seed data inserted + Steps: + 1. Run integration test that: + a. Inserts data for tenant-1 and tenant-2 using admin role (bypass RLS) + b. Opens connection as app_user WITHOUT `SET LOCAL` + c. SELECT * FROM work_items → assert 0 rows + d. Opens connection as app_user WITH `SET LOCAL app.current_tenant_id = 'tenant-1'` + e. SELECT * FROM work_items → assert only tenant-1 rows + Expected Result: RLS correctly filters by tenant, returns 0 without context + Failure Indicators: Data leaks across tenants, queries return all rows + Evidence: .sisyphus/evidence/task-7-rls-isolation.txt + + Scenario: RLS allows correct tenant access + Tool: Bash (integration test) + Preconditions: Migration applied, multi-tenant data seeded + Steps: + 1. Run integration test with Testcontainers: + a. Insert 5 work items for tenant-1, 3 for tenant-2 + b. SET LOCAL to tenant-1 → SELECT count(*) → assert 5 + c. SET LOCAL to tenant-2 → SELECT count(*) → assert 3 + Expected Result: Each tenant sees only their data + Failure Indicators: Wrong counts, cross-tenant data visible + Evidence: .sisyphus/evidence/task-7-rls-correct-access.txt + ``` + + **Commit**: YES (groups with Task 8) + - Message: `feat(data): add EF Core DbContext, migrations, RLS policies, and multi-tenant middleware` + - Files: `backend/src/WorkClub.Infrastructure/Data/**/*.cs`, SQL migration files + - Pre-commit: `dotnet test backend/tests/WorkClub.Tests.Integration --filter "Migration|Rls"` + +- [ ] 8. Finbuckle Multi-Tenant Middleware + Tenant Validation + + **What to do**: + - Configure Finbuckle in `Program.cs`: + - `builder.Services.AddMultiTenant().WithClaimStrategy("tenant_id").WithHeaderStrategy("X-Tenant-Id")` + - Middleware order: `UseAuthentication()` → `UseMultiTenant()` → `UseAuthorization()` + - Create `TenantValidationMiddleware`: + - Extract `clubs` claim from JWT + - Extract `X-Tenant-Id` header from request + - Validate: X-Tenant-Id MUST be present in JWT `clubs` claim → 403 if mismatch + - Set Finbuckle tenant context + - Create `ITenantProvider` service (scoped): + - `GetTenantId()`: returns current tenant ID from Finbuckle context + - `GetUserRole()`: returns user's role in current tenant from JWT clubs claim + - Register `TenantDbConnectionInterceptor` (from Task 7) in DI + - Write integration tests FIRST (TDD): + - Test: request with valid JWT + matching X-Tenant-Id → 200 + - Test: request with valid JWT + non-member X-Tenant-Id → 403 + - Test: request without X-Tenant-Id header → 400 + - Test: unauthenticated request → 401 + + **Must NOT do**: + - Do NOT use Finbuckle's RouteStrategy (tenant comes from credentials, not URL) + - Do NOT use `UseMultiTenant()` before `UseAuthentication()` (ClaimStrategy needs claims) + + **Recommended Agent Profile**: + - **Category**: `deep` + - Reason: Finbuckle middleware integration with custom validation, security-critical cross-tenant check + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 2 (with Tasks 7, 9, 10, 11, 12) + - **Blocks**: Tasks 13, 14, 15, 16 + - **Blocked By**: Tasks 1 (solution), 3 (Keycloak for JWT claims) + + **References**: + + **External References**: + - Finbuckle docs: `WithClaimStrategy(claimType)` — reads tenant from specified JWT claim + - Finbuckle docs: `WithHeaderStrategy(headerName)` — reads from HTTP header as fallback + - Middleware order for single realm: `UseAuthentication()` → `UseMultiTenant()` → `UseAuthorization()` + - `IMultiTenantContextAccessor`: injected service to access resolved tenant + + **Acceptance Criteria**: + + **If TDD:** + - [ ] Test file: `backend/tests/WorkClub.Tests.Integration/Middleware/TenantValidationTests.cs` + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Valid tenant request succeeds + Tool: Bash (integration test with WebApplicationFactory) + Preconditions: WebApplicationFactory configured with test Keycloak token + Steps: + 1. Run integration test: + a. Create JWT with clubs: {"club-1": "admin"} + b. Send GET /api/tasks with Authorization: Bearer + X-Tenant-Id: club-1 + c. Assert HTTP 200 + Expected Result: Request passes tenant validation + Failure Indicators: 401 or 403 when valid + Evidence: .sisyphus/evidence/task-8-valid-tenant.txt + + Scenario: Cross-tenant access denied + Tool: Bash (integration test) + Preconditions: WebApplicationFactory with test JWT + Steps: + 1. Run integration test: + a. Create JWT with clubs: {"club-1": "admin"} (no club-2) + b. Send GET /api/tasks with X-Tenant-Id: club-2 + c. Assert HTTP 403 + Expected Result: 403 Forbidden — user not member of requested club + Failure Indicators: Returns 200 (data leak) or wrong error code + Evidence: .sisyphus/evidence/task-8-cross-tenant-denied.txt + + Scenario: Missing tenant header returns 400 + Tool: Bash (integration test) + Preconditions: WebApplicationFactory + Steps: + 1. Send authenticated request WITHOUT X-Tenant-Id header + 2. Assert HTTP 400 + Expected Result: 400 Bad Request + Failure Indicators: 200 or 500 + Evidence: .sisyphus/evidence/task-8-missing-header.txt + ``` + + **Commit**: YES (groups with Task 7) + - Message: `feat(data): add EF Core DbContext, migrations, RLS policies, and multi-tenant middleware` + - Files: `backend/src/WorkClub.Api/Middleware/*.cs`, `Program.cs` updates + - Pre-commit: `dotnet test backend/tests/WorkClub.Tests.Integration --filter "TenantValidation"` + +--- + +- [ ] 9. Keycloak JWT Auth in .NET + Role-Based Authorization + + **What to do**: + - Configure JWT Bearer authentication in `Program.cs`: + - `builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(options => { options.Authority = keycloakIssuer; options.Audience = "workclub-api"; })` + - Create custom `ClaimsPrincipal` transformation: + - Parse `clubs` claim from JWT → extract role for current tenant → add role claims + - Map club role to ASP.NET `ClaimTypes.Role` (e.g., "Admin", "Manager", "Member", "Viewer") + - Create authorization policies: + - `RequireAdmin`: requires "Admin" role + - `RequireManager`: requires "Admin" OR "Manager" role + - `RequireMember`: requires "Admin" OR "Manager" OR "Member" role + - `RequireViewer`: any authenticated user with valid club membership + - Add `builder.Services.AddOpenApi()` for API documentation + - Map health check endpoints: `/health/live`, `/health/ready`, `/health/startup` + - Write integration tests FIRST (TDD): + - Test: Admin can access admin-only endpoints + - Test: Member cannot access admin-only endpoints → 403 + - Test: Viewer can only read, not write → 403 on POST/PUT/DELETE + + **Must NOT do**: + - Do NOT add Swashbuckle — use `AddOpenApi()` built-in + - Do NOT implement custom JWT validation — let ASP.NET handle it + - Do NOT add 2FA or password policies + + **Recommended Agent Profile**: + - **Category**: `deep` + - Reason: JWT authentication with custom claims transformation and role-based authorization requires careful security implementation + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 2 (with Tasks 7, 8, 10, 11, 12) + - **Blocks**: Tasks 14, 15, 16 + - **Blocked By**: Tasks 1 (solution), 3 (Keycloak config) + + **References**: + + **External References**: + - ASP.NET JWT Bearer: `AddJwtBearer` with `Authority` pointing to Keycloak realm + - .NET 10 OpenAPI: `builder.Services.AddOpenApi()` + `app.MapOpenApi()` + - Claims transformation: `IClaimsTransformation.TransformAsync(ClaimsPrincipal)` + - Authorization policies: `builder.Services.AddAuthorizationBuilder().AddPolicy("RequireAdmin", p => p.RequireRole("Admin"))` + - Health checks: `builder.Services.AddHealthChecks().AddNpgSql(connectionString)` + + **Acceptance Criteria**: + + **If TDD:** + - [ ] Test file: `backend/tests/WorkClub.Tests.Integration/Auth/AuthorizationTests.cs` + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Role-based access control works + Tool: Bash (integration test) + Preconditions: WebApplicationFactory with mocked JWT claims + Steps: + 1. Test: JWT with Admin role → GET /api/clubs → 200 + 2. Test: JWT with Viewer role → POST /api/tasks → 403 + 3. Test: JWT with Manager role → POST /api/tasks → 200 + 4. Test: No token → any endpoint → 401 + Expected Result: Each role gets correct access level + Failure Indicators: Wrong HTTP status codes, privilege escalation + Evidence: .sisyphus/evidence/task-9-rbac.txt + + Scenario: Health endpoints respond without auth + Tool: Bash + Preconditions: API running + Steps: + 1. curl http://localhost:5000/health/live → assert 200 + 2. curl http://localhost:5000/health/ready → assert 200 + Expected Result: Health endpoints are public (no auth required) + Failure Indicators: 401 on health endpoints + Evidence: .sisyphus/evidence/task-9-health.txt + ``` + + **Commit**: YES + - Message: `feat(auth): add Keycloak JWT authentication and role-based authorization` + - Files: `backend/src/WorkClub.Api/Auth/*.cs`, `Program.cs` updates + - Pre-commit: `dotnet test backend/tests/WorkClub.Tests.Integration --filter "Authorization"` + +- [ ] 10. NextAuth.js Keycloak Integration + + **What to do**: + - Install Auth.js v5: `bun add next-auth@beta @auth/core` + - Create `/frontend/src/auth/` directory with: + - `auth.ts`: NextAuth config with Keycloak OIDC provider + - Configure JWT callback to include `clubs` claim from Keycloak token + - Configure session callback to expose clubs + active club to client + - Create `/frontend/src/middleware.ts`: + - Protect all routes except `/`, `/login`, `/api/auth/*` + - Redirect unauthenticated users to `/login` + - Create auth utility hooks: + - `useSession()` wrapper that includes club membership + - `useActiveClub()` — reads from local storage / cookie, provides club context + - Create API fetch utility: + - Wraps `fetch` with `Authorization: Bearer ` and `X-Tenant-Id: ` headers + - Used by all frontend API calls + - Write tests FIRST (TDD): + - Test: `useActiveClub` returns stored club + - Test: API fetch utility includes correct headers + + **Must NOT do**: + - Do NOT create custom HTTP client class wrapper + - Do NOT add social login providers + - Do NOT store tokens in localStorage (use HTTP-only cookies via NextAuth) + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: Auth.js v5 configuration with OIDC + custom callbacks requires understanding of token flows + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 2 (with Tasks 7, 8, 9, 11, 12) + - **Blocks**: Tasks 18, 21 + - **Blocked By**: Tasks 3 (Keycloak realm), 5 (Next.js scaffold) + + **References**: + + **External References**: + - Auth.js v5 Keycloak: `import KeycloakProvider from "next-auth/providers/keycloak"` + - Auth.js JWT callback: `jwt({ token, account }) → add clubs claim from account.access_token` + - Auth.js session callback: `session({ session, token }) → expose clubs to client` + - Next.js middleware: `export { auth as middleware } from "@/auth"` — or custom matcher + - HTTP-only cookies: Default in Auth.js — tokens never exposed to client JS + + **Acceptance Criteria**: + + **If TDD:** + - [ ] Test file: `frontend/src/hooks/__tests__/useActiveClub.test.ts` + - [ ] Test file: `frontend/src/lib/__tests__/api.test.ts` + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Auth utility includes correct headers + Tool: Bash (bun test) + Preconditions: Frontend tests configured + Steps: + 1. Run `bun run test -- --filter "api fetch"` in frontend/ + 2. Assert: test verifies Authorization header contains Bearer token + 3. Assert: test verifies X-Tenant-Id header contains active club ID + Expected Result: API utility correctly attaches auth and tenant headers + Failure Indicators: Missing headers, wrong header names + Evidence: .sisyphus/evidence/task-10-api-headers.txt + + Scenario: Protected routes redirect to login + Tool: Bash (bun test) + Preconditions: Frontend middleware configured + Steps: + 1. Test middleware: unauthenticated request to /dashboard → redirect to /login + 2. Test middleware: request to /api/auth/* → pass through + Expected Result: Middleware protects routes correctly + Failure Indicators: Protected route accessible without auth + Evidence: .sisyphus/evidence/task-10-middleware.txt + ``` + + **Commit**: YES + - Message: `feat(frontend-auth): add NextAuth.js Keycloak integration` + - Files: `frontend/src/auth/**`, `frontend/src/middleware.ts`, `frontend/src/lib/api.ts`, `frontend/src/hooks/useActiveClub.ts` + - Pre-commit: `bun run build` (in frontend/) + +- [ ] 11. Seed Data Script + + **What to do**: + - Create `SeedDataService` in `WorkClub.Infrastructure/Seed/`: + - Seed 2 clubs: + - Club 1: "Sunrise Tennis Club" (Tennis), tenant_id: "club-1-uuid" + - Club 2: "Valley Cycling Club" (Cycling), tenant_id: "club-2-uuid" + - Seed 5 members (matching Keycloak test users): + - Admin user → Admin in Club 1, Member in Club 2 + - Manager user → Manager in Club 1 + - Member1 user → Member in Club 1, Member in Club 2 + - Member2 user → Member in Club 1 + - Viewer user → Viewer in Club 1 + - Seed sample work items per club: + - Club 1: 5 tasks in various states (Open, Assigned, InProgress, Review, Done) + - Club 2: 3 tasks (Open, Assigned, InProgress) + - Seed sample shifts per club: + - Club 1: 3 shifts (past, today, future) with varying capacity and sign-ups + - Club 2: 2 shifts (today, future) + - Register seed service to run on startup in Development environment only + - Use `app_admin` role connection for seeding (bypasses RLS) + - Make seed idempotent (check if data exists before inserting) + + **Must NOT do**: + - Do NOT seed in Production — guard with `IHostEnvironment.IsDevelopment()` + - Do NOT hard-code GUIDs — generate deterministic GUIDs from names for consistency + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Straightforward data insertion with known entities + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 2 (with Tasks 7, 8, 9, 10, 12) + - **Blocks**: Task 22 + - **Blocked By**: Tasks 2 (Docker PostgreSQL), 3 (Keycloak users), 4 (domain entities) + + **References**: + + **External References**: + - EF Core seeding: `context.Database.EnsureCreated()` or explicit `HasData()` in model config + - Idempotent seeding: `if (!context.Clubs.Any()) { context.Clubs.AddRange(...) }` + - Deterministic GUIDs: `new Guid("00000000-0000-0000-0000-000000000001")` or `Guid.CreateVersion5(namespace, name)` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Seed data populates database + Tool: Bash + Preconditions: Docker Compose up (postgres + keycloak), migrations applied + Steps: + 1. Run backend in Development mode + 2. Query: `docker compose exec postgres psql -U app_admin -d workclub -c "SELECT count(*) FROM clubs"` → assert 2 + 3. Query: `SELECT count(*) FROM members` → assert ≥ 7 (5 users × some in multiple clubs) + 4. Query: `SELECT count(*) FROM work_items` → assert 8 + 5. Query: `SELECT count(*) FROM shifts` → assert 5 + Expected Result: All seed data present + Failure Indicators: Missing data, wrong counts + Evidence: .sisyphus/evidence/task-11-seed-data.txt + + Scenario: Seed is idempotent + Tool: Bash + Preconditions: Seed already applied + Steps: + 1. Run backend again (triggers seed again) + 2. Assert same counts as before (no duplicates) + Expected Result: No duplicate records after re-running seed + Failure Indicators: Doubled counts + Evidence: .sisyphus/evidence/task-11-seed-idempotent.txt + ``` + + **Commit**: YES + - Message: `feat(seed): add development seed data script` + - Files: `backend/src/WorkClub.Infrastructure/Seed/*.cs` + - Pre-commit: `dotnet build` + +- [ ] 12. Backend Test Infrastructure (xUnit + Testcontainers + WebApplicationFactory) + + **What to do**: + - Configure `WorkClub.Tests.Integration` project: + - Create `CustomWebApplicationFactory` extending `WebApplicationFactory`: + - Override `ConfigureWebHost`: replace PostgreSQL connection with Testcontainers + - Spin up PostgreSQL container, apply migrations, configure test services + - Create `TestAuthHandler` for mocking JWT auth in tests: + - Allows tests to set custom claims (clubs, roles) without real Keycloak + - Register as default auth scheme in test factory + - Create base test class `IntegrationTestBase`: + - Provides `HttpClient` with auth headers + - Helper methods: `AuthenticateAs(email, clubs)` → sets JWT claims + - Helper: `SetTenant(tenantId)` → sets X-Tenant-Id header + - Implements `IAsyncLifetime` for test setup/teardown + - Create `DatabaseFixture` (collection fixture): + - Shares single PostgreSQL container across test class + - Resets data between tests (truncate tables, re-seed) + - Configure `WorkClub.Tests.Unit` project: + - Add reference to `WorkClub.Domain` and `WorkClub.Application` + - No database dependency (pure unit tests) + - Verify infrastructure works: + - Write 1 smoke test: GET /health/live → 200 + - Run: `dotnet test backend/tests/WorkClub.Tests.Integration` + + **Must NOT do**: + - Do NOT use in-memory database — MUST use real PostgreSQL for RLS testing + - Do NOT mock EF Core DbContext — use real DbContext with Testcontainers + - Do NOT share mutable state between test classes + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: Test infrastructure setup with Testcontainers + custom WebApplicationFactory requires careful DI configuration + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 2 (with Tasks 7, 8, 9, 10, 11) + - **Blocks**: Task 13 + - **Blocked By**: Task 1 (solution structure) + + **References**: + + **External References**: + - Testcontainers .NET: `new PostgreSqlBuilder().WithImage("postgres:16-alpine").Build()` + - WebApplicationFactory: `builder.ConfigureServices(services => { /* replace DB */ })` + - Test auth handler: `services.AddAuthentication("Test").AddScheme("Test", o => {})` + - `IAsyncLifetime`: `InitializeAsync` / `DisposeAsync` for container lifecycle + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Smoke test passes with Testcontainers + Tool: Bash + Preconditions: Docker running (for Testcontainers) + Steps: + 1. Run `dotnet test backend/tests/WorkClub.Tests.Integration --filter "SmokeTest" --verbosity normal` + 2. Assert exit code 0 + 3. Assert output shows 1 test passed + Expected Result: Health endpoint smoke test passes + Failure Indicators: Testcontainer fails to start, test timeout + Evidence: .sisyphus/evidence/task-12-smoke-test.txt + + Scenario: Test auth handler works + Tool: Bash + Preconditions: Test infrastructure configured + Steps: + 1. Run integration test that: + a. Creates client with TestAuthHandler claims: {"clubs": {"club-1": "admin"}} + b. Sends request with X-Tenant-Id: club-1 + c. Asserts controller can read claims correctly + Expected Result: Custom claims available in controller + Failure Indicators: Claims missing, auth fails + Evidence: .sisyphus/evidence/task-12-test-auth.txt + ``` + + **Commit**: YES + - Message: `test(infra): add xUnit + Testcontainers + WebApplicationFactory base` + - Files: `backend/tests/WorkClub.Tests.Integration/**/*.cs`, `backend/tests/WorkClub.Tests.Unit/**/*.cs` + - Pre-commit: `dotnet test backend/tests/WorkClub.Tests.Integration --filter "SmokeTest"` + +--- + +- [ ] 13. RLS Integration Tests — Multi-Tenant Isolation Proof + + **What to do**: + - Write comprehensive integration tests proving RLS data isolation: + - **Test 1: Complete isolation** — Insert data for tenant-1 and tenant-2. Query as tenant-1 → see only tenant-1 data. Query as tenant-2 → see only tenant-2 data. Zero overlap. + - **Test 2: No context = no data** — Query without `SET LOCAL` → 0 rows returned (RLS blocks everything) + - **Test 3: Insert protection** — Try to INSERT with tenant-2 context but tenant-1 tenant_id value → RLS blocks + - **Test 4: Concurrent requests** — Fire 50 parallel HTTP requests alternating tenant-1 and tenant-2 → each response contains ONLY the correct tenant's data (tests connection pool safety) + - **Test 5: Cross-tenant header spoof** — JWT has clubs: {club-1: admin}, send X-Tenant-Id: club-2 → 403 + - **Test 6: Tenant context in interceptor** — Verify `TenantDbConnectionInterceptor` correctly sets `SET LOCAL` on each request + - All tests use Testcontainers + WebApplicationFactory from Task 12 + - This is the CRITICAL RISK validation — must pass before building API endpoints + + **Must NOT do**: + - Do NOT skip concurrent request test — this validates connection pool safety + - Do NOT use in-memory database + - Do NOT mock the RLS layer + + **Recommended Agent Profile**: + - **Category**: `deep` + - Reason: Security-critical tests that validate the foundation of multi-tenancy. Concurrent test requires careful async handling. + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 3 (with Tasks 14, 15, 16, 17) + - **Blocks**: Tasks 14, 15 (unblocks API development once isolation is proven) + - **Blocked By**: Tasks 7 (schema + RLS), 8 (middleware), 12 (test infra) + + **References**: + + **Pattern References**: + - Task 7: `TenantDbConnectionInterceptor` — the interceptor being tested + - Task 8: `TenantValidationMiddleware` — cross-tenant validation being tested + - Task 12: `CustomWebApplicationFactory` + `IntegrationTestBase` — test infrastructure + + **External References**: + - `Task.WhenAll()` for concurrent request testing + - `Parallel.ForEachAsync()` for parallel HTTP requests + - EF Core concurrency: `DbUpdateConcurrencyException` when RowVersion conflicts + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: All 6 RLS isolation tests pass + Tool: Bash + Preconditions: Testcontainers + test infrastructure from Task 12 + Steps: + 1. Run `dotnet test backend/tests/WorkClub.Tests.Integration --filter "RlsIsolation" --verbosity normal` + 2. Assert 6 tests pass (complete isolation, no context, insert protection, concurrent, spoof, interceptor) + Expected Result: All 6 pass, 0 failures + Failure Indicators: ANY failure means multi-tenancy is BROKEN — stop all downstream work + Evidence: .sisyphus/evidence/task-13-rls-isolation.txt + + Scenario: Concurrent request test proves pool safety + Tool: Bash + Preconditions: Same as above + Steps: + 1. Run concurrent test specifically: `dotnet test --filter "ConcurrentRequests" --verbosity detailed` + 2. Review output: 50 requests, each response verified for correct tenant + 3. Assert 0 cross-contamination events + Expected Result: 50/50 requests return correct tenant data + Failure Indicators: Any request returns wrong tenant's data + Evidence: .sisyphus/evidence/task-13-concurrent-safety.txt + ``` + + **Commit**: YES + - Message: `test(rls): add multi-tenant isolation integration tests` + - Files: `backend/tests/WorkClub.Tests.Integration/MultiTenancy/*.cs` + - Pre-commit: `dotnet test backend/tests/WorkClub.Tests.Integration --filter "RlsIsolation"` + +- [ ] 14. Task CRUD API Endpoints + 5-State Workflow + + **What to do**: + - Create application services in `WorkClub.Application/Tasks/`: + - `TaskService`: CRUD operations + state transitions + - Uses `AppDbContext` directly (no generic repo) + - Validates state transitions using domain entity's `CanTransitionTo()` method + - Enforces role permissions: Create/Assign (Admin/Manager), Transition (assignee + Admin/Manager), Delete (Admin) + - Create minimal API endpoints in `WorkClub.Api/Endpoints/Tasks/`: + - `GET /api/tasks` — list tasks for current tenant (filtered by RLS). Supports `?status=Open&page=1&pageSize=20` + - `GET /api/tasks/{id}` — single task detail + - `POST /api/tasks` — create new task (status: Open). Requires Manager+ role. + - `PATCH /api/tasks/{id}` — update task (title, description, assignee, status). Enforces state machine. + - `DELETE /api/tasks/{id}` — soft-delete or hard-delete. Requires Admin role. + - Handle concurrency: catch `DbUpdateConcurrencyException` → return 409 + - DTOs: `TaskListDto`, `TaskDetailDto`, `CreateTaskRequest`, `UpdateTaskRequest` + - Write tests FIRST (TDD): + - Test: CRUD operations work correctly + - Test: Invalid state transition → 422 + - Test: Concurrency conflict → 409 + - Test: Role enforcement (Viewer can't create) + + **Must NOT do**: + - Do NOT use MediatR or CQRS — direct service injection + - Do NOT create generic CRUD base class + - Do NOT add full-text search + - Do NOT add sub-tasks or task dependencies + + **Recommended Agent Profile**: + - **Category**: `deep` + - Reason: Core business logic with state machine, concurrency handling, and role-based access + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 3 (with Tasks 13, 15, 16, 17) + - **Blocks**: Tasks 19, 22, 23 + - **Blocked By**: Tasks 7 (schema), 8 (multi-tenancy), 9 (auth) + + **References**: + + **Pattern References**: + - Task 4: `WorkItem` entity with `CanTransitionTo()` / `TransitionTo()` state machine + - Task 7: `AppDbContext` with `UseXminAsConcurrencyToken()` + - Task 8: `ITenantProvider.GetTenantId()` for current tenant + - Task 9: Authorization policies (`RequireManager`, `RequireAdmin`) + + **External References**: + - .NET 10 Minimal APIs: `app.MapGet("/api/tasks", handler).RequireAuthorization("RequireMember")` + - `TypedResults.Ok()`, `TypedResults.NotFound()`, `TypedResults.UnprocessableEntity()`, `TypedResults.Conflict()` + - Offset pagination: `Skip((page - 1) * pageSize).Take(pageSize)` + - Concurrency: `catch (DbUpdateConcurrencyException) → TypedResults.Conflict()` + + **Acceptance Criteria**: + + **If TDD:** + - [ ] Test files in `backend/tests/WorkClub.Tests.Integration/Tasks/` + - [ ] `dotnet test --filter "Tasks"` → all pass + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Full task lifecycle via API + Tool: Bash (curl) + Preconditions: Docker Compose up, seed data loaded, token obtained + Steps: + 1. POST /api/tasks with admin token + X-Tenant-Id: club-1 → assert 201, status "Open" + 2. PATCH /api/tasks/{id} with status "Assigned" + assigneeId → assert 200, status "Assigned" + 3. PATCH status "InProgress" → assert 200 + 4. PATCH status "Review" → assert 200 + 5. PATCH status "Done" → assert 200 + 6. GET /api/tasks/{id} → assert status "Done" + Expected Result: Task progresses through all 5 states + Failure Indicators: Any transition rejected, wrong status + Evidence: .sisyphus/evidence/task-14-task-lifecycle.txt + + Scenario: Invalid state transition rejected + Tool: Bash (curl) + Preconditions: Task in "Open" status + Steps: + 1. PATCH /api/tasks/{id} with status "Done" (skipping states) → assert 422 + 2. PATCH /api/tasks/{id} with status "InProgress" (skipping Assigned) → assert 422 + Expected Result: Invalid transitions return 422 Unprocessable Entity + Failure Indicators: Returns 200 (state machine bypassed) + Evidence: .sisyphus/evidence/task-14-invalid-transition.txt + + Scenario: Role enforcement on tasks + Tool: Bash (curl) + Preconditions: Viewer token obtained + Steps: + 1. GET /api/tasks with viewer token → assert 200 (can read) + 2. POST /api/tasks with viewer token → assert 403 (cannot create) + Expected Result: Viewer can read but not create tasks + Failure Indicators: Viewer can create tasks (privilege escalation) + Evidence: .sisyphus/evidence/task-14-role-enforcement.txt + ``` + + **Commit**: YES + - Message: `feat(tasks): add Task CRUD API with 5-state workflow` + - Files: `backend/src/WorkClub.Api/Endpoints/Tasks/*.cs`, `backend/src/WorkClub.Application/Tasks/*.cs` + - Pre-commit: `dotnet test backend/tests/ --filter "Tasks"` + +- [ ] 15. Shift CRUD API + Sign-Up/Cancel Endpoints + + **What to do**: + - Create application services in `WorkClub.Application/Shifts/`: + - `ShiftService`: CRUD + sign-up/cancel logic + - Sign-up: check capacity (count existing sign-ups < shift.Capacity), prevent duplicates, prevent sign-up for past shifts + - Cancel: remove sign-up record, allow only before shift starts + - Uses `AppDbContext` directly + - Handles concurrency for last-slot race: use optimistic concurrency with retry (catch `DbUpdateConcurrencyException`, retry once) + - Create minimal API endpoints in `WorkClub.Api/Endpoints/Shifts/`: + - `GET /api/shifts` — list shifts for current tenant. Supports `?from=date&to=date&page=1&pageSize=20` + - `GET /api/shifts/{id}` — shift detail including sign-up list + - `POST /api/shifts` — create shift. Requires Manager+ role. + - `PUT /api/shifts/{id}` — update shift details. Requires Manager+ role. + - `DELETE /api/shifts/{id}` — delete shift. Requires Admin role. + - `POST /api/shifts/{id}/signup` — member signs up for shift + - `DELETE /api/shifts/{id}/signup` — member cancels their sign-up + - DTOs: `ShiftListDto`, `ShiftDetailDto`, `CreateShiftRequest`, `UpdateShiftRequest` + - Write tests FIRST (TDD): + - Test: Sign-up succeeds when capacity available + - Test: Sign-up rejected when capacity full → 409 + - Test: Sign-up rejected for past shift → 422 + - Test: Cancel succeeds before shift starts + - Test: Duplicate sign-up rejected → 409 + + **Must NOT do**: + - Do NOT add recurring shift patterns + - Do NOT add waitlists or swap requests + - Do NOT add approval workflow for sign-ups (first-come-first-served) + - Do NOT add overlapping shift detection + + **Recommended Agent Profile**: + - **Category**: `deep` + - Reason: Concurrency-sensitive capacity management with race condition handling + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 3 (with Tasks 13, 14, 16, 17) + - **Blocks**: Tasks 20, 22 + - **Blocked By**: Tasks 7 (schema), 8 (multi-tenancy), 9 (auth) + + **References**: + + **Pattern References**: + - Task 4: `Shift` and `ShiftSignup` entities + - Task 7: `AppDbContext` with concurrency tokens + - Task 9: Authorization policies + + **External References**: + - Optimistic concurrency retry: `try { SaveChanges } catch (DbUpdateConcurrencyException) { retry once }` + - Date filtering: `shifts.Where(s => s.StartTime >= from && s.StartTime <= to)` + - `DateTimeOffset.UtcNow` for past-shift check + + **Acceptance Criteria**: + + **If TDD:** + - [ ] Test files in `backend/tests/WorkClub.Tests.Integration/Shifts/` + - [ ] `dotnet test --filter "Shifts"` → all pass + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Sign-up with capacity enforcement + Tool: Bash (curl) + Preconditions: Shift created with capacity=2, 0 sign-ups + Steps: + 1. POST /api/shifts/{id}/signup with member1 token → assert 200 + 2. POST /api/shifts/{id}/signup with member2 token → assert 200 + 3. POST /api/shifts/{id}/signup with admin token → assert 409 (capacity full) + 4. GET /api/shifts/{id} → assert signupCount: 2, capacity: 2 + Expected Result: Third sign-up rejected, capacity enforced + Failure Indicators: Third sign-up succeeds, wrong signup count + Evidence: .sisyphus/evidence/task-15-capacity.txt + + Scenario: Past shift sign-up rejected + Tool: Bash (curl) + Preconditions: Shift with startTime in the past + Steps: + 1. POST /api/shifts/{id}/signup → assert 422 + Expected Result: Cannot sign up for past shifts + Failure Indicators: Sign-up succeeds for past shift + Evidence: .sisyphus/evidence/task-15-past-shift.txt + + Scenario: Cancel sign-up before shift + Tool: Bash (curl) + Preconditions: Member signed up for future shift + Steps: + 1. DELETE /api/shifts/{id}/signup with member token → assert 200 + 2. GET /api/shifts/{id} → assert signupCount decreased by 1 + Expected Result: Sign-up removed, capacity freed + Failure Indicators: Sign-up not removed + Evidence: .sisyphus/evidence/task-15-cancel.txt + ``` + + **Commit**: YES + - Message: `feat(shifts): add Shift CRUD API with sign-up and capacity` + - Files: `backend/src/WorkClub.Api/Endpoints/Shifts/*.cs`, `backend/src/WorkClub.Application/Shifts/*.cs` + - Pre-commit: `dotnet test backend/tests/ --filter "Shifts"` + +--- + +- [ ] 16. Club + Member API Endpoints + + **What to do**: + - Create endpoints in `WorkClub.Api/Endpoints/Clubs/`: + - `GET /api/clubs/me` — list clubs the current user belongs to (from JWT claims + DB) + - `GET /api/clubs/current` — current club details (from X-Tenant-Id context) + - `GET /api/members` — list members of current club. Requires Member+ role. + - `GET /api/members/{id}` — member detail + - `GET /api/members/me` — current user's membership in current club + - Create `MemberSyncService`: + - On first API request from a user, check if their Keycloak `sub` exists in Members table + - If not, create Member record from JWT claims (name, email, role) + - This keeps DB in sync with Keycloak without separate sync process + - Write tests FIRST (TDD): + - Test: `/api/clubs/me` returns only clubs user belongs to + - Test: `/api/members` returns only members of current tenant + - Test: Member auto-sync creates record on first request + + **Must NOT do**: + - Do NOT add member management CRUD (invite, remove) — managed in Keycloak + - Do NOT add club settings or logo upload + - Do NOT add member search or filtering beyond basic list + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: Member sync logic requires understanding Keycloak-DB relationship + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 3 (with Tasks 13, 14, 15, 17) + - **Blocks**: Task 18 + - **Blocked By**: Tasks 7 (schema), 8 (multi-tenancy), 9 (auth) + + **References**: + + **Pattern References**: + - Task 4: `Member` entity + - Task 8: `ITenantProvider` for current tenant + - Task 9: JWT claims parsing for user info + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Club list returns only user's clubs + Tool: Bash (curl) + Preconditions: Admin user (member of club-1 + club-2) + Steps: + 1. GET /api/clubs/me with admin token → assert 200 + 2. Assert response contains exactly 2 clubs + 3. GET /api/clubs/me with manager token → assert 1 club (club-1 only) + Expected Result: Each user sees only their clubs + Failure Indicators: Wrong club count, sees other users' clubs + Evidence: .sisyphus/evidence/task-16-clubs-me.txt + + Scenario: Member auto-sync on first request + Tool: Bash (curl + psql) + Preconditions: New user authenticated but no Member record in DB + Steps: + 1. GET /api/members/me with new user token → assert 200 + 2. Query DB: SELECT * FROM members WHERE external_user_id = '{sub}' → assert 1 row + Expected Result: Member record created automatically + Failure Indicators: 404 or no DB record + Evidence: .sisyphus/evidence/task-16-member-sync.txt + ``` + + **Commit**: YES + - Message: `feat(clubs): add Club and Member API endpoints with auto-sync` + - Files: `backend/src/WorkClub.Api/Endpoints/Clubs/*.cs`, `backend/src/WorkClub.Application/Members/*.cs` + - Pre-commit: `dotnet test backend/tests/ --filter "Clubs|Members"` + +- [ ] 17. Frontend Test Infrastructure (Vitest + RTL + Playwright) + + **What to do**: + - Install and configure Vitest: `bun add -D vitest @testing-library/react @testing-library/jest-dom @vitejs/plugin-react jsdom` + - Create `frontend/vitest.config.ts` with React + jsdom environment + - Install and configure Playwright: `bun add -D @playwright/test && bunx playwright install chromium` + - Create `frontend/playwright.config.ts` with: + - Base URL: `http://localhost:3000` + - Chromium only (faster for development) + - Screenshot on failure + - Create test helpers: + - `frontend/tests/helpers/render.tsx` — custom render with providers (session, tenant context) + - `frontend/tests/helpers/mock-session.ts` — mock NextAuth session for component tests + - Write 1 smoke test each: + - Vitest: render a shadcn Button component, assert it renders + - Playwright: navigate to homepage, assert page loads + - Add scripts to `package.json`: `"test": "vitest run"`, `"test:watch": "vitest"`, `"test:e2e": "playwright test"` + + **Must NOT do**: + - Do NOT install Jest (use Vitest) + - Do NOT install Cypress (use Playwright) + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Standard test tool setup with config files + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 3 (with Tasks 13, 14, 15, 16) + - **Blocks**: Tasks 18, 19, 20, 21 + - **Blocked By**: Task 5 (Next.js scaffold) + + **References**: + + **External References**: + - Vitest + React: `@vitejs/plugin-react` plugin, `jsdom` environment + - RTL custom render: wrap with providers for consistent test setup + - Playwright config: `baseURL`, `use.screenshot: 'only-on-failure'` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Vitest smoke test passes + Tool: Bash + Preconditions: Vitest configured in frontend/ + Steps: + 1. Run `bun run test` in frontend/ + 2. Assert exit code 0, 1 test passed + Expected Result: Vitest runs and passes smoke test + Failure Indicators: Config errors, test failure + Evidence: .sisyphus/evidence/task-17-vitest-smoke.txt + + Scenario: Playwright smoke test passes + Tool: Bash + Preconditions: Playwright + Chromium installed, dev server running + Steps: + 1. Start dev server in background + 2. Run `bunx playwright test tests/e2e/smoke.spec.ts` + 3. Assert exit code 0 + Expected Result: Playwright navigates to app and page loads + Failure Indicators: Browser launch failure, navigation timeout + Evidence: .sisyphus/evidence/task-17-playwright-smoke.txt + ``` + + **Commit**: YES + - Message: `test(frontend): add Vitest + RTL + Playwright setup` + - Files: `frontend/vitest.config.ts`, `frontend/playwright.config.ts`, `frontend/tests/**` + - Pre-commit: `bun run test` (in frontend/) + +--- + +- [ ] 18. App Layout + Club-Switcher + Auth Guard + + **What to do**: + - Create root layout (`frontend/src/app/layout.tsx`): + - SessionProvider wrapper (NextAuth) + - TenantProvider wrapper (active club context) + - Sidebar navigation: Dashboard, Tasks, Shifts, Members + - Top bar: Club-switcher dropdown, user avatar/name, logout button + - Create `ClubSwitcher` component (`frontend/src/components/club-switcher.tsx`): + - Dropdown (shadcn DropdownMenu) showing user's clubs + - On switch: update local storage + cookie, refetch all data (TanStack Query `queryClient.invalidateQueries()`) + - Show current club name + sport type badge + - Create `AuthGuard` component: + - Wraps protected pages + - If not authenticated → redirect to /login + - If authenticated, no active club, 1 club → auto-select + - If authenticated, no active club, multiple clubs → redirect to /select-club + - If authenticated, 0 clubs → show "Contact admin" message + - Install TanStack Query: `bun add @tanstack/react-query` + - Create `QueryProvider` wrapper with `QueryClient` + - Create `TenantContext` (React Context) with `activeClubId`, `setActiveClub()`, `userRole` + - Write tests FIRST (TDD): + - Test: ClubSwitcher renders clubs from session + - Test: ClubSwitcher calls setActiveClub on selection + - Test: AuthGuard redirects when no session + + **Must NOT do**: + - Do NOT add settings pages + - Do NOT add theme customization per club + - Do NOT create custom component wrappers over shadcn/ui + + **Recommended Agent Profile**: + - **Category**: `visual-engineering` + - Reason: Layout design, responsive sidebar, dropdown component — frontend UI work + - **Skills**: [`frontend-ui-ux`] + - `frontend-ui-ux`: Crafts clean UI layout even without mockups + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 4 (with Tasks 19, 20, 21) + - **Blocks**: Tasks 19, 20, 22 + - **Blocked By**: Tasks 10 (NextAuth), 16 (Club API), 17 (test infra) + + **References**: + + **Pattern References**: + - Task 10: NextAuth session with clubs claim + - Task 16: `GET /api/clubs/me` endpoint for club list + + **External References**: + - shadcn/ui DropdownMenu: `` pattern + - TanStack Query: `useQuery({ queryKey: ['clubs'], queryFn: fetchClubs })` + - React Context: `createContext()` + - Next.js App Router layout: shared across all pages in directory + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Club switcher renders and switches + Tool: Bash (bun test — Vitest + RTL) + Preconditions: Mock session with 2 clubs + Steps: + 1. Render ClubSwitcher with mock session containing clubs: [{name: "Tennis"}, {name: "Cycling"}] + 2. Assert both club names visible in dropdown + 3. Click "Cycling" → assert setActiveClub called with cycling club ID + Expected Result: Switcher renders clubs and handles selection + Failure Indicators: Clubs not rendered, click handler not called + Evidence: .sisyphus/evidence/task-18-club-switcher.txt + + Scenario: Layout renders with navigation + Tool: Playwright + Preconditions: Frontend running with mock auth + Steps: + 1. Navigate to /dashboard + 2. Assert sidebar contains links: "Tasks", "Shifts", "Members" + 3. Assert top bar shows club name and user name + 4. Take screenshot + Expected Result: Full layout visible with navigation + Failure Indicators: Missing sidebar, broken layout + Evidence: .sisyphus/evidence/task-18-layout.png + ``` + + **Commit**: YES (groups with Tasks 19, 20, 21) + - Message: `feat(ui): add layout, club-switcher, login, task and shift pages` + - Files: `frontend/src/app/layout.tsx`, `frontend/src/components/club-switcher.tsx`, `frontend/src/components/auth-guard.tsx` + - Pre-commit: `bun run build && bun run test` (in frontend/) + +- [ ] 19. Task List + Task Detail + Status Transitions UI + + **What to do**: + - Create `/frontend/src/app/(protected)/tasks/page.tsx`: + - Task list view using shadcn Table component + - Columns: Title, Status (Badge with color per status), Assignee, Due Date, Actions + - Filter by status (DropdownMenu with status options) + - Pagination (offset-based) + - "New Task" button (visible for Manager+ role) + - Create `/frontend/src/app/(protected)/tasks/[id]/page.tsx`: + - Task detail view + - Status transition buttons (only valid next states shown) + - Assign member dropdown (for Manager+ role) + - Edit title/description (for Manager+ or assignee) + - Create `/frontend/src/app/(protected)/tasks/new/page.tsx`: + - New task form: title, description, due date (optional) + - Form validation with shadcn form components + - Use TanStack Query hooks: + - `useTasks(filters)`, `useTask(id)`, `useCreateTask()`, `useUpdateTask()`, `useTransitionTask()` + - Write tests FIRST (TDD): + - Test: Task list renders with mock data + - Test: Status badge shows correct color per status + - Test: Only valid transition buttons are shown + + **Must NOT do**: + - Do NOT add drag-and-drop Kanban board + - Do NOT add inline editing + - Do NOT add bulk actions + + **Recommended Agent Profile**: + - **Category**: `visual-engineering` + - Reason: Data table, form design, interactive status transitions + - **Skills**: [`frontend-ui-ux`] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 4 (with Tasks 18, 20, 21) + - **Blocks**: Task 27 + - **Blocked By**: Tasks 14 (Task API), 17 (test infra), 18 (layout) + + **References**: + + **Pattern References**: + - Task 14: Task API endpoints (GET /api/tasks, PATCH /api/tasks/{id}) + - Task 18: Layout with TenantContext for API headers + - Task 4: WorkItemStatus enum values and valid transitions + + **External References**: + - shadcn Table: `` with mapped rows + - shadcn Badge: `Open` with color variants + - TanStack Query mutations: `useMutation({ mutationFn: updateTask, onSuccess: invalidate })` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Task list renders with data + Tool: Bash (bun test) + Preconditions: Mock API response with 5 tasks + Steps: + 1. Render TaskListPage with mocked TanStack Query + 2. Assert 5 table rows rendered + 3. Assert each row has title, status badge, assignee + Expected Result: All tasks displayed in table + Failure Indicators: Missing rows, wrong data + Evidence: .sisyphus/evidence/task-19-task-list.txt + + Scenario: Status transition buttons shown correctly + Tool: Bash (bun test) + Preconditions: Task with status "InProgress" + Steps: + 1. Render TaskDetailPage with task in "InProgress" status + 2. Assert "Move to Review" button is visible + 3. Assert "Mark as Done" button is NOT visible (invalid transition) + Expected Result: Only valid transitions shown + Failure Indicators: Invalid transitions displayed + Evidence: .sisyphus/evidence/task-19-transitions.txt + ``` + + **Commit**: YES (groups with Tasks 18, 20, 21) + - Message: (grouped in Task 18 commit) + - Files: `frontend/src/app/(protected)/tasks/**/*.tsx`, `frontend/src/hooks/useTasks.ts` + - Pre-commit: `bun run build && bun run test` + +- [ ] 20. Shift List + Shift Detail + Sign-Up UI + + **What to do**: + - Create `/frontend/src/app/(protected)/shifts/page.tsx`: + - Shift list view using shadcn Card components (not table — more visual for schedules) + - Each card: Title, Date/Time, Location, Capacity bar (X/Y signed up), Sign-up button + - Filter by date range (DatePicker) + - "New Shift" button (visible for Manager+ role) + - Create `/frontend/src/app/(protected)/shifts/[id]/page.tsx`: + - Shift detail: full info + list of signed-up members + - "Sign Up" button (if capacity available and shift is future) + - "Cancel Sign-up" button (if user is signed up) + - Visual capacity indicator (progress bar) + - Create `/frontend/src/app/(protected)/shifts/new/page.tsx`: + - New shift form: title, description, location, start time, end time, capacity + - TanStack Query hooks: `useShifts(dateRange)`, `useShift(id)`, `useSignUp()`, `useCancelSignUp()` + - Write tests FIRST (TDD): + - Test: Shift card shows capacity correctly (2/3) + - Test: Sign-up button disabled when full + - Test: Past shift shows "Past" label, no sign-up button + + **Must NOT do**: + - Do NOT add calendar view (list/card view only for MVP) + - Do NOT add recurring shift creation + - Do NOT add shift swap functionality + + **Recommended Agent Profile**: + - **Category**: `visual-engineering` + - Reason: Card-based UI, capacity visualization, date/time components + - **Skills**: [`frontend-ui-ux`] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 4 (with Tasks 18, 19, 21) + - **Blocks**: Task 28 + - **Blocked By**: Tasks 15 (Shift API), 17 (test infra), 18 (layout) + + **References**: + + **Pattern References**: + - Task 15: Shift API endpoints + - Task 18: Layout with TenantContext + - Task 4: Shift entity fields + + **External References**: + - shadcn Card: `` for shift cards + - Progress component: shadcn Progress for capacity bar + - Date picker: shadcn Calendar + Popover for date range filter + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Shift card shows capacity and sign-up state + Tool: Bash (bun test) + Preconditions: Mock shift with capacity 3, 2 signed up + Steps: + 1. Render ShiftCard with mock data + 2. Assert "2/3 spots filled" text visible + 3. Assert "Sign Up" button is enabled (1 spot left) + 4. Re-render with capacity 3, 3 signed up + 5. Assert "Sign Up" button is disabled + Expected Result: Capacity displayed correctly, button state matches availability + Failure Indicators: Wrong count, button enabled when full + Evidence: .sisyphus/evidence/task-20-capacity-display.txt + + Scenario: Past shift cannot be signed up for + Tool: Bash (bun test) + Preconditions: Shift with startTime in the past + Steps: + 1. Render ShiftCard with past shift + 2. Assert "Past" label visible + 3. Assert "Sign Up" button not rendered + Expected Result: Past shifts clearly marked, no sign-up option + Failure Indicators: Sign-up button on past shift + Evidence: .sisyphus/evidence/task-20-past-shift.txt + ``` + + **Commit**: YES (groups with Tasks 18, 19, 21) + - Message: (grouped in Task 18 commit) + - Files: `frontend/src/app/(protected)/shifts/**/*.tsx`, `frontend/src/hooks/useShifts.ts` + - Pre-commit: `bun run build && bun run test` + +- [ ] 21. Login Page + First-Login Club Picker + + **What to do**: + - Create `/frontend/src/app/login/page.tsx`: + - Clean login page with "Sign in with Keycloak" button + - Uses NextAuth `signIn("keycloak")` function + - Shows app name/logo placeholder + - Create `/frontend/src/app/select-club/page.tsx`: + - Club selection page for multi-club users + - Shows cards for each club with name and sport type + - Clicking a club → sets active club → redirects to /dashboard + - Only shown when user has 2+ clubs and no active club + - Create `/frontend/src/app/(protected)/dashboard/page.tsx`: + - Simple dashboard showing: + - Active club name + - My open tasks count + - My upcoming shifts count + - Quick links to Tasks and Shifts pages + - Write tests FIRST (TDD): + - Test: Login page renders sign-in button + - Test: Club picker shows correct number of clubs + - Test: Dashboard shows summary counts + + **Must NOT do**: + - Do NOT add custom login form (use Keycloak hosted login) + - Do NOT add registration page + - Do NOT add charts or analytics on dashboard + + **Recommended Agent Profile**: + - **Category**: `visual-engineering` + - Reason: Login page design, club selection cards, dashboard layout + - **Skills**: [`frontend-ui-ux`] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 4 (with Tasks 18, 19, 20) + - **Blocks**: Task 26 + - **Blocked By**: Tasks 10 (NextAuth), 17 (test infra) + + **References**: + + **Pattern References**: + - Task 10: `signIn("keycloak")` and session with clubs claim + - Task 18: AuthGuard redirects to /select-club or /login + + **External References**: + - NextAuth signIn: `import { signIn } from "next-auth/react"` → `signIn("keycloak")` + - shadcn Card: for club selection cards + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Login page renders + Tool: Bash (bun test) + Steps: + 1. Render LoginPage + 2. Assert "Sign in" button visible + Expected Result: Login page renders with sign-in button + Failure Indicators: Missing button, render error + Evidence: .sisyphus/evidence/task-21-login-page.txt + + Scenario: Club picker for multi-club user + Tool: Bash (bun test) + Preconditions: Mock session with 2 clubs, no active club + Steps: + 1. Render SelectClubPage with mock session + 2. Assert 2 club cards rendered + 3. Click first card → assert redirect to /dashboard + Expected Result: Club picker shows clubs and handles selection + Failure Indicators: Wrong club count, no redirect + Evidence: .sisyphus/evidence/task-21-club-picker.txt + ``` + + **Commit**: YES (groups with Tasks 18, 19, 20) + - Message: (grouped in Task 18 commit) + - Files: `frontend/src/app/login/page.tsx`, `frontend/src/app/select-club/page.tsx`, `frontend/src/app/(protected)/dashboard/page.tsx` + - Pre-commit: `bun run build && bun run test` + +--- + +- [ ] 22. Docker Compose Full Stack (Backend + Frontend + Hot Reload) + + **What to do**: + - Update `/docker-compose.yml` to add: + - `dotnet-api` service: build from `backend/Dockerfile.dev`, port 5000→8080, volume mount `/backend:/app` (hot reload via `dotnet watch`), depends on postgres + keycloak + - `nextjs` service: build from `frontend/Dockerfile.dev`, port 3000, volume mount `/frontend:/app` (hot reload via `bun run dev`), depends on dotnet-api + - Configure environment variables: + - Backend: `ConnectionStrings__DefaultConnection`, `Keycloak__Issuer`, `ASPNETCORE_ENVIRONMENT=Development` + - Frontend: `NEXT_PUBLIC_API_URL=http://localhost:5000`, `API_INTERNAL_URL=http://dotnet-api:8080`, `KEYCLOAK_ISSUER` + - Ensure service startup order: postgres → keycloak → dotnet-api → nextjs + - Add `wait-for-it` or health-check-based depends_on conditions + - Backend runs migrations + seed on startup in Development mode + - Verify: `docker compose up` → all 4 services healthy → frontend accessible at localhost:3000 → can authenticate via Keycloak + + **Must NOT do**: + - Do NOT use production Dockerfiles for local dev (use Dockerfile.dev with hot reload) + - Do NOT hardcode production secrets + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: Multi-service Docker Compose orchestration with health checks and dependency ordering + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 5 (with Tasks 23, 24, 25) + - **Blocks**: Tasks 26, 27, 28 + - **Blocked By**: Tasks 14 (API), 15 (Shifts API), 18 (Frontend layout) + + **References**: + + **Pattern References**: + - Task 2: Docker Compose base (postgres + keycloak) + - Task 11: Seed data service (runs on Development startup) + + **External References**: + - `dotnet watch run`: Hot reload in Docker with volume mount + - Docker Compose `depends_on` with `condition: service_healthy` + - Volume mount caching: `:cached` on macOS for performance + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Full stack starts from clean state + Tool: Bash + Preconditions: Docker installed, no conflicting ports + Steps: + 1. Run `docker compose down -v` (clean slate) + 2. Run `docker compose up -d` + 3. Wait up to 180s for all services healthy: `docker compose ps` + 4. Assert 4 services running: postgres, keycloak, dotnet-api, nextjs + 5. curl http://localhost:5000/health/live → assert 200 + 6. curl http://localhost:3000 → assert 200 + 7. curl Keycloak OIDC discovery → assert 200 + Expected Result: All 4 services healthy and responding + Failure Indicators: Service fails to start, health check fails + Evidence: .sisyphus/evidence/task-22-full-stack.txt + + Scenario: Authentication works end-to-end + Tool: Bash (curl) + Preconditions: Full stack running + Steps: + 1. Get token from Keycloak for admin@test.com + 2. Call GET /api/tasks with token + X-Tenant-Id → assert 200 + 3. Assert response contains seed data tasks + Expected Result: Auth + API + data all connected + Failure Indicators: Auth fails, API returns 401/403, no data + Evidence: .sisyphus/evidence/task-22-e2e-auth.txt + ``` + + **Commit**: YES (groups with Tasks 23, 24, 25) + - Message: `infra(deploy): add full Docker Compose stack, Dockerfiles, and Kustomize dev overlay` + - Files: `docker-compose.yml` + - Pre-commit: `docker compose config` + +- [ ] 23. Backend Dockerfiles (Dev + Prod Multi-Stage) + + **What to do**: + - Create `/backend/Dockerfile.dev`: + - Base: `mcr.microsoft.com/dotnet/sdk:10.0` + - Install dotnet-ef tool + - WORKDIR /app, copy csproj + restore, copy source + - ENTRYPOINT: `dotnet watch run --project src/WorkClub.Api/WorkClub.Api.csproj` + - Create `/backend/Dockerfile`: + - Multi-stage build: + - Stage 1 (build): `sdk:10.0`, restore + build + publish + - Stage 2 (runtime): `aspnet:10.0-alpine`, copy published output, non-root user + - HEALTHCHECK: `curl -sf http://localhost:8080/health/live || exit 1` + - Final image ~110MB + + **Must NOT do**: + - Do NOT use full SDK image for production + - Do NOT run as root in production image + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Standard .NET Docker patterns + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 5 (with Tasks 22, 24, 25) + - **Blocks**: Task 25 + - **Blocked By**: Task 14 (working API to build) + + **References**: + + **External References**: + - .NET 10 Docker images: `mcr.microsoft.com/dotnet/aspnet:10.0-alpine` (runtime), `sdk:10.0` (build) + - Multi-stage: restore in separate layer for caching + - Non-root: `USER app` (built into .NET Docker images) + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Production image builds and runs + Tool: Bash + Steps: + 1. Run `docker build -t workclub-api:test backend/` + 2. Assert build succeeds + 3. Run `docker run --rm -d -p 18080:8080 --name test-api workclub-api:test` + 4. Wait 10s, curl http://localhost:18080/health/live + 5. Assert response (may fail without DB — that's OK, just verify container starts) + 6. Check image size: `docker image inspect workclub-api:test --format='{{.Size}}'` + 7. Assert < 200MB + 8. Cleanup: `docker stop test-api` + Expected Result: Image builds, starts, is <200MB + Failure Indicators: Build fails, image too large + Evidence: .sisyphus/evidence/task-23-backend-docker.txt + ``` + + **Commit**: YES (groups with Tasks 22, 24, 25) + - Message: (grouped in Task 22 commit) + - Files: `backend/Dockerfile`, `backend/Dockerfile.dev` + - Pre-commit: `docker build -t test backend/` + +- [ ] 24. Frontend Dockerfiles (Dev + Prod Standalone) + + **What to do**: + - Create `/frontend/Dockerfile.dev`: + - Base: `node:22-alpine` + - Install bun: `npm install -g bun` + - Copy package.json + bun.lock, install deps + - CMD: `bun run dev` + - Create `/frontend/Dockerfile`: + - Multi-stage build (3 stages): + - Stage 1 (deps): `node:22-alpine`, install bun, `bun install --frozen-lockfile` + - Stage 2 (build): copy deps + source, `bun run build` + - Stage 3 (runner): `node:22-alpine`, copy `.next/standalone` + `.next/static` + `public`, non-root user + - CMD: `node server.js` + - HEALTHCHECK: `curl -sf http://localhost:3000/api/health || exit 1` + - Final image ~180MB + + **Must NOT do**: + - Do NOT use Bun as production runtime (latency issues) — use Node.js + - Do NOT include dev dependencies in production image + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: Standard Next.js Docker patterns + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 5 (with Tasks 22, 23, 25) + - **Blocks**: Task 25 + - **Blocked By**: Task 18 (working frontend) + + **References**: + + **External References**: + - Next.js standalone Docker: copy `.next/standalone`, `.next/static`, `public` + - `node server.js` as entry point (standalone output) + - Non-root user: `adduser --system --uid 1001 nextjs` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Production image builds and starts + Tool: Bash + Steps: + 1. Run `docker build -t workclub-frontend:test frontend/` + 2. Assert build succeeds + 3. Run `docker run --rm -d -p 13000:3000 --name test-frontend workclub-frontend:test` + 4. Wait 10s, curl http://localhost:13000 + 5. Assert HTTP 200 + 6. Check image size < 250MB + 7. Cleanup: `docker stop test-frontend` + Expected Result: Frontend image builds, starts, serves pages + Failure Indicators: Build fails, no response + Evidence: .sisyphus/evidence/task-24-frontend-docker.txt + ``` + + **Commit**: YES (groups with Tasks 22, 23, 25) + - Message: (grouped in Task 22 commit) + - Files: `frontend/Dockerfile`, `frontend/Dockerfile.dev` + - Pre-commit: `docker build -t test frontend/` + +- [ ] 25. Kustomize Dev Overlay + Resource Limits + Health Checks + + **What to do**: + - Create `/infra/k8s/overlays/dev/kustomization.yaml`: + - Reference `../../base` + - Override replicas: 1 for all deployments + - Override resource limits: lower CPU/memory for dev + - Add dev-specific ConfigMap values (Development env, debug logging) + - Add dev-specific image tags + - Create `/infra/k8s/overlays/dev/patches/`: + - `backend-resources.yaml`: Lower resource requests/limits for dev + - `frontend-resources.yaml`: Lower resources + - Update base manifests if needed: + - Ensure health check endpoints match actual implementations + - Backend: `/health/startup`, `/health/live`, `/health/ready` (from Task 9) + - Frontend: `/api/health` (from Task 5 or Task 18) + - Verify: `kustomize build infra/k8s/overlays/dev` produces valid YAML with dev overrides + + **Must NOT do**: + - Do NOT add HPA or PDB (not needed for dev) + - Do NOT add production secrets + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: Kustomize overlay configuration with patches + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 5 (with Tasks 22, 23, 24) + - **Blocks**: None + - **Blocked By**: Tasks 6 (base manifests), 23 (backend Dockerfile), 24 (frontend Dockerfile) + + **References**: + + **Pattern References**: + - Task 6: Kustomize base manifests + - Task 9: Health check endpoints + + **External References**: + - Kustomize overlays: `resources: [../../base]` + `patches:` list + - `replicas:` directive for scaling + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Dev overlay builds with correct overrides + Tool: Bash + Steps: + 1. Run `kustomize build infra/k8s/overlays/dev` + 2. Assert exit code 0 + 3. Verify replicas are 1 for all deployments + 4. Verify resource limits are lower than base + Expected Result: Valid YAML with dev-specific overrides + Failure Indicators: Build fails, wrong values + Evidence: .sisyphus/evidence/task-25-kustomize-dev.txt + ``` + + **Commit**: YES (groups with Tasks 22, 23, 24) + - Message: (grouped in Task 22 commit) + - Files: `infra/k8s/overlays/dev/**/*.yaml` + - Pre-commit: `kustomize build infra/k8s/overlays/dev` + +--- + +- [ ] 26. Playwright E2E Tests — Auth Flow + Club Switching + + **What to do**: + - Create `frontend/tests/e2e/auth.spec.ts`: + - Test: Navigate to protected page → redirected to login + - Test: Click "Sign in" → redirected to Keycloak login → enter credentials → redirected back with session + - Test: After login, club picker shown (if multi-club user) + - Test: Select club → redirected to dashboard → club name visible in header + - Test: Switch club via dropdown → data refreshes → new club name visible + - Test: Logout → redirected to login page → protected page no longer accessible + - Configure Playwright to work with Docker Compose stack: + - `webServer` config points to Docker Compose `nextjs` service + - Use `globalSetup` to ensure Docker Compose is running + - Save screenshots and trace on failure + + **Must NOT do**: + - Do NOT test Keycloak admin console + - Do NOT test direct API calls (covered in backend tests) + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: E2E browser automation with Keycloak OIDC redirect flow + - **Skills**: [`playwright`] + - `playwright`: Browser automation for E2E testing + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 6 (with Tasks 27, 28) + - **Blocks**: None + - **Blocked By**: Tasks 21 (login page), 22 (Docker Compose full stack) + + **References**: + + **Pattern References**: + - Task 21: Login page with Keycloak sign-in + - Task 18: Club-switcher component + - Task 3: Test user credentials (admin@test.com / testpass123) + + **External References**: + - Playwright Keycloak login: `page.goto('/dashboard')` → assert redirect to Keycloak → `page.fill('#username')` → `page.fill('#password')` → `page.click('#kc-login')` + - Playwright screenshot: `await page.screenshot({ path: 'evidence/...' })` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Full auth flow E2E + Tool: Playwright + Preconditions: Docker Compose full stack running + Steps: + 1. Navigate to http://localhost:3000/dashboard + 2. Assert redirected to /login page + 3. Click "Sign in" button + 4. Assert redirected to Keycloak login (http://localhost:8080/realms/workclub/...) + 5. Fill username: "admin@test.com", password: "testpass123" + 6. Click Login + 7. Assert redirected back to /select-club (multi-club user) + 8. Click first club card ("Sunrise Tennis Club") + 9. Assert URL is /dashboard + 10. Assert text "Sunrise Tennis Club" visible in header + 11. Screenshot + Expected Result: Complete login + club selection flow works + Failure Indicators: Redirect loop, Keycloak errors, stuck on club picker + Evidence: .sisyphus/evidence/task-26-auth-flow.png + + Scenario: Club switching refreshes data + Tool: Playwright + Preconditions: Logged in, club-1 active + Steps: + 1. Navigate to /tasks → assert tasks visible (club-1 data) + 2. Open club switcher dropdown + 3. Click "Valley Cycling Club" + 4. Assert tasks list updates (different data) + 5. Assert header shows "Valley Cycling Club" + Expected Result: Switching clubs changes visible data + Failure Indicators: Data doesn't refresh, old club's data shown + Evidence: .sisyphus/evidence/task-26-club-switch.png + ``` + + **Commit**: YES (groups with Tasks 27, 28) + - Message: `test(e2e): add Playwright E2E tests for auth, tasks, and shifts` + - Files: `frontend/tests/e2e/auth.spec.ts` + - Pre-commit: `bunx playwright test tests/e2e/auth.spec.ts` + +- [ ] 27. Playwright E2E Tests — Task Management Flow + + **What to do**: + - Create `frontend/tests/e2e/tasks.spec.ts`: + - Test: Create new task → appears in list + - Test: View task detail → all fields displayed + - Test: Transition task through all states (Open → Assigned → InProgress → Review → Done) + - Test: Viewer role cannot see "New Task" button + - Test: Task list filters by status + - Use authenticated session from Task 26 setup + + **Must NOT do**: + - Do NOT test API directly (use UI interactions only) + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: Complex E2E flow with multiple pages and state transitions + - **Skills**: [`playwright`] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 6 (with Tasks 26, 28) + - **Blocks**: None + - **Blocked By**: Tasks 19 (task UI), 22 (Docker Compose) + + **References**: + + **Pattern References**: + - Task 19: Task list page, task detail page, task creation form + - Task 14: Task API behavior (valid/invalid transitions) + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Full task lifecycle via UI + Tool: Playwright + Preconditions: Logged in as admin, club-1 active + Steps: + 1. Navigate to /tasks + 2. Click "New Task" button + 3. Fill title: "Replace court net", description: "Net on court 3 is torn" + 4. Click Submit → assert redirected to task detail + 5. Assert status badge shows "Open" + 6. Click "Assign" → select member → assert status "Assigned" + 7. Click "Start" → assert status "In Progress" + 8. Click "Submit for Review" → assert status "Review" + 9. Click "Approve" → assert status "Done" + 10. Screenshot final state + Expected Result: Task flows through all 5 states via UI + Failure Indicators: Transition fails, wrong status shown + Evidence: .sisyphus/evidence/task-27-task-lifecycle.png + + Scenario: Viewer cannot create tasks + Tool: Playwright + Preconditions: Logged in as viewer@test.com + Steps: + 1. Navigate to /tasks + 2. Assert "New Task" button is NOT visible + Expected Result: Viewer sees task list but no create button + Failure Indicators: Create button visible for viewer + Evidence: .sisyphus/evidence/task-27-viewer-no-create.png + ``` + + **Commit**: YES (groups with Tasks 26, 28) + - Message: (grouped in Task 26 commit) + - Files: `frontend/tests/e2e/tasks.spec.ts` + - Pre-commit: `bunx playwright test tests/e2e/tasks.spec.ts` + +- [ ] 28. Playwright E2E Tests — Shift Sign-Up Flow + + **What to do**: + - Create `frontend/tests/e2e/shifts.spec.ts`: + - Test: Create new shift → appears in list + - Test: View shift detail → capacity bar shows 0/N + - Test: Sign up for shift → capacity updates, user listed + - Test: Cancel sign-up → capacity decreases + - Test: Full capacity → sign-up button disabled + - Test: Past shift → no sign-up button + - Use authenticated session from Task 26 setup + + **Must NOT do**: + - Do NOT test concurrent sign-ups via UI (covered in backend integration tests) + + **Recommended Agent Profile**: + - **Category**: `unspecified-high` + - Reason: E2E flow with capacity state tracking + - **Skills**: [`playwright`] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 6 (with Tasks 26, 27) + - **Blocks**: None + - **Blocked By**: Tasks 20 (shift UI), 22 (Docker Compose) + + **References**: + + **Pattern References**: + - Task 20: Shift list page, shift detail page, sign-up button + - Task 15: Shift API behavior (capacity, past shift rejection) + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Sign up and cancel for shift + Tool: Playwright + Preconditions: Logged in as member1, future shift with capacity 3, 0 signed up + Steps: + 1. Navigate to /shifts + 2. Click on future shift card + 3. Assert "0/3 spots filled" + 4. Click "Sign Up" → assert "1/3 spots filled" + 5. Assert user name appears in sign-up list + 6. Click "Cancel Sign-up" → assert "0/3 spots filled" + 7. Screenshot + Expected Result: Sign-up and cancel update capacity correctly + Failure Indicators: Count doesn't update, name not shown + Evidence: .sisyphus/evidence/task-28-shift-signup.png + + Scenario: Full capacity disables sign-up + Tool: Playwright + Preconditions: Shift with capacity 1, 1 already signed up + Steps: + 1. Navigate to shift detail for full shift + 2. Assert "1/1 spots filled" + 3. Assert "Sign Up" button is disabled or not present + Expected Result: Cannot sign up for full shift + Failure Indicators: Sign-up button still active + Evidence: .sisyphus/evidence/task-28-full-capacity.png + ``` + + **Commit**: YES (groups with Tasks 26, 27) + - Message: (grouped in Task 26 commit) + - Files: `frontend/tests/e2e/shifts.spec.ts` + - Pre-commit: `bunx playwright test tests/e2e/shifts.spec.ts` + +--- + +## Final Verification Wave + +> 4 review agents run in PARALLEL. ALL must APPROVE. Rejection → fix → re-run. + +- [ ] F1. **Plan Compliance Audit** — `oracle` + Read the plan end-to-end. For each "Must Have": verify implementation exists (read file, curl endpoint, run command). For each "Must NOT Have": search codebase for forbidden patterns (`MediatR`, `IRepository`, `Swashbuckle`, `IsMultiTenant()`, `SET app.current_tenant` without `LOCAL`) — reject with file:line if found. Check evidence files exist in `.sisyphus/evidence/`. Compare deliverables against plan. + Output: `Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT: APPROVE/REJECT` + +- [ ] F2. **Code Quality Review** — `unspecified-high` + Run `dotnet build` + `dotnet format --verify-no-changes` + `dotnet test` + `bun run build` + `bun run lint`. Review all changed files for: `as any`/`@ts-ignore`, empty catches, `console.log` in prod, commented-out code, unused imports, `// TODO` without ticket. Check AI slop: excessive comments, over-abstraction, generic names (data/result/item/temp), unnecessary null checks on non-nullable types. + Output: `Build [PASS/FAIL] | Format [PASS/FAIL] | Tests [N pass/N fail] | Lint [PASS/FAIL] | Files [N clean/N issues] | VERDICT` + +- [ ] F3. **Real Manual QA** — `unspecified-high` (+ `playwright` skill) + Start `docker compose up` from clean state. Execute EVERY QA scenario from EVERY task — follow exact steps, capture evidence. Test cross-task integration: login → pick club → create task → assign → transition through states → switch club → verify isolation → create shift → sign up → verify capacity. Test edge cases: invalid JWT, expired token, cross-tenant header spoof, concurrent sign-up. Save to `.sisyphus/evidence/final-qa/`. + Output: `Scenarios [N/N pass] | Integration [N/N] | Edge Cases [N tested] | VERDICT` + +- [ ] F4. **Scope Fidelity Check** — `deep` + For each task: read "What to do", read actual diff (`git log`/`git diff`). Verify 1:1 — everything in spec was built (no missing), nothing beyond spec was built (no creep). Check "Must NOT do" compliance across ALL tasks. Detect cross-task contamination: Task N touching Task M's files. Flag unaccounted changes. Verify no CQRS, no MediatR, no generic repo, no Swashbuckle, no social login, no recurring shifts, no notifications. + Output: `Tasks [N/N compliant] | Contamination [CLEAN/N issues] | Unaccounted [CLEAN/N files] | VERDICT` + +--- + +## Commit Strategy + +| Wave | Commit | Message | Files | Pre-commit | +|------|--------|---------|-------|------------| +| 1 | T1 | `chore(scaffold): initialize git repo and monorepo with .NET solution` | backend/**/*.csproj, backend/WorkClub.sln, .gitignore, .editorconfig | `dotnet build` | +| 1 | T2 | `infra(docker): add Docker Compose with PostgreSQL and Keycloak` | docker-compose.yml, backend/Dockerfile.dev | `docker compose config` | +| 1 | T3 | `infra(keycloak): configure realm with test users and club memberships` | infra/keycloak/realm-export.json | — | +| 1 | T4 | `feat(domain): add core entities — Club, Member, Task, Shift` | backend/src/WorkClub.Domain/**/*.cs | `dotnet build` | +| 1 | T5 | `chore(frontend): initialize Next.js project with Tailwind and shadcn/ui` | frontend/**, package.json, next.config.ts, tailwind.config.ts | `bun run build` | +| 1 | T6 | `infra(k8s): add Kustomize base manifests` | infra/k8s/base/**/*.yaml | `kustomize build infra/k8s/base` | +| 2 | T7+T8 | `feat(data): add EF Core DbContext, migrations, RLS policies, and multi-tenant middleware` | backend/src/WorkClub.Infrastructure/**/*.cs, backend/src/WorkClub.Api/Middleware/*.cs | `dotnet build` | +| 2 | T9 | `feat(auth): add Keycloak JWT authentication and role-based authorization` | backend/src/WorkClub.Api/Auth/*.cs, Program.cs | `dotnet build` | +| 2 | T10 | `feat(frontend-auth): add NextAuth.js Keycloak integration` | frontend/src/auth/**, frontend/src/middleware.ts | `bun run build` | +| 2 | T11 | `feat(seed): add development seed data script` | backend/src/WorkClub.Infrastructure/Seed/*.cs | `dotnet build` | +| 2 | T12 | `test(infra): add xUnit + Testcontainers + WebApplicationFactory base` | backend/tests/**/*.cs | `dotnet test` | +| 3 | T13 | `test(rls): add multi-tenant isolation integration tests` | backend/tests/WorkClub.Tests.Integration/MultiTenancy/*.cs | `dotnet test` | +| 3 | T14 | `feat(tasks): add Task CRUD API with 5-state workflow` | backend/src/WorkClub.Api/Endpoints/Tasks/*.cs, backend/src/WorkClub.Application/Tasks/*.cs | `dotnet test` | +| 3 | T15 | `feat(shifts): add Shift CRUD API with sign-up and capacity` | backend/src/WorkClub.Api/Endpoints/Shifts/*.cs, backend/src/WorkClub.Application/Shifts/*.cs | `dotnet test` | +| 3 | T16 | `feat(clubs): add Club and Member API endpoints` | backend/src/WorkClub.Api/Endpoints/Clubs/*.cs | `dotnet test` | +| 3 | T17 | `test(frontend): add Vitest + RTL + Playwright setup` | frontend/vitest.config.ts, frontend/playwright.config.ts | `bun run test` | +| 4 | T18-T21 | `feat(ui): add layout, club-switcher, login, task and shift pages` | frontend/src/app/**/*.tsx, frontend/src/components/**/*.tsx | `bun run build && bun run test` | +| 5 | T22-T25 | `infra(deploy): add full Docker Compose stack, Dockerfiles, and Kustomize dev overlay` | docker-compose.yml, **/Dockerfile*, infra/k8s/overlays/dev/**/*.yaml | `docker compose config && kustomize build infra/k8s/overlays/dev` | +| 6 | T26-T28 | `test(e2e): add Playwright E2E tests for auth, tasks, and shifts` | frontend/tests/e2e/**/*.spec.ts | `bunx playwright test` | + +--- + +## Success Criteria + +### Verification Commands +```bash +# All services start and are healthy +docker compose up -d && docker compose ps # Expected: 4 services running + +# Backend health +curl -sf http://localhost:5000/health/live # Expected: 200, "Healthy" + +# Keycloak OIDC discovery +curl -sf http://localhost:8080/realms/workclub/.well-known/openid-configuration # Expected: 200, JSON with "issuer" + +# Get auth token +TOKEN=$(curl -sf -X POST http://localhost:8080/realms/workclub/protocol/openid-connect/token \ + -d "client_id=workclub-app&username=admin@test.com&password=testpass123&grant_type=password" | jq -r '.access_token') + +# Tenant isolation +curl -sf -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: club-1-uuid" http://localhost:5000/api/tasks # Expected: 200, only club-1 tasks +curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: nonexistent-club" http://localhost:5000/api/tasks # Expected: 403 + +# Backend tests +dotnet test backend/tests/ --no-build # Expected: All pass + +# Frontend build + tests +bun run build # Expected: Exit 0 +bun run test # Expected: All pass + +# K8s manifests valid +kustomize build infra/k8s/overlays/dev > /dev/null # Expected: Exit 0 +``` + +### Final Checklist +- [ ] All "Must Have" items present and verified +- [ ] All "Must NOT Have" items absent (no MediatR, no generic repo, no Swashbuckle, etc.) +- [ ] All backend tests pass (`dotnet test`) +- [ ] All frontend tests pass (`bun run test`) +- [ ] All E2E tests pass (`bunx playwright test`) +- [ ] Docker Compose stack starts clean and healthy +- [ ] Kustomize manifests build without errors +- [ ] RLS isolation proven at database level +- [ ] Cross-tenant access returns 403 +- [ ] Task state machine rejects invalid transitions (422) +- [ ] Shift sign-up respects capacity (409 when full) diff --git a/backend/WorkClub.Api/Program.cs b/backend/WorkClub.Api/Program.cs new file mode 100644 index 0000000..ee9d65d --- /dev/null +++ b/backend/WorkClub.Api/Program.cs @@ -0,0 +1,41 @@ +var builder = WebApplication.CreateBuilder(args); + +// Add services to the container. +// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi +builder.Services.AddOpenApi(); + +var app = builder.Build(); + +// Configure the HTTP request pipeline. +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} + +app.UseHttpsRedirection(); + +var summaries = new[] +{ + "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" +}; + +app.MapGet("/weatherforecast", () => +{ + var forecast = Enumerable.Range(1, 5).Select(index => + new WeatherForecast + ( + DateOnly.FromDateTime(DateTime.Now.AddDays(index)), + Random.Shared.Next(-20, 55), + summaries[Random.Shared.Next(summaries.Length)] + )) + .ToArray(); + return forecast; +}) +.WithName("GetWeatherForecast"); + +app.Run(); + +record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) +{ + public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); +} diff --git a/backend/WorkClub.Api/WorkClub.Api.csproj b/backend/WorkClub.Api/WorkClub.Api.csproj new file mode 100644 index 0000000..4cd510d --- /dev/null +++ b/backend/WorkClub.Api/WorkClub.Api.csproj @@ -0,0 +1,19 @@ + + + + net10.0 + enable + enable + + + + + + + + + + + + + diff --git a/backend/WorkClub.Api/WorkClub.Api.http b/backend/WorkClub.Api/WorkClub.Api.http new file mode 100644 index 0000000..24e7a6d --- /dev/null +++ b/backend/WorkClub.Api/WorkClub.Api.http @@ -0,0 +1,6 @@ +@WorkClub.Api_HostAddress = http://localhost:5142 + +GET {{WorkClub.Api_HostAddress}}/weatherforecast/ +Accept: application/json + +### diff --git a/backend/WorkClub.Api/appsettings.Development.json b/backend/WorkClub.Api/appsettings.Development.json new file mode 100644 index 0000000..0c208ae --- /dev/null +++ b/backend/WorkClub.Api/appsettings.Development.json @@ -0,0 +1,8 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + } +} diff --git a/backend/WorkClub.Api/appsettings.json b/backend/WorkClub.Api/appsettings.json new file mode 100644 index 0000000..10f68b8 --- /dev/null +++ b/backend/WorkClub.Api/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + }, + "AllowedHosts": "*" +} diff --git a/backend/WorkClub.Application/Class1.cs b/backend/WorkClub.Application/Class1.cs new file mode 100644 index 0000000..e2952be --- /dev/null +++ b/backend/WorkClub.Application/Class1.cs @@ -0,0 +1,6 @@ +namespace WorkClub.Application; + +public class Class1 +{ + +} diff --git a/backend/WorkClub.Application/WorkClub.Application.csproj b/backend/WorkClub.Application/WorkClub.Application.csproj new file mode 100644 index 0000000..ef3c672 --- /dev/null +++ b/backend/WorkClub.Application/WorkClub.Application.csproj @@ -0,0 +1,18 @@ + + + + + + + + + + + + + net10.0 + enable + enable + + + diff --git a/backend/WorkClub.Domain/Class1.cs b/backend/WorkClub.Domain/Class1.cs new file mode 100644 index 0000000..d500a58 --- /dev/null +++ b/backend/WorkClub.Domain/Class1.cs @@ -0,0 +1,6 @@ +namespace WorkClub.Domain; + +public class Class1 +{ + +} diff --git a/backend/WorkClub.Domain/WorkClub.Domain.csproj b/backend/WorkClub.Domain/WorkClub.Domain.csproj new file mode 100644 index 0000000..b760144 --- /dev/null +++ b/backend/WorkClub.Domain/WorkClub.Domain.csproj @@ -0,0 +1,9 @@ + + + + net10.0 + enable + enable + + + diff --git a/backend/WorkClub.Infrastructure/Class1.cs b/backend/WorkClub.Infrastructure/Class1.cs new file mode 100644 index 0000000..adcdea9 --- /dev/null +++ b/backend/WorkClub.Infrastructure/Class1.cs @@ -0,0 +1,6 @@ +namespace WorkClub.Infrastructure; + +public class Class1 +{ + +} diff --git a/backend/WorkClub.Infrastructure/WorkClub.Infrastructure.csproj b/backend/WorkClub.Infrastructure/WorkClub.Infrastructure.csproj new file mode 100644 index 0000000..093a99c --- /dev/null +++ b/backend/WorkClub.Infrastructure/WorkClub.Infrastructure.csproj @@ -0,0 +1,17 @@ + + + + + + + + + + + + net10.0 + enable + enable + + + diff --git a/backend/WorkClub.Tests.Integration/UnitTest1.cs b/backend/WorkClub.Tests.Integration/UnitTest1.cs new file mode 100644 index 0000000..a5bb915 --- /dev/null +++ b/backend/WorkClub.Tests.Integration/UnitTest1.cs @@ -0,0 +1,10 @@ +namespace WorkClub.Tests.Integration; + +public class UnitTest1 +{ + [Fact] + public void Test1() + { + + } +} diff --git a/backend/WorkClub.Tests.Integration/WorkClub.Tests.Integration.csproj b/backend/WorkClub.Tests.Integration/WorkClub.Tests.Integration.csproj new file mode 100644 index 0000000..38aeb3c --- /dev/null +++ b/backend/WorkClub.Tests.Integration/WorkClub.Tests.Integration.csproj @@ -0,0 +1,30 @@ + + + + net10.0 + enable + enable + false + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/backend/WorkClub.Tests.Unit/UnitTest1.cs b/backend/WorkClub.Tests.Unit/UnitTest1.cs new file mode 100644 index 0000000..dcf7477 --- /dev/null +++ b/backend/WorkClub.Tests.Unit/UnitTest1.cs @@ -0,0 +1,10 @@ +namespace WorkClub.Tests.Unit; + +public class UnitTest1 +{ + [Fact] + public void Test1() + { + + } +} diff --git a/backend/WorkClub.Tests.Unit/WorkClub.Tests.Unit.csproj b/backend/WorkClub.Tests.Unit/WorkClub.Tests.Unit.csproj new file mode 100644 index 0000000..2fa19d9 --- /dev/null +++ b/backend/WorkClub.Tests.Unit/WorkClub.Tests.Unit.csproj @@ -0,0 +1,28 @@ + + + + net10.0 + enable + enable + false + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/backend/WorkClub.slnx b/backend/WorkClub.slnx new file mode 100644 index 0000000..46dbc5b --- /dev/null +++ b/backend/WorkClub.slnx @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/backend/global.json b/backend/global.json new file mode 100644 index 0000000..512142d --- /dev/null +++ b/backend/global.json @@ -0,0 +1,6 @@ +{ + "sdk": { + "version": "10.0.100", + "rollForward": "latestFeature" + } +}