# GitHub Operations (OSS That Scales)

This repo is designed to run "like a product" on GitHub: required checks, automation, and a living roadmap.

## 1) Branch protection (required checks)

We provide a single required check: `ci / gate`.

In GitHub UI:
- Settings -> Branches -> Branch protection rules
- Protect `main`
- Require pull request reviews
- Require status checks: `ci / gate`

As code (recommended): run the workflow `repo-settings` which uses `github/safe-settings` and `.github/repo-settings.yml`.

## 2) CODEOWNERS

Edit `.github/CODEOWNERS` to point to real maintainers/teams.

## 3) Labels + triage automation

1. Run `sync-labels` workflow to create/update labels from `.github/labels.yml`.
2. `pr-labeler` auto-labels PRs based on file changes via `.github/labeler.yml`.

## 4) Releases

- Tag a release: push `vX.Y.Z`
- GitHub Actions workflow `release` will:
  - run tests
  - build + validate
  - publish to PyPI (requires `PYPI_API_TOKEN`)
  - create GitHub Release with auto-generated notes + attach `dist/*`

## 5) Roadmap -> milestones

Use `ROADMAP.md` as the narrative, but keep the source of truth as GitHub Milestones.
Milestone titles are generated as:
- `P0 - Foundations (P0)`
- `P1 - Reliability Runtime`
- `P2 - Verifiable Hallucination Reduction`
- `P3 - Production Observability`

Automation included:
- Workflow: `.github/workflows/roadmap-sync.yml`
- Script: `tools/sync_roadmap_to_github.py`

What it does:
- creates/reopens milestones from section headers `## N. ...` in `ROADMAP.md`
- creates missing issues with title prefix `[Roadmap] ...`
- moves existing `[Roadmap] ...` issues to the correct milestone

## 6) Whitepaper automation

Workflow `whitepaper` regenerates `docs/whitepaper.html` from committed eval runs and opens a PR.

Note: you typically publish the run artifacts via:
- a separate `results/` repo, or
- Git LFS, or
- a storage bucket, plus a small index JSON committed to this repo.

## 7) Continuous Results Publication

Workflow:
- `.github/workflows/continuous-results.yml`

Pipeline:
1. run benchmark A/B (`entropic-killer-demo`)
2. version snapshots into `evals/results/history/`
3. regenerate `evals/results/leaderboard/`
4. regenerate `docs/whitepaper.html`
5. open PR with all updated artifacts

Manual trigger inputs:
- `provider`: `openrouter` or `mock` (empty = auto)
- `model`: provider model id
- `max_cases`: throttle for daily costs/latency

## 8) Nightly Real Benchmark + External Results Repo

Workflow:
- `.github/workflows/nightly-openrouter-results.yml`

Goal:
- run nightly on **real OpenRouter/Gemini**
- publish versioned artifacts (including `events.jsonl`) to external repo `entropic-core-results`
- optionally mirror to S3 bucket for static hosting/CDN

Required GitHub secrets and vars:
- secret: `OPENROUTER_API_KEY`
- secret: `RESULTS_REPO_TOKEN` (token with push rights to results repo)
- var: `RESULTS_REPO` (format: `owner/entropic-core-results`)
- optional vars:
  - `OPENROUTER_HTTP_REFERER`
  - `OPENROUTER_APP_TITLE`
  - `RESULTS_S3_BUCKET`
  - `AWS_DEFAULT_REGION`
- optional secrets for S3 mirror:
  - `AWS_ACCESS_KEY_ID`
  - `AWS_SECRET_ACCESS_KEY`
