Chat Application

🏗️ @arch responds with a scoring matrix:

## /agile-explore-brainstorm — Results

### Problem Statement
Real-time bidirectional messaging for multi-user chat rooms.
Constraints: instant delivery, presence awareness, multiple rooms.

### Scoring Matrix

| Approach            | Feasibility | Maintainability | Performance | Risk | Total |
|---------------------|------------|-----------------|-------------|------|-------|
| WebSockets (ws/Socket.io) | 9/10  | 8/10            | 9/10        | 8/10 | 34    |
| SSE + POST fallback | 7/10       | 6/10            | 6/10        | 7/10 | 26    |
| Long polling         | 6/10       | 5/10            | 4/10        | 8/10 | 23    |
| WebTransport         | 5/10       | 5/10            | 10/10       | 4/10 | 24    |

### Recommendation
WebSockets — clear winner for bidirectional chat.

### Why NOT SSE This Time?
In Project 03 (Realtime Dashboard), SSE was the right choice: the server
pushed updates and clients only read. Chat is different — users SEND
messages too. SSE is unidirectional (server → client only). You'd need
a separate POST endpoint for sending, creating unnecessary complexity.

WebSockets give you a single persistent connection for both directions.

### What Would Change This
- If browser support is a hard constraint → SSE + POST fallback
- If you need UDP-like performance → WebTransport (experimental)

💬 "Set up the project with WebSocket support and a test framework.
    Then run /agile-setup-init to populate the memory."

→ @dev scaffolds: package.json, src/, WebSocket server setup, test config
→ /agile-setup-init scans and populates memory files
→ /agile-setup-onboard generates coding rules
→ /agile-setup-health → ✅ All checks pass

💬 /agile-story-create I need users to register with a username
   and password so they can be identified in chat rooms
   → @po creates US-001: "User registration" (3 pts)

💬 /agile-story-create I need users to create new chat rooms
   with a name and join existing rooms
   → @po creates US-002: "Create and join rooms" (3 pts)

💬 /agile-story-create I need users to send messages in a room
   and have them appear instantly for all room members via WebSocket
   → @po creates US-003: "Send and receive messages" (5 pts)

💬 /agile-story-create I need to see the message history when
   joining a room so I can catch up on the conversation
   → @po creates US-004: "Message history" (2 pts)

🔄 @sm facilitates:

## Sprint Planning Output

### Sprint Goal
"Deliver a working chat app with rooms, messaging, and history"

### Sprint Backlog
| Story  | Title                    | Points | Priority |
|--------|--------------------------|--------|----------|
| US-001 | User registration        | 3      | P1       |
| US-002 | Create and join rooms    | 3      | P1       |
| US-003 | Send and receive messages | 5      | P1       |
| US-004 | Message history          | 2      | P1       |

### Capacity
- Committed: 13 points
- Sprint duration: 1 week

/agile-code-branch feature US-001 user-registration
/agile-story-plan US-001
/agile-code-tdd US-001
  🔴 Test: POST /auth/register creates user → ❌
  🟢 Implement registration with hashed password → ✅
  🔴 Test: duplicate username returns 409 → ❌
  🟢 Add unique constraint check → ✅
  🔴 Test: missing fields return 400 → ❌
  🟢 Add validation → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(auth): add user registration endpoint
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved (🟡 S2: extract validation to middleware)
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

/agile-code-branch feature US-002 rooms
/agile-story-plan US-002
/agile-code-tdd US-002
  🔴 Test: POST /rooms creates a room → ❌
  🟢 Implement room creation → ✅
  🔴 Test: POST /rooms/:id/join adds user to room → ❌
  🟢 Implement join with WebSocket room subscription → ✅
  🔴 Test: joining nonexistent room returns 404 → ❌
  🟢 Add room existence check → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(rooms): add create and join room endpoints
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

/agile-code-branch feature US-003 messaging
/agile-story-plan US-003
/agile-code-tdd US-003
  🔴 Test: WebSocket message in room broadcasts to all members → ❌
  🟢 Implement message broadcast via WebSocket → ✅
  🔴 Test: message persists to database → ❌
  🟢 Add message persistence layer → ✅
  🔴 Test: message to room user hasn't joined is rejected → ❌
  🟢 Add room membership check → ✅
  🔴 Test: message includes sender, timestamp, content → ❌
  🟢 Add message envelope format → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(messages): add real-time messaging via WebSocket
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved (🟡 S2: consider message size limit)
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (5 points)

/agile-code-branch feature US-004 message-history
/agile-story-plan US-004
/agile-code-tdd US-004
  🔴 Test: GET /rooms/:id/messages returns last 50 messages → ❌
  🟢 Implement paginated message history → ✅
  🔴 Test: empty room returns empty array → ❌
  🟢 Handle edge case → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(messages): add message history endpoint
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (2 points)

/agile-sprint-review
  Sprint Goal: "Deliver a working chat app with rooms, messaging, and history"
  Sprint Goal Met: ✅ Yes
  Velocity: 13/13 points (100%)

/agile-sprint-retro
  What went well: WebSocket architecture clean, TDD caught edge cases
  To improve: Need encoding tests for user input fields
  Action items: add input sanitization tests in Sprint 2

/agile-memory-learn → Saved Sprint 1 learnings

/agile-ship-changelog
  ## Changelog: v1.0.0
  ### Added
  - User registration with secure password hashing (US-001)
  - Create and join chat rooms (US-002)
  - Real-time messaging via WebSockets (US-003)
  - Message history with pagination (US-004)

/agile-ship-release v1.0.0
  🚀 @devops: Release v1.0.0
    Branch: release/v1.0.0 from develop
    CI: ✅ Green
    Merged to main ✅
    Tagged: v1.0.0 ✅
    Back-merged to develop ✅

/agile-ship-deploy
  🚀 @devops: Deployed v1.0.0
    Smoke tests: ✅ All endpoints responding
    WebSocket connections: ✅ Healthy
    Health check: ✅

🔄 @sm assesses:

## Incident Assessment

Severity: S0 — CRITICAL
Impact: App crashes for affected users. Any room with non-ASCII
characters in the name is unusable. Server restarts but crashes
again on next message to affected rooms.

Decision: Trigger the hotfix workflow immediately.
Do NOT wait for Sprint 2 planning. This is a production emergency.

⌨️ @dev: Hotfix branch created
  Branch: hotfix/crash-special-chars
  From: main (v1.0.0)
  Linked to: INCIDENT-001

🔴 RED — Write a test that reproduces the crash

// test/hotfix-special-chars.test.js
test('sending a message to a room with emoji name should succeed', async () => {
  const room = await createRoom({ name: 'cafe-☕' });
  const ws = await connectToRoom(room.id, testUser);

  const response = await sendMessage(ws, {
    roomId: room.id,
    content: 'Hello from the cafe!'
  });

  expect(response.status).toBe('delivered');
  expect(response.content).toBe('Hello from the cafe!');
});

// Result: ❌ FAIL — TypeError: Cannot read properties of undefined
// (reading 'normalize') — the room name encoding crashes
// the message routing lookup

🟢 GREEN — Fix the encoding issue (minimal fix)

// src/rooms/normalize.js — BEFORE (broken)
function normalizeRoomName(name) {
  return name.toLowerCase().replace(/[^a-z0-9-]/g, '');
}

// src/rooms/normalize.js — AFTER (fixed)
function normalizeRoomName(name) {
  return name.normalize('NFC').toLowerCase();
}

// The bug: the old regex stripped ALL non-ASCII characters,
// turning "cafe-☕" into "cafe-" which then failed to match
// the stored room ID in the WebSocket routing table.

// Result: ✅ PASS

/agile-code-ci
  🚀 @devops: CI Pipeline Results
    Build:    ✅
    Tests:    ✅ 24/24 passing (including new hotfix test)
    Lint:     ✅ 0 errors
    Security: ✅ No vulnerabilities

All existing tests still pass — the fix doesn't introduce regressions.

/agile-code-pr-review

👨‍💻 @lead: EXPEDITED Hotfix Review (30 min max, not 24 hours)

| # | Check                          | Status |
|---|--------------------------------|--------|
| 1 | Does it fix the reported issue? | ✅     |
| 2 | Is the fix minimal?            | ✅ (2 lines changed) |
| 3 | Does it introduce regressions? | ✅ No (all 24 tests pass) |
| 4 | Is the new test adequate?      | ✅ Covers the exact scenario |

Score: 9/10
Verdict: ✅ APPROVED — ship it

/agile-code-merge

⌨️ @dev: Hotfix merge complete
  1. Merged hotfix/crash-special-chars → main ✅
  2. Tagged: v1.0.1 ✅
  3. Merged hotfix/crash-special-chars → develop ✅
  4. Branch hotfix/crash-special-chars deleted

/agile-ship-deploy

🚀 @devops: Deployed v1.0.1
  Smoke tests: ✅ All endpoints responding
  Hotfix verification: ✅ Room "cafe-☕" — messages delivered
  Health check: ✅
  WebSocket connections: ✅ Stable

## /agile-ship-rollback — Emergency Rollback

🚀 @devops executes:
  1. Rolling back to: v1.0.0
  2. Deploy v1.0.0: ✅ Complete
  3. Health checks: ✅ All passing
  4. WebSocket connections: ✅ Re-established
  5. 500 errors: ✅ Resolved

### Status
- Production is back on v1.0.0
- The original bug (special chars) still exists
- Team has time to investigate why the hotfix deploy failed

### Next Steps
- Debug the deployment issue (not the code fix)
- Re-attempt deploy after fixing deployment config

## Blameless Post-Mortem — INCIDENT-001

### Timeline
- Day 0: v1.0.0 deployed. All smoke tests pass.
- Day 2: First user report — room "cafe-☕" crashes on message send.
- Day 2 + 1h: Incident triaged as S0.
- Day 2 + 2h: Hotfix branch created, test written, fix applied.
- Day 2 + 3h: Expedited review approved. v1.0.1 deployed.
- Day 2 + 3.5h: Verified fix in production. Incident closed.

### Root Cause
UTF-8 encoding not handled in room name normalization.
The normalizeRoomName() function used a regex that stripped
all non-ASCII characters, breaking the room ID lookup for
any room with emojis, accents, or other Unicode characters.

### Why It Wasn't Caught
- No test cases used non-ASCII characters in room names
- Smoke tests only used ASCII room names
- No fuzzing or Unicode-aware input testing

### Action Items
| # | Action                                           | Owner | Due       |
|---|--------------------------------------------------|-------|-----------|
| 1 | Add encoding tests for ALL user-input fields     | @qa   | Sprint 2  |
| 2 | Add monitoring/alerting for crash rate spikes     | @devops | Sprint 2 |
| 3 | Add Unicode room names to smoke test suite        | @dev  | Sprint 2  |
| 4 | Review all string normalization functions          | @lead | Sprint 2  |

💬 /agile-story-create I need to show which users are currently
   online in a room so people know who's available to chat
   → @po creates US-005: "Online presence indicators" (3 pts)

💬 /agile-story-create I need users to react to messages
   with emoji reactions (like 👍, ❤️, 😂) without sending
   a separate message
   → @po creates US-006: "Message reactions" (2 pts)

💬 /agile-story-create I need users to receive notifications
   when new messages arrive in rooms they've joined but aren't
   currently viewing
   → @po creates US-007: "Room notifications" (5 pts)

🔄 @sm facilitates:

## Sprint 2 Planning

### Sprint Goal
"Add presence, reactions, and notifications to enhance the chat experience"

### Sprint Backlog
| Story  | Title                   | Points | Priority |
|--------|-------------------------|--------|----------|
| US-005 | Online presence         | 3      | P1       |
| US-006 | Message reactions       | 2      | P1       |
| US-007 | Room notifications      | 5      | P1       |

### Capacity
- Velocity (Sprint 1): 13 points
- Committed: 10 points (conservative — accounting for incident overhead)

### Notes
- Post-mortem action items (encoding tests, monitoring) are
  technical tasks, not stories — woven into Sprint 2 work

/agile-code-branch feature US-005 online-presence
/agile-story-plan US-005
/agile-code-tdd US-005
  🔴 Test: joining room broadcasts "user joined" to members → ❌
  🟢 Implement presence events on WebSocket connect → ✅
  🔴 Test: leaving room broadcasts "user left" → ❌
  🟢 Implement disconnect detection with heartbeat → ✅
  🔴 Test: GET /rooms/:id/members returns online users → ❌
  🟢 Implement members endpoint → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(presence): add online presence indicators
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

/agile-code-branch feature US-006 reactions
/agile-story-plan US-006
/agile-code-tdd US-006
  🔴 Test: adding reaction to message broadcasts to room → ❌
  🟢 Implement reaction WebSocket events → ✅
  🔴 Test: message includes reaction counts in history → ❌
  🟢 Add reaction aggregation to message query → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(reactions): add emoji reactions to messages
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (2 points)

🛡️ @sec responds:

## /agile-security-review — WebSocket Auth Review

### Findings

| # | Severity | Finding                                    | Risk                        |
|---|----------|--------------------------------------------|-----------------------------|
| 1 | 🔴 S0   | Missing token validation on WS upgrade     | Any client can connect      |
|   |          | handshake — auth only checked on HTTP       | without authentication      |
|   |          | endpoints, not on WebSocket connection      |                             |
| 2 | 🟡 S2   | No token expiry check on long-lived WS     | Revoked tokens remain       |
|   |          | connections                                 | active until disconnect     |
| 3 | 🟡 S2   | Room membership not re-validated on         | Users could receive         |
|   |          | reconnect                                   | messages from left rooms    |

### Required Before Sprint 2 Release
Fix #1 is mandatory — S0 security finding.

### Recommendation
Add JWT validation to the WebSocket upgrade handshake.
Reject connections with invalid/missing/expired tokens
BEFORE the upgrade completes.

/agile-code-tdd Fix S0: validate JWT on WebSocket upgrade handshake

🔴 RED:
test('WS connection without token is rejected', async () => {
  const ws = new WebSocket('ws://localhost:3000/chat');
  await expect(waitForOpen(ws)).rejects.toThrow('401');
});
// ❌ FAIL — connection succeeds without token

🟢 GREEN:
// src/websocket/auth.js
server.on('upgrade', (request, socket, head) => {
  const token = parseToken(request);
  if (!token || !verifyJWT(token)) {
    socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
    socket.destroy();
    return;
  }
  // ... proceed with upgrade
});
// ✅ PASS

/agile-code-ci → ✅ All green (including existing WS tests updated with auth)

/agile-code-branch feature US-007 notifications
/agile-story-plan US-007
/agile-code-tdd US-007
  🔴 Test: user receives notification for message in joined room → ❌
  🟢 Implement notification dispatch via WebSocket → ✅
  🔴 Test: no notification for room user is currently viewing → ❌
  🟢 Track active room per connection → ✅
  🔴 Test: notification includes room name, sender, preview → ❌
  🟢 Add notification payload format → ✅
  🔴 Test: unread count increments per room → ❌
  🟢 Add unread counter per user per room → ✅
/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(notifications): add room notifications with unread counts
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (5 points)

/agile-sprint-review
  Sprint Goal Met: ✅ Yes
  Velocity: 10/10 points (100%)

/agile-sprint-retro
  What went well: Security review caught critical auth gap before release
  What went well: Post-mortem action items all addressed
  To improve: Should run /agile-security-review earlier in the sprint
  Action items: security review in Sprint 0 for future projects

/agile-memory-learn → Saved Sprint 2 learnings

/agile-ship-changelog
  ## Changelog: v1.1.0
  ### Added
  - Online presence indicators (US-005)
  - Emoji reactions on messages (US-006)
  - Room notifications with unread counts (US-007)
  ### Fixed
  - JWT validation on WebSocket upgrade handshake (Security)

/agile-ship-release v1.1.0
  🚀 @devops: Release v1.1.0
    Tagged: v1.1.0 ✅
    Merged to main ✅
    Back-merged to develop ✅

/agile-ship-deploy
  🚀 @devops: Deployed v1.1.0
    Smoke tests: ✅ (now includes Unicode room names!)
    Health check: ✅