chati-dev 1.4.0 → 2.0.2

package/framework/tasks/detail-edge-case-analysis.md

@@ -0,0 +1,300 @@
+---
+id: detail-edge-case-analysis
+agent: detail
+trigger: detail-nfr-extraction
+phase: clarity
+requires_input: false
+parallelizable: true
+outputs: [edge-cases.yaml]
+handoff_to: detail-acceptance-criteria
+autonomous_gate: true
+criteria:
+  - Edge cases identified for all critical features
+  - Error scenarios documented
+  - Boundary conditions defined
+---
+# Analyze Edge Cases and Error Scenarios
+
+## Purpose
+Identify edge cases, error scenarios, and boundary conditions that must be handled for robust implementation.
+
+## Prerequisites
+- `prd-draft.yaml` with functional requirements
+
+## Steps
+
+### 1. Analyze Each Functional Requirement
+For each FR, identify potential edge cases.
+
+### 2. Identify Input Boundary Conditions
+- Empty input (empty string, null, undefined)
+- Max length exceeded
+- Invalid format (malformed email, weak password)
+- Special characters (SQL, XSS, Unicode)
+- Very large input (10MB text, huge arrays)
+
+### 3. Identify State Edge Cases
+- User not logged in attempts protected action
+- User tries to edit others' posts
+- Concurrent edits to same post
+- Deleted resource accessed
+- Expired JWT token
+
+### 4. Identify Timing Edge Cases
+- Rapid successive requests (double submit)
+- Long-running operations timeout
+- Race conditions in parallel operations
+- Token expires mid-operation
+
+### 5. Identify Network Edge Cases
+- API request fails mid-flight
+- Slow network (3G, offline)
+- Partial response received
+- WebSocket disconnection
+
+### 6. Identify Data Edge Cases
+- Foreign key constraints violated
+- Unique constraint violations
+- Database connection pool exhausted
+- Transaction deadlock
+- Cascading deletes
+
+### 7. Document Error Scenarios
+For each edge case:
+- Scenario description
+- Expected behavior
+- Error message
+- User impact
+- Recovery strategy
+
+### 8. Define Boundary Conditions
+For numerical/string limits:
+- Minimum and maximum values
+- What happens at boundaries
+- What happens beyond boundaries
+
+### 9. Identify Security Edge Cases
+- Injection attempts (SQL, XSS, command injection)
+- Authorization bypass attempts
+- Token manipulation
+- Brute force attacks
+- Mass assignment vulnerabilities
+
+### 10. Create Edge Case Catalog
+Comprehensive list with test scenarios.
+
+## Decision Points
+None - systematic analysis of all features.
+
+## Error Handling
+- **Too Many Edge Cases**: Prioritize by severity and likelihood
+
+## Output Format
+```yaml
+# edge-cases.yaml
+timestamp: 2026-02-13T15:15:00Z
+
+authentication_edge_cases:
+  - scenario: User submits empty email
+    input: {email: "", password: "Valid123"}
+    expected_behavior: Validation error, form not submitted
+    error_message: "Email is required"
+    http_status: 400
+  - scenario: User submits malformed email
+    input: {email: "not-an-email", password: "Valid123"}
+    expected_behavior: Validation error
+    error_message: "Invalid email format"
+    http_status: 400
+  - scenario: Password with only lowercase
+    input: {email: "test@example.com", password: "alllowercase123"}
+    expected_behavior: Validation error
+    error_message: "Password must contain at least one uppercase letter"
+    http_status: 400
+  - scenario: Extremely long password (>1000 chars)
+    input: {email: "test@example.com", password: "A1" + "x"*1000}
+    expected_behavior: Accept but truncate or reject with max length
+    error_message: "Password exceeds maximum length (256 characters)"
+    http_status: 400
+  - scenario: SQL injection attempt in email
+    input: {email: "admin'--", password: "Valid123"}
+    expected_behavior: Parameterized query prevents injection, email validation fails
+    error_message: "Invalid email format"
+    http_status: 400
+  - scenario: Concurrent registration with same email
+    input: Two users submit same email simultaneously
+    expected_behavior: First succeeds, second fails with duplicate email error
+    error_message: "Email already registered"
+    http_status: 409
+  - scenario: JWT token expired
+    input: Request with expired token
+    expected_behavior: 401 error, redirect to login, clear token
+    error_message: "Session expired, please log in again"
+    http_status: 401
+
+post_management_edge_cases:
+  - scenario: Create post with empty title
+    input: {title: "", content: "Content"}
+    expected_behavior: Validation error
+    error_message: "Title is required"
+    http_status: 400
+  - scenario: Title exceeds 200 characters
+    input: {title: "x"*201, content: "Content"}
+    expected_behavior: Validation error
+    error_message: "Title must be 200 characters or less"
+    http_status: 400
+  - scenario: Create post with XSS attempt in content
+    input: {title: "Test", content: "<script>alert('xss')</script>"}
+    expected_behavior: Content sanitized before storage and display
+    error_message: None (sanitized silently)
+  - scenario: Upload image >5MB
+    input: Image file of 6MB
+    expected_behavior: Upload rejected
+    error_message: "Image must be smaller than 5MB"
+    http_status: 413
+  - scenario: Upload non-image file
+    input: .exe file
+    expected_behavior: Upload rejected
+    error_message: "Only JPG and PNG images are allowed"
+    http_status: 400
+  - scenario: User tries to edit another user's post
+    input: PUT /api/posts/:id where post.user_id != current_user.id
+    expected_behavior: 403 Forbidden
+    error_message: "You don't have permission to edit this post"
+    http_status: 403
+  - scenario: User tries to delete non-existent post
+    input: DELETE /api/posts/invalid-uuid
+    expected_behavior: 404 Not Found
+    error_message: "Post not found"
+    http_status: 404
+  - scenario: Concurrent edits to same post
+    input: Two users edit same post simultaneously
+    expected_behavior: Last write wins (simple approach) or optimistic locking (advanced)
+    mitigation: Show warning if post was modified since user loaded it
+  - scenario: Create post with 1000 tags
+    input: {title: "Test", content: "Content", tags: ["tag1", "tag2", ..., "tag1000"]}
+    expected_behavior: Accept but limit to first 20 tags
+    error_message: "Maximum 20 tags allowed"
+    http_status: 400
+
+search_edge_cases:
+  - scenario: Search with empty query
+    input: GET /api/search?q=
+    expected_behavior: Return all posts (paginated) or require non-empty query
+    response: All posts or 400 error
+  - scenario: Search with special characters
+    input: GET /api/search?q=%#@!
+    expected_behavior: Escape special characters, perform search
+    response: Empty results or posts matching literal characters
+  - scenario: Search with extremely long query (>1000 chars)
+    input: GET /api/search?q=x*1000
+    expected_behavior: Truncate to reasonable length (256 chars) or reject
+    error_message: "Search query too long"
+    http_status: 400
+  - scenario: Search returns 10,000 results
+    input: GET /api/search?q=common-word
+    expected_behavior: Paginate results, return first page
+    response: 20 results + pagination metadata
+  - scenario: Search with SQL injection attempt
+    input: GET /api/search?q=' OR '1'='1
+    expected_behavior: Parameterized query or full-text search prevents injection
+    response: Empty results or posts matching literal string
+
+network_edge_cases:
+  - scenario: API request timeout (>30s)
+    expected_behavior: Client shows timeout error, allows retry
+    user_impact: Temporary inability to complete action
+    recovery: Retry button, exponential backoff
+  - scenario: Request fails mid-flight
+    expected_behavior: Client detects network error, offers retry
+    user_impact: Action not completed
+    recovery: Auto-retry up to 3 times, then manual retry
+  - scenario: User goes offline mid-form
+    expected_behavior: Form data preserved in localStorage
+    user_impact: Work not lost
+    recovery: Auto-submit when online again (with user confirmation)
+  - scenario: Partial response received
+    expected_behavior: Detect incomplete JSON, treat as error
+    recovery: Retry request
+
+database_edge_cases:
+  - scenario: Database connection pool exhausted
+    expected_behavior: New requests wait or fail with 503
+    error_message: "Service temporarily unavailable, please try again"
+    http_status: 503
+    mitigation: Connection pooling with reasonable limits, monitoring
+  - scenario: Unique constraint violation (duplicate email race condition)
+    expected_behavior: Database rejects insert, return 409
+    error_message: "Email already registered"
+    http_status: 409
+  - scenario: Foreign key constraint violation (delete user with posts)
+    expected_behavior: Cascade delete posts or prevent user deletion
+    implementation: CASCADE on foreign key or check before delete
+  - scenario: Transaction deadlock
+    expected_behavior: Database rolls back one transaction, retry
+    mitigation: Keep transactions short, retry with exponential backoff
+
+security_edge_cases:
+  - scenario: Mass assignment attempt
+    input: POST /api/users with {email, password, is_admin: true}
+    expected_behavior: is_admin field ignored
+    implementation: Explicitly whitelist allowed fields
+  - scenario: Brute force password attempts
+    expected_behavior: Rate limit to 5 attempts per 15 minutes
+    error_message: "Too many login attempts, please try again in 15 minutes"
+    http_status: 429
+  - scenario: JWT token tampered with
+    expected_behavior: Signature verification fails, 401 error
+    error_message: "Invalid authentication token"
+    http_status: 401
+  - scenario: User changes email in token to impersonate another
+    expected_behavior: Signature verification fails
+    security_control: JWT signature validation
+
+boundary_conditions:
+  - field: title
+    type: string
+    min_length: 1
+    max_length: 200
+    at_min: Accepted (1 char title)
+    at_max: Accepted (200 char title)
+    below_min: Rejected (empty string)
+    above_max: Rejected (201+ chars)
+  - field: password
+    type: string
+    min_length: 8
+    max_length: 256
+    pattern: At least 1 uppercase, 1 lowercase, 1 number
+    at_min: Accepted if meets pattern
+    at_max: Accepted
+    below_min: Rejected (<8 chars)
+    above_max: Rejected (>256 chars)
+  - field: image_size
+    type: file
+    max_size: 5242880 (5MB)
+    at_max: Accepted (exactly 5MB)
+    above_max: Rejected (>5MB)
+  - field: pagination_limit
+    type: integer
+    min: 1
+    max: 100
+    default: 20
+    at_min: Return 1 result
+    at_max: Return 100 results
+    below_min: Use default (20)
+    above_max: Use max (100)
+  - field: concurrent_users
+    type: system_load
+    target: 10000
+    at_target: System performs normally
+    above_target: Graceful degradation, may slow down but not crash
+
+testing_scenarios:
+  - Create post with boundary title lengths (0, 1, 200, 201 chars)
+  - Register with various invalid emails
+  - Upload files of various types and sizes
+  - Attempt unauthorized actions (edit others' posts)
+  - Simulate network failures and timeouts
+  - Test concurrent operations (double submit, parallel edits)
+  - Inject SQL, XSS, command injection attempts
+  - Stress test with 10k+ concurrent users
+```

package/framework/tasks/detail-expand-prd.md

@@ -0,0 +1,389 @@
+---
+id: detail-expand-prd
+agent: detail
+trigger: brief
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [prd-draft.yaml]
+handoff_to: detail-nfr-extraction
+autonomous_gate: true
+criteria:
+  - All functional requirements expanded with details
+  - User stories written in Given-When-Then format
+  - Data models identified
+  - API endpoints outlined
+---
+# Expand Brief into Formal PRD
+
+## Purpose
+Transform the approved brief into a comprehensive Product Requirements Document with technical details.
+
+## Prerequisites
+- `brief.yaml` approved by user
+
+## Steps
+
+### 1. Load Approved Brief
+Read brief.yaml and extract all requirements and context.
+
+### 2. Expand Each Functional Requirement
+For each FR, add:
+- **Description**: Detailed explanation of what it does
+- **User Story**: As a [persona], I want [action] so that [benefit]
+- **Acceptance Criteria**: Given-When-Then scenarios
+- **Priority**: P0 (must-have), P1 (should-have), P2 (nice-to-have)
+- **Estimated Complexity**: Small (1-3 days), Medium (4-7 days), Large (8+ days)
+- **Dependencies**: Other FRs that must be completed first
+
+### 3. Define Data Models
+Identify entities and their relationships:
+- User (id, email, password_hash, created_at, updated_at)
+- Post (id, user_id, title, content, tags, images, created_at, updated_at, published_at)
+- Tag (id, name)
+- PostTag (post_id, tag_id) - many-to-many relationship
+
+Document:
+- Entity name
+- Attributes with types
+- Relationships (one-to-one, one-to-many, many-to-many)
+- Constraints (unique, required, foreign keys)
+
+### 4. Outline API Endpoints
+For each FR, define required endpoints:
+- **Method**: GET, POST, PUT, DELETE
+- **Path**: /api/users, /api/posts/:id
+- **Request**: Body, query params, path params
+- **Response**: Success (200, 201) and error codes (400, 401, 404, 500)
+- **Authentication**: Required or public
+
+### 5. Define UI Screens
+For each user-facing FR:
+- Screen name
+- Purpose
+- Key elements (forms, buttons, lists)
+- Navigation flow
+- Responsive breakpoints
+
+### 6. Document Business Rules
+Extract business logic:
+- Validation rules (email format, password strength, max image size)
+- Authorization rules (users can only edit own posts)
+- Data constraints (post title max 200 chars)
+- Workflow rules (post must have title to publish)
+
+### 7. Identify Integration Points
+For external systems:
+- WordPress API: Read posts and metadata
+- Email service: Registration confirmation (if needed)
+- File storage: Image uploads (Supabase storage)
+
+### 8. Define Error Handling
+- Input validation errors
+- Authentication/authorization failures
+- Network failures
+- Database errors
+- External API failures
+
+### 9. Document State Management
+- Authentication state (logged in/out)
+- Form state (draft, submitting, submitted)
+- Data loading state (loading, success, error)
+- Cache invalidation strategy
+
+### 10. Create Initial PRD Draft
+Structured document with all sections populated.
+
+## Decision Points
+- **Missing Technical Details**: Make reasonable assumptions based on best practices
+- **Ambiguous Requirements**: Note for NFR extraction or edge case analysis
+
+## Error Handling
+- **Incomplete Brief**: Request brief completion before proceeding
+- **Contradictory Requirements**: Flag and request clarification
+
+## Output Format
+```yaml
+# prd-draft.yaml
+timestamp: 2026-02-13T14:30:00Z
+
+functional_requirements_detailed:
+  - id: FR-001
+    title: User Registration
+    description: |
+      New users can create an account by providing email and password.
+      Email must be unique and valid format. Password must meet strength requirements.
+      Upon successful registration, user is automatically logged in.
+    user_story: |
+      As a content creator, I want to register for an account with my email and
+      password so that I can start publishing blog posts.
+    acceptance_criteria:
+      - scenario: Successful registration
+        given: User is on registration page and not logged in
+        when: User submits valid email and password
+        then: |
+          - Account is created in database
+          - User receives JWT token
+          - User is redirected to dashboard
+          - Confirmation email is sent (future phase)
+      - scenario: Duplicate email
+        given: Email already exists in database
+        when: User submits registration form with existing email
+        then: |
+          - Registration fails with 409 error
+          - User sees "Email already registered" message
+          - Form remains populated (password cleared)
+      - scenario: Invalid password
+        given: User is on registration page
+        when: User submits password that doesn't meet requirements
+        then: |
+          - Registration fails with 400 error
+          - User sees specific validation errors
+          - Form shows password requirements
+    priority: P0
+    complexity: medium (5 days)
+    dependencies: []
+    api_endpoints:
+      - method: POST
+        path: /api/auth/register
+        request:
+          body:
+            email: string (required, valid email)
+            password: string (required, min 8 chars, 1 uppercase, 1 number)
+        response:
+          success: 201 Created
+            body:
+              user: {id, email, created_at}
+              token: string (JWT)
+          errors:
+            400: Invalid input (validation errors)
+            409: Email already registered
+    ui_screens:
+      - name: Registration Page
+        route: /register
+        elements:
+          - Email input field
+          - Password input field
+          - Password strength indicator
+          - Submit button
+          - Link to login page
+        validation:
+          - Real-time email format validation
+          - Real-time password strength check
+          - Disable submit until valid
+    data_model:
+      entity: User
+      attributes:
+        id: uuid (primary key)
+        email: string (unique, required)
+        password_hash: string (required)
+        created_at: timestamp
+        updated_at: timestamp
+    business_rules:
+      - Email must be unique across all users
+      - Password must be at least 8 characters
+      - Password must contain 1 uppercase, 1 lowercase, 1 number
+      - Email must be valid format (regex validation)
+      - Password must be hashed with bcrypt before storage
+
+  - id: FR-002
+    title: User Login
+    description: |
+      Registered users can log in with email and password to access protected features.
+    user_story: |
+      As a registered user, I want to log in with my credentials so that I can
+      access my dashboard and manage my posts.
+    acceptance_criteria:
+      - scenario: Successful login
+        given: User has valid account
+        when: User submits correct email and password
+        then: |
+          - User receives JWT token
+          - User is redirected to dashboard
+          - Token is stored in localStorage
+      - scenario: Invalid credentials
+        given: User is on login page
+        when: User submits incorrect email or password
+        then: |
+          - Login fails with 401 error
+          - User sees "Invalid credentials" message
+          - Form is cleared for security
+    priority: P0
+    complexity: medium (4 days)
+    dependencies: [FR-001]
+    api_endpoints:
+      - method: POST
+        path: /api/auth/login
+        request:
+          body:
+            email: string (required)
+            password: string (required)
+        response:
+          success: 200 OK
+            body:
+              user: {id, email}
+              token: string (JWT)
+          errors:
+            401: Invalid credentials
+    ui_screens:
+      - name: Login Page
+        route: /login
+        elements:
+          - Email input
+          - Password input
+          - Submit button
+          - Link to registration
+          - "Forgot password" link (future)
+
+data_models:
+  - name: User
+    attributes:
+      - name: id
+        type: uuid
+        constraints: [primary_key]
+      - name: email
+        type: string
+        constraints: [unique, required]
+      - name: password_hash
+        type: string
+        constraints: [required]
+      - name: created_at
+        type: timestamp
+        constraints: [required, default_now]
+      - name: updated_at
+        type: timestamp
+        constraints: [required, default_now, update_on_change]
+  - name: Post
+    attributes:
+      - name: id
+        type: uuid
+        constraints: [primary_key]
+      - name: user_id
+        type: uuid
+        constraints: [required, foreign_key(User.id)]
+      - name: title
+        type: string
+        constraints: [required, max_length(200)]
+      - name: content
+        type: text
+        constraints: [required]
+      - name: tags
+        type: array(string)
+        constraints: []
+      - name: image_urls
+        type: array(string)
+        constraints: []
+      - name: published_at
+        type: timestamp
+        constraints: [nullable]
+      - name: created_at
+        type: timestamp
+        constraints: [required, default_now]
+      - name: updated_at
+        type: timestamp
+        constraints: [required, default_now, update_on_change]
+    relationships:
+      - type: many_to_one
+        entity: User
+        description: Each post belongs to one user
+
+api_endpoints_summary:
+  authentication:
+    - POST /api/auth/register
+    - POST /api/auth/login
+    - GET /api/auth/me (get current user)
+    - POST /api/auth/logout
+  posts:
+    - GET /api/posts (list all, with pagination)
+    - GET /api/posts/:id (get single post)
+    - POST /api/posts (create new post, auth required)
+    - PUT /api/posts/:id (update post, auth required, owner only)
+    - DELETE /api/posts/:id (delete post, auth required, owner only)
+  search:
+    - GET /api/search?q=keyword&tag=tagname
+  wordpress:
+    - GET /api/wordpress/posts (fetch from WordPress API)
+
+ui_screens_summary:
+  public:
+    - / (home page with post list)
+    - /posts/:id (post detail page)
+    - /register (registration page)
+    - /login (login page)
+    - /search (search results page)
+  authenticated:
+    - /dashboard (user dashboard)
+    - /posts/new (create post page)
+    - /posts/:id/edit (edit post page)
+    - /profile (user profile, future)
+
+business_rules:
+  authentication:
+    - Password must be 8+ chars with 1 uppercase, 1 number
+    - JWT token expires after 7 days
+    - Email must be unique
+  posts:
+    - Title required, max 200 characters
+    - Content required, no max length
+    - Users can only edit/delete their own posts
+    - Published posts visible to all, drafts only to owner
+    - Tags are optional, stored as array
+    - Images must be <5MB, JPG/PNG only
+  search:
+    - Search is case-insensitive
+    - Matches in title, content, and tags
+    - Results paginated (20 per page)
+
+integration_points:
+  - name: WordPress API
+    purpose: Fetch existing blog posts
+    endpoint: https://existing-blog.com/wp-json/wp/v2/posts
+    authentication: API key in header
+    data_format: JSON
+    error_handling: Cache results, show stale data if API down
+  - name: Supabase
+    services: [auth, database, storage]
+    purpose: Backend infrastructure
+  - name: Image Storage
+    service: Supabase Storage
+    purpose: Store uploaded images
+    constraints: 5MB max per file, JPG/PNG only
+
+error_handling_strategy:
+  input_validation:
+    - Client-side validation for immediate feedback
+    - Server-side validation for security
+    - Return specific error messages (not generic "invalid input")
+  authentication:
+    - 401 for missing/invalid token
+    - Redirect to login page
+    - Clear token from localStorage
+  authorization:
+    - 403 for insufficient permissions
+    - User-friendly error message
+  network_errors:
+    - Retry up to 3 times with exponential backoff
+    - Show user-friendly error message
+    - Provide offline capability where possible
+  database_errors:
+    - Log error details server-side
+    - Return generic 500 error to client
+    - Do not expose database structure
+
+state_management:
+  authentication_state:
+    - Stored in React Context
+    - Persisted in localStorage (JWT)
+    - Checked on app initialization
+    - Cleared on logout
+  data_cache:
+    - Use TanStack Query for server state
+    - 5-minute stale time
+    - Background refetch on window focus
+  form_state:
+    - React Hook Form for form management
+    - Validation on blur and submit
+    - Autosave drafts every 30 seconds (future)
+
+next_step: nfr_extraction
+```