feat: feat(api): Add RFC9457-compliant error handling and state machines

.claude/hookify.block-push-main.local.md

@@ -0,0 +1,19 @@
+---
+name: block-push-main
+enabled: true
+event: bash
+pattern: git push[^|]*\bmain\b
+action: block
+---
+
+🚫 **Direct push to main blocked!**
+
+This project requires all changes to `main` to go through pull requests.
+
+**What to do instead:**
+
+1. Create a feature branch: `git checkout -b feature/your-feature`
+2. Push your branch: `git push -u origin feature/your-feature`
+3. Create a PR: `gh pr create --base main`
+
+See AGENTS.md Git Rules for more details.

.claude/hookify.warn-lru-cache.local.md

@@ -0,0 +1,28 @@
+---
+name: warn-lru-cache
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: \.py$
+  - field: new_text
+    operator: regex_match
+    pattern: from functools import.*lru_cache|@lru_cache
+---
+
+⚠️ **functools.lru_cache detected!**
+
+This project uses **cashews** for caching instead of `functools.lru_cache`.
+
+**Replace with:**
+
+```python
+from cashews import cache
+
+
+@cache(ttl="1h")
+async def your_function(): ...
+```
+
+See AGENTS.md "Required Library Substitutions" for details.

.claude/hookify.warn-stdlib-logging.local.md

@@ -0,0 +1,27 @@
+---
+name: warn-stdlib-logging
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: \.py$
+  - field: new_text
+    operator: regex_match
+    pattern: ^import logging$|^from logging import
+---
+
+⚠️ **stdlib logging detected!**
+
+This project uses **loguru** instead of the stdlib `logging` module.
+
+**Replace with:**
+
+```python
+from app.core.logging import logger
+
+logger.info("Your message")
+logger.bind(key=value).info("Structured logging")
+```
+
+See AGENTS.md "Required Library Substitutions" for details.

.claude/hookify.warn-utcnow.local.md

@@ -0,0 +1,28 @@
+---
+name: warn-utcnow
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: \.py$
+  - field: new_text
+    operator: regex_match
+    pattern: datetime\.utcnow\(\)
+---
+
+⚠️ **Deprecated datetime.utcnow() detected!**
+
+`datetime.utcnow()` is deprecated and returns a naive datetime.
+
+**Replace with:**
+
+```python
+from datetime import UTC, datetime
+
+now = datetime.now(UTC)
+```
+
+This returns a timezone-aware datetime, which is the correct approach.
+
+See AGENTS.md "Required Library Substitutions" for details.

.claude/instincts/api-architecture.md

@@ -0,0 +1,46 @@
+# Instinct: Three-API Architecture
+
+**Confidence**: 100% **Source**: AGENTS.md, codebase structure **Category**: architecture
+
+## Pattern
+
+Ouroboros uses three distinct APIs with different purposes and authentication:
+
+### Agent API (`/api/v1/client/*`)
+
+- **Purpose**: Communication with CipherSwarmAgent (Go hashcat runners)
+- **Auth**: Bearer token (`csa_<agent_id>_<random>`)
+- **Contract**: IMMUTABLE - locked to `contracts/v1_api_swagger.json`
+- **Breaking changes**: NEVER allowed
+
+### Web UI API (`/api/v1/web/*`)
+
+- **Purpose**: SvelteKit frontend interactions
+- **Auth**: OAuth2 + refresh tokens (session cookies)
+- **Responses**: Optimized for UI consumption
+
+### Control API (`/api/v1/control/*`)
+
+- **Purpose**: CLI tool (csadmin), automation, integrations
+- **Auth**: API key bearer (`cst_<user_id>_<random>`)
+- **Errors**: RFC9457 `application/problem+json` format
+- **Pagination**: Offset-based for programmatic consumption
+
+## Service Layer Reuse
+
+All three APIs delegate to shared service functions:
+
+```
+Web UI API  ──┐
+Control API ──┼──> app/core/services/* ──> SQLAlchemy ORM
+Agent API   ──┘
+```
+
+## Trigger
+
+Activate when:
+
+- Creating new endpoints
+- Modifying existing API behavior
+- Discussing authentication
+- Planning API changes

.claude/instincts/commit-conventions.md

@@ -0,0 +1,29 @@
+# Instinct: Commit Conventions
+
+**Confidence**: 95% **Source**: Git history analysis (100+ commits) **Category**: workflow
+
+## Pattern
+
+When creating commits in the Ouroboros project:
+
+1. Use conventional commit format: `<type>(<scope>): <description>`
+2. Most common types: `chore`, `fix`, `feat`, `docs`, `test`, `ci`
+3. Common scopes: `api`, `deps`, `docs`, `auth`, `security`, `state-machines`
+4. Keep descriptions lowercase and concise
+5. No period at end of subject line
+
+## Examples
+
+```
+fix(api): improve error handling and add get_valid_actions method
+test(state-machines): add tests for get_valid_actions method
+chore(deps): bump docker/login-action from 3.6.0 to 3.7.0
+docs: link CLAUDE.md to AGENTS.md for reference
+feat(api): implement Agent API v2 with enhanced features
+```
+
+## Anti-patterns
+
+- `Fixed bug` (missing type/scope)
+- `feat(api): Added new feature.` (capitalized, has period)
+- Long multi-line commit messages for simple changes

.claude/instincts/library-substitutions.md

@@ -0,0 +1,65 @@
+# Instinct: Library Substitutions
+
+**Confidence**: 100% **Source**: AGENTS.md (documented requirement) **Category**: code-style
+
+## Pattern
+
+The Ouroboros project requires specific library substitutions. Always use the prescribed alternatives.
+
+| Never Use             | Always Use                   |
+| --------------------- | ---------------------------- |
+| `logging` (stdlib)    | `loguru`                     |
+| `functools.lru_cache` | `cashews`                    |
+| `datetime.utcnow()`   | `datetime.now(datetime.UTC)` |
+| `Optional[T]`         | `T \| None`                  |
+
+## Examples
+
+### Logging
+
+```python
+# Wrong
+import logging
+
+logger = logging.getLogger(__name__)
+logger.info("Message")
+
+# Correct
+from loguru import logger
+
+logger.info("Message")
+logger.bind(task_id=task.id).info("Task started")
+```
+
+### Datetime
+
+```python
+# Wrong
+from datetime import datetime
+
+now = datetime.utcnow()
+
+# Correct
+from datetime import datetime, UTC
+
+now = datetime.now(UTC)
+```
+
+### Type Hints
+
+```python
+# Wrong
+from typing import Optional
+def get_user(id: int) -> Optional[User]:
+
+# Correct
+def get_user(id: int) -> User | None:
+```
+
+## Trigger
+
+Activate when:
+
+- Writing new Python code
+- Reviewing code for style issues
+- Seeing `import logging`, `lru_cache`, `utcnow()`, or `Optional[`

.claude/instincts/protected-files.md

@@ -0,0 +1,48 @@
+# Instinct: Protected Files
+
+**Confidence**: 100% **Source**: AGENTS.md (documented requirement) **Category**: safety
+
+## Pattern
+
+Certain directories and files are protected and must NEVER be modified without explicit permission.
+
+### Protected Directories
+
+| Directory    | Contents             | Why Protected           |
+| ------------ | -------------------- | ----------------------- |
+| `contracts/` | API contract specs   | Agent API compatibility |
+| `alembic/`   | Database migrations  | Data integrity          |
+| `.cursor/`   | Cursor configuration | IDE settings            |
+| `.github/`   | GitHub workflows     | CI/CD stability         |
+
+### Protected Files
+
+- `contracts/v1_api_swagger.json` - Agent API v1 contract (IMMUTABLE)
+- `contracts/current_api_openapi.json` - Current API snapshot
+
+### Agent API v1 Rules
+
+The Agent API at `/api/v1/client/*` is IMMUTABLE:
+
+- Contract MUST match `contracts/v1_api_swagger.json` exactly
+- Breaking changes are NEVER allowed
+- Locked to OpenAPI 3.0.1 spec
+- All responses must validate against spec
+
+## Response When Asked to Modify
+
+```
+I notice you're asking me to modify [protected path].
+This is a protected file/directory in Ouroboros.
+
+Per project rules, I cannot modify this without explicit permission.
+Should I proceed anyway, or would you like to discuss alternatives?
+```
+
+## Trigger
+
+Activate when:
+
+- Asked to modify files in contracts/, alembic/, .cursor/, .github/
+- Touching Agent API v1 endpoints
+- Making changes that could break API compatibility

.claude/instincts/rfc9457-errors.md

@@ -0,0 +1,58 @@
+# Instinct: RFC9457 Error Responses
+
+**Confidence**: 100% **Source**: Control API implementation, design specs **Category**: api-design
+
+## Pattern
+
+Control API errors must return `application/problem+json` format per RFC9457:
+
+```python
+{
+    "type": "https://example.com/problems/invalid-request",
+    "title": "Invalid Request",
+    "status": 400,
+    "detail": "The request parameters are invalid",
+    "instance": "/api/v1/control/campaigns/123",
+}
+```
+
+### Extension Fields
+
+Add context-specific extension fields:
+
+```python
+# For state transition errors
+{
+    "type": "...",
+    "title": "Invalid State Transition",
+    "status": 409,
+    "detail": "Cannot start campaign from COMPLETED state",
+    "instance": "/api/v1/control/campaigns/123/start",
+    "current_state": "COMPLETED",
+    "valid_actions": ["archive"],  # What CAN be done
+}
+
+# For validation errors
+{
+    "type": "...",
+    "title": "Validation Error",
+    "status": 422,
+    "detail": "Request validation failed",
+    "instance": "/api/v1/control/campaigns",
+    "errors": [
+        {"field": "name", "message": "Field is required"},
+    ],
+}
+```
+
+## Middleware Implementation
+
+Use `app/core/control_rfc9457_middleware.py` for automatic exception translation.
+
+## Trigger
+
+Activate when:
+
+- Implementing Control API endpoints
+- Handling errors in Control API
+- Adding new exception types for Control API