Merge pull request #2 from jeremyeder/feature/autonomous-quality-enforcement

Add Autonomous Quality Enforcement pattern documentation

Author: jeremyeder

.claude/agents/codebase-agent.md

@@ -28,6 +28,7 @@ You are the Codebase Agent for the Ambient Code Reference Repository. You assist
 Convert well-defined GitHub issues into pull requests:
 
 **Process**:
+
 1. Read issue description and acceptance criteria
 2. Review relevant code in `.claude/context/` and codebase
 3. Create implementation plan
@@ -39,6 +40,7 @@ Convert well-defined GitHub issues into pull requests:
 9. Push and create PR with detailed description
 
 **Requirements**:
+
 - Issue must have clear acceptance criteria
 - All tests must pass
 - All linters must pass
@@ -49,13 +51,15 @@ Convert well-defined GitHub issues into pull requests:
 Provide actionable feedback on pull requests:
 
 **Review Focus**:
+
 - **Bugs**: Logic errors, edge cases, error handling
 - **Security**: Input validation, OWASP Top 10 vulnerabilities
 - **Performance**: Inefficient algorithms, unnecessary operations
 - **Style**: Adherence to black/isort/ruff standards
 - **Testing**: Coverage, missing test cases
 
 **Feedback Guidelines**:
+
 - Be specific and actionable
 - Provide code examples for fixes
 - Explain "why" not just "what"
@@ -67,13 +71,15 @@ Provide actionable feedback on pull requests:
 Maintain codebase health:
 
 **Tasks**:
+
 - Dependency updates (via Dependabot or manual)
 - Linting fixes (black, isort, ruff)
 - Documentation updates (keep in sync with code)
 - Test coverage improvements
 - Security vulnerability patches
 
 **Approach**:
+
 - Create separate PRs for each type of change
 - Include clear rationale in PR description
 - Ensure all tests pass before creating PR
@@ -114,9 +120,10 @@ Follow CLAUDE.md strictly:
 
 ### Level 2 (Future): Auto-Merge Low-Risk
 
-*Requires explicit configuration*
+> Note: Requires explicit configuration
 
 Auto-merge conditions:
+
 - Dependency updates (patch versions only)
 - Linting fixes (no logic changes)
 - Documentation updates (no code changes)
@@ -130,6 +137,7 @@ Use modular context files in `.claude/context/`:
 ### architecture.md
 
 Layered architecture patterns:
+
 - API Layer: FastAPI routes, request/response models
 - Service Layer: Business logic, data manipulation
 - Model Layer: Pydantic models, validation
@@ -138,6 +146,7 @@ Layered architecture patterns:
 ### security-standards.md
 
 Security patterns:
+
 - Input validation at API boundary (Pydantic)
 - Sanitization in `app/core/security.py`
 - Environment variables for secrets (.env files)
@@ -146,6 +155,7 @@ Security patterns:
 ### testing-patterns.md
 
 Testing strategies:
+
 - Unit tests: Service layer isolation, Arrange-Act-Assert
 - Integration tests: API endpoints, TestClient
 - E2E tests: Full workflows (outline only)
@@ -158,6 +168,7 @@ Testing strategies:
 **Issue**: "Add pagination support to Items endpoint"
 
 **Process**:
+
 1. Read issue and understand requirements
 2. Review `app/api/v1/items.py` and `app/services/item_service.py`
 3. Create plan:
@@ -175,6 +186,7 @@ Testing strategies:
 **PR**: "Add caching to item lookups"
 
 **Review**:
+
 ```markdown
 **Security** 🔴
 - Line 45: Cache keys should be sanitized to prevent cache poisoning
@@ -188,25 +200,31 @@ Testing strategies:
   ```
 
 **Performance** 🟡
+
 - Line 78: Consider using TTL to prevent cache bloat
 
 **Testing** 🟡
+
 - Missing test case for cache invalidation on update
 
 **Positive** ✅
+
 - Good use of context manager for cache cleanup
-```
+
+```text
 
 ### Example 3: Proactive Maintenance
 
 **Task**: Update Pydantic from 2.5.0 to 2.6.0
 
 **Process**:
+
 1. Update `requirements.txt`
 2. Run tests to verify compatibility
 3. Update any deprecated API usage
 4. Create PR:
-   ```
+
+   ```text
    Update Pydantic to 2.6.0
 
    - Update requirements.txt
@@ -235,6 +253,7 @@ When errors occur:
 ## Anti-Patterns
 
 **NEVER**:
+
 - ❌ Commit without running linters and tests
 - ❌ Push to main without PR
 - ❌ Make assumptions about ambiguous requirements
@@ -246,6 +265,7 @@ When errors occur:
 ## Success Criteria
 
 A successful CBA operation:
+
 - ✅ All linters pass (black, isort, ruff)
 - ✅ All tests pass (80%+ coverage)
 - ✅ Security scans pass (bandit, safety)

.claude/context/architecture.md

@@ -4,7 +4,7 @@
 
 The application follows a strict layered architecture with clear separation of concerns:
 
-```
+```text
 ┌─────────────────────────────────┐
 │      API Layer (FastAPI)        │  HTTP routes, request/response models
 ├─────────────────────────────────┤
@@ -14,7 +14,7 @@ The application follows a strict layered architecture with clear separation of c
 ├─────────────────────────────────┤
 │   Core Layer (Utilities)        │  Config, security, logging
 └─────────────────────────────────┘
-```
+```text
 
 ## Layer Responsibilities
 
@@ -23,17 +23,20 @@ The application follows a strict layered architecture with clear separation of c
 **Purpose**: Handle HTTP concerns
 
 **Files**:
+
 - `health.py` - Health check endpoints
 - `v1/items.py` - Resource endpoints
 
 **Responsibilities**:
+
 - Route definitions
 - Request/response serialization
 - HTTP status codes
 - Error responses
 - OpenAPI documentation
 
 **Never in API Layer**:
+
 - Business logic
 - Database/storage operations
 - Complex validation
@@ -43,15 +46,18 @@ The application follows a strict layered architecture with clear separation of c
 **Purpose**: Implement business logic
 
 **Files**:
+
 - `item_service.py` - Item business logic
 
 **Responsibilities**:
+
 - CRUD operations
 - Business rules
 - Data manipulation
 - Transaction coordination
 
 **Never in Service Layer**:
+
 - HTTP concerns (status codes, headers)
 - Request/response serialization
 
@@ -60,15 +66,18 @@ The application follows a strict layered architecture with clear separation of c
 **Purpose**: Data validation and representation
 
 **Files**:
+
 - `item.py` - Item models (ItemBase, ItemCreate, ItemUpdate, Item)
 
 **Responsibilities**:
+
 - Field validation (Pydantic validators)
 - Type annotations
 - Serialization rules
 - Sanitization (via validators)
 
 **Never in Model Layer**:
+
 - Business logic
 - HTTP concerns
 
@@ -77,27 +86,29 @@ The application follows a strict layered architecture with clear separation of c
 **Purpose**: Cross-cutting concerns
 
 **Files**:
+
 - `config.py` - Application settings
 - `security.py` - Sanitization, validation utilities
 - `logging.py` - Structured logging
 
 **Responsibilities**:
+
 - Configuration management
 - Security utilities
 - Logging setup
 - Shared utilities
 
 ## Dependency Flow
 
-```
+```text
 API Layer
   ↓ (depends on)
 Service Layer
   ↓ (depends on)
 Model Layer
   ↓ (depends on)
 Core Layer
-```
+```text
 
 **Rule**: Higher layers can depend on lower layers, but not vice versa.
 
@@ -124,7 +135,7 @@ def create_item(self, data: ItemCreate) -> Item:
     # Store
     self._items[item.id] = item
     return item
-```
+```text
 
 ## Common Patterns
 
@@ -138,7 +149,7 @@ item_service = ItemService()
 
 # app/api/v1/items.py
 from app.services.item_service import item_service
-```
+```text
 
 ### Pydantic Validators
 
@@ -149,7 +160,7 @@ Sanitization in model validators:
 @classmethod
 def sanitize_name(cls, v: str) -> str:
     return sanitize_string(v, max_length=200)
-```
+```text
 
 ### Error Handling
 
@@ -167,7 +178,7 @@ def create_item(data: ItemCreate) -> Item:
         return item_service.create_item(data)
     except ValueError as e:
         raise HTTPException(status_code=409, detail=str(e))
-```
+```text
 
 ## Testing Architecture
 

.claude/context/security-standards.md

@@ -5,6 +5,7 @@
 ### Principle: Validate at Boundaries
 
 **Validate external input at API boundary only**:
+
 - Use Pydantic models for all request payloads
 - Validation happens automatically in route parameters
 - Trust internal code - don't re-validate
@@ -42,11 +43,13 @@ All sanitization functions in `app/core/security.py`.
 ### Functions
 
 **`sanitize_string(value, max_length)`**:
+
 - Remove control characters
 - Trim whitespace
 - Enforce length limits
 
 **`validate_slug(value)`**:
+
 - Ensure URL-safe (lowercase, numbers, hyphens only)
 - No leading/trailing hyphens
 - No consecutive hyphens
@@ -112,12 +115,14 @@ podman run -e SECRET_KEY=xxx myapp
 ### Input Validation Rules
 
 **String fields**:
+
 - Max length limits
 - Character allowlist (for slugs)
 - Trim whitespace
 - Remove control characters
 
 **Numeric fields**:
+
 - Min/max validation
 - Type checking (Pydantic automatic)
 
@@ -175,20 +180,23 @@ safety check
 ### CI Integration
 
 Both run in `.github/workflows/security.yml`:
+
 - Weekly schedule
 - On push/PR
 - Fail build on HIGH severity
 
 ## Common Mistakes
 
 **DON'T**:
+
 - ❌ Validate the same data multiple times
 - ❌ Sanitize in both model and service layer
 - ❌ Trust user input without validation
 - ❌ Commit `.env` files
 - ❌ Hardcode secrets
 
 **DO**:
+
 - ✅ Validate once at API boundary
 - ✅ Use Pydantic validators
 - ✅ Keep secrets in environment