ChooChoo for Warp.

# WARP.md
# Generated by ChooChoo. Do not edit by hand.

## payments-api
Warp's Agent Mode reads WARP.md for project context.
This file describes what the repo is, how to run it,
and what NOT to touch from the terminal.

## Quick commands
mise run dev          Start dev server
mise run test         pytest -v
mise run lint         ruff check

## Safe surfaces
✓ src/**, tests/**, docs/**
✓ Read-only DB queries against staging
✓ pytest, ruff, mise tasks

## Confirm-first surfaces
⚠ Any DB migration (live or staging)
⚠ Branch deletes, force-pushes
⚠ Anything under infra/, .github/

## Never run without explicit human OK
✗ rm -rf, dropdb, drop table
✗ kubectl apply against prod
✗ Anything that modifies billing config

# SKILLS.md
# Generated by ChooChoo. Do not edit by hand.

## auth
JWT token lifecycle: creation, validation, refresh.
  Entry: src/auth/service.py
  Tests: tests/auth/

## payments
Stripe integration: charges, subscriptions, webhooks.
  Entry: src/payments/processor.py
  Note:  Never log STRIPE_KEY or card numbers

## database
SQLAlchemy sessions and query patterns.
  Entry: src/db/session.py
  Rule:  Always use get_db() dependency injection

## notifications
Email (SendGrid) and SMS (Twilio) dispatch.
  Entry: src/notifications/dispatch.py

# PLAN.md
# Generated by ChooChoo. Do not edit by hand.

## Goal
Refactor the authentication service to support
multi-factor authentication (MFA) via TOTP.

## Steps
1. [ ] Add TOTP secret column to users table
       migration: src/db/migrations/0023_add_totp.py
2. [ ] Implement TOTP validation in auth service
       src/auth/service.py → verify_totp()
3. [ ] Add /auth/mfa/setup and /auth/mfa/verify routes
       src/api/auth.py
4. [ ] Write unit tests for new MFA paths
       tests/auth/test_mfa.py (≥ 90% coverage)
5. [ ] Update AGENTS.md with new ADR-012

## Constraints
- Do not break existing JWT flow (ADR-001)
- TOTP secrets encrypted at rest (AES-256)
- Rate-limit /auth/mfa/verify to 5 attempts / 15 min

# ARCHITECTURE.md
# Generated by ChooChoo. Do not edit by hand.

## System Overview
payments-api is a stateless FastAPI service.
All state lives in PostgreSQL (primary data) and
Redis (sessions, rate limiting, event streams).

## Request Flow
Client → API Gateway → FastAPI → Service Layer
                                → Repository Layer
                                → PostgreSQL / Redis

## Key Modules
src/auth/        JWT issuance + TOTP (ADR-001, ADR-012)
src/payments/    Stripe integration (charges, webhooks)
src/db/          SQLAlchemy sessions + migration runner
src/api/         Route definitions (v1 + v2 namespaces)

## ADR Index
ADR-001  RS256 JWT for authentication
ADR-004  Redis Streams for webhook event bus
ADR-007  URL versioning (/v1/, /v2/)
ADR-012  TOTP-based MFA (in progress)

## Deployment
Docker → ECS Fargate  (app)
RDS PostgreSQL 15      (primary)
ElastiCache Redis 7    (cache + streams)

# GOAL.md
# Generated by ChooChoo. Do not edit by hand.

## Current Sprint Goal
Implement MFA support without breaking existing
single-factor authentication flows.

## Success Criteria
- All existing auth tests continue to pass
- New /auth/mfa/* endpoints return correct responses
- TOTP validation rejects tokens older than 30 s
- Coverage for src/auth/ stays above 90%

## Out of Scope
- SMS-based MFA (deferred to ADR-013)
- Admin UI for MFA management (separate ticket)
- Recovery codes (phase 2)

## Definition of Done
- PR reviewed and approved
- CI green (lint + test + coverage)
- AGENTS.md updated with ADR-012 summary
- Deployed to staging and smoke-tested

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-23T14:30:00Z",
  "vcs": {
    "type": "git",
    "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  },
  "tool": { "name": "cursor", "version": "2.4.0" },
  "files": [
    {
      "path": "src/utils/parser.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [
            {
              "start_line": 42,
              "end_line": 67,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ],
          "related": [
            {
              "type": "session",
              "url": "https://api.cursor.com/v1/sessions/67890"
            }
          ]
        }
      ]
    },
    {
      "path": "src/utils/helpers.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "openai/gpt-4o"
          },
          "ranges": [
            { "start_line": 10, "end_line": 25 }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "confidence": 0.95,
    "dev.cursor": { "workspace_id": "ws-abc123" }
  }
}