docs: add Phase 2 domain verification design and clarifications

Add comprehensive Phase 2 documentation:
- Complete design document for two-factor domain verification
- Implementation guide with code examples
- ADR for implementation decisions (ADR-0004)
- ADR for rel="me" email discovery (ADR-008)
- Phase 1 impact assessment
- All 23 clarification questions answered
- Updated architecture docs (indieauth-protocol, security)
- Updated ADR-005 with rel="me" approach
- Updated backlog with technical debt items

Design ready for Phase 2 implementation.

Generated with Claude Code https://claude.com/claude-code

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

docs/CLARIFICATIONS-ANSWERED.md

@@ -0,0 +1,135 @@
+# Phase 2 Clarifications - Architect's Responses
+
+**Date**: 2024-11-20
+**Status**: All 23 questions answered
+**Developer Action**: Proceed with implementation
+
+## Overview
+
+The Architect has provided complete answers to all 8 categories (23 specific questions) raised by the Developer. This document provides a quick reference to the decisions made.
+
+**Full Details**: See `/docs/designs/phase-2-implementation-guide.md` for complete implementation specifications.
+
+**Architectural Decision Record**: See `/docs/decisions/0004-phase-2-implementation-decisions.md` for rationale and consequences.
+
+## Quick Reference Answers
+
+### 1. Rate Limiting Implementation
+
+**Q: Should actual rate limiting be implemented or leave as stubs?**
+- A: Implement actual rate limiting with in-memory storage
+
+**Q: Should metadata storage use CodeStorage?**
+- A: No, use simple dictionary in RateLimiter service instance
+
+**Q: Should "Max 3 codes per domain per hour" be implemented?**
+- A: Yes, with timestamp list tracking and automatic cleanup
+
+### 2. Authorization Code Metadata Structure
+
+**Q: Should storage include 'used' field in Phase 2?**
+- A: Yes, include now (set to False, consume in Phase 3)
+
+**Q: Use Phase 1's CodeStorage or separate storage?**
+- A: Reuse Phase 1's CodeStorage with key prefix `authz:`
+
+**Q: Store datetime objects or epoch integers?**
+- A: Epoch integers (simpler)
+
+### 3. HTML Template Implementation
+
+**Q: Use Jinja2 or plain Python f-strings?**
+- A: Use Jinja2 templates
+
+**Q: Where should template files be located?**
+- A: `src/gondulf/templates/`
+
+**Q: Reusable layout templates or self-contained?**
+- A: Reusable `base.html` with template inheritance
+
+**Q: Template files vs inline HTML?**
+- A: Separate template files
+
+### 4. Database Migration Timing
+
+**Q: Apply migration 002 as part of Phase 2?**
+- A: Yes, apply immediately before Phase 2 implementation
+
+**Q: Is migration necessary since Phase 1 doesn't write to domains?**
+- A: Yes, keeps schema current with code expectations
+
+**Q: Should new code use 'two_factor' immediately?**
+- A: Yes, assume column exists (migration handles it)
+
+### 5. Client Validation Helper Functions
+
+**Q: Implement as standalone functions or methods on helper class?**
+- A: Standalone functions in `src/gondulf/utils/validation.py`
+
+**Q: Create shared utility module?**
+- A: Yes, `gondulf.utils.validation` module
+
+**Q: Full subdomain validation now or stub for Phase 3?**
+- A: Full validation now (security should be complete)
+
+### 6. Error Response Format Consistency
+
+**Q: Should verification endpoints return JSON (200 OK with success:false)?**
+- A: Yes, always JSON with 200 OK
+
+**Q: Should authorization endpoint errors return HTML or redirects?**
+- A: Depends on validation stage:
+  - Pre-client validation: HTML error page
+  - Post-client validation: OAuth redirect with error
+
+**Q: When to use HTML vs OAuth redirect errors?**
+- A: See decision tree in implementation guide
+
+### 7. Dependency Injection Pattern
+
+**Q: Create dependencies.py module?**
+- A: Yes, `src/gondulf/dependencies.py`
+
+**Q: Services instantiated at startup (singleton) or per-request?**
+- A: Singleton at startup using `@lru_cache()`
+
+**Q: Configuration passed at instantiation or read each time?**
+- A: Read at instantiation (services configured once)
+
+### 8. Test Organization for Authorization Endpoint
+
+**Q: Separate test files per router?**
+- A: Yes:
+  - `test_verification_endpoints.py`
+  - `test_authorization_endpoint.py`
+
+**Q: Test sub-endpoints separately or as part of full flow?**
+- A: Test complete flows (black box testing)
+
+**Q: Shared fixtures for common scenarios?**
+- A: Yes, use `tests/conftest.py` for shared fixtures
+
+## Implementation Priority
+
+All decisions are final and ready for implementation. The Developer should:
+
+1. **Read** `/docs/designs/phase-2-implementation-guide.md` thoroughly
+2. **Review** code examples and patterns provided
+3. **Apply** migration 002 before starting implementation
+4. **Implement** following the exact patterns specified
+5. **Ask** additional questions ONLY if new ambiguities arise
+
+## Architect's Guiding Principles
+
+Every decision made reflects these core values:
+- **Simplicity**: Real implementations using simple patterns
+- **Reuse**: Leverage Phase 1 infrastructure where possible
+- **Standards**: Use established tools (Jinja2, FastAPI patterns)
+- **Clarity**: Explicit structures over implicit behavior
+- **Security**: Complete security features, not stubs
+
+## Status
+
+**DESIGN READY: Phase 2 Implementation - All clarifications resolved**
+
+Developer: Please proceed with implementation following the patterns in the implementation guide.