Add OpenAPI spec validation hook (Redocly CLI)

PostToolUse hook triggers on openapi/*.yaml edits and runs
redocly lint with the recommended ruleset (security-defined
disabled since endpoints are intentionally public).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/hooks/openapi-validate.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Read hook input from stdin (JSON with tool_input.file_path)
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))" 2>/dev/null || echo "")
+
+# Only run for OpenAPI spec files
+case "$FILE_PATH" in
+    */openapi/*.yaml|*/openapi/*.yml) ;;
+    *) exit 0 ;;
+esac
+
+cd "$CLAUDE_PROJECT_DIR/backend"
+
+# Run validation (zero-config: structural validity only)
+if OUTPUT=$(npx @redocly/cli@latest lint src/main/resources/openapi/api.yaml --format=stylish 2>&1); then
+    echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"✓ OpenAPI spec validation passed."}}'
+else
+    ESCAPED=$(echo "$OUTPUT" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":$ESCAPED}}"
+fi

.claude/settings.json

@@ -13,6 +13,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/frontend-check.sh\"",
             "timeout": 120
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/openapi-validate.sh\"",
+            "timeout": 120
           }
         ]
       }

CLAUDE.md

@@ -16,6 +16,7 @@ These are the non-negotiable principles of this project. Every decision — arch
 ### Methodology
 
 - Follow Research → Spec → Test → Implement → Review. No shortcuts.
+- API-first development: the OpenAPI spec (`backend/src/main/resources/openapi/api.yaml`) is the single source of truth for the REST API contract. Define endpoints and schemas in the spec first, then generate backend interfaces and frontend types before writing any implementation code.
 - Never write implementation code without a specification.
 - Always write tests before implementation (TDD). Red → Green → Refactor.
 - Refactoring is permitted freely as long as it does not alter the fundamental architecture.

README.md

@@ -150,6 +150,16 @@ ArchUnit enforces hexagonal boundaries: domain must not depend on adapters, appl
 |---------------------|------------------|-------------------|
 | Prettier            | `npm run format` | Formatting issues |
 
+### OpenAPI Spec (YAML)
+
+**After editing an `openapi/*.yaml` file** (PostToolUse hook):
+
+| What                | Command                  | Fails on                          |
+|---------------------|--------------------------|-----------------------------------|
+| Redocly CLI         | `redocly lint api.yaml`  | Structural and ruleset violations |
+
+Validates the OpenAPI 3.1 spec against the Redocly `recommended` ruleset (with `security-defined` disabled, since endpoints are intentionally public). Runs via `npx @redocly/cli@latest`.
+
 ## Deployment
 
 ### Docker Compose

backend/redocly.yaml

@@ -0,0 +1,5 @@
+extends:
+  - recommended
+
+rules:
+  security-defined: off

docs/agents/research/2026-03-04-openapi-validation-pipeline.md

@@ -0,0 +1,215 @@
+---
+date: "2026-03-04T22:27:37.933286+00:00"
+git_commit: 91e566efea0cbf53ba06a29b63317b7435609bd8
+branch: master
+topic: "Automatic OpenAPI Validation Pipelines for Backpressure Hooks"
+tags: [research, openapi, validation, hooks, backpressure, linting]
+status: complete
+---
+
+# Research: Automatic OpenAPI Validation Pipelines
+
+## Research Question
+
+What automatic validation pipelines exist for OpenAPI specs that can be integrated into the current Claude Code backpressure hook setup, running after the OpenAPI spec has been modified?
+
+## Summary
+
+The project already has a PostToolUse hook system that runs backend compile checks and frontend lint/type-checks after Edit/Write operations. Adding OpenAPI spec validation requires a new hook script that triggers specifically when `api.yaml` is modified. Several CLI tools support OpenAPI 3.1.0 validation — **Redocly CLI** is the strongest fit given the existing Node.js toolchain, MIT license, active maintenance, and zero-config baseline.
+
+## Current Backpressure Setup
+
+### Hook Architecture (`.claude/settings.json`)
+
+The project uses Claude Code hooks for automated quality gates:
+
+| Hook Event | Trigger | Scripts |
+|---|---|---|
+| `PostToolUse` | `Edit\|Write` tool calls | `backend-compile-check.sh`, `frontend-check.sh` |
+| `Stop` | Agent attempts to stop | `run-tests.sh` |
+
+### How Hooks Work
+
+Each hook script:
+1. Reads JSON from stdin containing `tool_input.file_path`
+2. Pattern-matches the file path to decide if it should run
+3. Executes validation (compile, lint, type-check, test)
+4. Returns JSON with either success message or failure details
+5. On failure: outputs `hookSpecificOutput` with error context (PostToolUse) or `{"decision":"block"}` (Stop)
+
+### Existing Pattern for File Matching
+
+```bash
+# backend-compile-check.sh — matches Java files
+case "$FILE_PATH" in
+    */backend/src/*.java|backend/src/*.java) ;;
+    *) exit 0 ;;
+esac
+
+# frontend-check.sh — matches TS/Vue files
+case "$FILE_PATH" in
+    */frontend/src/*.ts|*/frontend/src/*.vue|frontend/src/*.ts|frontend/src/*.vue) ;;
+    *) exit 0 ;;
+esac
+```
+
+An OpenAPI validation hook would use the same pattern:
+```bash
+case "$FILE_PATH" in
+    */openapi/api.yaml|*/openapi/*.yaml) ;;
+    *) exit 0 ;;
+esac
+```
+
+### Existing OpenAPI Tooling in the Project
+
+- **Backend:** `openapi-generator-maven-plugin` v7.20.0 generates Spring interfaces from `api.yaml` (`pom.xml:149-178`)
+- **Frontend:** `openapi-typescript` v7.13.0 generates TypeScript types; `openapi-fetch` v0.17.0 provides type-safe client
+- **No validation/linting tools** currently installed — no Redocly, Spectral, or other linter config exists
+
+## Tool Evaluation
+
+### Redocly CLI (`@redocly/cli`)
+
+| Attribute | Value |
+|---|---|
+| OpenAPI 3.1 | Full support |
+| Install | `npm install -g @redocly/cli` or `npx @redocly/cli@latest` |
+| CLI | `redocly lint api.yaml` |
+| License | MIT |
+| Maintenance | Very active — latest v2.20.3 (2026-03-03), daily/weekly releases |
+| GitHub | ~1.4k stars (Redocly ecosystem: 24k+ combined) |
+
+**Checks:** Structural validity against OAS schema, configurable linting rules (naming, descriptions, operation IDs, security), style/consistency enforcement. Built-in rulesets: `minimal`, `recommended`, `recommended-strict`. Zero-config baseline works immediately. Custom rules via `redocly.yaml`.
+
+**Fit for this project:** Node.js already in the toolchain (frontend). `npx` form requires no permanent install. MIT license compatible with GPL-3.0. The `@redocly/openapi-core` package is already present as a transitive dependency of `openapi-typescript` in `node_modules`.
+
+### Spectral (`@stoplight/spectral-cli`)
+
+| Attribute | Value |
+|---|---|
+| OpenAPI 3.1 | Full support (since v6.x) |
+| Install | `npm install -g @stoplight/spectral-cli` |
+| CLI | `spectral lint api.yaml` |
+| License | Apache 2.0 |
+| Maintenance | Active — latest v6.15.0 (2025-04-22), slower cadence |
+| GitHub | ~3k stars |
+
+**Checks:** Schema compliance, missing descriptions/tags/operationIds, contact/license metadata. Highly extensible custom rulesets via YAML/JS. Configurable severity levels.
+
+**Fit for this project:** Well-established industry standard. Apache 2.0 compatible with GPL. Less actively maintained than Redocly (10 months since last release). Heavier custom ruleset system may be over-engineered for current needs.
+
+### Vacuum (`daveshanley/vacuum`)
+
+| Attribute | Value |
+|---|---|
+| OpenAPI 3.1 | Full support (via libopenapi) |
+| Install | `brew install daveshanley/vacuum/vacuum` or Go binary |
+| CLI | `vacuum lint api.yaml` |
+| License | MIT |
+| Maintenance | Active — latest release 2025-12-22 |
+| GitHub | ~1k stars |
+
+**Checks:** Structural validation, Spectral-compatible rulesets, OWASP security checks, naming conventions, descriptions/examples/tags. Single Go binary — no runtime dependencies.
+
+**Fit for this project:** Zero-dependency binary is appealing for CI. However, adds a non-Node.js tool dependency when the project already has Node.js. Spectral ruleset compatibility is a plus for portability.
+
+### oasdiff (`oasdiff/oasdiff`)
+
+| Attribute | Value |
+|---|---|
+| OpenAPI 3.1 | Beta |
+| Install | `brew install oasdiff` or Go binary |
+| CLI | `oasdiff breaking base.yaml revision.yaml` |
+| License | Apache 2.0 |
+| Maintenance | Active — latest v1.11.10 (2026-02-05) |
+| GitHub | ~1.1k stars |
+
+**Checks:** 300+ breaking change detection rules (paths, parameters, schemas, security, headers, enums). Requires two spec versions to compare — not a standalone validator.
+
+**Fit for this project:** Different category — detects breaking changes between spec versions, not structural validity. Useful as a CI-only check comparing `HEAD~1` vs `HEAD`. OAS 3.1 support is still beta.
+
+### Not Recommended
+
+- **swagger-cli:** Abandoned, no OAS 3.1 support
+- **IBM OpenAPI Validator:** Active but opinionated IBM-specific rules add configuration overhead for no benefit
+
+## Tool Comparison Matrix
+
+| Tool | OAS 3.1 | License | Last Release | Stars | Runtime | Category |
+|---|---|---|---|---|---|---|
+| **Redocly CLI** | Full | MIT | 2026-03-03 | ~1.4k | Node.js | Lint + validate |
+| **Spectral** | Full | Apache 2.0 | 2025-04-22 | ~3k | Node.js | Lint |
+| **Vacuum** | Full | MIT | 2025-12-22 | ~1k | Go binary | Lint + validate |
+| **oasdiff** | Beta | Apache 2.0 | 2026-02-05 | ~1.1k | Go binary | Breaking changes |
+
+## Integration Pattern
+
+### Hook Script Structure
+
+An OpenAPI validation hook would follow the existing pattern in `.claude/hooks/`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))" 2>/dev/null || echo "")
+
+# Only run for OpenAPI spec files
+case "$FILE_PATH" in
+    */openapi/*.yaml|*/openapi/*.yml) ;;
+    *) exit 0 ;;
+esac
+
+cd "$CLAUDE_PROJECT_DIR/backend"
+
+# Run validation
+if OUTPUT=$(npx @redocly/cli@latest lint src/main/resources/openapi/api.yaml --format=stylish 2>&1); then
+    echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"✓ OpenAPI spec validation passed."}}'
+else
+    ESCAPED=$(echo "$OUTPUT" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":$ESCAPED}}"
+fi
+```
+
+### Registration in `.claude/settings.json`
+
+The hook would be added to the existing `PostToolUse` array alongside the compile and lint hooks:
+
+```json
+{
+  "type": "command",
+  "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/openapi-validate.sh\"",
+  "timeout": 120
+}
+```
+
+### Configuration (Optional)
+
+A `redocly.yaml` in the project root or `backend/` directory can customize rules:
+
+```yaml
+extends:
+  - recommended
+
+rules:
+  operation-operationId: error
+  tag-description: warn
+  no-ambiguous-paths: error
+```
+
+## Code References
+
+- `.claude/settings.json:1-32` — Hook configuration (PostToolUse + Stop events)
+- `.claude/hooks/backend-compile-check.sh` — Java file detection pattern + compile check
+- `.claude/hooks/frontend-check.sh` — TS/Vue file detection pattern + type-check + lint
+- `.claude/hooks/run-tests.sh` — Stop hook with test execution and block/approve logic
+- `backend/pom.xml:149-178` — openapi-generator-maven-plugin configuration
+- `backend/src/main/resources/openapi/api.yaml` — The OpenAPI 3.1.0 spec to validate
+
+## Open Questions
+
+- Should the validation use a pinned version (`npx @redocly/cli@1.x.x`) or latest? Pinned is more reproducible; latest gets rule updates automatically.
+- Should a `redocly.yaml` config be added immediately with the `recommended` ruleset, or start with zero-config (structural validation only) and add rules incrementally?
+- Is breaking change detection (oasdiff) desirable as a separate CI check, or is structural validation sufficient for now?

review-findings.md

@@ -44,7 +44,7 @@ US-1 hat 8 ACs, aber implizit beinhaltet sie den gesamten Erstaufbau des Stacks:
 | Schicht | Was US-1 implizit verlangt |
 |---------|---------------------------|
 | DB | Event-Tabelle, Migration, Flyway-Setup |
-| Backend | Entity, Repository, Service, REST Controller, UUID-Generation, Honeypot-Validation, JSON-Serialisierung |
+| Backend | Entity, Repository, Service, REST Controller, UUID-Generation, JSON-Serialisierung |
 | Frontend | Formular, Validierung, API-Call, localStorage-Management, Routing zur Erstellungsseite, Redirect zur Event-Page |
 | Integration | Frontend↔Backend Verbindung, CORS-Konfiguration |
 

spec/implementation-phases.md

@@ -1,160 +1,123 @@
-# Implementation Phases
+# Implementation Order
 
-A recommended implementation order based on the dependency graph across all stories and setup tasks.
+Sequential implementation order for all user stories. No parallelization — one story at a time.
 
-## Phase 0: Project Infrastructure
+## Progress Tracker
 
-All setup tasks must complete before any user story work begins. T-3 can run in parallel with Phase 1.
+- [ ] US-1 Create event
+- [ ] US-2 View event page
+- [ ] US-3 RSVP
+- [ ] US-5 Edit event
+- [ ] US-4 Manage guest list
+- [ ] US-18 Cancel event
+- [ ] US-19 Delete event
+- [ ] US-12 Auto-cleanup after expiry
+- [ ] US-13 Limit active events
+- [ ] US-6 Bookmark event
+- [ ] US-7 Local event overview
+- [ ] US-17 Dark/light mode
+- [ ] US-8 Calendar integration
+- [ ] US-11 QR code
+- [ ] US-9 Change highlights
+- [ ] US-10a Update messages
+- [ ] US-10b New-update indicator
+- [ ] US-15 Color themes
+- [ ] US-16 Unsplash header images
+- [ ] US-14 PWA install
 
-| Order | Task | Depends on | Notes |
+## Prerequisites
-|-------|------|------------|-------|
-| 1 | T-1: Initialize monorepo structure | — | Scaffolds empty backend + frontend projects |
-| 2 | T-5: API-first tooling setup | T-1 | OpenAPI spec, codegen plugins, generated types |
-| 3 | T-2: Docker deployment setup | T-1, T-5 | Multi-stage Dockerfile — builds backend + frontend into one container |
-| 4 | T-4: Development infrastructure | T-2, T-5 | Migrations, DB wiring, router, test infra, docker-compose docs — gates all user stories |
-| 4* | T-3: CI/CD pipeline | T-1, T-2 | Parallelizable with T-4. Uses Gitea Actions (per Q-5 resolution) |
 
-## Phase 1: Core Event Flow (Vertical Slice)
+All setup tasks (T-1 through T-5) are complete.
 
-The end-to-end journey from creating an event to viewing it to RSVPing. US-1 is the "Durchstich" that bootstraps the full stack (DB table, backend endpoint, frontend form, localStorage, routing). It will take significantly longer than subsequent stories.
+## Order Rationale
 
-| Order | Story | Depends on | Parallelizable |
+### Increment 1: Minimal Viable Event — US-1, US-2, US-3
-|-------|-------|------------|----------------|
-| 1 | US-1: Create an event | T-4 | — |
-| 2 | US-2: View event landing page | US-1 | — |
-| 3 | US-3: RSVP to an event | US-2 | — |
 
-These three stories are strictly sequential. No parallelization within this phase.
+The vertical slice. After these three stories, the app is usable: an organizer creates an event, shares the link, guests view it and RSVP.
 
-## Phase 2: Organizer Management & Event Lifecycle
+| # | Story | Depends on | Delivers |
+|---|-------|------------|----------|
+| 1 | US-1: Create event | T-4 | Event creation with tokens, localStorage |
+| 2 | US-2: View event page | US-1 | Public event page with attendee list, expired state |
+| 3 | US-3: RSVP | US-2 | Attend/decline flow, localStorage dedup |
 
-All stories in this phase depend on US-1 (and T-4 transitively). They can be implemented in parallel since they are independent of each other. Some are more useful after Phase 1 completes (e.g. US-4 needs RSVPs to manage), but they are structurally implementable after US-1.
+### Increment 2: Organizer Toolset — US-5, US-4
 
-| Story | Depends on | Notes |
+The organizer needs to correct mistakes and moderate spam before the app goes to real users.
-|-------|------------|-------|
-| US-4: Manage guest list | US-1 | Most useful after US-3 provides RSVPs to manage |
-| US-5: Edit event details | US-1 | Required by US-9 in Phase 3 |
-| US-18: Cancel an event | US-1 | Enables deferred ACs in US-2, US-3, US-8 |
-| US-19: Delete an event | US-1 | Enables deferred AC in US-2 |
-| US-12: Automatic data deletion after expiry | US-1 | Enables deferred AC in US-2; server-side scheduled job |
-| US-13: Limit active events | US-1 | Server-side config; independent of all other stories |
 
-**Recommended order within phase:** US-5, US-4, US-18, US-19, US-12, US-13 — starting with US-5 because US-9 (Phase 3) depends on it, and US-4 because it completes the organizer toolset around RSVPs.
+| # | Story | Depends on | Delivers |
+|---|-------|------------|----------|
+| 4 | US-5: Edit event | US-1 | Edit all fields, expiry-must-be-future constraint |
+| 5 | US-4: Manage guest list | US-1 | View RSVPs, delete spam entries |
 
-## Phase 3: Enhanced Event Page Features
+US-5 before US-4: US-9 (change highlights) depends on US-5, so getting it done early unblocks Phase 3 work.
 
-Features that enrich the event page for guests. Most depend on US-2 (event page exists). US-9 additionally requires US-5 (editing). US-10b requires US-10a.
+### Increment 3: Event Lifecycle — US-18, US-19, US-12, US-13
 
-| Story | Depends on | Parallelizable with |
+Complete lifecycle management. After this increment, the privacy guarantee is enforced and abuse prevention is in place.
-|-------|------------|---------------------|
-| US-6: Bookmark an event | US-2 | US-8, US-10a, US-11 |
-| US-8: Add event to calendar (.ics / webcal) | US-2 | US-6, US-10a, US-11 |
-| US-9: Highlight changed event details | US-2, US-5 | US-6, US-8, US-10a, US-11 (if US-5 is done) |
-| US-10a: Post update messages | US-1, US-2 | US-6, US-8, US-11 |
-| US-10b: New-update indicator | US-10a | Must follow US-10a |
-| US-11: Generate QR code | US-2 | US-6, US-8, US-10a |
 
-**Recommended order within phase:** US-6, US-8, US-11 (simple, independent), then US-10a → US-10b (sequential pair), then US-9 (requires US-5 from Phase 2).
+| # | Story | Depends on | Delivers | Activates deferred ACs |
+|---|-------|------------|----------|----------------------|
+| 6 | US-18: Cancel event | US-1 | One-way cancellation with optional message, expiry adjustment | US-2 AC5, US-3 AC11 |
+| 7 | US-19: Delete event | US-1 | Immediate permanent deletion, localStorage cleanup | US-2 AC6 (partial) |
+| 8 | US-12: Auto-cleanup | US-1 | Scheduled deletion after expiry, silent logging | US-2 AC6 (complete) |
+| 9 | US-13: Event limit | US-1 | `MAX_ACTIVE_EVENTS` env var, server-side enforcement | — |
 
-## Phase 4: Visual Customization
+When implementing US-18, US-19, and US-12: immediately activate their deferred ACs in US-2 and US-3 (cancelled state display, RSVP blocking, event-not-found handling). These stories exist at this point — no reason to defer further.
 
-Event-level theming and image selection. Both depend on US-1 and US-2. US-15 and US-16 are independent of each other but share the event creation/editing form surface area, so coordinating them is beneficial.
+### Increment 4: App Shell — US-6, US-7, US-17
 
-| Story | Depends on | Notes |
+The app gets a home screen. Users can find their events without the original link.
-|-------|------------|-------|
-| US-15: Choose event color theme | US-1, US-2 | Predefined theme picker in creation/edit forms |
-| US-16: Select header image from Unsplash | US-1, US-2 | Optional feature gated by API key config |
 
-**Recommended order:** US-15 first (simpler, no external dependency), then US-16. Consider the interaction between event themes and dark/light mode (US-17) — implement US-17 before or alongside US-15 if possible.
+| # | Story | Depends on | Delivers |
+|---|-------|------------|----------|
+| 10 | US-6: Bookmark event | US-2 | Client-only bookmark, no server contact |
+| 11 | US-7: Local event overview | — | Root page `/` with all tracked events from localStorage |
+| 12 | US-17: Dark/light mode | — | System preference detection, manual toggle, localStorage persistence |
 
-## Phase 5: App Shell & PWA
+US-6 before US-7: bookmarking populates localStorage entries that the overview displays. Without US-6, the overview only shows created and RSVPed events.
 
-Client-side infrastructure and app-level UX features. These have no or minimal structural dependencies but are only meaningfully testable after earlier phases provide content and data.
+US-17 here (not in a late phase): event color themes (US-15) must account for dark/light mode. Having it in place before US-15 avoids rework.
 
-| Story | Depends on | Practically useful after |
+### Increment 5: Rich Event Page — US-8, US-11, US-9, US-10a, US-10b
-|-------|------------|------------------------|
-| US-7: Local event overview | None (structural) | US-1, US-3, US-6 populate localStorage |
-| US-14: Install as PWA | T-4 (structural) | US-2, US-7 provide pages to cache |
-| US-17: Dark/light mode | None (structural) | T-4 provides frontend scaffold |
 
-**Recommended order:** US-17 (can be started early once the frontend scaffold exists — consider implementing alongside Phase 2 or 3), then US-7 (after localStorage-populating stories are available), then US-14 (after the app has real pages and assets).
+Features that enrich the event page for guests and organizers.
 
-**Note on US-17 timing:** US-17 is listed in Phase 5 for logical grouping, but it can be implemented as early as Phase 2 since it only needs the frontend scaffold. Implementing it earlier is recommended because US-15 (Phase 4) must consider the interaction between event color themes and dark/light mode. Having dark/light mode in place before US-15 simplifies that work.
+| # | Story | Depends on | Delivers |
+|---|-------|------------|----------|
+| 13 | US-8: Calendar .ics + webcal | US-2 | RFC 5545 download, webcal subscription, STATUS:CANCELLED support |
+| 14 | US-11: QR code | US-2 | Server-generated QR, SVG/PNG download |
+| 15 | US-9: Change highlights | US-2, US-5 | Field-level change indicators, localStorage-based read tracking |
+| 16 | US-10a: Update messages | US-1, US-2 | Organizer posts, reverse-chronological display, delete capability |
+| 17 | US-10b: New-update indicator | US-10a | localStorage-based unread badge |
 
-## Deferred Acceptance Criteria
+US-8 benefits from US-18 being complete: `STATUS:CANCELLED` in .ics can be implemented directly instead of deferred.
 
-Several stories contain ACs that reference features from later phases. These are marked `[deferred until US-X is implemented]` in the story text:
+US-9 benefits from US-5 being complete (increment 2): no dependency waiting.
 
-| Story | AC | Deferred until | Phase unlocked |
+### Increment 6: Visual Polish & PWA — US-15, US-16, US-14
-|-------|-----|---------------|----------------|
-| US-2 AC 5 | Cancelled state display | US-18 | Phase 2 |
-| US-2 AC 6 | Event not found (expiry deletion) | US-12 | Phase 2 |
-| US-2 AC 6 | Event not found (organizer deletion) | US-19 | Phase 2 |
-| US-3 AC 11 | RSVP blocked on cancelled event | US-18 | Phase 2 |
-| US-8 AC 9 | STATUS:CANCELLED in .ics | US-18 | Phase 2 |
-| US-12 AC 2 | Delete stored header images | US-16 | Phase 4 |
 
-Once the referenced story is implemented, revisit the deferring story to activate the deferred AC.
+Final layer: visual customization and native app feel.
 
-## Dependency Graph
+| # | Story | Depends on | Delivers |
+|---|-------|------------|----------|
+| 18 | US-15: Color themes | US-1, US-2 | Predefined theme picker, event-scoped styling |
+| 19 | US-16: Unsplash images | US-1, US-2 | Server-proxied search, local storage, attribution |
+| 20 | US-14: PWA | T-4 | Manifest, service worker, installability |
 
-Render this diagram at [mermaid.live](https://mermaid.live) or view it directly in Gitea (which renders `mermaid` blocks natively).
+US-15 before US-16: themes are self-contained, Unsplash adds external API complexity.
 
-```mermaid
+US-14 last: PWA caching is most effective when the app has all its pages and assets. Service worker strategy can cover everything in one pass.
-graph TD
-    classDef infra fill:#4a90d9,stroke:#2c5f8a,color:#fff
-    classDef core fill:#e8a838,stroke:#b07c1e,color:#fff
-    classDef organizer fill:#50b86c,stroke:#2d8043,color:#fff
-    classDef enhanced fill:#9b59b6,stroke:#6c3483,color:#fff
-    classDef visual fill:#e74c3c,stroke:#a93226,color:#fff
-    classDef shell fill:#7f8c8d,stroke:#566566,color:#fff
 
-    %% Phase 0: Infrastructure
+Note: US-12 AC2 (delete stored header images on expiry) remains deferred until US-16 is implemented. When implementing US-16, activate this AC in US-12.
-    T1(["T-1: Monorepo"]):::infra --> T5(["T-5: API-First Tooling"]):::infra
-    T1 --> T2(["T-2: Docker"]):::infra
-    T5 --> T2
-    T2 --> T4(["T-4: Dev Infra + DB"]):::infra
-    T5 --> T4
-    T2 --> T3(["T-3: CI/CD"]):::infra
 
-    %% Phase 1: Core Event Flow
+## Deferred AC Activation Schedule
-    T4 --> US1["US-1: Create Event"]:::core
-    US1 --> US2["US-2: View Event"]:::core
-    US2 --> US3["US-3: RSVP"]:::core
 
-    %% Phase 2: Organizer & Lifecycle (branch from US-1)
+| When implementing | Activate deferred AC in | AC description |
-    US1 --> US4["US-4: Guest List"]:::organizer
+|-------------------|------------------------|----------------|
-    US1 --> US5["US-5: Edit Event"]:::organizer
+| US-18 (#6) | US-2 AC5 | Cancelled state display |
-    US1 --> US18["US-18: Cancel"]:::organizer
+| US-18 (#6) | US-3 AC11 | RSVP blocked on cancelled event |
-    US1 --> US19["US-19: Delete"]:::organizer
+| US-18 (#6) | US-8 AC9 | STATUS:CANCELLED in .ics (if US-8 not yet done — in this order, US-8 comes later, so implement directly) |
-    US1 --> US12["US-12: Auto-Cleanup"]:::organizer
+| US-19 (#7) | US-2 AC6 | Event not found (organizer deletion) |
-    US1 --> US13["US-13: Event Limit"]:::organizer
+| US-12 (#8) | US-2 AC6 | Event not found (expiry deletion) |
-
+| US-16 (#19) | US-12 AC2 | Delete stored header images on expiry |
-    %% Phase 3: Enhanced Features (branch from US-2)
-    US2 --> US6["US-6: Bookmark"]:::enhanced
-    US2 --> US8["US-8: Calendar .ics"]:::enhanced
-    US2 --> US10a["US-10a: Messages"]:::enhanced
-    US2 --> US11["US-11: QR Code"]:::enhanced
-    US5 --> US9["US-9: Change Highlights"]:::enhanced
-    US2 --> US9
-    US10a --> US10b["US-10b: New-Update Badge"]:::enhanced
-
-    %% Phase 4: Visual Customization (branch from US-2)
-    US2 --> US15["US-15: Color Themes"]:::visual
-    US2 --> US16["US-16: Unsplash Images"]:::visual
-
-    %% Phase 5: App Shell & PWA
-    T4 --> US14["US-14: PWA"]:::shell
-    US7["US-7: Local Overview"]:::shell
-    US17["US-17: Dark/Light Mode"]:::shell
-```
-
-**Legend:**
-- 🔵 Infrastructure (T-1 – T-5)
-- 🟠 Core Event Flow (US-1 – US-3)
-- 🟢 Organizer & Lifecycle (US-4, US-5, US-12, US-13, US-18, US-19)
-- 🟣 Enhanced Features (US-6, US-8 – US-11)
-- 🔴 Visual Customization (US-15, US-16)
-- ⚪ App Shell & PWA (US-7, US-14, US-17)
-
-US-7 and US-17 appear as isolated nodes — they have no structural dependencies but are only practically useful after earlier phases provide content (see Phase 5 notes above).

spec/userstories.md

@@ -32,13 +32,14 @@ The following terms are used consistently across all stories:
 - [ ] The event token, title, and date are also stored in localStorage alongside the organizer token, so the local event overview (US-7) can display the event without additional server contact
 - [ ] No account, login, or personal data is required to create an event
 - [ ] The expiry date field is mandatory and cannot be left blank
-- [ ] A honeypot field is present in the event creation form: hidden from real users; any submission with the field populated is silently discarded server-side
 - [ ] The event is not discoverable except via its direct link
 
 **Dependencies:** T-4
 
 **Notes:** Non-guessable tokens (UUIDs) are specified in Ideen.md under security. Expiry date is mandatory per Ideen.md. No registration required per core principles. Per Q-4 resolution: organizer authentication uses the organizer token stored in localStorage on the device where the event was created. The organizer token is separate from the event token — since the event link is designed to be shared in group chats, using the same token for both public access and organizer auth would allow any guest to manage the event.
 
+**Addendum (2026-03-04):** Honeypot field removed — overengineered for this project's scope. Expiry date must be in the future at creation time — an event should never exist in an invalid state (resolved during US-1 research).
+
 ---
 
 ### US-2: View event landing page
@@ -78,14 +79,15 @@ The following terms are used consistently across all stories:
 - [ ] The event token, title, and date are also stored in localStorage alongside the RSVP data, so the local event overview (US-7) can display the event and link to it without server contact
 - [ ] If a prior RSVP exists in localStorage for this event, the form pre-fills with the previous choice and name
 - [ ] Re-submitting from the same device updates the existing RSVP entry rather than creating a duplicate
-- [ ] A honeypot field is present in the RSVP form: hidden from real users; any submission with the field populated is silently discarded server-side
 - [ ] RSVP submission is not possible after the event's expiry date
 - [ ] RSVP submission is not possible if the event has been cancelled (US-18) [deferred until US-18 is implemented]
 - [ ] No account, login, or data beyond the optionally entered name is required
 
 **Dependencies:** US-2, T-4
 
-**Notes:** RSVP flow specified in Ideen.md: "Ich komme" (with name) / "Ich komme nicht" (optional with name). LocalStorage device binding is the explicit duplicate-prevention mechanism — not a hard guarantee, but sufficient against accidental duplicates. Ideen.md acknowledges that malicious spam without accounts is an acceptable risk. Honeypot fields are listed under Ideen.md security measures.
+**Notes:** RSVP flow specified in Ideen.md: "Ich komme" (with name) / "Ich komme nicht" (optional with name). LocalStorage device binding is the explicit duplicate-prevention mechanism — not a hard guarantee, but sufficient against accidental duplicates. Ideen.md acknowledges that malicious spam without accounts is an acceptable risk.
+
+**Addendum (2026-03-04):** Honeypot field removed — overengineered for this project's scope.
 
 ---
 
@@ -464,3 +466,4 @@ The following terms are used consistently across all stories:
 **Dependencies:** US-1, T-4
 
 **Notes:** The overseer identified that using the expiry date as a deletion mechanism (setting it to today or a past date in US-5) was unintuitive and conflated two different actions. US-5 now enforces that the expiry date can only be set to a future date. If the organizer wants the event gone immediately, they use this explicit deletion feature. Unlike cancellation (US-18), which keeps the event visible with a cancellation notice until the expiry date, deletion removes the event entirely and immediately. This is the organizer's "nuclear option" — useful when the event was created by mistake, contains wrong information, or is no longer needed at all. The deletion behavior is identical to what US-12 does automatically after expiry, but triggered manually and immediately by the organizer.
+