docs(02-04): complete human escalation handoff plan

- Summary with decisions, metrics, and self-check
- STATE.md: advance progress to 78%, add decisions, record session
- ROADMAP.md: update phase 2 plan progress (3 of 5 complete)
- REQUIREMENTS.md: mark AGNT-05 complete

.planning/REQUIREMENTS.md

@@ -21,7 +21,7 @@ Requirements for beta-ready release. Each maps to roadmap phases.
 - [x] **AGNT-02**: Agent maintains conversational memory within sessions (sliding window)
 - [x] **AGNT-03**: Agent retrieves relevant past context via vector search (pgvector long-term memory)
 - [ ] **AGNT-04**: Agent can invoke registered tools to perform actions (tool registry + execution)
-- [ ] **AGNT-05**: Agent escalates to human when configured rules trigger, transferring full conversation context
+- [x] **AGNT-05**: Agent escalates to human when configured rules trigger, transferring full conversation context
 - [ ] **AGNT-06**: Every agent action (LLM call, tool invocation, handoff) is logged in an audit trail
 - [ ] **AGNT-07**: Agent token usage is tracked per-agent per-tenant with configurable budget limits
 
@@ -104,7 +104,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | AGNT-02 | Phase 2 | Complete |
 | AGNT-03 | Phase 2 | Complete |
 | AGNT-04 | Phase 2 | Pending |
-| AGNT-05 | Phase 2 | Pending |
+| AGNT-05 | Phase 2 | Complete |
 | AGNT-06 | Phase 2 | Pending |
 | AGNT-07 | Phase 3 | Pending |
 | LLM-01 | Phase 1 | Complete |

.planning/ROADMAP.md

@@ -79,7 +79,7 @@ Phases execute in numeric order: 1 → 2 → 3
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
 | 1. Foundation | 4/4 | Complete    | 2026-03-23 |
-| 2. Agent Features | 2/5 | In Progress|  |
+| 2. Agent Features | 3/5 | In Progress|  |
 | 3. Operator Experience | 0/2 | Not started | - |
 
 ---

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: planning
-stopped_at: Completed 02-agent-features/02-01-PLAN.md
+stopped_at: Completed 02-agent-features/02-04-PLAN.md
-last_updated: "2026-03-23T20:46:53.813Z"
+last_updated: "2026-03-23T20:55:02.545Z"
 last_activity: 2026-03-23 — Roadmap created, ready for Phase 1 planning
 progress:
   total_phases: 3
   completed_phases: 1
   total_plans: 9
-  completed_plans: 6
+  completed_plans: 7
   percent: 0
 ---
 
@@ -56,6 +56,7 @@ Progress: [░░░░░░░░░░] 0%
 | Phase 01-foundation P03 | 9 | 2 tasks | 20 files |
 | Phase 02-agent-features P03 | 7 | 2 tasks | 7 files |
 | Phase 02-agent-features P02-01 | 9m 22s | 2 tasks | 15 files |
+| Phase 02-agent-features P04 | 5m | 2 tasks | 7 files |
 
 ## Accumulated Context
 
@@ -87,6 +88,9 @@ Recent decisions affecting current work:
 - [Phase 02-agent-features]: pgvector/pgvector:pg16 Docker image required for pgvector extension — postgres:16-alpine does not include vector extension control file
 - [Phase 02-agent-features]: SentenceTransformer loaded as lazy singleton — model loaded once on first use to avoid per-call 2s overhead; 384d all-MiniLM-L6-v2 matches vector(384) column
 - [Phase 02-agent-features]: embed_and_store Celery task is fire-and-forget (ignore_result=True) — embedding backfill never blocks LLM response path
+- [Phase 02-agent-features]: Keyword-based conversation metadata detection (v1) uses billing keywords + attempt counter from sliding window — simple and sufficient for initial escalation rules
+- [Phase 02-agent-features]: Escalation condition parser uses regex not eval — safe, no code injection risk, supports 'keyword AND count > N' format
+- [Phase 02-agent-features]: No-op audit logger stub in tasks.py allows escalation to function before Plan 02 audit module ships — one-import swap when ready
 
 ### Pending Todos
 
@@ -98,6 +102,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-03-23T20:46:53.810Z
+Last session: 2026-03-23T20:55:02.542Z
-Stopped at: Completed 02-agent-features/02-01-PLAN.md
+Stopped at: Completed 02-agent-features/02-04-PLAN.md
 Resume file: None

.planning/phases/02-agent-features/02-04-SUMMARY.md

@@ -0,0 +1,127 @@
+---
+phase: 02-agent-features
+plan: 04
+subsystem: orchestrator
+tags: [escalation, handoff, slack-api, redis, celery, pydantic, postgres, alembic]
+
+requires:
+  - phase: 02-01
+    provides: "get_recent_messages for transcript assembly; Redis short-term memory infrastructure"
+
+provides:
+  - "Escalation rule evaluator: 'keyword AND count > N' condition parser + natural language phrase detection"
+  - "Conversation transcript packager: Slack mrkdwn format with 3000-char truncation"
+  - "Human DM delivery: Slack conversations.open + chat.postMessage via httpx"
+  - "Escalation status tracking in Redis: escalation_status_key sets 'escalated' flag"
+  - "Post-escalation assistant mode: end-user messages to escalated threads get auto-reply, skipping LLM"
+  - "Agent model fields: escalation_assignee (Slack user ID), natural_language_escalation (bool)"
+  - "Alembic migration 003: adds escalation_assignee and natural_language_escalation to agents table"
+  - "No-op audit logger stub for escalation events (replaced when Plan 02 audit module ships)"
+
+affects:
+  - "02-02 (audit) — escalation events use no-op logger stub, ready for real AuditLogger swap"
+  - "tasks.py pipeline — escalation pre/post checks integrated around LLM call"
+
+tech-stack:
+  added: []
+  patterns:
+    - "Condition parsing: 'keyword AND count_field > N' format, regex-based, no eval()"
+    - "TDD pattern: RED (failing tests committed) then GREEN (implementation committed)"
+    - "Escalation pre-check before LLM: Redis flag gates whether LLM is called at all"
+    - "No-op logger stub: allows feature to work before audit plan is implemented"
+
+key-files:
+  created:
+    - packages/orchestrator/orchestrator/escalation/__init__.py
+    - packages/orchestrator/orchestrator/escalation/handler.py
+    - migrations/versions/003_escalation_fields.py
+    - tests/unit/test_escalation.py
+    - tests/integration/test_escalation.py
+  modified:
+    - packages/shared/shared/models/tenant.py
+    - packages/orchestrator/orchestrator/tasks.py
+
+key-decisions:
+  - "Keyword-based conversation metadata detection (v1): billing keywords + attempt counter from sliding window — simple and sufficient for initial rules"
+  - "Natural language escalation condition uses literal string 'natural_language_escalation' in escalation_rules config — matches plan spec"
+  - "Bot token loaded unconditionally in _process_message (not gated on placeholder_ts) — escalation DM needs it regardless of Slack placeholder presence"
+  - "No-op audit logger stub in tasks.py: escalation works independently of Plan 02 audit module; swap is a one-line change"
+  - "Condition parser uses regex (not eval): safe, deterministic, no code injection risk"
+
+patterns-established:
+  - "Escalation check is two-phase: pre-LLM (assistant mode gate) and post-LLM (rule trigger)"
+  - "assistant mode: escalated thread + end user sender → skip LLM entirely, return static reply"
+  - "Escalation DM format follows employee metaphor: '{agent.name} needs human assistance'"
+
+requirements-completed:
+  - AGNT-05
+
+duration: 5min
+completed: 2026-03-23
+---
+
+# Phase 02 Plan 04: Human Escalation Handoff Summary
+
+**Rule-based and natural-language escalation with Slack DM delivery, Redis assistant-mode gate, and full transcript packaging**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-23T21:08:30Z
+- **Completed:** 2026-03-23T21:13:12Z
+- **Tasks:** 2
+- **Files modified:** 7
+
+## Accomplishments
+
+- Built complete escalation handler: condition evaluator, transcript builder, and Slack DM pipeline
+- Wired escalation checks into the orchestrator message pipeline at both pre-LLM and post-LLM positions
+- Added Agent model columns and Alembic migration for escalation configuration
+- 28 tests passing (22 unit, 6 integration) covering all escalation behaviors
+
+## Task Commits
+
+1. **Task 1 (TDD RED): Failing tests for escalation handler** - `d489551` (test)
+2. **Task 1 (TDD GREEN): Escalation handler implementation** - `4047b55` (feat)
+3. **Task 2: Wire escalation into orchestrator pipeline** - `a025cad` (feat)
+
+## Files Created/Modified
+
+- `packages/orchestrator/orchestrator/escalation/__init__.py` - Package init for escalation module
+- `packages/orchestrator/orchestrator/escalation/handler.py` - check_escalation_rules, build_transcript, escalate_to_human
+- `packages/shared/shared/models/tenant.py` - Added escalation_assignee and natural_language_escalation to Agent model
+- `migrations/versions/003_escalation_fields.py` - Alembic migration for new Agent columns
+- `packages/orchestrator/orchestrator/tasks.py` - Escalation pre/post checks in _process_message
+- `tests/unit/test_escalation.py` - 22 unit tests (rule matching, NL phrases, transcript formatting)
+- `tests/integration/test_escalation.py` - 6 integration tests (Slack API mocking, Redis, audit)
+
+## Decisions Made
+
+- **Keyword-based metadata detection (v1):** Rather than LLM-structured output, detect billing keywords and count user turns as a proxy for attempts. Simple, zero-latency, sufficient for v1 escalation rules.
+- **Bot token loaded unconditionally:** Changed from conditional load (only when placeholder_ts set) to always load from channel_connections. Escalation DM delivery requires it regardless.
+- **No-op audit logger stub:** tasks.py includes a minimal no-op AuditLogger stub so escalation works before Plan 02 (audit) ships. Swap is one import change.
+- **Condition parser uses regex, not eval:** Prevents code injection. Supports "X AND Y op Z" format with standard comparison operators.
+
+## Deviations from Plan
+
+None - plan executed exactly as written. The no-op audit logger is specified in the plan's "CRITICAL constraints" section.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+- Escalation handler ready; can be tested end-to-end with a real Slack bot token in escalation_assignee
+- When Plan 02 (audit) ships, replace `_get_no_op_audit_logger()` in tasks.py with the real AuditLogger import
+- Conversation metadata detection is v1 keyword-based; can be upgraded to LLM-structured output in a future plan
+
+---
+*Phase: 02-agent-features*
+*Completed: 2026-03-23*
+
+## Self-Check: PASSED
+
+- All 7 files created/modified: FOUND
+- All 3 task commits (d489551, 4047b55, a025cad): FOUND
+- All 28 tests passing