# StarPunk V1 Implementation Plan

## Overview

This document provides a comprehensive, dependency-ordered implementation plan for StarPunk V1, taking the project from its current state to a fully functional IndieWeb CMS.

**Current State**: V1.1.0 Released - Full-text search, custom slugs, and RSS fixes
**Current Version**: 1.1.0 "SearchLight"
**Target State**: Working V1 with all features implemented, tested, and documented
**Estimated Total Effort**: ~40-60 hours of focused development
**Completed Effort**: ~35 hours (Phases 1-5 mostly complete)
**Remaining Effort**: ~15-25 hours (Micropub, REST API optional, QA)

## Progress Summary

**Last Updated**: 2025-11-25

### Completed Phases ✅

| Phase | Status | Version | Test Coverage | Report |
|-------|--------|---------|---------------|--------|
| 1.1 - Core Utilities | ✅ Complete | 0.1.0 | >90% | N/A |
| 1.2 - Data Models | ✅ Complete | 0.1.0 | >90% | N/A |
| 2.1 - Notes Management | ✅ Complete | 0.3.0 | 86% (85 tests) | [Phase 2.1 Report](/home/phil/Projects/starpunk/docs/reports/phase-2.1-implementation-20251118.md) |
| 3.1 - Authentication | ✅ Complete | 0.8.0 | 96% (51 tests) | [Phase 3 Report](/home/phil/Projects/starpunk/docs/reports/phase-3-authentication-20251118.md) |
| 4.1-4.4 - Web Interface | ✅ Complete | 0.5.2 | 87% (405 tests) | Phase 4 implementation |
| 5.1-5.2 - RSS Feed | ✅ Complete | 0.6.0 | 96% | ADR-014, ADR-015 |
| 6 - Micropub | ✅ Complete | 1.0.0 | 95% | [v1.0.0 Release](/home/phil/Projects/starpunk/docs/reports/v1.0.0-implementation-report.md) |
| V1.1 - Search & Enhancements | ✅ Complete | 1.1.0 | 598 tests | [v1.1.0 Report](/home/phil/Projects/starpunk/docs/reports/v1.1.0-implementation-report.md) |

### Current Status 🔵

**V1.1.0 RELEASED** - StarPunk "SearchLight"
- **Status**: ✅ COMPLETE - Released 2025-11-25
- **Major Features**: Full-text search, custom slugs, RSS fixes
- **Test Coverage**: 598 tests (588 passing)
- **Backwards Compatible**: 100%

### Completed V1 Features ✅

All core V1 features are now complete:
- ✅ IndieAuth authentication
- ✅ Micropub endpoint (v1.0.0)
- ✅ Notes management CRUD
- ✅ RSS feed generation
- ✅ Web interface (public & admin)
- ✅ Full-text search (v1.1.0)
- ✅ Custom slugs (v1.1.0)
- ✅ Database migrations

### Optional Features (Not Required for V1)

| Feature | Estimated Effort | Priority | Status |
|---------|-----------------|----------|---------|
| REST API (Notes CRUD) | 3-4 hours | LOW | ⏳ DEFERRED to v1.2.0 |
| Enhanced Documentation | 5-7 hours | MEDIUM | ⏳ ONGOING |
| Performance Optimization | 3-5 hours | LOW | ⏳ As needed |

**Overall Progress**: ✅ **100% V1 COMPLETE** - All required features implemented

---

## V1 Features Implementation Status

All V1 required features have been successfully implemented:

### 1. Micropub Endpoint ✅
**Status**: IMPLEMENTED (v1.0.0)
**Routes**: `/api/micropub` fully functional
**Features**: Create notes, mp-slug support, IndieAuth integration
**Testing**: Comprehensive test suite, Micropub.rocks validated

### 2. IndieAuth Integration ✅
**Status**: IMPLEMENTED (v1.0.0)
**Features**: Authorization endpoint, token verification
**Integration**: Works with IndieLogin.com and other providers
**Security**: Token validation, PKCE support

### 3. RSS Feed Generation ✅
**Status**: IMPLEMENTED (v0.6.0, fixed in v1.1.0)
**Route**: `/feed.xml` active and working
**Features**: Valid RSS 2.0, newest-first ordering
**Validation**: W3C feed validator passed

### 4. Full-Text Search ✅
**Status**: IMPLEMENTED (v1.1.0)
**Features**: SQLite FTS5, search UI, API endpoint
**Routes**: `/search`, `/api/search`
**Security**: XSS prevention, query validation

### 5. Custom Slugs ✅
**Status**: IMPLEMENTED (v1.1.0)
**Features**: Micropub mp-slug support
**Validation**: Reserved slug protection, sanitization
**Integration**: Seamless with existing slug generation

---

## Implementation Strategy

1. **Bottom-up approach**: Build foundation modules before features that depend on them
2. **Feature completeness**: Implement each feature fully (code + tests + docs) before moving to the next
3. **Continuous validation**: Test integration points as we build
4. **Documentation alongside code**: Update docs as implementation progresses

---

## Phase 1: Core Utilities and Models (Foundation)

These utilities are used by all other features. Must be implemented first.

### 1.1 Utility Functions (`starpunk/utils.py`)

**Status**: ✅ COMPLETE
**Priority**: CRITICAL - Required by all other features
**Estimated Effort**: 2-3 hours
**Actual Effort**: ~2 hours
**Completed**: 2025-11-18
**Dependencies**: None

- [x] Implement slug generation function
  - Extract first 5 words from content
  - Normalize to lowercase with hyphens
  - Remove special characters, preserve alphanumeric + hyphens
  - Fallback to timestamp-based slug if content too short
  - Check uniqueness against database
  - Add random suffix if slug exists
  - **References**: ADR-004 (File-Based Storage), ADR-007 (Slug Generation)
  - **Acceptance Criteria**: ✅ Generates valid, unique, URL-safe slugs

- [x] Implement content hash calculation
  - Use SHA-256 algorithm
  - Return hex digest string
  - Handle UTF-8 encoding properly
  - **Acceptance Criteria**: ✅ Consistent hashes for same content

- [x] Implement file path helpers
  - Generate year/month directory structure from timestamp
  - Build file paths: `data/notes/YYYY/MM/slug.md`
  - Validate paths (prevent directory traversal)
  - Ensure paths stay within DATA_PATH
  - **References**: ADR-004, architecture/security.md
  - **Acceptance Criteria**: ✅ Safe path generation and validation

- [x] Implement atomic file operations
  - Write to temp file first (`.tmp` suffix)
  - Atomic rename to final destination
  - Handle errors with rollback
  - Create parent directories if needed
  - **References**: ADR-004
  - **Acceptance Criteria**: ✅ Files written safely without corruption risk

- [x] Implement date/time utilities
  - RFC-822 date formatting (for RSS)
  - ISO 8601 formatting (for timestamps)
  - Timezone handling (UTC)
  - **Acceptance Criteria**: ✅ Correct date formatting for all use cases

- [x] Implement URL validation utility (`is_valid_url()`)
  - Added in Phase 3 for authentication
  - Validates HTTP/HTTPS URLs
  - **Acceptance Criteria**: ✅ Validates URLs correctly

- [x] Write comprehensive tests (`tests/test_utils.py`)
  - Test slug generation with various inputs
  - Test uniqueness enforcement
  - Test content hash consistency
  - Test path validation (including security tests)
  - Test atomic file operations
  - Test date formatting
  - **Result**: ✅ All tests passing with excellent coverage

**Completion Criteria**: ✅ All utility functions implemented and tested with >90% coverage

---

### 1.2 Data Models (`starpunk/models.py`)

**Status**: ✅ COMPLETE
**Priority**: CRITICAL - Used by all feature modules
**Estimated Effort**: 3-4 hours
**Actual Effort**: ~3 hours
**Completed**: 2025-11-18
**Dependencies**: `utils.py`

- [x] Implement `Note` model class
  - Properties: id, slug, file_path, published, created_at, updated_at, content_hash
  - Method: `from_row()` - Create Note from database row
  - Method: `to_dict()` - Serialize to dictionary
  - Property: `content` - Lazy load from file
  - Property: `html` - Render markdown to HTML (cached)
  - Method: `permalink()` - Generate public URL
  - **References**: ADR-004, architecture/overview.md
  - **Acceptance Criteria**: ✅ Clean interface for note data access

- [x] Implement `Session` model class
  - Properties: id, session_token_hash, me, created_at, expires_at, last_used_at, user_agent, ip_address
  - Method: `from_row()` - Create Session from database row
  - Property: `is_expired` - Check if session expired
  - Method: `is_valid()` - Comprehensive validation
  - **References**: ADR-005, ADR-010
  - **Note**: Uses token hash instead of plaintext for security
  - **Acceptance Criteria**: ✅ Session validation works correctly

- [x] Implement `Token` model class (Micropub)
  - Properties: token, me, client_id, scope, created_at, expires_at
  - Method: `from_row()` - Create Token from database row
  - Property: `is_expired` - Check if token expired
  - Method: `has_scope()` - Check if token has required scope
  - **References**: Micropub spec
  - **Note**: Ready for Phase 6 implementation
  - **Acceptance Criteria**: ✅ Token scope checking works

- [x] Implement `AuthState` model class
  - Properties: state, created_at, expires_at, redirect_uri
  - Method: `from_row()` - Create AuthState from database row
  - Property: `is_expired` - Check if state expired
  - **References**: ADR-005, ADR-010
  - **Acceptance Criteria**: ✅ State token validation works

- [x] Write model tests (`tests/test_models.py`)
  - Test all model creation methods
  - Test property access
  - Test expiration logic
  - Test serialization/deserialization
  - Test edge cases (None values, invalid data)
  - **Result**: ✅ All tests passing with excellent coverage

**Completion Criteria**: ✅ All models implemented with clean interfaces and full test coverage

---

## Phase 2: Notes Management (Core Feature)

This is the heart of the application. File operations + database sync.

### 2.1 Notes Module (`starpunk/notes.py`)

**Status**: ✅ COMPLETE
**Priority**: CRITICAL - Core functionality
**Estimated Effort**: 6-8 hours
**Actual Effort**: ~6 hours
**Completed**: 2025-11-18
**Dependencies**: `utils.py`, `models.py`, `database.py`
**Test Coverage**: 86% (85 tests passing)

- [x] Implement `create_note()` function
  - Accept: content (markdown), published (boolean), created_at (optional)
  - Generate unique slug using utils
  - Determine file path (year/month from timestamp)
  - Create directory structure if needed
  - Write markdown file atomically
  - Calculate content hash
  - Begin database transaction
  - Insert note record with metadata
  - If DB insert fails: delete file, raise error
  - If successful: commit transaction, return Note object
  - **References**: ADR-004, docs/reports/phase-2.1-implementation-20251118.md
  - **Acceptance Criteria**: ✅ Note created with file + database entry in sync

- [x] Implement `get_note()` function
  - Accept: slug (string) or id (int)
  - Query database for note metadata
  - If not found: return None
  - Read file content from disk
  - Verify content hash (optional, log if mismatch)
  - Return Note object with content loaded
  - **References**: ADR-004
  - **Acceptance Criteria**: ✅ Note retrieved with content from file

- [x] Implement `list_notes()` function
  - Accept: published_only (boolean), limit (int), offset (int)
  - Query database with filters and sorting (created_at DESC)
  - Return list of Note objects (metadata only, no content)
  - Support pagination
  - SQL injection prevention (validated order_by field)
  - **References**: ADR-004
  - **Acceptance Criteria**: ✅ Efficient listing with proper filtering

- [x] Implement `update_note()` function
  - Accept: slug or id, new content, published status
  - Query database for existing note
  - Write new content to file atomically
  - Calculate new content hash
  - Update database record (updated_at, content_hash, published)
  - Return updated Note object
  - **References**: ADR-004
  - **Acceptance Criteria**: ✅ Note updated safely with sync maintained

- [x] Implement `delete_note()` function
  - Accept: slug or id, hard_delete (boolean, default False)
  - Query database for note
  - If soft delete: update deleted_at timestamp, optionally move file to .trash/
  - If hard delete: delete database record, delete file
  - Idempotent operation (safe to call multiple times)
  - **References**: ADR-004
  - **Acceptance Criteria**: ✅ Note deleted (soft or hard) correctly

- [ ] Implement `search_notes()` function (optional for V1)
  - Accept: query string
  - Search file content using grep or Python search
  - Return matching Note objects
  - **Priority**: LOW - Deferred to V2
  - **Status**: Not implemented in Phase 2.1
  - **Acceptance Criteria**: N/A - Deferred

- [x] Handle edge cases
  - Orphaned files (file exists, no DB record)
  - Orphaned records (DB record exists, no file)
  - File read/write errors
  - Permission errors
  - Disk full errors
  - **References**: architecture/security.md
  - **Result**: ✅ Comprehensive error handling implemented

- [x] Implement custom exceptions
  - `NoteError` - Base exception
  - `NoteNotFoundError` - Note not found
  - `InvalidNoteDataError` - Invalid data
  - `NoteSyncError` - Sync failure
  - **Result**: ✅ Complete exception hierarchy

- [x] Write comprehensive tests (`tests/test_notes.py`)
  - Test create with various content
  - Test slug uniqueness enforcement
  - Test file/database sync
  - Test get by slug and id
  - Test list with filters and pagination
  - Test update operations
  - Test delete (soft and hard)
  - Test error handling (DB failure, file failure)
  - Test edge cases (empty content, very long content, special characters)
  - Integration test: create → read → update → delete cycle
  - **Result**: ✅ 85 tests, 86% coverage, all passing

**Completion Criteria**: ✅ Full CRUD operations working with file+database sync, comprehensive tests passing

**Report**: See `/home/phil/Projects/starpunk/docs/reports/phase-2.1-implementation-20251118.md`

---

## Phase 3: Authentication (IndieLogin)

Implements the IndieLogin OAuth flow for admin access.

### 3.1 Authentication Module (`starpunk/auth.py`)

**Status**: ✅ COMPLETE
**Priority**: HIGH - Required for admin interface
**Estimated Effort**: 5-6 hours
**Actual Effort**: ~5 hours
**Completed**: 2025-11-18
**Dependencies**: `models.py`, `database.py`, `httpx` library
**Test Coverage**: 96% (37 tests passing)

- [x] Implement state token management
  - Helper functions for state token generation and verification
  - Single-use tokens with 5-minute expiry
  - Automatic cleanup of expired tokens
  - **References**: ADR-005, ADR-010
  - **Acceptance Criteria**: ✅ State tokens prevent CSRF attacks

- [x] Implement session token management
  - `create_session()` - Create session with SHA-256 hashed token
  - `verify_session()` - Validate session and check expiration
  - `destroy_session()` - Delete session (logout)
  - Session metadata tracking (user_agent, ip_address)
  - Automatic cleanup of expired sessions
  - 30-day expiry with activity-based refresh
  - **References**: ADR-005, ADR-010, architecture/security.md
  - **Note**: Uses token hashing for security (never stores plaintext)
  - **Acceptance Criteria**: ✅ Sessions work for 30 days, extend on use

- [x] Implement IndieLogin OAuth flow
  - `initiate_login()` - Build authorization URL, store state
    - Validates 'me' URL format using `is_valid_url()`
    - Generates cryptographically secure state token
    - Stores state in database with 5-minute expiry
    - Builds indielogin.com authorization URL
    - Returns authorization URL for redirect
  - `handle_callback()` - Exchange code for identity
    - Verifies state token (CSRF check, single-use)
    - POSTs to indielogin.com/auth with code
    - Validates HTTP response (200 OK)
    - Extracts 'me' from JSON response
    - Verifies 'me' matches ADMIN_ME config
    - Creates session if authorized
    - Returns session token for cookie setting
  - **References**: ADR-005, ADR-010, IndieLogin API docs
  - **Acceptance Criteria**: ✅ Full OAuth flow works with indielogin.com

- [x] Implement authentication decorator
  - `require_auth()` - Decorator for protected routes
  - Extracts session token from cookie
  - Validates session using `verify_session()`
  - Stores user info in Flask `g.user`
  - Returns 401/redirect if not authenticated
  - **Acceptance Criteria**: ✅ Protects admin routes correctly

- [x] Implement custom exceptions
  - `AuthError` - Base exception
  - `InvalidStateError` - CSRF validation failed
  - `UnauthorizedError` - User not authorized
  - `IndieLoginError` - External service error
  - **Result**: ✅ Complete exception hierarchy

- [x] Error handling
  - Invalid state token rejection
  - IndieLogin API error handling
  - Network timeout handling (10s timeout)
  - Unauthorized user rejection (wrong 'me')
  - Expired session handling
  - Comprehensive logging for all auth events
  - **References**: architecture/security.md, ADR-010
  - **Result**: ✅ Comprehensive error handling

- [x] Write comprehensive tests (`tests/test_auth.py`)
  - Test state token generation and validation
  - Test session creation and validation
  - Test session expiry
  - Mock IndieLogin API responses
  - Test full OAuth flow (integration test with mocked API)
  - Test CSRF protection (invalid state)
  - Test unauthorized user rejection (wrong 'me')
  - Test session cookie security (HttpOnly, Secure flags)
  - Test logout functionality
  - Test decorator on protected routes
  - **Result**: ✅ 37 tests, 96% coverage, all passing

**Completion Criteria**: ✅ Authentication works end-to-end, all security measures tested

**Report**: See `/home/phil/Projects/starpunk/docs/reports/phase-3-authentication-20251118.md`

**New ADRs**: ADR-010 (Authentication Module Design)

---

## Phase 4: Web Routes and Templates

User-facing interface (public site + admin interface).

**Status**: 🔵 IN PROGRESS - Design complete, ready for implementation
**Design Complete**: 2025-11-18
**Documentation**:
- `/home/phil/Projects/starpunk/docs/design/phase-4-web-interface.md`
- `/home/phil/Projects/starpunk/docs/reports/phase-4-architectural-assessment-20251118.md`
- `/home/phil/Projects/starpunk/docs/decisions/ADR-011-development-authentication-mechanism.md`

**Key Decisions**:
- Development authentication mechanism approved (ADR-011)
- Template structure defined
- Route organization finalized
- CSS architecture specified

**Target Version**: 0.5.0

### 4.1 Public Routes Blueprint (`starpunk/routes/public.py`)

**Status**: ⏳ NOT STARTED
**Priority**: HIGH - Public interface
**Estimated Effort**: 3-4 hours
**Dependencies**: `notes.py`, `models.py`

Note: Create `starpunk/routes/` directory first

- [ ] Create routes module structure
  - Create `starpunk/routes/__init__.py`
  - Create `starpunk/routes/public.py`
  - Create `starpunk/routes/admin.py`
  - Create `starpunk/routes/api.py`

- [ ] Implement homepage route (`/`)
  - GET handler
  - List published notes (limit 20, newest first)
  - Render `templates/index.html`
  - Pass notes to template
  - **Acceptance Criteria**: Homepage displays recent published notes

- [ ] Implement note permalink route (`/note/<slug>`)
  - GET handler
  - Retrieve note by slug
  - Check if published (404 if not published)
  - Render `templates/note.html`
  - Pass note with rendered HTML content
  - **Acceptance Criteria**: Individual notes display correctly

- [ ] Register blueprint in `starpunk/__init__.py`
  - Import public blueprint
  - Register with app
  - **Acceptance Criteria**: Routes are accessible

- [ ] Write route tests
  - Test homepage returns 200
  - Test homepage lists published notes only
  - Test note permalink returns 200 for published note
  - Test note permalink returns 404 for unpublished note
  - Test note permalink returns 404 for non-existent note

**Completion Criteria**: Public routes work, return correct content

---

### 4.2 Admin Routes Blueprint (`starpunk/routes/admin.py`)

**Priority**: HIGH - Admin interface
**Estimated Effort**: 4-5 hours
**Dependencies**: `auth.py`, `notes.py`

- [ ] Implement login routes
  - GET `/admin/login` - Display login form
  - POST `/admin/login` - Initiate IndieLogin flow
  - GET `/auth/callback` - Handle IndieLogin callback
  - POST `/admin/logout` - Logout and clear session
  - **References**: ADR-005
  - **Acceptance Criteria**: Authentication flow works

- [ ] Implement admin dashboard (`/admin`)
  - GET handler (protected with `@require_auth`)
  - List all notes (published and drafts)
  - Show note count, recent activity
  - Render `templates/admin/dashboard.html`
  - **Acceptance Criteria**: Dashboard shows all notes

- [ ] Implement create note routes (`/admin/new`)
  - GET handler - Display note creation form
  - POST handler - Create note from form data
  - Extract content and published status
  - Call `create_note()`
  - Redirect to dashboard on success
  - Show errors on failure
  - **Acceptance Criteria**: Can create notes via web form

- [ ] Implement edit note routes (`/admin/edit/<slug>`)
  - GET handler - Display edit form with existing content
  - POST handler - Update note
  - Call `update_note()`
  - Redirect to dashboard on success
  - Show errors on failure
  - **Acceptance Criteria**: Can edit notes via web form

- [ ] Implement delete note route (`/admin/delete/<slug>`)
  - POST handler - Delete note
  - Confirm deletion (soft delete by default)
  - Call `delete_note()`
  - Redirect to dashboard
  - **Acceptance Criteria**: Can delete notes

- [ ] Register blueprint in `starpunk/__init__.py`
  - Import admin blueprint
  - Register with app
  - **Acceptance Criteria**: Admin routes accessible

- [ ] Write route tests
  - Test login flow (with mocked IndieLogin)
  - Test authentication required for admin routes
  - Test dashboard displays notes
  - Test create note form submission
  - Test edit note form submission
  - Test delete note
  - Test logout

**Completion Criteria**: Admin interface fully functional, authentication working

---

### 4.3 HTML Templates

**Priority**: HIGH - Required for web interface
**Estimated Effort**: 6-8 hours
**Dependencies**: None (can be done in parallel with routes)

#### Base Templates

- [ ] Implement `templates/base.html`
  - HTML5 semantic structure
  - Meta tags (charset, viewport)
  - Link to stylesheet (`/static/css/style.css`)
  - Navigation (home, admin)
  - Content block (`{% block content %}`)
  - Footer with attribution
  - **Microformats**: h-card for site author
  - **References**: ADR-003, architecture/overview.md
  - **Acceptance Criteria**: Clean, semantic HTML base template

- [ ] Implement `templates/admin/base.html`
  - Extends base or separate admin layout
  - Admin navigation (dashboard, new note, logout)
  - Admin-specific styling
  - Flash message display
  - **Acceptance Criteria**: Consistent admin layout

#### Public Templates

- [ ] Implement `templates/index.html`
  - Extends `base.html`
  - Display list of notes
  - Each note: title (first line), excerpt, timestamp, permalink
  - Pagination controls (if >20 notes)
  - **Microformats**: h-feed with h-entry for each note
  - **References**: Microformats2 spec
  - **Acceptance Criteria**: Homepage displays notes with proper markup

- [ ] Implement `templates/note.html`
  - Extends `base.html`
  - Display full note content (rendered HTML)
  - Timestamp, permalink
  - **Microformats**: h-entry with e-content, dt-published
  - **References**: Microformats2 h-entry spec
  - **Acceptance Criteria**: Note displays with proper semantic markup

#### Admin Templates

- [ ] Implement `templates/admin/login.html`
  - Simple form asking for website URL
  - Input for 'me' URL
  - Submit button
  - Explanation of IndieLogin
  - **Acceptance Criteria**: Clean login form

- [ ] Implement `templates/admin/dashboard.html`
  - Extends `admin/base.html`
  - Table of all notes (published + drafts)
  - Columns: title, status, created, updated, actions (edit, delete)
  - "New Note" button
  - Summary stats (total notes, published count)
  - **Acceptance Criteria**: Dashboard shows all notes with actions

- [ ] Implement `templates/admin/new.html`
  - Extends `admin/base.html`
  - Form with markdown textarea
  - Published checkbox
  - Submit button
  - Optional: markdown preview (if JS enabled)
  - **Acceptance Criteria**: Form for creating notes

- [ ] Implement `templates/admin/edit.html`
  - Extends `admin/base.html`
  - Form pre-filled with existing content
  - Markdown textarea
  - Published checkbox
  - Save and Cancel buttons
  - Optional: markdown preview
  - **Acceptance Criteria**: Form for editing notes

**Completion Criteria**: All templates implemented with proper HTML5 and Microformats2 markup

---

### 4.4 CSS Styling (`static/css/style.css`)

**Priority**: MEDIUM - Functional without, better with
**Estimated Effort**: 4-5 hours
**Dependencies**: None

- [ ] Implement CSS custom properties (variables)
  - Colors (background, text, accent, borders)
  - Typography (font families, sizes, line heights)
  - Spacing scale
  - **References**: ADR-003
  - **Acceptance Criteria**: Consistent design tokens

- [ ] Implement base styles
  - CSS reset/normalize
  - Typography (readable font sizes, line heights)
  - Links and buttons
  - Forms and inputs
  - **Acceptance Criteria**: Clean, readable defaults

- [ ] Implement layout
  - Centered content container (max-width: 800px)
  - Header and footer
  - Navigation
  - Grid for note lists
  - **Acceptance Criteria**: Responsive layout works

- [ ] Implement component styles
  - Note cards
  - Note content (markdown rendering)
  - Forms (admin interface)
  - Tables (dashboard)
  - Buttons and inputs
  - **Acceptance Criteria**: Components look consistent

- [ ] Implement responsive design
  - Mobile-first approach
  - Breakpoints for tablet and desktop
  - Touch-friendly targets
  - Readable on all screen sizes
  - **References**: ADR-003 (Progressive Enhancement)
  - **Acceptance Criteria**: Works on mobile, tablet, desktop

- [ ] Keep total CSS under 300 lines
  - Minimal styling philosophy
  - No fancy animations or effects
  - Focus on readability and usability
  - **References**: ADR-003
  - **Acceptance Criteria**: CSS is simple and maintainable

**Completion Criteria**: Site is usable and looks clean on all devices

---

### 4.5 Optional JavaScript Enhancement (`static/js/preview.js`)

**Priority**: LOW - Optional enhancement only
**Estimated Effort**: 2-3 hours
**Dependencies**: None

This is OPTIONAL for V1. Can be deferred.

- [ ] Implement markdown preview (optional)
  - Load marked.js from CDN
  - Listen to textarea input
  - Render markdown in real-time
  - Display preview beside textarea
  - Degrades gracefully if JS disabled
  - **References**: ADR-003 (Progressive Enhancement)
  - **Acceptance Criteria**: Preview works, form works without it

**Completion Criteria**: Preview enhances editing experience but isn't required

---

## Phase 5: RSS Feed Generation

Syndication for published notes.

### 5.1 Feed Module (`starpunk/feed.py`)

**Priority**: HIGH - Core feature
**Estimated Effort**: 3-4 hours
**Dependencies**: `notes.py`, `feedgen` library

- [ ] Implement `generate_rss_feed()` function
  - Create FeedGenerator instance
  - Set feed metadata (title, link, description, language)
  - Set feed author from config
  - Query published notes (limit 50, newest first)
  - For each note:
    - Add feed entry
    - Set entry title (first line or slug)
    - Set entry link (permalink)
    - Set entry description/content (rendered HTML, CDATA-wrapped)
    - Set entry published date (RFC-822 format)
    - Set entry GUID (permalink)
  - Generate RSS 2.0 XML string
  - Return XML
  - **References**: ADR-002 (feedgen), RSS 2.0 spec, architecture/overview.md
  - **Acceptance Criteria**: Valid RSS 2.0 feed generated

- [ ] Implement feed caching (optional)
  - Cache generated feed for 5 minutes
  - Invalidate on note create/update/delete
  - **Priority**: MEDIUM - Can defer to V2
  - **Acceptance Criteria**: Feed generation is performant

- [ ] Write tests (`tests/test_feed.py`)
  - Test feed generation with notes
  - Test feed metadata is correct
  - Test entry format
  - Test date formatting (RFC-822)
  - Test HTML content in CDATA
  - Validate XML structure
  - Test empty feed (no published notes)
  - Test W3C Feed Validator compliance (manual test)

**Completion Criteria**: RSS feed generates valid XML, passes W3C validator

---

### 5.2 Feed Route (`/feed.xml`)

**Priority**: HIGH - Part of RSS feature
**Estimated Effort**: 1 hour
**Dependencies**: `feed.py`

- [ ] Add feed route to public blueprint
  - GET `/feed.xml`
  - Call `generate_rss_feed()`
  - Return XML with correct Content-Type (`application/rss+xml`)
  - Set Cache-Control header (5 minutes)
  - **Acceptance Criteria**: Feed accessible at /feed.xml

- [ ] Add feed auto-discovery to templates
  - Add `<link rel="alternate" type="application/rss+xml">` to base.html
  - **Acceptance Criteria**: RSS readers auto-discover feed

- [ ] Write route tests
  - Test feed returns 200
  - Test Content-Type is correct
  - Test feed contains published notes
  - Test feed is valid XML

**Completion Criteria**: Feed is accessible and discoverable

---

## Phase 6: Micropub API

Micropub endpoint for publishing from external clients.

### 6.1 Token Management (for Micropub)

**Priority**: HIGH - Required for Micropub
**Estimated Effort**: 2-3 hours
**Dependencies**: `models.py`, `database.py`

Note: Micropub clients will obtain tokens via external IndieAuth flow. StarPunk just validates tokens.

- [ ] Implement token validation in `starpunk/auth.py`
  - `validate_micropub_token()` - Check if token exists and valid
  - Query tokens table
  - Check expiration
  - Return Token object with 'me' and scope
  - **References**: IndieAuth spec, Micropub spec
  - **Acceptance Criteria**: Token validation works

- [ ] Implement token creation (for testing)
  - `create_token()` - Manually create token (for development/testing)
  - Store token with 'me', client_id, scope
  - **Priority**: For testing only, real tokens come from IndieAuth server
  - **Acceptance Criteria**: Can create test tokens

- [ ] Implement Micropub authentication decorator
  - `require_micropub_auth()` - Decorator for Micropub endpoint
  - Extract Bearer token from Authorization header
  - Validate token
  - Check scope (must have 'create' or 'post')
  - Store token info in Flask `g`
  - Return 401 if invalid
  - **Acceptance Criteria**: Protects Micropub endpoint

**Completion Criteria**: Token validation works for Micropub

---

### 6.2 Micropub Endpoint (`starpunk/micropub.py`)

**Priority**: HIGH - Core IndieWeb feature
**Estimated Effort**: 6-8 hours
**Dependencies**: `auth.py`, `notes.py`, Micropub spec knowledge

- [ ] Implement Micropub POST handler (create)
  - Handle `application/json` content type
  - Handle `application/x-www-form-urlencoded` content type
  - Parse Micropub payload
  - Validate h-entry structure
  - Extract content from properties.content[0]
  - Extract name from properties.name[0] (if present)
  - Call `create_note()` with content
  - Return 201 Created with Location header (note URL)
  - Handle errors (400, 500)
  - **References**: Micropub spec, ADR-005
  - **Acceptance Criteria**: Can create notes via Micropub

- [ ] Implement Micropub GET handler (query)
  - Handle `q=config` query - Return supported config
  - Handle `q=source` query - Return note source by URL
  - Handle `q=syndicate-to` query - Return empty (no syndication targets in V1)
  - Return JSON responses
  - **References**: Micropub spec
  - **Acceptance Criteria**: Query endpoints return correct data

- [ ] Implement Micropub media endpoint (optional for V1)
  - Handle file uploads
  - Store in `data/media/`
  - Return media URL
  - **Priority**: LOW - Defer to V2
  - **Acceptance Criteria**: Media uploads work (if implemented)

- [ ] Implement error responses
  - 400 Bad Request - Invalid payload
  - 401 Unauthorized - Missing/invalid token
  - 403 Forbidden - Insufficient scope
  - 500 Server Error - Internal errors
  - Return JSON error responses with Micropub error codes
  - **References**: Micropub spec error handling
  - **Acceptance Criteria**: Errors return proper Micropub responses

- [ ] Write comprehensive tests (`tests/test_micropub.py`)
  - Test POST with JSON payload
  - Test POST with form-encoded payload
  - Test authentication (valid token, invalid token, missing token)
  - Test scope checking
  - Test content extraction from h-entry
  - Test error responses
  - Test query endpoints (config, source)
  - Integration test: Full Micropub create flow

**Completion Criteria**: Micropub endpoint fully implements spec, passes micropub.rocks tests

---

### 6.3 Micropub Route

**Priority**: HIGH - Part of Micropub feature
**Estimated Effort**: 1 hour
**Dependencies**: `micropub.py`

- [ ] Add Micropub route to API blueprint
  - POST `/api/micropub` - Create entry
  - GET `/api/micropub` - Query endpoint
  - Apply `@require_micropub_auth` decorator
  - **Acceptance Criteria**: Micropub endpoint accessible

- [ ] Add Micropub endpoint discovery
  - Add `<link rel="micropub">` to base template
  - Point to `/api/micropub`
  - **References**: Micropub spec
  - **Acceptance Criteria**: Clients can discover endpoint

- [ ] Write route tests
  - Test endpoint returns 401 without auth
  - Test endpoint accepts authenticated requests
  - Test both POST and GET methods

**Completion Criteria**: Micropub endpoint discoverable and functional

---

## Phase 7: API Routes (CRUD API)

Optional REST API for notes (in addition to Micropub).

### 7.1 Notes API Blueprint (`starpunk/routes/api.py`)

**Priority**: MEDIUM - Nice to have, not critical
**Estimated Effort**: 3-4 hours
**Dependencies**: `auth.py`, `notes.py`

This is OPTIONAL for V1. The admin interface uses forms, Micropub handles external publishing. This JSON API is a bonus.

- [ ] Implement notes CRUD API
  - GET `/api/notes` - List published notes (JSON)
  - POST `/api/notes` - Create note (requires auth)
  - GET `/api/notes/<slug>` - Get single note (JSON)
  - PUT `/api/notes/<slug>` - Update note (requires auth)
  - DELETE `/api/notes/<slug>` - Delete note (requires auth)
  - Use session auth for write operations
  - Return JSON responses
  - **Acceptance Criteria**: JSON API works for notes

- [ ] Register API blueprint
  - Import in `starpunk/__init__.py`
  - Register with app
  - **Acceptance Criteria**: API routes accessible

- [ ] Write API tests
  - Test list notes
  - Test get single note
  - Test create requires auth
  - Test update requires auth
  - Test delete requires auth
  - Test JSON serialization

**Completion Criteria**: REST API provides JSON access to notes (if implemented)

---

## Phase 8: Testing and Quality Assurance

Comprehensive testing to ensure reliability.

### 8.1 Integration Tests

**Priority**: HIGH - Ensure components work together
**Estimated Effort**: 4-5 hours
**Dependencies**: All features implemented

- [ ] Write end-to-end tests (`tests/test_integration.py`)
  - Test complete user journey: login → create note → view note → edit → delete
  - Test complete Micropub flow: authenticate → publish → view on site
  - Test RSS feed updates when notes created
  - Test file/database sync integrity
  - Test error recovery (DB failure, file failure)
  - **Acceptance Criteria**: All major user flows tested

- [ ] Test data consistency
  - Create note, verify file exists
  - Create note, verify DB record exists
  - Update note, verify file content changes
  - Update note, verify DB timestamp changes
  - Delete note, verify file and DB record handled correctly
  - **Acceptance Criteria**: File and database stay in sync

- [ ] Test edge cases
  - Very long content (>10k characters)
  - Special characters in content (unicode, emoji)
  - Concurrent requests (if applicable)
  - Low disk space scenarios
  - **Acceptance Criteria**: Edge cases handled gracefully

**Completion Criteria**: Integration tests pass, coverage >80%

---

### 8.2 Standards Validation

**Priority**: HIGH - Ensure compliance
**Estimated Effort**: 2-3 hours
**Dependencies**: All features implemented

- [ ] Validate HTML output
  - Run W3C HTML Validator on templates
  - Fix any validation errors
  - **Tool**: https://validator.w3.org/
  - **Acceptance Criteria**: Valid HTML5

- [ ] Validate RSS feed
  - Run W3C Feed Validator on /feed.xml
  - Fix any validation errors
  - **Tool**: https://validator.w3.org/feed/
  - **Acceptance Criteria**: Valid RSS 2.0

- [ ] Validate Microformats
  - Use IndieWebify.me to check h-entry markup
  - Verify h-card, h-feed, h-entry parsing
  - **Tool**: https://indiewebify.me/
  - **Acceptance Criteria**: Microformats2 properly parsed

- [ ] Validate Micropub
  - Use micropub.rocks to test endpoint
  - Pass all required tests
  - **Tool**: https://micropub.rocks/
  - **Acceptance Criteria**: Micropub spec compliant

**Completion Criteria**: All standards validators pass

---

### 8.3 Security Testing

**Priority**: HIGH - Critical for production
**Estimated Effort**: 3-4 hours
**Dependencies**: All features implemented

- [ ] Test authentication security
  - CSRF protection (state tokens)
  - Session hijacking prevention
  - Cookie security (HttpOnly, Secure, SameSite)
  - Session expiry
  - **References**: architecture/security.md
  - **Acceptance Criteria**: Authentication is secure

- [ ] Test input validation
  - SQL injection prevention (parameterized queries)
  - XSS prevention (markdown sanitization)
  - Path traversal prevention
  - File upload security (if media implemented)
  - **References**: architecture/security.md
  - **Acceptance Criteria**: All inputs validated

- [ ] Test authorization
  - Only ADMIN_ME can login
  - Unauthorized users rejected
  - Protected routes require auth
  - Token scope enforcement
  - **Acceptance Criteria**: Authorization works correctly

- [ ] Security headers
  - Content-Security-Policy
  - X-Frame-Options
  - X-Content-Type-Options
  - Referrer-Policy
  - **References**: architecture/security.md
  - **Acceptance Criteria**: Security headers set

**Completion Criteria**: No security vulnerabilities found

---

### 8.4 Manual Testing

**Priority**: HIGH - Real-world validation
**Estimated Effort**: 3-4 hours
**Dependencies**: All features implemented

- [ ] Test with real IndieLogin
  - Authenticate with actual indielogin.com
  - Verify session persistence
  - Test logout
  - **Acceptance Criteria**: Real IndieLogin works

- [ ] Test with real Micropub client
  - Use Quill or Indigenous app
  - Publish a note
  - Verify it appears on site
  - **Tools**: Quill (https://quill.p3k.io/)
  - **Acceptance Criteria**: Real clients work

- [ ] Test in multiple browsers
  - Chrome/Chromium
  - Firefox
  - Safari (if available)
  - Mobile browsers
  - **Acceptance Criteria**: Works in all major browsers

- [ ] Test responsive design
  - Mobile phone (320px width)
  - Tablet (768px width)
  - Desktop (1200px width)
  - **Acceptance Criteria**: Responsive on all sizes

- [ ] Test accessibility
  - Keyboard navigation
  - Screen reader (if available)
  - Color contrast
  - **Acceptance Criteria**: Basic accessibility works

**Completion Criteria**: Manual testing reveals no critical issues

---

## Phase 9: Documentation and Deployment

Final documentation and deployment preparation.

### 9.1 User Documentation

**Priority**: HIGH - Required for V1 release
**Estimated Effort**: 3-4 hours
**Dependencies**: All features complete

- [ ] Update README.md
  - Verify all sections accurate
  - Update installation instructions
  - Add screenshots (optional)
  - Update configuration examples
  - **Acceptance Criteria**: README is complete and accurate

- [ ] Create deployment guide (`docs/architecture/deployment.md`)
  - Production setup instructions
  - Systemd service configuration
  - Nginx/Caddy reverse proxy setup
  - SSL/TLS configuration
  - Backup procedures
  - **References**: architecture/overview.md
  - **Acceptance Criteria**: Deployment guide is comprehensive

- [ ] Create user guide (`docs/user-guide.md`)
  - How to login
  - How to create notes
  - How to use Micropub clients
  - How to backup data
  - Troubleshooting common issues
  - **Acceptance Criteria**: Users can self-serve

- [ ] Create API documentation (`docs/api.md`)
  - REST API endpoints
  - Micropub endpoint
  - Authentication methods
  - Example requests/responses
  - **Acceptance Criteria**: API is documented

**Completion Criteria**: Documentation is complete and helpful

---

### 9.2 Developer Documentation

**Priority**: MEDIUM - Helpful for maintenance
**Estimated Effort**: 2-3 hours
**Dependencies**: All features complete

- [ ] Create contributing guide (`CONTRIBUTING.md`)
  - Development setup
  - Running tests
  - Code style
  - Pull request process
  - **Acceptance Criteria**: Contributors can get started

- [ ] Create architecture diagram
  - Visual representation of system
  - Component interactions
  - Data flow
  - Save to `docs/architecture/diagrams/`
  - **Acceptance Criteria**: Architecture is visualized

- [ ] Update ADRs if needed
  - Document any architectural changes made during implementation
  - Add new ADRs for new decisions
  - **Acceptance Criteria**: All decisions documented

**Completion Criteria**: Developer documentation is complete

---

### 9.3 Deployment Testing

**Priority**: HIGH - Verify production readiness
**Estimated Effort**: 2-3 hours
**Dependencies**: Deployment guide complete

- [ ] Test production deployment
  - Deploy to test server
  - Use gunicorn (not Flask dev server)
  - Configure reverse proxy
  - Enable HTTPS
  - Test performance under load
  - **Acceptance Criteria**: Runs in production environment

- [ ] Test backup and restore
  - Create backup of data/
  - Restore to new instance
  - Verify all notes accessible
  - **Acceptance Criteria**: Backup/restore works

- [ ] Performance testing
  - Test response times (< 300ms target)
  - Test with 100+ notes
  - Test RSS generation time
  - Check memory usage
  - **References**: architecture/overview.md (performance targets)
  - **Acceptance Criteria**: Meets performance targets

**Completion Criteria**: Production deployment verified

---

## Phase 10: Release Preparation

Final steps before V1 release.

### 10.1 Final Quality Checks

**Priority**: CRITICAL - No release without this
**Estimated Effort**: 2-3 hours
**Dependencies**: Everything complete

- [ ] Run full test suite
  - All unit tests pass
  - All integration tests pass
  - Test coverage >80%
  - **Acceptance Criteria**: All tests green

- [ ] Code quality checks
  - Run black (code formatting)
  - Run flake8 (linting)
  - Run mypy (type checking)
  - Fix any issues
  - **Acceptance Criteria**: Code passes all quality checks

- [ ] Final security review
  - Review security checklist
  - Verify all secrets in .env (not code)
  - Verify data/ is gitignored
  - Check for any hardcoded credentials
  - **Acceptance Criteria**: No security issues

- [ ] Final documentation review
  - All docs accurate
  - All links working
  - All code examples correct
  - **Acceptance Criteria**: Documentation complete

**Completion Criteria**: Ready for release

---

### 10.2 Release

**Priority**: CRITICAL - V1 milestone
**Estimated Effort**: 1-2 hours
**Dependencies**: All quality checks pass

- [ ] Version tagging
  - Update version in `starpunk/__init__.py` to `1.0.0`
  - Create git tag `v1.0.0`
  - Write release notes
  - **Acceptance Criteria**: Version tagged

- [ ] Release announcement
  - Post to IndieWeb wiki
  - Share on personal site
  - Optional: Announce on social media
  - **Acceptance Criteria**: V1 announced

- [ ] Archive project state
  - Create release branch `release/v1.0.0`
  - Tag in git
  - **Acceptance Criteria**: Release archived

**Completion Criteria**: StarPunk V1 released!

---

## Post-V1 Roadmap

### Phase 11: Micropub Extended Operations (V1.1)

**Priority**: HIGH for V1.1 release
**Estimated Effort**: 4-6 hours
**Dependencies**: Phase 6 (Micropub Core) must be complete

#### 11.1 Update Operations
- [ ] Implement `action=update` handler in `/micropub`
  - Support replace operations (replace entire property)
  - Support add operations (append to array properties)
  - Support delete operations (remove from array properties)
  - Map Micropub properties to StarPunk note fields
  - Validate URL belongs to this StarPunk instance
  - **Acceptance Criteria**: Can update posts via Micropub clients

#### 11.2 Delete Operations
- [ ] Implement `action=delete` handler in `/micropub`
  - Soft delete implementation (set deleted_at timestamp)
  - URL validation and slug extraction
  - Authorization check (delete scope required)
  - Proper 204 No Content response
  - **Acceptance Criteria**: Can delete posts via Micropub clients

#### 11.3 Extended Scopes
- [ ] Add "update" and "delete" to SUPPORTED_SCOPES
- [ ] Update authorization form to display requested scopes
- [ ] Implement scope-specific permission checks
- [ ] Update token endpoint to validate extended scopes
- [ ] **Acceptance Criteria**: Fine-grained permission control

### Phase 12: Media Endpoint (V1.2)

**Priority**: MEDIUM for V1.2 release
**Estimated Effort**: 6-8 hours
**Dependencies**: Micropub core functionality

#### 12.1 Media Upload Endpoint
- [ ] Create `/micropub/media` endpoint
- [ ] Handle multipart/form-data file uploads
- [ ] Store files in `/data/media/YYYY/MM/` structure
- [ ] Generate unique filenames to prevent collisions
- [ ] Image optimization (resize, compress)
- [ ] Return 201 Created with Location header
- [ ] **Acceptance Criteria**: Can upload images via Micropub clients

#### 12.2 Media in Posts
- [ ] Support photo property in Micropub create/update
- [ ] Embed images in Markdown content
- [ ] Update templates to display images properly
- [ ] Add media-endpoint to Micropub config query
- [ ] **Acceptance Criteria**: Posts can include images

### Phase 13: Advanced IndieWeb Features (V2.0)

**Priority**: LOW - Future enhancement
**Estimated Effort**: 10-15 hours per feature
**Dependencies**: All V1.x features complete

#### 13.1 Webmentions
- [ ] Receive webmentions at `/webmention` endpoint
- [ ] Verify source links to target
- [ ] Extract microformats from source
- [ ] Store webmentions in database
- [ ] Display webmentions on posts
- [ ] Send webmentions on publish
- [ ] Moderation interface in admin

#### 13.2 Syndication (POSSE)
- [ ] Add syndication targets configuration
- [ ] Support mp-syndicate-to in Micropub
- [ ] Implement Mastodon syndication
- [ ] Implement Twitter/X syndication (if API available)
- [ ] Store syndication URLs in post metadata
- [ ] Display syndication links on posts

#### 13.3 IndieAuth Server
- [ ] Implement full authorization server
- [ ] Allow StarPunk to be identity provider
- [ ] Profile URL verification
- [ ] Client registration/discovery
- [ ] Token introspection endpoint
- [ ] Token revocation endpoint
- [ ] Refresh tokens support

### Phase 14: Enhanced Features (V2.0+)

**Priority**: LOW - Long-term vision
**Estimated Effort**: Variable

#### 14.1 Multiple Post Types
- [ ] Articles (long-form with title)
- [ ] Replies (in-reply-to support)
- [ ] Likes (like-of property)
- [ ] Bookmarks (bookmark-of property)
- [ ] Events (h-event microformat)
- [ ] Check-ins (location data)

#### 14.2 Multi-User Support
- [ ] User registration system
- [ ] Per-user permissions and roles
- [ ] Separate author feeds (/author/username)
- [ ] Multi-author Micropub (me verification)
- [ ] User profile pages

#### 14.3 Advanced UI Features
- [ ] WYSIWYG Markdown editor
- [ ] Draft/schedule posts
- [ ] Batch operations interface
- [ ] Analytics dashboard
- [ ] Theme customization
- [ ] Plugin system

---

## Summary Checklist

### Core Features (Must Have)
- [x] **Notes CRUD operations (file + database sync)** ✅ v0.3.0
  - 86% test coverage, 85 tests passing
  - Full file/database synchronization
  - Soft and hard delete support
- [x] **IndieLogin authentication** ✅ v0.8.0
  - 96% test coverage, 51 tests passing
  - CSRF protection, session management, PKCE
  - Token hashing for security
  - IndieLogin.com integration working
- [x] **Admin web interface** ✅ v0.5.2
  - Routes: `/auth/login`, `/auth/callback`, `/auth/logout`, `/admin/*`
  - Dashboard, note editor, delete functionality
  - Flash messages, form handling
  - 87% test coverage, 405 tests passing
- [x] **Public web interface** ✅ v0.5.0
  - Routes: `/`, `/note/<slug>`
  - Microformats2 markup (h-entry, h-card, h-feed)
  - Responsive design
  - Server-side rendering
- [x] **RSS feed generation** ✅ v0.6.0
  - Route: `/feed.xml` active
  - RSS 2.0 compliant
  - 96% test coverage
  - Auto-discovery links in HTML
- [ ] **Micropub endpoint** ❌ NOT IMPLEMENTED
  - Phase 6 not started
  - Critical blocker for V1
  - Token model ready but no endpoint
- [x] **Core tests passing** ✅ v0.9.5
  - Utils: >90% coverage
  - Models: >90% coverage
  - Notes: 86% coverage
  - Auth: 96% coverage
  - Feed: 96% coverage
  - Routes: 87% coverage
  - Overall: 87% coverage
- [ ] **Standards compliance** ⚠️ PARTIAL
  - HTML5: ⚠️ Not validated (markup exists)
  - RSS: ✅ Implemented and tested
  - Microformats: ⚠️ Markup exists, not validated
  - Micropub: ❌ Not implemented
- [x] **Documentation extensive** ✅ v0.9.5
  - ADRs 001-025 complete
  - Design docs for Phases 1-5
  - Implementation reports for major features
  - Container deployment guide
  - CHANGELOG maintained

### Optional Features (Nice to Have)
- [ ] Markdown preview (JavaScript) - Phase 4.5
- [ ] Notes search - Deferred to V2
- [ ] Media uploads (Micropub) - Deferred to V2
- [ ] JSON REST API - Phase 7 (optional)
- [ ] Feed caching - Deferred to V2

### Quality Gates
- [x] **Test coverage >80%** ✅ v0.9.5 achieves 87% overall
- [ ] **All validators pass** ⚠️ PARTIAL
  - HTML validator: ⏳ Not tested
  - RSS validator: ✅ RSS 2.0 compliant (v0.6.0)
  - Microformats validator: ⏳ Not tested (markup exists)
  - Micropub validator: ❌ N/A (not implemented)
- [x] **Security tests pass** ✅ v0.9.5
  - SQL injection prevention tested
  - Path traversal prevention tested
  - CSRF protection tested
  - Token hashing tested
  - PKCE implementation tested
- [x] **Manual testing complete** ✅ v0.9.5
  - IndieLogin.com authentication working
  - Admin interface functional
  - Note CRUD operations tested
  - RSS feed generation verified
- [x] **Performance targets met** ✅ v0.9.5
  - Containerized deployment with gunicorn
  - Response times acceptable
- [x] **Production deployment tested** ✅ v0.9.5
  - Container deployment working
  - Gitea CI/CD pipeline operational
  - Health check endpoint functional

**Current Status**: 5/7 critical phases complete (71%), Micropub is primary blocker for V1

---

## Estimated Timeline

**Total Effort**: 40-60 hours of focused development work
**Completed Effort**: ~35 hours (Phases 1-5)
**Remaining Effort**: ~15-25 hours (Phase 6, validation, V1 release)

**Breakdown by Phase**:
- ~~Phase 1 (Utilities & Models): 5-7 hours~~ ✅ Complete (v0.1.0)
- ~~Phase 2 (Notes Management): 6-8 hours~~ ✅ Complete (v0.3.0)
- ~~Phase 3 (Authentication): 5-6 hours~~ ✅ Complete (v0.8.0)
- ~~Phase 4 (Web Interface): 13-17 hours~~ ✅ Complete (v0.5.2)
- ~~Phase 5 (RSS Feed): 4-5 hours~~ ✅ Complete (v0.6.0)
- Phase 6 (Micropub): 9-12 hours ❌ NOT STARTED
- Phase 7 (REST API): 3-4 hours ⏳ OPTIONAL (can defer to V2)
- Phase 8 (Testing & QA): 9-12 hours ⚠️ PARTIAL (validation tests pending)
- Phase 9 (Documentation): 5-7 hours ⚠️ PARTIAL (README update needed)
- Phase 10 (Release Prep): 3-5 hours ⏳ PENDING

**Current Status** (as of 2025-11-24):
- **Completed**: Phases 1-5 (foundation, auth, web, RSS) - ~35 hours ✅
- **In Progress**: Container deployment, CI/CD (v0.9.5) ✅
- **Critical Blocker**: Phase 6 (Micropub) - ~12 hours ❌
- **Remaining**: Validation tests, final docs, V1 release - ~8 hours ⏳

**Path to V1**:
1. **Micropub Implementation** (9-12 hours) - Required for V1
2. **Standards Validation** (3-4 hours) - HTML, Microformats, Micropub.rocks
3. **Documentation Polish** (2-3 hours) - Update README, verify all docs
4. **V1 Release** (1-2 hours) - Tag, announce, publish

**Estimated V1 Completion**: ~2-3 development days from 2025-11-24 (if Micropub implemented)

---

## Development Notes

### Working Incrementally
1. Complete each phase before moving to next
2. Run tests after each feature
3. Keep commits small and focused
4. Document as you go (don't defer to end)

### When Stuck
1. Review relevant ADRs and architecture docs
2. Check IndieWeb specs (Micropub, Microformats)
3. Look at reference implementations
4. Ask for architectural guidance

### Testing Strategy
1. Write tests alongside features (not after)
2. Test happy path AND error cases
3. Integration tests for cross-component features
4. Manual testing for user experience

### Quality Over Speed
- Don't skip tests
- Don't skip documentation
- Don't compromise security
- Simple implementations are better than clever ones

---

## References

### Project Documentation
- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
- [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
- [ADR-002: Flask Extensions](/home/phil/Projects/starpunk/docs/decisions/ADR-002-flask-extensions.md)
- [ADR-003: Frontend Technology](/home/phil/Projects/starpunk/docs/decisions/ADR-003-frontend-technology.md)
- [ADR-004: File-Based Storage](/home/phil/Projects/starpunk/docs/decisions/ADR-004-file-based-note-storage.md)
- [ADR-005: IndieLogin Authentication](/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md)
- [ADR-006: Python Virtual Environment](/home/phil/Projects/starpunk/docs/decisions/ADR-006-python-virtual-environment-uv.md)
- [ADR-007: Slug Generation Algorithm](/home/phil/Projects/starpunk/docs/decisions/ADR-007-slug-generation-algorithm.md)
- [ADR-008: Versioning Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-008-versioning-strategy.md)
- [ADR-009: Git Branching Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-009-git-branching-strategy.md)
- [ADR-010: Authentication Module Design](/home/phil/Projects/starpunk/docs/decisions/ADR-010-authentication-module-design.md)
- [ADR-011: Development Authentication Mechanism](/home/phil/Projects/starpunk/docs/decisions/ADR-011-development-authentication-mechanism.md)
- [Project Structure](/home/phil/Projects/starpunk/docs/design/project-structure.md)
- [Phase 4 Web Interface Design](/home/phil/Projects/starpunk/docs/design/phase-4-web-interface.md)
- [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
- [Versioning Strategy](/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md)
- [Git Branching Strategy](/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md)

### Implementation Reports
- [Phase 2.1 Implementation Report](/home/phil/Projects/starpunk/docs/reports/phase-2.1-implementation-20251118.md)
- [Phase 3 Authentication Report](/home/phil/Projects/starpunk/docs/reports/phase-3-authentication-20251118.md)
- [Phase 4 Architectural Assessment](/home/phil/Projects/starpunk/docs/reports/phase-4-architectural-assessment-20251118.md)

### External Standards
- [Micropub Specification](https://micropub.spec.indieweb.org/)
- [IndieAuth Specification](https://www.w3.org/TR/indieauth/)
- [Microformats2](http://microformats.org/wiki/microformats2)
- [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
- [IndieLogin API](https://indielogin.com/api)

### Testing Tools
- [W3C HTML Validator](https://validator.w3.org/)
- [W3C Feed Validator](https://validator.w3.org/feed/)
- [IndieWebify.me](https://indiewebify.me/)
- [Micropub.rocks](https://micropub.rocks/)

---

**This implementation plan is a living document. Update as implementation progresses and new insights emerge.**
