stack-matrix.yml

name: Stack Matrix

# Runs the full stack generate → install → lint → typecheck → pytest pipeline,
# one runner per stack combination. This is the slow tier — gated off the
# default ``ci.yml`` run so day-to-day PRs stay fast: it starts on every PR,
# but only a PR touching template or core-engine code (where drift lands,
# ``changes`` below) runs the stacks; nightly catches anything that merged
# without touching a gated path. On any other PR every job is skipped, and a
# skipped job counts as passed, so the required "Illiana" check still
# reports instead of waiting forever.
#
# Fan-out over fan-in: the repo is public, so standard runners are free —
# splitting 18 serial stacks across 18 machines costs nothing and cuts wall
# clock from ~16-20 min to the longest single stack. The failed job's NAME
# says which stack broke, one venv per runner means no disk-space triage,
# and a flaky stack re-runs alone instead of replaying the whole matrix.

on:
  pull_request:
    branches: [ main ]
  schedule:
    # 07:00 UTC daily — catches drift merged via PRs that didn't match the
    # path filter above (e.g. docs-only PRs that inadvertently move a
    # template Jinja file).
    - cron: '0 7 * * *'
  workflow_dispatch: {}

concurrency:
  group: stack-matrix-${{ github.ref }}
  cancel-in-progress: true

env:
  # Deliberately NO UV_PYTHON here. This workflow generates and installs real
  # stacks, and generated projects require Python >=3.13. A global UV_PYTHON
  # would force their `uv sync` onto the tool's 3.11 and fail with
  # "incompatible with the project's Python requirement: >=3.13". Each project
  # must resolve its own interpreter.
  UV_LINK_MODE: "copy"  # Avoid broken cache hardlinks (partial-install errors)

jobs:
  # Whether this run has stacks to check: always off a pull request; on one,
  # only when it touches a path below.
  changes:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      stack: ${{ steps.paths.outputs.stack }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Paths the stacks depend on
        id: paths
        run: |
          if [ "${{ github.event_name }}" != pull_request ]; then
            echo "stack=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          paths='^(aegis/templates/|aegis/core/|aegis/cli/|tests/cli/|tests/fixtures/queryspy-baseline\.json$|pyproject\.toml$|uv\.lock$|\.github/workflows/stack-matrix\.yml$)'
          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -qE "$paths"; then
            echo "stack=true" >> "$GITHUB_OUTPUT"
          else
            echo "stack=false" >> "$GITHUB_OUTPUT"
          fi

  # Full validation (generate → uv sync → lint → typecheck → pytest), one
  # stack per runner. The list mirrors STACK_COMBINATIONS in
  # tests/cli/test_stack_generation.py — the guard job below fails if the
  # two ever drift. Node-id selection (not -k) so ``base`` can never
  # substring-match ``base_htmx``.
  validate:
    needs: changes
    if: needs.changes.outputs.stack == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        stack:
          - base
          - scheduler
          - worker
          - full
          - auth_basic
          - auth_org
          - ai_service
          - ai_langchain
          - ai_ollama
          - inference_docker
          - deploy
          - deploy_backups
          - ai_voice
          - insights
          - insights_per_user
          - payment
          - blog
          - documents_auth
          - documents_worker
          - research
          - meetings
          - storage
          - browser
          - finance
          - finance_auth
          - finance_ai_rbac
          - mcp_finance
          - comms
          - base_htmx
          - htmx_auth
          - htmx_with_components
          - everything
    name: validate (${{ matrix.stack }})
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Set up Python
        run: uv python install 3.11

      - name: Install dependencies
        run: uv sync --all-extras

      - name: Validate ${{ matrix.stack }}
        run: >
          uv run pytest
          "tests/cli/test_stack_validation.py::test_stack_full_validation[${{ matrix.stack }}]"
          -v -m slow --tb=short

  # The non-parametrized slow tests: the representative end-to-end pipeline
  # (worker stack + CLI smoke) and the validation performance benchmarks.
  validate-extras:
    needs: changes
    if: needs.changes.outputs.stack == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Set up Python
        run: uv python install 3.11

      - name: Install dependencies
        run: uv sync --all-extras

      - name: Run pipeline + benchmark tests
        run: >
          uv run pytest
          tests/cli/test_stack_validation.py::test_full_stack_validation_pipeline
          tests/cli/test_stack_validation.py::test_validation_performance_benchmarks
          -v -m slow --tb=short

  # Guard: the matrix list above is hand-maintained. If STACK_COMBINATIONS
  # gains or loses a name, this fails with the diff instead of a stack
  # silently never running in CI again.
  matrix-complete:
    needs: changes
    if: needs.changes.outputs.stack == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Set up Python
        run: uv python install 3.11

      - name: Install dependencies
        run: uv sync --all-extras

      - name: Matrix covers every combination
        run: |
          uv run python - <<'PY'
          import re, sys, pathlib

          from tests.cli.test_stack_generation import STACK_COMBINATIONS

          code = {c.name for c in STACK_COMBINATIONS}
          wf = pathlib.Path(".github/workflows/stack-matrix.yml").read_text()
          block = wf.split("stack:\n", 1)[1]
          listed = set()
          for line in block.splitlines():
              m = re.match(r"\s+- ([\w-]+)$", line)
              if not m:
                  break
              listed.add(m.group(1))
          missing = sorted(code - listed)
          extra = sorted(listed - code)
          if missing or extra:
              sys.exit(f"matrix drift - missing: {missing} extra: {extra}")
          print(f"matrix covers all {len(code)} combinations")
          PY

  # A pull request's new conformance findings (``patterns check``), advisory.
  # The everything stack generated from the base branch's templates gives the
  # known debt; the one generated from this branch is checked against it, and
  # each new finding is annotated on the template line it came from
  # (scripts/template_annotations.py). Illiana gives the verdict: a new place
  # breaking a rule that holds a change (enforced, or gated) blocks it
  # (``--strict``), known debt aside; her comment explains it, and posts
  # whether or not the model answers; each new finding on a changed line gets
  # her own thread (scripts/illiana_threads.py). What the change touches goes
  # in the job summary. Make "Illiana" a required check to hold the merge on it.
  conformance:
    name: Illiana
    needs: changes
    if: github.event_name == 'pull_request' && needs.changes.outputs.stack == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 25
    permissions:
      contents: read
      pull-requests: write  # her comment, and her threads on the lines
      issues: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Set up Python
        run: uv python install 3.11

      - name: Generate the everything stack, from the base branch and this one
        run: |
          git worktree add "$RUNNER_TEMP/base-repo" "origin/${{ github.base_ref }}"
          (cd "$RUNNER_TEMP/base-repo" && uv sync --python 3.11 --all-extras && "$GITHUB_WORKSPACE/scripts/generate_stack.sh" everything "$RUNNER_TEMP/base")
          uv sync --python 3.11 --all-extras && scripts/generate_stack.sh everything "$RUNNER_TEMP/head"

      - name: Known debt, from the base branch
        working-directory: ${{ runner.temp }}/base/everything
        # A base branch older than ``patterns check`` has no known debt.
        run: |
          if uv run python -m app.cli.main patterns check --update; then
            cp .patterns-baseline.json "$RUNNER_TEMP/head/everything/"
          fi

      - name: New findings, annotated
        id: findings
        # Her verdict is held to the last step, so her comment still posts.
        run: |
          set +e
          stack="$RUNNER_TEMP/head/everything"
          changed=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD")
          template="aegis/templates/copier-aegis-project/{{ project_slug }}"
          (cd "$stack" && PATTERNS_FOUND="$RUNNER_TEMP/found.json" \
            uv run python -m app.cli.main patterns check --strict $changed) \
            | python3 scripts/template_annotations.py "$stack" "$template"
          echo "code=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT"
          python3 scripts/template_annotations.py "$stack" "$template" \
            --found "$RUNNER_TEMP/found.json"

      # Illiana's write-up of the new findings (``patterns review``): one
      # comment, edited on each push; never fails the job.
      - name: Is there her app
        id: key
        env:
          APP: ${{ secrets.ILLIANA_APP_ID }}
        run: |
          echo "app=${APP:+yes}" >> "$GITHUB_OUTPUT"

      # Her own GitHub App (her name and face on the comment), where its
      # secrets are set; the workflow's bot otherwise.
      - name: Illiana's token
        id: app
        if: steps.key.outputs.app == 'yes'
        uses: actions/create-github-app-token@v3
        with:
          app-id: ${{ secrets.ILLIANA_APP_ID }}
          private-key: ${{ secrets.ILLIANA_APP_PRIVATE_KEY }}

      # Without a model key she still posts: the verdict and every place,
      # in the rules' own words (``pattern_review.UNSAID``).
      - name: Illiana's review, on the pull request
        continue-on-error: true
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          AI_PROVIDER: openai
          AI_MODEL: gpt-6-luna
          GH_TOKEN: ${{ steps.app.outputs.token || github.token }}
          REPO: ${{ github.repository }}
          PR: ${{ github.event.pull_request.number }}
        run: |
          stack="$RUNNER_TEMP/head/everything"
          review="$RUNNER_TEMP/review.md"
          changed=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD")
          # Its comment as it stands: the reviews before this one, kept
          # below it; the same findings again change nothing.
          id=$(gh api "repos/$REPO/issues/$PR/comments" --paginate \
            --jq '.[] | select(.body | startswith("<!-- illiana-review -->")) | .id' | head -1)
          previous="$RUNNER_TEMP/previous.md"
          : > "$previous"
          [ -z "$id" ] || gh api "repos/$REPO/issues/comments/$id" --jq .body > "$previous"
          (cd "$stack" && uv run alembic -c alembic/alembic.ini upgrade head >&2 \
            && uv run python -m app.cli.main patterns review $changed \
              --previous "$previous" --commit "${{ github.event.pull_request.head.sha }}") > "$review"
          [ -s "$review" ] || exit 0
          if [ -n "$id" ]; then
            gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@"$review" > /dev/null
          else
            gh api "repos/$REPO/issues/$PR/comments" -F body=@"$review" > /dev/null
          fi

      # Her threads on the lines (scripts/illiana_threads.py); never the gate.
      - name: Illiana's threads, on the lines
        continue-on-error: true
        env:
          GH_TOKEN: ${{ steps.app.outputs.token || github.token }}
          REPO: ${{ github.repository }}
          PR: ${{ github.event.pull_request.number }}
          SHA: ${{ github.event.pull_request.head.sha }}
        run: python3 scripts/illiana_threads.py "$RUNNER_TEMP/found.json"

      - name: Illiana's verdict
        run: exit "${{ steps.findings.outputs.code }}"