How to: Continuous Integration
[![PR CI](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/pr-ci.yml/badge.svg)](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/pr-ci.yml)
[![🚀 CI — Insight Demo](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/ci.yml?query=branch%3Amain)
[![🔥 Smoke Test](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/smoke.yml/badge.svg)](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/smoke.yml)
[![🩺 CI Health](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/ci-health.yml/badge.svg)](https://github.com/montrealai/AGI-Alpha-Agent-v0/actions/workflows/ci-health.yml)

The CI matrix is pinned to the canonical `$AGIALPHA` token contract (`0xa61a3b3a130a9c20768eebf97e21515a6046a1fa`, **18 decimals**). Each workflow calls `python scripts/check_agialpha_config.py` to fail fast if the address, decimals, or workflow environment variables drift away from [`token.config.js`](token.config.js) or the Solidity constants. Run the same helper locally before dispatching CI to keep badges green and avoid PR surprises.

The **PR CI** workflow runs Ruff linting and focused smoke tests on every pull request and on pushes to `main`. The full **🚀 CI — Insight Demo** matrix (lint, type-check, tests, docs, Docker build, and signed artifacts) now runs on the same events so the badge stays fresh without manual dispatch. A separate **🩺 CI Health** watchdog automatically cancels pending runs that linger beyond a 10-minute grace window (hard stop at 60 minutes), re-dispatches missing jobs with `GITHUB_TOKEN`, and alerts when any workflow is stuck; it now also triggers after every **PR CI**, **🚀 CI**, or **🔥 Smoke Test** completion so badge issues are remediated immediately instead of waiting for the hourly cron. Tests target Python 3.11 and 3.12 until PyTorch releases stable 3.13 wheels.

When a workflow does fail, the watchdog now also requests an automatic rerun using `GITHUB_TOKEN` so transient network blips or flaky mirrors self-heal before raising an alert. This keeps required checks green on `main` without manual button clicks while preserving visibility into repeated failures.

`workflow_dispatch` runs triggered by the **🩺 CI Health** watchdog now bypass the manual owner gate when they originate from `github-actions[bot]`, so automated re-dispatches can heal stale badges without waiting for the repository owner to click "Re-run".

To enforce branch-protection verification inside the watchdog, add a fine-grained or classic `ADMIN_GITHUB_TOKEN` secret with branch-administration scope; when absent, the workflow logs a warning and skips the check so the rest of CI remains green.

Pushes of signed release tags (`v*` or `release-*`) also trigger **🚀 CI — Insight Demo**, exercising the deploy and signing stages so production artifacts stay provably green.

#### Run CI locally

1. Create and activate a Python 3.11–3.13 virtual environment, then upgrade pip:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -U pip
   ```
2. Install required and optional Python dependencies (set `ALPHA_FACTORY_FULL=1` for heavier extras or `--wheelhouse
` when offline):
   ```bash
   python check_env.py --auto-install
   ```
3. Run formatting and lint hooks:
   ```bash
   pre-commit run --all-files
   ```
4. Execute the tests:
   ```bash
   pytest
   ```
5. Trigger the GitHub Actions pipeline from **Actions → 🚀 CI — Insight Demo** (or **PR CI** for pull requests) and click **Run workflow** (repository owners only).

**Troubleshooting:**
- Missing optional packages (`openai_agents`, `gymnasium`, etc.) can fail tests—rerun `python check_env.py --auto-install` with `ALPHA_FACTORY_FULL=1`.
- When offline or behind strict firewalls, set `WHEELHOUSE=$(pwd)/wheels` and pass `--wheelhouse "$WHEELHOUSE"` so installs pull from the local wheel cache instead of PyPI.

Mark **all** of these checks as required branch protections so contributors see the results on every PR and the `main` branch stays green:

- `✅ PR CI / Lint (ruff)`
- `✅ PR CI / Smoke tests`
- `🚀 CI — Insight Demo / 🧹 Ruff + 🏷️ Mypy (3.11)`
- `🚀 CI — Insight Demo / 🧹 Ruff + 🏷️ Mypy (3.12)`
- `🚀 CI — Insight Demo / ✅ Actionlint`
- `🚀 CI — Insight Demo / ✅ Pytest (3.11)`
- `🚀 CI — Insight Demo / ✅ Pytest (3.12)`
- `🚀 CI — Insight Demo / Windows Smoke`
- `🚀 CI — Insight Demo / macOS Smoke`
- `🚀 CI — Insight Demo / 📜 MkDocs`
- `🚀 CI — Insight Demo / 📚 Docs Build`
- `🚀 CI — Insight Demo / 🐳 Docker build`
- `🩺 CI Health / CI watchdog`

Pushes to `main`, merge-queue runs, and pull requests from any source now run a `🔒 Branch protection guardrails` job inside **🚀 CI — Insight Demo**. The job stays read-only when only the default `GITHUB_TOKEN` is available (for example, forked PRs), so the required check still reports while repositories with an `ADMIN_GITHUB_TOKEN` continue enforcing