nitrix/fete
1
0
Fork 0
Code Issues 1 Pull Requests 10 Actions Packages Projects Releases 13 Wiki Activity

Migrate project artifacts to spec-kit format

Browse Source 
- Move cross-cutting docs (personas, design system, implementation phases,
  Ideen.md) to .specify/memory/
- Move cross-cutting research and plans to .specify/memory/research/ and
  .specify/memory/plans/
- Extract 5 setup tasks from spec/setup-tasks.md into individual
  specs/001-005/spec.md files with spec-kit template format
- Extract 20 user stories from spec/userstories.md into individual
  specs/006-026/spec.md files with spec-kit template format
- Relocate feature-specific research and plan docs into specs/[feature]/
- Add spec-kit constitution, templates, scripts, and slash commands
- Slim down CLAUDE.md to Claude-Code-specific config, delegate principles
  to .specify/memory/constitution.md
- Update ralph.sh with stream-json output and per-iteration logging
- Delete old spec/ and docs/agents/ directories
- Gitignore Ralph iteration JSONL logs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
nitrix
2026-03-06 20:19:41 +01:00
parent 0b2b84dafc
commit 6aeb4b8bca
83 changed files with 6486 additions and 660 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
specs/016-guest-notifications/spec.md Normal file
View File

@@ -0,0 +1,84 @@
# Feature Specification: New-Update Indicator for Guests
**Feature**: `016-guest-notifications`
**Created**: 2026-03-06
**Status**: Draft
**Source**: Migrated from spec/userstories.md
## User Scenarios & Testing
### User Story 1 - Unread update indicator (Priority: P1)
A guest opens the event page and sees a visual indicator (badge or highlighted section) drawing attention to update messages that were posted since their last visit. The read state is tracked entirely in localStorage — no server involvement.
**Why this priority**: Core purpose of this feature. Without this, guests miss new organizer announcements unless they manually read through all messages.
**Independent Test**: Can be tested by opening an event page after new update messages have been posted, verifying that a badge or visual highlight appears on the update messages section.
**Acceptance Scenarios**:
1. **Given** a guest has previously visited the event page and `updates_last_seen_at` is stored in localStorage, **When** they return and the event has updates newer than `updates_last_seen_at`, **Then** a visual indicator is shown drawing attention to the unread messages.
2. **Given** the event page is rendered with unread updates shown, **When** the page finishes loading, **Then** `updates_last_seen_at` in localStorage is updated to the timestamp of the most recent update, so the indicator does not appear on the next visit.
3. **Given** a guest opens the event page and all updates are older than the stored `updates_last_seen_at`, **When** the page loads, **Then** no "new update" indicator is shown.
---
### User Story 2 - First visit: no indicator (Priority: P2)
A guest who has never visited the event page before (no `updates_last_seen_at` in localStorage) sees the update messages without any "new" badge or indicator.
**Why this priority**: A first-time visitor has not established a baseline; labeling existing updates as "new" would be misleading since they have never seen the event before.
**Independent Test**: Can be tested by opening an event page on a device with no prior localStorage state for that event token, verifying that no unread indicator is shown even if update messages are present.
**Acceptance Scenarios**:
1. **Given** a guest opens an event page for the first time (no `updates_last_seen_at` in localStorage for this event token), **When** the page loads and update messages are present, **Then** no "new update" indicator is shown and `updates_last_seen_at` is initialized to the most recent update timestamp.
---
### User Story 3 - No server read-tracking (Priority: P1)
No server request is made to record that a guest viewed the updates. The read state is purely client-side.
**Why this priority**: Fundamental privacy requirement — tracking which guests have read which updates would be a form of user surveillance, violating the project's privacy statutes.
**Independent Test**: Can be tested by inspecting network traffic when a guest opens the event page, verifying that no "mark as read" or analytics request is sent.
**Acceptance Scenarios**:
1. **Given** a guest opens the event page with unread updates, **When** the page loads and `updates_last_seen_at` is updated in localStorage, **Then** no additional server request is made to record the read event.
---
### Edge Cases
- What happens when all update messages are deleted (US-10a) and a guest reopens the page? The stored `updates_last_seen_at` should remain in localStorage; no indicator is shown since there are no updates to compare against.
- What happens if localStorage is unavailable (private browsing, storage quota exceeded)? The indicator is not shown (degrades gracefully); no error is displayed to the user.
- The `updates_last_seen_at` key is separate from the `last_seen_at` key used in US-9 (field-change highlights). The two mechanisms operate independently.
## Requirements
### Functional Requirements
- **FR-001**: System MUST display a visual indicator (badge or highlighted section) on the event page when the guest has unread update messages, determined by comparing the newest update's timestamp against `updates_last_seen_at` stored in localStorage.
- **FR-002**: System MUST store the `updates_last_seen_at` timestamp in localStorage per event token after each page render, so the indicator clears on subsequent visits.
- **FR-003**: System MUST NOT show a "new update" indicator on a guest's first visit to an event page (when no `updates_last_seen_at` exists in localStorage for that event token).
- **FR-004**: System MUST initialize `updates_last_seen_at` in localStorage on first visit, set to the timestamp of the most recent update (or a sentinel value if no updates exist), to prevent spurious indicators on subsequent visits.
- **FR-005**: System MUST NOT transmit any data to the server when a guest views or is marked as having read update messages — read tracking is purely client-side.
- **FR-006**: System MUST use a localStorage key distinct from the `last_seen_at` key used in US-9 to avoid conflicts between the two read-state mechanisms.
- **FR-007**: System MUST degrade gracefully if localStorage is unavailable: no indicator is shown, and no error is surfaced to the user.
### Key Entities
- **UpdateReadState** (client-side only): Stored in localStorage, keyed by event token. Contains `updates_last_seen_at` (timestamp of the most recent update at last visit). Never transmitted to the server.
## Success Criteria
### Measurable Outcomes
- **SC-001**: A guest who has not visited an event page since a new update was posted sees a visual indicator on their next visit, without any server request being made to track readership.
- **SC-002**: After the event page is rendered, the same guest sees no indicator on their next visit (indicator clears after viewing).
- **SC-003**: A first-time visitor to an event page with existing updates sees no "new" indicator.
- **SC-004**: No network request is sent to the server when the read state transitions from unread to read.
- **SC-005**: The read-state mechanism is independent of US-9's field-change highlight mechanism — toggling one does not affect the other.