Phase A + B1

Hi, team —

As agreed, we’ll execute Phase A + B1 (CI/CD complete + Terraform “thin skeleton”) before Phases J and K.
Please apply the following changes first, then we’ll proceed to J/K.

---

Scope reminder (A + B1 only)

• Lock the API contract (OpenAPI 3.1).
• Ship a complete CI/CD (lint → type → unit → contract diff → minimal E2E → SBOM/scan → cosign sign → GHCR push → Release automation).
• Apply Terraform skeleton: remote state, OIDC (GitHub→AWS), ECR, Route53+ACM, minimal VPC.
• No EKS/RDS or Cron wiring yet (those come later in B2/J/K).

---

Files to modify (delta on existing)

Application / Spec

• api/app/openapi/openapi.yaml
  – Freeze the contract; only backward-compatible additions going forward (CI contract diff will gate).

Python deps

• api/requirements.txt
  – Add minimal test/tooling deps: pytest, pytest-asyncio, httpx (and keep FastAPI/Uvicorn pins consistent with your repo).

(Optional, for dev verification) K8s overlay

• k8s/overlays/dev/kustomization.yaml
• k8s/overlays/dev/patch-api-image.yaml
  – Prefer digest pinning for images (tags OK short-term; digest is the target policy).

---

Files to add (new)

CI/CD (GitHub Actions)

• .github/workflows/ci.yml
  – Full pipeline: Lint → Type → Unit → OpenAPI contract diff (oasdiff) → minimal E2E → SBOM (Syft) → vuln scan (Trivy) → build → sign (cosign) → (PR: build only / main: push).
• .github/workflows/release.yml
  – On SemVer tags: build, push, sign, create Release; attach SBOM and notes.

Tooling / Conventions

• pyproject.toml
  – ruff/black/mypy/pytest config (centralized).
• pytest.ini (optional if not in pyproject.toml)
  – Test discovery/markers.
• .github/PULL_REQUEST_TEMPLATE.md
  – PR checklist (tests, contract changes, docs).
• CODEOWNERS
  – Review ownership.
• .gitignore, .editorconfig, .ruff.toml (if not present).
• Makefile (optional)
  – Shortcuts: lint, type, test, build, sbom, scan.

Minimal tests (so CI is green immediately)

• api/app/tests/e2e/test_health_minimal.py
  – Smoke against /health/* (or /healthz/* fallback) — returns 200/204.
• api/app/tests/contract/test_openapi_diff.py
  – Ensures the OpenAPI file exists and is non-empty (heavy breaking-change check runs in CI via containerized oasdiff).

You can add repo upsert/pagination/i18n negative tests next; the pipeline already supports them.

Cron placeholder (so CI builds two images)

• cron-runner/Dockerfile
• cron-runner/requirements.txt
• cron-runner/app.py
  – Minimal placeholder; Phase K will replace this with the API-call orchestration.

Terraform — “thin skeleton” (B1 is apply here only)

• infra/terraform/bootstrap/
  • main.tf, variables.tf
    – One-time creation of S3 remote state (encrypted) + DynamoDB state lock.
• infra/terraform/core/
  • backend.tf (use the S3/DDB created above)
  • providers.tf, versions.tf (default tags: customer, env, owner, cost-center)
  • ecr.tf (create portal-api, cron-runner)
  • oidc_github.tf (GitHub→AWS OIDC role for CI; no long-lived keys)
  • route53_acm.tf (hosted zone + wildcard ACM, DNS validation)
  • vpc_minimal.tf (minimal VPC + public subnets; a footing for later EKS/RDS)

Documentation

• docs/RUNBOOK.md
  – Release/rollback steps; cosign verification; SBOM/scan report locations; CI job responsibilities.

---

Acceptance checklist (please acknowledge)

• CI on PR: lint/type/unit/contract diff/minimal E2E runs and passes.
• On main: SBOM/scan, build + sign + GHCR push for portal-api and cron-runner.
• On SemVer tag: Release created with SBOM attached; image digests recorded.
• Terraform “bootstrap” applied once (S3+DDB), then “core” applied (OIDC/ECR/Route53+ACM/VPC).
• OpenAPI contract is frozen; breaking changes fail the CI gate.

---

Important note on sequencing

This A + B1 work is a prerequisite for Phases J and K.
Please implement these changes now, then we will move to:

• Phase J (K8s dev optimization: health probes, bearer auth, Idempotency-Key, request/audit middlewares, config separation), and
• Phase K (Cron layer wiring extract → translate → package → upsert).

If any path or tooling in your environment requires a tweak (e.g., Python version, container registry), please flag it and propose the minimal change to keep A + B1 on track.