docs: update CLAUDE.md and commands for services-layer architecture

.claude/commands/debug.md

@@ -8,13 +8,14 @@ You are debugging an issue. Follow this structured approach to avoid spinning in
 - Read the full error message and stack trace
 - Identify the layer where the error originated:
   - **CLI/Args** - Input validation, path resolution
-  - **Config Parsing** - YAML parsing, JSON Schema validation
-  - **Session Management** - Mutex, session.json, lock files
-  - **Audit System** - Logging, metrics tracking, atomic writes
-  - **Claude SDK** - Agent execution, MCP servers, turn handling
-  - **Git Operations** - Checkpoints, rollback, commit
-  - **Tool Execution** - nmap, subfinder, whatweb
-  - **Validation** - Deliverable checks, queue validation
+  - **Config Parsing** - YAML parsing, JSON Schema validation (`src/config-parser.ts`)
+  - **Session Management** - Agent definitions (`src/session-manager.ts`), mutex (`src/utils/concurrency.ts`)
+  - **DI Container** - Container initialization/lookup (`src/services/container.ts`)
+  - **Services** - AgentExecutionService, ConfigLoaderService, ExploitationCheckerService, error-handling (`src/services/`)
+  - **Audit System** - Logging, metrics tracking, atomic writes (`src/audit/`)
+  - **Claude SDK** - Agent execution, MCP servers, turn handling (`src/ai/claude-executor.ts`)
+  - **Git Operations** - Checkpoints, rollback, commit (`src/services/git-manager.ts`)
+  - **Validation** - Deliverable checks, queue validation (`src/services/queue-validation.ts`)
 
 ## Step 2: Check Relevant Logs
 
@@ -37,12 +38,14 @@ For Shannon, trace through these layers:
 
 1. **Temporal Client** → `src/temporal/client.ts` - Workflow initiation
 2. **Workflow** → `src/temporal/workflows.ts` - Pipeline orchestration
-3. **Activities** → `src/temporal/activities.ts` - Agent execution with heartbeats
-4. **Config** → `src/config-parser.ts` - YAML loading, schema validation
-5. **Session** → `src/session-manager.ts` - Agent definitions, execution order
-6. **Audit** → `src/audit/audit-session.ts` - Logging facade, metrics tracking
-7. **Executor** → `src/ai/claude-executor.ts` - SDK calls, MCP setup, retry logic
-8. **Validation** → `src/queue-validation.ts` - Deliverable checks
+3. **Activities** → `src/temporal/activities.ts` - Thin wrappers: heartbeat, error classification
+4. **Container** → `src/services/container.ts` - Per-workflow DI
+5. **Services** → `src/services/agent-execution.ts` - Agent lifecycle
+6. **Config** → `src/config-parser.ts` via `src/services/config-loader.ts`
+7. **Prompts** → `src/services/prompt-manager.ts`
+8. **Audit** → `src/audit/audit-session.ts` - Logging facade, metrics tracking
+9. **Executor** → `src/ai/claude-executor.ts` - SDK calls, MCP setup, retry logic
+10. **Validation** → `src/services/queue-validation.ts` - Deliverable checks
 
 ## Step 4: Identify Root Cause
 
@@ -58,7 +61,10 @@ For Shannon, trace through these layers:
 | Cost/timing not tracked | Metrics not reloaded before update | Add `metricsTracker.reload()` before updates |
 | session.json corrupted | Partial write during crash | Delete and restart, or restore from backup |
 | YAML config rejected | Invalid schema or unsafe content | Run through AJV validator manually |
-| Prompt variable not replaced | Missing `{{VARIABLE}}` in context | Check `prompt-manager.ts` interpolation |
+| Prompt variable not replaced | Missing `{{VARIABLE}}` in context | Check `src/services/prompt-manager.ts` interpolation |
+| Service returns Err result | Check `ErrorCode` in Result | Trace through `classifyErrorForTemporal()` in `src/services/error-handling.ts` |
+| Container not found | `getOrCreateContainer()` not called | Check activity setup code in `src/temporal/activities.ts` |
+| ActivityLogger undefined | `createActivityLogger()` not called | Must be called at top of each activity function |
 
 **MCP Server Issues:**
 ```bash
@@ -123,6 +129,8 @@ shannon <URL> <REPO> --pipeline-testing
 
 ## Quick Reference: Error Types
 
+`ErrorCode` enum in `src/types/errors.ts` provides finer-grained classification used by `classifyErrorForTemporal()` in `src/services/error-handling.ts`.
+
 | PentestError Type | Meaning | Retryable? |
 |-------------------|---------|------------|
 | `config` | Configuration file issues | No |

.claude/commands/review.md

@@ -19,6 +19,8 @@ git diff HEAD
 - [ ] **Retryable flag matches behavior** - If error will be retried, set `retryable: true`
 - [ ] **Context includes debugging info** - Add relevant paths, tool names, error codes to context object
 - [ ] **Never swallow errors silently** - Always log or propagate errors
+- [ ] **Use ErrorCode enum** - Prefer `ErrorCode.CONFIG_INVALID` over string matching for classification
+- [ ] **Result<T,E> for service returns** - Services return `Result`, not throw
 
 ### Audit System & Concurrency (CRITICAL)
 - [ ] **Mutex protection for parallel operations** - Use `sessionMutex.lock()` when updating `session.json` during parallel agent execution
@@ -41,6 +43,13 @@ git diff HEAD
 - [ ] **Duplicate rule detection** - Same `type:url_path` cannot appear twice
 - [ ] **JSON Schema validation before use** - Config must pass AJV validation
 
+### Services Layer & DI Container (CRITICAL)
+- [ ] **Business logic in services, not activities** — Activities: heartbeat loop, error classification, container calls only. Domain logic → `src/services/`
+- [ ] **Services accept ActivityLogger** — Never import `@temporalio/*` in services. Use `ActivityLogger` interface from `src/types/`
+- [ ] **Result type for fallible operations** — Service methods return `Result<T, PentestError>`, unwrap with `isOk()`/`isErr()`. Activities call `executeOrThrow()` at the boundary
+- [ ] **Container lifecycle** — `getOrCreateContainer()` at activity start, `removeContainer()` only in workflow cleanup
+- [ ] **AuditSession not in container** — Must be passed per-agent call (parallel safety)
+
 ### Session & Agent Management (CRITICAL)
 - [ ] **Deliverable dependencies respected** - Exploitation agents only run if vulnerability queue exists AND has items
 - [ ] **Queue validation before exploitation** - Use `safeValidateQueueAndDeliverable()` to check eligibility
@@ -91,6 +100,8 @@ git diff HEAD
 - [ ] **Duplicate retry logic** - Don't implement retry at both caller and callee level
 - [ ] **Hardcoded error message matching** - Prefer error codes over regex on error.message
 - [ ] **Missing timeout on long operations** - Git operations and API calls should have timeouts
+- [ ] **Console.log in services** — Use `ActivityLogger`. Only CLI display code (`client.ts`, `worker.ts`, `output-formatters.ts`) uses console.log
+- [ ] **Temporal imports in services** — Services must stay Temporal-agnostic. If you need Temporal APIs, it belongs in activities
 
 ### Code Quality
 - [ ] **No dead code added** - Remove unused imports, functions, variables