initial

docs/superpowers/plans/travel-planner-implementation-roadmap.md

@@ -0,0 +1,183 @@
+# Travel Planner AI Agent Implementation Roadmap
+
+> **For agentic workers:** This roadmap decomposes the approved design into independent implementation plans. Execute only one phase plan at a time. Each phase must leave the repository buildable, testable, and deployable before the next phase begins.
+
+**Goal:** Deliver the approved self-hosted multi-trip travel planner with Mistral-powered agent behavior, optional web research, proactive watches, email/PWA notifications, structured planning, and TeamCity deployment.
+
+**Architecture:** A modular-monolith NestJS backend exposes an API and a separate BullMQ worker from one codebase. An Angular PWA is compiled into the edge image. PostgreSQL is the source of truth; Redis is queue infrastructure. Exactly one TCP port is published by the production Compose stack, owned by the edge proxy.
+
+**Tech Stack:** Node.js 24 LTS, TypeScript, Angular 22, NestJS 11, PostgreSQL 18, Redis 8, BullMQ, Docker Compose, TeamCity, Mistral.
+
+## Global Constraints
+
+- PostgreSQL is the source of truth; the LLM is never the source of truth.
+- Mistral is the only LLM provider implemented in MVP, behind an `LlmProvider` interface.
+- The LLM never receives direct database, shell, arbitrary HTTP, or filesystem access.
+- Agent tools call application services, never repositories directly.
+- `webResearchEnabled=false` means the web-research tool is not registered for that trip/run.
+- Structured APIs such as routing, places, geocoding, and weather remain independently configurable.
+- Locked itinerary items and confirmed bookings are protected by deterministic backend rules.
+- Background agent runs have fewer permissions than interactive/planning runs.
+- AI output is schema-validated before any mutation.
+- Facts retain provenance, verification state, retrieval time, and confidence where applicable.
+- Critical actions require explicit confirmation.
+- Notifications are delivered by application policy, not directly by the LLM.
+- Background work is queued, retryable, and idempotent.
+- External-provider failure must not corrupt stored trip state or prevent ordinary trip viewing/editing.
+- Exactly one TCP port from production Compose is published to the host, by `edge` only.
+- `api`, `worker`, `postgres`, and `redis` have no host-published ports.
+- TeamCity deploys immutable application-image versions and runs versioned database migrations.
+- Secrets are never committed, baked into images, or embedded in the Angular bundle.
+- Direct purchase, cancellation, payment, Gmail ingestion, expense splitting, native apps, Kubernetes, and microservices are non-goals for MVP.
+
+---
+
+## Plan Dependency Graph
+
+```text
+01 Foundation & Deployment
+        |
+        v
+02 Auth & Trip Core
+        |
+        v
+03 Activities & Itinerary
+        |
+        v
+04 Agent Foundation
+        |
+        v
+05 Policies & Planning Tools
+        |
+        +------------------+
+        v                  v
+06 Research Providers   10 Budget
+        |
+        v
+07 Watch System & Worker
+        |
+        v
+08 Notifications
+        |
+        v
+09 Bookings & Documents
+        |
+        v
+11 UX Completion
+        |
+        v
+12 Evaluation & Hardening
+```
+
+Budget can begin after Phase 5 but must be complete before Phase 11. All other phases should be executed in numeric order unless a reviewed dependency change is made.
+
+## Phase Plans
+
+### 01 — Foundation & Deployment
+
+**Plan file:** `docs/superpowers/plans/2026-08-17-phase-01-foundation-deployment.md`
+
+**Outcome:** A repository with Angular PWA, NestJS API and worker, PostgreSQL/Redis development infrastructure, health/readiness endpoints, production images, single-port edge topology, and repo-owned TeamCity build/deploy scripts.
+
+**Exit gate:**
+- `pnpm test`, `pnpm lint`, and `pnpm build` pass.
+- API `/health/live` and `/health/ready` pass with PostgreSQL/Redis available.
+- Production Compose publishes exactly one host port from `edge`.
+- A smoke deployment can be performed using immutable `IMAGE_TAG` images.
+
+### 02 — Authentication & Trip Core
+
+**Outcome:** OIDC SSO, local users, preferences, trips, trip settings, members, invitations, and account-less travelers.
+
+**Primary domain:** `User`, `UserPreference`, `Trip`, `TripSettings`, `TripMember`, `TripInvitation`, `Traveler`, `TripPreferenceOverride`.
+
+**Exit gate:** A user can sign in via the existing OIDC IdP, create multiple trips, invite a member, add an infant traveler without an account, and toggle web research per trip.
+
+### 03 — Activities & Itinerary
+
+**Outcome:** Activity ideas, voting, day-by-day itinerary, drag/drop mutations, locking, optimistic concurrency, and initial trip UI.
+
+**Exit gate:** Two users cannot silently overwrite the same itinerary version; locked items cannot be moved through normal mutation APIs; the frontend can drag/drop unlocked items.
+
+### 04 — Agent Foundation
+
+**Outcome:** `LlmProvider`, Mistral implementation, structured-output/tool-call contract, `AgentRun`, `AgentAction`, context builder, tool registry, and basic interactive agent endpoint with streaming status events.
+
+**Exit gate:** A mocked provider can drive a deterministic tool-call loop; a live Mistral smoke test is opt-in; ordinary app functions continue when Mistral is unavailable.
+
+### 05 — Policies & Planning Tools
+
+**Outcome:** Deterministic action policy, protected actions, pending confirmations, audit trail, undo model, activity/itinerary planning tools, interactive and planning run modes.
+
+**Exit gate:** A request to optimize a trip may move unlocked items but creates a pending confirmation instead of mutating a locked/confirmed resource.
+
+### 06 — Research & Structured Providers
+
+**Outcome:** `ResearchFact`, `ResearchSource`, web-research abstraction, places/geocoding/routing/weather abstractions, provenance UI, and provider capability handling.
+
+**Exit gate:** With web research disabled, no web tool exists in the tool registry. Structured routing can still run. Current facts are labeled verified/unverified based on provenance.
+
+### 07 — Watch System & Background Worker
+
+**Outcome:** Watch items, dynamic `nextCheckAt`, scheduler, BullMQ processors, periodic trip review, web-condition checks, background permission restrictions, retry/idempotency behavior.
+
+**Exit gate:** A due watch is queued and processed exactly once semantically; background runs cannot perform protected itinerary/bookings mutations.
+
+### 08 — Notifications
+
+**Outcome:** In-app notifications, SMTP mail, Web Push subscriptions/delivery, severity routing, per-user preferences, trip overrides, deduplication.
+
+**Exit gate:** A HIGH watch transition results in one deduplicated in-app notification and, when enabled, one email and one PWA push.
+
+### 09 — Bookings & Documents
+
+**Outcome:** Manual bookings, local storage abstraction, PDF/JPEG/PNG uploads, extraction draft, user confirmation, confirmed-booking planning constraints.
+
+**Exit gate:** Uploaded booking evidence cannot become authoritative without explicit confirmation; confirmed bookings are protected from autonomous agent mutation.
+
+### 10 — Budget
+
+**Outcome:** Trip budget, categories, estimates/actuals, budget UI, budget-impact agent tool and planning validation.
+
+**Exit gate:** The agent can compare the cost impact of a plan and must not represent estimates as actual costs.
+
+### 11 — UX Completion
+
+**Outcome:** Trip dashboard, watches, ideas/details, bookings, budget, group page, global agent side panel, planning/travel mode emphasis, responsive PWA polish.
+
+**Exit gate:** Core workflows are usable on desktop and mobile without requiring chat prompts for ordinary CRUD/planning actions.
+
+### 12 — Evaluation & Hardening
+
+**Outcome:** Slovenia 2027 golden scenario suite, resilience/concurrency/security tests, live-provider smoke profiles, deployment rollback rehearsal, backup/restore rehearsal, documentation completion.
+
+**Exit gate:** All MVP acceptance criteria from the approved specification pass, including the single-port production invariant and TeamCity rollback without rebuild.
+
+---
+
+## Implementation Rules for Coding Agents
+
+1. Load the approved design spec plus only the current phase plan and directly relevant source files.
+2. Do not pre-implement later phases “for convenience”. Introduce interfaces only when the current phase needs their boundary.
+3. Use TDD for deterministic domain/application behavior: failing test, minimal implementation, passing test, commit.
+4. Prefer focused files and narrow interfaces. Split a file when it develops multiple independent reasons to change.
+5. Every task ends in a repository state that can be reviewed independently.
+6. Do not weaken architecture invariants to make a test pass.
+7. Never add a generic agent `executeSql`, shell, arbitrary HTTP, or arbitrary filesystem tool.
+8. Live/paid external-provider tests are opt-in and must not run on every TeamCity commit build.
+9. Production Compose invariant tests are mandatory and must fail if any service other than `edge` adds `ports:`.
+10. TeamCity should call repository scripts rather than duplicating deployment logic in opaque UI steps.
+
+## Version Baseline (2026-08-17)
+
+- Node.js: 24 LTS line.
+- Angular: 22.x.
+- NestJS: 11.x.
+- PostgreSQL production image baseline: `postgres:18.4-alpine`.
+- Redis production image baseline: `redis:8.8.1-alpine`.
+
+Image tags are reviewed upgrade inputs, not floating `latest` tags. JavaScript dependencies are locked by `pnpm-lock.yaml`.
+
+## Roadmap Completion Definition
+
+The roadmap is complete only when the end-to-end Slovenia 2027 scenario passes: OIDC sign-in, multi-person trip planning including a child, optional web research, provenance-aware suggestions, votes, realistic itinerary generation, protected locks/bookings, background marathon watch, deduplicated email and PWA push, booking-document confirmation, budget-aware planning, graceful LLM outage, single published production port, and TeamCity immutable deployment/rollback.