docs: create roadmap (3 phases)

.planning/REQUIREMENTS.md

@@ -29,7 +29,7 @@ Requirements for beta-ready release. Each maps to roadmap phases.
 
 - [ ] **LLM-01**: LiteLLM router abstracts LLM provider selection with fallback routing
 - [ ] **LLM-02**: Platform supports Ollama (local) and commercial APIs (Anthropic, OpenAI) as LLM providers
-- [ ] **LLM-03**: Tenant can provide their own API keys for supported LLM providers (BYO keys, encrypted at rest)
+- [ ] **LLM-03**: Tenant can provide their own API keys for supported LLM providers (BYO keys, encrypted at rest) ⚠️ CONFLICT: listed as v1 here but out-of-scope in PROJECT.md — resolve before Phase 3 planning
 
 ### Multi-Tenancy & Security
 
@@ -95,37 +95,37 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| CHAN-01 | — | Pending |
+| CHAN-01 | Phase 1 | Pending |
-| CHAN-02 | — | Pending |
+| CHAN-02 | Phase 1 | Pending |
-| CHAN-03 | — | Pending |
+| CHAN-03 | Phase 2 | Pending |
-| CHAN-04 | — | Pending |
+| CHAN-04 | Phase 2 | Pending |
-| CHAN-05 | — | Pending |
+| CHAN-05 | Phase 1 | Pending |
-| AGNT-01 | — | Pending |
+| AGNT-01 | Phase 1 | Pending |
-| AGNT-02 | — | Pending |
+| AGNT-02 | Phase 2 | Pending |
-| AGNT-03 | — | Pending |
+| AGNT-03 | Phase 2 | Pending |
-| AGNT-04 | — | Pending |
+| AGNT-04 | Phase 2 | Pending |
-| AGNT-05 | — | Pending |
+| AGNT-05 | Phase 2 | Pending |
-| AGNT-06 | — | Pending |
+| AGNT-06 | Phase 2 | Pending |
-| AGNT-07 | — | Pending |
+| AGNT-07 | Phase 3 | Pending |
-| LLM-01 | — | Pending |
+| LLM-01 | Phase 1 | Pending |
-| LLM-02 | — | Pending |
+| LLM-02 | Phase 1 | Pending |
-| LLM-03 | — | Pending |
+| LLM-03 | Phase 3 | Pending |
-| TNNT-01 | — | Pending |
+| TNNT-01 | Phase 1 | Pending |
-| TNNT-02 | — | Pending |
+| TNNT-02 | Phase 1 | Pending |
-| TNNT-03 | — | Pending |
+| TNNT-03 | Phase 1 | Pending |
-| TNNT-04 | — | Pending |
+| TNNT-04 | Phase 1 | Pending |
-| PRTA-01 | — | Pending |
+| PRTA-01 | Phase 3 | Pending |
-| PRTA-02 | — | Pending |
+| PRTA-02 | Phase 3 | Pending |
-| PRTA-03 | — | Pending |
+| PRTA-03 | Phase 3 | Pending |
-| PRTA-04 | — | Pending |
+| PRTA-04 | Phase 3 | Pending |
-| PRTA-05 | — | Pending |
+| PRTA-05 | Phase 3 | Pending |
-| PRTA-06 | — | Pending |
+| PRTA-06 | Phase 3 | Pending |
 
 **Coverage:**
 - v1 requirements: 25 total
-- Mapped to phases: 0
+- Mapped to phases: 25
-- Unmapped: 25 ⚠️
+- Unmapped: 0
 
 ---
 *Requirements defined: 2026-03-23*
-*Last updated: 2026-03-23 after initial definition*
+*Last updated: 2026-03-23 after roadmap creation — traceability complete*

.planning/ROADMAP.md

@@ -0,0 +1,92 @@
+# Roadmap: Konstruct
+
+## Overview
+
+Konstruct ships in three coarse phases ordered by dependency: first build the secure multi-tenant pipeline and prove that a Slack message triggers an LLM response (Phase 1 — Foundation), then add the agent capabilities that make it a real product: memory, tools, WhatsApp, and escalation (Phase 2 — Agent Features), then complete the operator-facing experience so tenants can self-onboard and pay (Phase 3 — Operator Experience). Phase 3 is gated on DB schema stability, which only exists after Phase 2 defines the memory and tool data models.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Foundation** - Secure multi-tenant pipeline with Slack end-to-end and basic agent response
+- [ ] **Phase 2: Agent Features** - Persistent memory, tool framework, WhatsApp integration, and human escalation
+- [ ] **Phase 3: Operator Experience** - Admin portal, tenant onboarding, and Stripe billing
+
+## Phase Details
+
+### Phase 1: Foundation
+**Goal**: Operators can deploy the platform, a Slack message triggers an LLM response back in-thread, and no tenant can ever see another tenant's data
+**Depends on**: Nothing (first phase)
+**Requirements**: CHAN-01, CHAN-02, CHAN-05, AGNT-01, LLM-01, LLM-02, TNNT-01, TNNT-02, TNNT-03, TNNT-04
+**Success Criteria** (what must be TRUE):
+  1. A user can send a Slack @mention or DM to the AI employee and receive a coherent reply in the same thread — end-to-end in under 30 seconds
+  2. Tenant A's messages, agent configuration, and conversation data are completely invisible to Tenant B — verified by integration tests with two-tenant fixtures
+  3. A request that exceeds the per-tenant or per-channel rate limit is rejected with an informative response rather than silently dropped
+  4. The LLM backend pool routes requests through LiteLLM to both Ollama (local) and Anthropic/OpenAI, with automatic fallback when a provider is unavailable
+  5. A new AI employee can be configured with a custom name, role, and persona — and that persona is reflected in responses
+**Plans**: TBD
+
+Plans:
+- [ ] 01-01: Monorepo scaffolding, Docker Compose dev environment, shared Pydantic models, DB schema with RLS
+- [ ] 01-02: LiteLLM backend pool service with Ollama + Anthropic/OpenAI providers and Celery async dispatch
+- [ ] 01-03: Channel Gateway (Slack adapter), Message Router (tenant resolution), basic Agent Orchestrator (single agent, no memory/tools)
+
+### Phase 2: Agent Features
+**Goal**: The AI employee maintains conversation memory, can execute tools, handles WhatsApp messages, and escalates to humans when rules trigger — making it a capable product rather than a demo
+**Depends on**: Phase 1
+**Requirements**: CHAN-03, CHAN-04, AGNT-02, AGNT-03, AGNT-04, AGNT-05, AGNT-06
+**Success Criteria** (what must be TRUE):
+  1. The AI employee remembers context from earlier in the same conversation and can reference it accurately — tested at 30+ conversation turns without degradation
+  2. A user can send a WhatsApp message to the AI employee and receive a reply — with per-tenant phone number isolation and business-function scoping enforced per Meta 2026 policy
+  3. The agent can invoke a registered tool (e.g., knowledge base search) and incorporate the result into its response
+  4. When a configured escalation rule triggers (e.g., failed resolution attempts), the conversation and full context are handed off to a human with no information lost
+  5. Every LLM call, tool invocation, and handoff event is recorded in an immutable audit trail queryable by tenant
+**Plans**: TBD
+
+Plans:
+- [ ] 02-01: Conversational memory layer (Redis sliding window + pgvector long-term storage with HNSW index)
+- [ ] 02-02: Tool framework (registry, schema-validated execution, authorization enforcement, audit logging)
+- [ ] 02-03: WhatsApp adapter (Business Cloud API, per-tenant phone numbers, opt-in enforcement, Meta policy compliance)
+- [ ] 02-04: Human escalation/handoff with full context transfer and audit trail
+
+### Phase 3: Operator Experience
+**Goal**: An operator can sign up, onboard their tenant through a web UI, connect their messaging channels, configure their AI employee, and manage their subscription — without touching config files or the command line
+**Depends on**: Phase 2
+**Requirements**: AGNT-07, LLM-03, PRTA-01, PRTA-02, PRTA-03, PRTA-04, PRTA-05, PRTA-06
+**Success Criteria** (what must be TRUE):
+  1. An operator can create a tenant, configure an AI employee's name, role, persona, tools, and escalation rules entirely through the portal web UI
+  2. An operator can connect Slack and WhatsApp to their tenant through a guided in-portal wizard without reading documentation
+  3. A new tenant completes the full onboarding sequence (connect channel → configure agent → send test message) in under 15 minutes
+  4. An operator can subscribe, upgrade, and cancel their plan through Stripe — and feature limits are enforced automatically based on subscription state
+  5. The portal displays per-tenant agent cost and token usage, giving operators visibility into spending without requiring access to backend logs
+**Plans**: TBD
+
+Plans:
+- [ ] 03-01: Next.js 16 admin portal foundation with Auth.js v5, API layer, tenant CRUD
+- [ ] 03-02: Agent configuration UI, channel connection wizard (Slack + WhatsApp), onboarding flow
+- [ ] 03-03: Stripe subscription integration, cost tracking dashboard, usage metrics display
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Foundation | 0/3 | Not started | - |
+| 2. Agent Features | 0/4 | Not started | - |
+| 3. Operator Experience | 0/3 | Not started | - |
+
+---
+
+## Coverage Notes
+
+**LLM-03 conflict flagged:** LLM-03 (BYO API keys, encrypted at rest) is listed as a v1 requirement in REQUIREMENTS.md but is explicitly listed as out-of-scope in PROJECT.md ("BYO API key support — v2"). LLM-03 has been assigned to Phase 3 (least disruptive placement) but this conflict must be resolved before Phase 3 planning begins. Options: (1) confirm v2 deferral and move LLM-03 to REQUIREMENTS.md v2 section, or (2) confirm it's in scope for v1 and keep in Phase 3.
+
+---
+*Roadmap created: 2026-03-23*
+*Coverage: 25/25 v1 requirements mapped*

.planning/STATE.md

@@ -0,0 +1,61 @@
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-03-22)
+
+**Core value:** An AI employee that works in the channels your team already uses — no new tools to learn, no dashboards to check, just a capable coworker in Slack or WhatsApp.
+**Current focus:** Phase 1 — Foundation
+
+## Current Position
+
+Phase: 1 of 3 (Foundation)
+Plan: 0 of 3 in current phase
+Status: Ready to plan
+Last activity: 2026-03-23 — Roadmap created, ready for Phase 1 planning
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: —
+- Total execution time: —
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: —
+- Trend: —
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- [Roadmap]: Coarse 3-phase structure — Foundation → Agent Features → Operator Experience
+- [Roadmap]: Phase 3 portal gated on Phase 2 completing (DB schema stability after memory + tool data models)
+- [Roadmap]: WhatsApp Business Verification must be initiated during Phase 1 (1-6 week approval, WhatsApp goes live in Phase 2)
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+- [Roadmap] LLM-03 (BYO API keys) conflicts between REQUIREMENTS.md (v1) and PROJECT.md (v2 out-of-scope). Resolve before Phase 3 planning.
+
+## Session Continuity
+
+Last session: 2026-03-23
+Stopped at: Roadmap created — next step is `/gsd:plan-phase 1`
+Resume file: None