junior_task:
  id: "TASK-001-A"
  parent_task: "TASK-001"
  description: "Implement helper function to validate email addresses"
  scope: "Single function, no external dependencies"

  specification:
    function_name: "validate_email"
    signature: "def validate_email(email: str) -> bool"
    behavior: "Returns True if email matches RFC 5322 basic format"

  acceptance_criteria:
    - "Function signature matches specification exactly"
    - "Returns True for valid emails (see examples)"
    - "Returns False for invalid emails (see examples)"
    - "Unit tests cover all examples plus edge cases"
    - "Docstring explains purpose, parameters, returns"
    - "Type hints present"

  examples:
    valid:
      - "user@example.com"
      - "user.name@example.co.uk"
      - "user+tag@example.org"
    invalid:
      - "userexample.com"  # missing @
      - "@example.com"     # missing local part
      - "user@"            # missing domain

  constraints:
    - "Do not use external libraries (regex only)"
    - "Must handle empty string input"

  time_limit: "1h"

junior_deliverable:
  task_id: "TASK-001-A"
  status: "ready_for_review"

  files:
    - path: "src/utils/validation.py"
      type: "implementation"
    - path: "tests/utils/test_validation.py"
      type: "unit_tests"

  self_check:
    tests_pass: true
    ruff_clean: true
    coverage: 100  # for this function

  questions:
    - "Should we also validate against DNS MX records?"

  notes:
    - "Used re module for regex matching"

# src/utils/validation.py
"""Email validation utilities.

This module provides email validation functions following
RFC 5322 basic format requirements.
"""

import re


def validate_email(email: str) -> bool:
    """Validate email address format.

    Checks if the provided email string matches RFC 5322
    basic format requirements.

    Args:
        email: The email address string to validate.

    Returns:
        True if email format is valid, False otherwise.

    Examples:
        >>> validate_email("user@example.com")
        True
        >>> validate_email("invalid-email")
        False
    """
    if not email:
        return False

    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return bool(re.match(pattern, email))

# tests/utils/test_validation.py
"""Tests for email validation utilities."""

import pytest
from src.utils.validation import validate_email


class TestValidateEmail:
    """Tests for validate_email function."""

    @pytest.mark.parametrize("email", [
        "user@example.com",
        "user.name@example.co.uk",
        "user+tag@example.org",
    ])
    def test_valid_emails(self, email: str) -> None:
        """Valid emails should return True."""
        assert validate_email(email) is True

    @pytest.mark.parametrize("email", [
        "userexample.com",   # missing @
        "@example.com",      # missing local part
        "user@",             # missing domain
    ])
    def test_invalid_emails(self, email: str) -> None:
        """Invalid emails should return False."""
        assert validate_email(email) is False

    def test_empty_string(self) -> None:
        """Empty string should return False."""
        assert validate_email("") is False

    def test_none_input(self) -> None:
        """None input should raise TypeError or return False."""
        # Depends on contract - document behavior
        with pytest.raises(TypeError):
            validate_email(None)  # type: ignore

## Clarification Request: TASK-001-A

### Task as Understood
[Restate task in your own words]

### Unclear Points
1. [Specific question about requirement]
2. [Specific question about edge case]

### Assumptions (if proceeding without clarification)
1. [Assumption about behavior]

### Requested Information
- [What you need to proceed]

## Code Review: TASK-001-A

### Status: CHANGES_REQUESTED

### Required Changes
1. [File:Line] Add handling for unicode email addresses
2. [File:Line] Test missing for international domain (.co.jp)

junior_deliverable:
  task_id: "TASK-001-A"
  status: "ready_for_review"
  revision: 2

  changes_in_revision:
    - "Added unicode handling per review feedback"
    - "Added test for .co.jp domain"

  self_check:
    tests_pass: true
    ruff_clean: true

# Progress: TASK-001-A

**Status**: In Progress | Complete | Blocked | Awaiting Review
**Last Update**: 2026-02-03 14:32:15
**Completion**: 75%

## Completed
- Implemented validate_email function
- Added basic unit tests

## In Progress
- Writing edge case tests

## Blockers
- None

## Time Remaining
- Estimated: 15 minutes
- Time limit: 1h (45 min elapsed)

junior_task:
  id: "TASK-007-B"
  description: "Implement function to sanitize user input strings"

  specification:
    function_name: "sanitize_input"
    signature: "def sanitize_input(text: str, max_length: int = 255) -> str"
    behavior: |
      - Strip leading/trailing whitespace
      - Remove control characters (except newline, tab)
      - Truncate to max_length
      - Return sanitized string

  acceptance_criteria:
    - "Strips whitespace from both ends"
    - "Removes ASCII control characters 0-8, 11-12, 14-31"
    - "Preserves newline (10) and tab (9)"
    - "Truncates to max_length if longer"
    - "Returns empty string for None input (raise TypeError)"

  examples:
    - input: ["  hello world  ", 255]
      output: "hello world"
    - input: ["hello\x00world", 255]
      output: "helloworld"
    - input: ["hello\nworld", 255]
      output: "hello\nworld"
    - input: ["a" * 300, 255]
      output: "a" * 255

  time_limit: "45m"

# src/utils/sanitize.py
"""String sanitization utilities."""


def sanitize_input(text: str, max_length: int = 255) -> str:
    """Sanitize user input string.

    Removes dangerous characters and enforces length limits
    for safe storage and display.

    Args:
        text: The input string to sanitize.
        max_length: Maximum allowed length (default 255).

    Returns:
        Sanitized string with control characters removed
        and length enforced.

    Raises:
        TypeError: If text is None.

    Examples:
        >>> sanitize_input("  hello  ")
        'hello'
        >>> sanitize_input("a" * 300, max_length=10)
        'aaaaaaaaaa'
    """
    if text is None:
        raise TypeError("text cannot be None")

    # Strip whitespace
    result = text.strip()

    # Remove control characters except \n (10) and \t (9)
    allowed = {9, 10}  # tab, newline
    result = ''.join(
        char for char in result
        if ord(char) >= 32 or ord(char) in allowed
    )

    # Truncate to max_length
    return result[:max_length]

junior_deliverable:
  task_id: "TASK-007-B"
  status: "ready_for_review"
  files:
    - path: "src/utils/sanitize.py"
    - path: "tests/utils/test_sanitize.py"
  self_check:
    tests_pass: true
    ruff_clean: true
    coverage: 100
  questions: []
  notes:
    - "Used ord() for character code checking"
    - "Truncation happens after control char removal"