chore(repo): merge dev to main — seeder phases 1+2 + ci/docs hardening (#92)

.github/workflows/cd-release.yml

@@ -28,7 +28,7 @@ jobs:
       upload_url: ${{ steps.release.outputs.upload_url }}
 
     steps:
-      - uses: googleapis/release-please-action@v5
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
         id: release
         with:
           # Use PAT to trigger CI workflows on release PRs
@@ -52,7 +52,7 @@ jobs:
           ref: ${{ needs.release-please.outputs.tag_name }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
           ref: ${{ env.CHECKOUT_REF }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -48,10 +48,10 @@ jobs:
         run: uv sync --frozen --all-extras --dev
 
       - name: Run Ruff linter
-        run: uv run ruff check .
+        run: uv run --frozen ruff check .
 
       - name: Run Ruff formatter check
-        run: uv run ruff format --check .
+        run: uv run --frozen ruff format --check .
 
   typecheck:
     name: Type Check
@@ -62,7 +62,7 @@ jobs:
           ref: ${{ env.CHECKOUT_REF }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -74,10 +74,10 @@ jobs:
         run: uv sync --frozen --all-extras --dev
 
       - name: Run MyPy
-        run: uv run mypy app/
+        run: uv run --frozen mypy app/
 
       - name: Run Pyright
-        run: uv run pyright app/
+        run: uv run --frozen pyright app/
 
   test:
     name: Test
@@ -104,7 +104,7 @@ jobs:
           ref: ${{ env.CHECKOUT_REF }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -118,13 +118,13 @@ jobs:
       - name: Run migrations
         env:
           DATABASE_URL: postgresql+asyncpg://forecastlab:forecastlab@localhost:5432/forecastlab_test
-        run: uv run alembic upgrade head
+        run: uv run --frozen alembic upgrade head
 
       - name: Run tests
         env:
           DATABASE_URL: postgresql+asyncpg://forecastlab:forecastlab@localhost:5432/forecastlab_test
           APP_ENV: testing
-        run: uv run pytest -v --tb=short
+        run: uv run --frozen pytest -v --tb=short
 
   migration-check:
     name: Migration Check
@@ -151,7 +151,7 @@ jobs:
           ref: ${{ env.CHECKOUT_REF }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -165,12 +165,12 @@ jobs:
       - name: Apply migrations to fresh DB
         env:
           DATABASE_URL: postgresql+asyncpg://forecastlab:forecastlab@localhost:5432/forecastlab_migration_test
-        run: uv run alembic upgrade head
+        run: uv run --frozen alembic upgrade head
 
       - name: Verify no pending migrations
         env:
           DATABASE_URL: postgresql+asyncpg://forecastlab:forecastlab@localhost:5432/forecastlab_migration_test
         run: |
           # Check that current head matches database
-          uv run alembic current
+          uv run --frozen alembic current
           # This would fail if there are unapplied migrations

.github/workflows/dependency-check.yml

@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -76,7 +76,7 @@ jobs:
 
       - name: Upload SARIF to GitHub Security
         if: always()
-        uses: github/codeql-action/upload-sarif@v4
+        uses: github/codeql-action/upload-sarif@c6f931105cb2c34c8f901cc885ba1e2e259cf745 # v4.34.0
         with:
           sarif_file: audit-results.sarif
           category: dependency-vulnerability-scan

.github/workflows/phase-snapshot.yml

@@ -44,7 +44,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -58,24 +58,24 @@ jobs:
       - name: Lint check
         id: lint
         run: |
-          uv run ruff check .
-          uv run ruff format --check .
+          uv run --frozen ruff check .
+          uv run --frozen ruff format --check .
 
       - name: Type check
         id: typecheck
         run: |
-          uv run mypy app/
-          uv run pyright app/
+          uv run --frozen mypy app/
+          uv run --frozen pyright app/
 
       - name: Run migrations
         id: migration
-        run: uv run alembic upgrade head
+        run: uv run --frozen alembic upgrade head
 
       - name: Run tests
         id: test
         env:
           APP_ENV: testing
-        run: uv run pytest -v --tb=short
+        run: uv run --frozen pytest -v --tb=short
 
   create-snapshot:
     name: Create Audit Snapshot
@@ -90,7 +90,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true

.github/workflows/schema-validation.yml

@@ -45,7 +45,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
@@ -59,14 +59,14 @@ jobs:
       - name: Fresh DB migration test
         run: |
           echo "::group::Applying all migrations to fresh database"
-          uv run alembic upgrade head
+          uv run --frozen alembic upgrade head
           echo "::endgroup::"
 
       - name: Check migration chain integrity
         run: |
           echo "::group::Verifying migration chain"
           # Get all revision heads - should be exactly one
-          HEADS=$(uv run alembic heads 2>&1)
+          HEADS=$(uv run --frozen alembic heads 2>&1)
           HEAD_COUNT=$(echo "$HEADS" | grep -c "^[a-f0-9]" || true)
 
           if [ "$HEAD_COUNT" -gt 1 ]; then
@@ -84,7 +84,7 @@ jobs:
           echo "::group::Checking for schema drift"
           # alembic check compares models to current DB state
           # Returns non-zero if autogenerate would create new migrations
-          if uv run alembic check 2>&1; then
+          if uv run --frozen alembic check 2>&1; then
             echo "Schema is in sync with models"
           else
             echo "::error::Schema drift detected - models don't match migrations"
@@ -97,7 +97,7 @@ jobs:
         run: |
           echo "::group::Testing migration reversibility"
           # Get current revision
-          CURRENT=$(uv run alembic current 2>&1 | grep -oE "^[a-f0-9]+" | head -1)
+          CURRENT=$(uv run --frozen alembic current 2>&1 | grep -oE "^[a-f0-9]+" | head -1)
 
           if [ -z "$CURRENT" ]; then
             echo "No migrations applied, skipping cycle test"
@@ -108,14 +108,14 @@ jobs:
 
           # Downgrade one step
           echo "Downgrading one migration..."
-          uv run alembic downgrade -1
+          uv run --frozen alembic downgrade -1
 
           # Upgrade back
           echo "Upgrading back to head..."
-          uv run alembic upgrade head
+          uv run --frozen alembic upgrade head
 
           # Verify we're back at head
-          FINAL=$(uv run alembic current 2>&1 | grep -oE "^[a-f0-9]+" | head -1)
+          FINAL=$(uv run --frozen alembic current 2>&1 | grep -oE "^[a-f0-9]+" | head -1)
 
           if [ "$CURRENT" != "$FINAL" ]; then
             echo "::error::Migration cycle failed - revision mismatch after downgrade/upgrade"
@@ -133,10 +133,10 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Migration History" >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY
-          uv run alembic history --verbose 2>&1 | head -50 >> $GITHUB_STEP_SUMMARY
+          uv run --frozen alembic history --verbose 2>&1 | head -50 >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Current State" >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY
-          uv run alembic current --verbose 2>&1 >> $GITHUB_STEP_SUMMARY
+          uv run --frozen alembic current --verbose 2>&1 >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -1,6 +1,6 @@
 /.vscode
 /.claude
-CLAUDE.md
+CLAUDE.local.md
 .mcp.json
 .claude
 .DS_Store
@@ -37,3 +37,8 @@ frontend/.vite/
 
 # Generated artifacts (models, backtest results)
 artifacts/
+
+# Local session artifacts (plans, handoffs, current session notes)
+.agents/
+.handoffs/
+HANDOFF.md

CLAUDE.md

@@ -0,0 +1,116 @@
+# ForecastLabAI
+
+Deep-dive references (Claude loads only when needed):
+- Developer guide & tech stack:  @docs/_base/DEV_GUIDE.md
+- Architecture & boundaries:     @docs/_base/ARCHITECTURE.md
+- API contracts & interfaces:    @docs/_base/API_CONTRACTS.md
+- Operational runbooks:          @docs/_base/RUNBOOKS.md
+- Security & compliance:         @docs/_base/SECURITY.md
+- Rules & constraints:           @docs/_base/RULES.md
+- Domain model & glossary:       @docs/_base/DOMAIN_MODEL.md
+- Service & dependency map:      @docs/_base/REPO_MAP_INDEX.md
+- Pipeline contract (CI/CD):     @docs/_base/PIPELINE_CONTRACT.md
+
+> Project rules already enforced via `.claude/rules/` (commit-format, branch-naming, security-patterns, product-vision, test-requirements, ui-design, versioning, output-formatting). Read those first; this file is the operating index.
+
+## Stack
+
+- Language: Python 3.12 (backend), TypeScript 5.9 + React 19 (frontend)
+- Framework: FastAPI + SQLAlchemy 2.0 async + Pydantic v2; Vite 7 + Tailwind 4 + shadcn/ui
+- Infrastructure: Single-host `docker-compose` (no K8s, no cloud SDK in core path)
+- Database: PostgreSQL 16 + pgvector (port `5433` host → `5432` container)
+- CI/CD: GitHub Actions + release-please (SemVer, pre-1.0 patch bumps)
+
+## Architecture
+
+**Owns:** Full vertical-slice retail-demand-forecasting demo — data platform, ingest, feature engineering (time-safe), forecasting, backtesting, model registry, RAG (pgvector), agentic layer (PydanticAI), React dashboard.
+
+**Depends on:** PostgreSQL+pgvector (required), OpenAI/Anthropic/Google API (agent + RAG embeddings), Ollama (optional local embeddings).
+
+**Depended on by:** Nothing internal — single deployment, no consumers. Frontend ↔ backend over HTTP + WebSocket (`/agents/stream`).
+
+**Vertical-slice layout:** Every domain lives under `app/features/<slice>/{models,schemas,service,routes,tests}.py`. Cross-slice code goes through `app/core/` or `app/shared/`. Wire-up in `app/main.py`.
+
+**Core data flow:** Seeder/Ingest → `sales_daily` + dimensions → Featuresets (lag/rolling/calendar, leakage-safe) → Forecasting (naive/seasonal/MA/LightGBM) → Backtesting (rolling/expanding splits) → Registry (runs + aliases) → Serving via `/forecasting`, `/backtesting`, `/analytics`. RAG indexes docs → pgvector → Agents (experiment / rag_assistant) call tools with human-in-loop approval for mutating ops.
+
+## Commands
+
+### Local Development
+```bash
+docker-compose up -d                          # Postgres+pgvector on :5433
+uv sync --extra dev                            # install backend deps (Python 3.12)
+uv run alembic upgrade head                    # apply migrations
+uv run uvicorn app.main:app --reload --port 8123
+cd frontend && pnpm install && pnpm dev       # UI on :5173
+```
+
+### Testing
+```bash
+uv run pytest -v -m "not integration"          # unit, no DB
+uv run pytest -v -m integration                # integration, requires docker-compose up
+cd frontend && pnpm tsc --noEmit && pnpm lint && pnpm test --run
+```
+
+### Validation gates (run before commit)
+```bash
+uv run ruff check . && uv run ruff format --check .
+uv run mypy app/ && uv run pyright app/        # both --strict, both block merge
+```
+
+### Database & seeder
+```bash
+uv run alembic revision --autogenerate -m "<desc>"
+uv run python scripts/seed_random.py --full-new --seed 42 --confirm
+uv run python scripts/seed_random.py --status
+```
+
+## Conventions
+
+- Branches: `<type>/<kebab-slug>` off `dev` (off `main` for hotfix). See `.claude/rules/branch-naming.md`.
+- Commits: `type(scope): description (#issue)` — scope from allow-list, no AI co-author trailer, every commit references an open GitHub issue. Hook `.claude/hooks/check-commit-format.sh` enforces it.
+- All errors via `app/core/problem_details.py` (RFC 7807 `application/problem+json`).
+- Pydantic v2 at every boundary (HTTP, agent tools, seeder config). SQLAlchemy with `Mapped[]` + async sessions.
+- Time-safe features only — `app/features/featuresets/tests/test_leakage.py` is the spec; never weaken to make a feature pass.
+- UI work goes through the skills in `.claude/rules/ui-design.md` (stitch-design, frontend-design, webapp-testing) — never hand-roll.
+
+## Safety
+
+> Load `docs/_base/RULES.md` for the full constraint matrix.
+
+**STOP and ask before:**
+- Cutting `dev` → `main` (release-please will tag) or any tag push
+- Editing a merged Alembic migration (migrations are forward-only; create a new one)
+- `git push --force` on `dev` or `main` (forbidden)
+- Adding a managed-cloud SDK to `app/` core path (violates single-host vision)
+- Bumping pydantic-ai / FastAPI / SQLAlchemy major versions
+
+**NEVER:**
+- Commit `.env` (only `.env.example` is tracked) or embed secrets in URLs/code/logs
+- Use raw SQL string concat — always SQLAlchemy parameter binding
+- Disable `verify=False` on httpx / openai clients
+- Skip `mypy --strict` or `pyright --strict` — both gate merge
+- Add AI co-author trailers to commits (`commit-format.md` forbids it)
+- Mock external services in integration tests (use real Postgres via docker-compose)
+
+## Verification
+
+```bash
+uv run ruff check . && uv run mypy app/ && uv run pyright app/ && uv run pytest -v -m "not integration"
+gh issue view <N> --json state                # confirm referenced issue exists
+wc -l CLAUDE.md                                # must stay ≤ 150
+```
+
+## Workflow
+
+1. Open or pick a GitHub issue (`gh issue list`); branch off `dev` per `branch-naming.md`.
+2. Implement inside the matching `app/features/<slice>/` (or new slice with PRP).
+3. Run `ruff` → `mypy` → `pyright` → `pytest -m "not integration"` locally.
+4. (DB/UI touched) Run integration tests + frontend type-check + dogfood via webapp-testing skill.
+5. Commit with `type(scope): description (#issue)`; push.
+6. Open PR into `dev`; CI must be green; merge.
+7. When ready to release: PR `dev` → `main`. release-please opens a Release PR; merge to tag.
+
+## Learnings
+
+<!-- Session-specific discoveries Claude should remember. Update sparingly. -->
+- HEURISTIC_MODE generated this doc (no `docs/_kB/repo-map/` KB). Run `mapping-repo-context` to upgrade fidelity; sections marked `[UNVERIFIED]` in `docs/_base/` need verification.