Add complete CI validation pipeline, test entry, GitHub Pages site, and auto-approve workflow

- CI validation pipeline (ci/validate.py + ci/checks/) with modular checks:
  stockholm parsing, annotation consistency, protein/DNA checks, provenance,
  structures, and weighted scoring (diversity 40%, annotation 25%,
  functionality 20%, size 15%)
- Test entry (entries/test-entry/) built from real Mos1 transposase data
  (M14653.1) plus two synthetic variants
- GitHub Pages leaderboard site (docs/) with dark theme, expandable
  detail panels, and submission instructions
- Auto-approve workflow for PRs scoped to entries/{username}/
- Branch protection requiring validation + 1 approval
- 39 pytest tests covering all check modules and integration
- POLICY.md, README.md, .gitignore

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ihh

.github/workflows/auto-approve.yml

@@ -0,0 +1,108 @@
+name: Auto-approve own entry
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'entries/**'
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  check-and-approve:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if PR only modifies own entry
+        id: check
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const author = pr.user.login.toLowerCase();
+            const expectedDir = `entries/${author}/`;
+
+            // Get all files changed in this PR
+            const files = await github.paginate(
+              github.rest.pulls.listFiles,
+              { owner: context.repo.owner, repo: context.repo.repo, pull_number: pr.number }
+            );
+
+            const changedPaths = files.map(f => f.filename);
+            core.info(`PR author: ${author}`);
+            core.info(`Expected directory: ${expectedDir}`);
+            core.info(`Changed files: ${changedPaths.join(', ')}`);
+
+            // Every changed file must be under entries/{author}/
+            const unauthorized = changedPaths.filter(
+              p => !p.toLowerCase().startsWith(expectedDir)
+            );
+
+            if (unauthorized.length > 0) {
+              core.info(`Unauthorized changes: ${unauthorized.join(', ')}`);
+              core.setOutput('approved', 'false');
+              core.setOutput('reason',
+                `PR modifies files outside entries/${author}/: ${unauthorized.join(', ')}`
+              );
+              return;
+            }
+
+            if (changedPaths.length === 0) {
+              core.setOutput('approved', 'false');
+              core.setOutput('reason', 'No files changed');
+              return;
+            }
+
+            core.setOutput('approved', 'true');
+            core.setOutput('reason', `All ${changedPaths.length} files are under ${expectedDir}`);
+
+      - name: Approve PR
+        if: steps.check.outputs.approved == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            await github.rest.pulls.createReview({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number,
+              event: 'APPROVE',
+              body: `Auto-approved: all changes are scoped to \`entries/${pr.user.login.toLowerCase()}/\`.`
+            });
+            core.info('PR approved');
+
+      - name: Enable auto-merge
+        if: steps.check.outputs.approved == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            try {
+              await github.graphql(`
+                mutation($prId: ID!) {
+                  enablePullRequestAutoMerge(input: {
+                    pullRequestId: $prId,
+                    mergeMethod: SQUASH
+                  }) { clientMutationId }
+                }
+              `, { prId: pr.node_id });
+              core.info('Auto-merge enabled');
+            } catch (e) {
+              // Auto-merge may not be enabled in repo settings — that's OK
+              core.warning(`Could not enable auto-merge: ${e.message}`);
+            }
+
+      - name: Post rejection comment
+        if: steps.check.outputs.approved == 'false'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const reason = '${{ steps.check.outputs.reason }}';
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr.number,
+              body: `This PR cannot be auto-approved. ${reason}\n\nA maintainer will need to review manually.`
+            });

.github/workflows/validate.yml

@@ -0,0 +1,99 @@
+name: Validate entries
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'entries/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'entries/**'
+
+permissions:
+  contents: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install -r ci/requirements.txt
+
+      - name: Identify modified entries
+        id: entries
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            # For PRs, diff against the base branch
+            git fetch origin ${{ github.base_ref }} --depth=1
+            CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- entries/ \
+              | cut -d/ -f2 | sort -u | grep -v '^$' || true)
+          else
+            CHANGED=$(git diff --name-only HEAD~1 HEAD -- entries/ \
+              | cut -d/ -f2 | sort -u | grep -v '^$' || true)
+          fi
+          echo "entries=$CHANGED" >> "$GITHUB_OUTPUT"
+          echo "Modified entries: $CHANGED"
+
+      - name: Remove scores for deleted entries
+        if: github.event_name == 'push' && steps.entries.outputs.entries != ''
+        run: |
+          for TEAM in ${{ steps.entries.outputs.entries }}; do
+            if [ ! -d "entries/$TEAM" ]; then
+              echo "=== Entry $TEAM was deleted, removing score ==="
+              rm -f "scores/$TEAM.json"
+              rm -f "docs/scores/$TEAM.json"
+            fi
+          done
+
+      - name: Validate entries
+        if: steps.entries.outputs.entries != ''
+        run: |
+          COMMIT=$(git rev-parse --short HEAD)
+          EXIT=0
+          for TEAM in ${{ steps.entries.outputs.entries }}; do
+            if [ ! -d "entries/$TEAM" ]; then
+              echo "=== Skipping deleted entry $TEAM ==="
+              continue
+            fi
+            echo "=== Validating $TEAM ==="
+            python ci/validate.py \
+              --entry "entries/$TEAM" \
+              --commit "$COMMIT" \
+              --scores-dir scores \
+              --leaderboard leaderboard.json || EXIT=1
+          done
+          # Rebuild leaderboard to reflect any deletions
+          python -c "
+          from pathlib import Path; import sys; sys.path.insert(0, 'ci')
+          from validate import update_leaderboard
+          update_leaderboard(Path('scores'), Path('leaderboard.json'))
+          "
+          exit $EXIT
+
+      - name: Update GitHub Pages data
+        if: always() && github.event_name == 'push' && steps.entries.outputs.entries != ''
+        run: |
+          mkdir -p docs/scores
+          cp leaderboard.json docs/ 2>/dev/null || true
+          cp scores/*.json docs/scores/ 2>/dev/null || true
+
+      - name: Commit results
+        if: always() && github.event_name == 'push' && steps.entries.outputs.entries != ''
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add scores/ leaderboard.json docs/
+          git diff --cached --quiet || \
+            git commit -m "Update scores and leaderboard [skip ci]"
+          git push

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+.pytest_cache/

CLAUDE.md

@@ -27,6 +27,12 @@ tc1-leaderboard/
 │   ├── team-alpha.json         # Validation results + score
 │   └── team-beta.json
 ├── leaderboard.json            # Aggregated ranked leaderboard
+├── docs/                       # GitHub Pages site (auto-updated by CI)
+│   ├── index.html              # Main leaderboard page
+│   ├── style.css               # Styling
+│   ├── leaderboard.js          # Client-side rendering from JSON
+│   ├── leaderboard.json        # Copy of root leaderboard.json
+│   └── scores/                 # Copies of score files
 ├── ci/
 │   ├── validate.py             # Main validation + scoring script
 │   ├── checks/                 # Modular validation checks
@@ -209,6 +215,8 @@ All checks produce a pass/fail/warn status and a message. An entry with any hard
 - `assembly` is a plausible accession format.
 - Coordinates are internally consistent (`start` < `end`, `strand` is `+` or `-`).
 
+If it is not beyond the scope of GitHub actions (e.g. if there is a REST service for a fast subsequence retrieval that we can query), provenance should be verified.
+
 ### Scoring
 
 The score for an entry is a weighted combination of factors designed to reward phylogenetically diverse, well-annotated, high-confidence collections. The total score is normalized to 0–100.
@@ -241,7 +249,7 @@ Goal: span the phylogenetic space of the ITm superfamily, not pile up near-ident
 
 - Logarithmic scaling: score = min(1, log2(N) / log2(target)), where `target` is a configurable parameter (e.g. 64 sequences).
 - This rewards having enough sequences to be useful as a seed dataset, but saturates — 200 sequences is not much better than 64 for a seed. The point is to span space, not to be exhaustive.
-- Hard penalty if N < 3 (entry is rejected).
+- Hard penalty if N < 3 or N > 300 (entry is rejected).
 
 #### Score normalization
 
@@ -304,10 +312,63 @@ The GitHub Actions workflow (`.github/workflows/validate.yml`) triggers on pushe
 
 Entries that fail hard validation checks (format errors, missing required files, ID mismatches) receive a score of 0 and a descriptive error in their score file.
 
+
 ## Updating an entry
 
 To update an entry, simply push a new commit modifying files in your `entries/{team}/` directory. The CI will re-run validation and overwrite the previous score. The leaderboard always reflects the latest commit for each team.
 
+## GitHub Pages leaderboard site
+
+The leaderboard is published as a static site via GitHub Pages, automatically updated by CI.
+
+### Site structure
+
+```
+docs/
+├── index.html         # Main leaderboard page (auto-generated)
+├── style.css          # Minimal styling
+└── leaderboard.js     # Reads leaderboard.json and renders the table
+```
+
+### How it works
+
+1. The validation CI workflow (`.github/workflows/validate.yml`) produces `leaderboard.json` at the repo root as before.
+2. A second workflow step (or a dedicated workflow `.github/workflows/pages.yml`) runs after validation completes:
+   - Copies `leaderboard.json` and all `scores/*.json` into `docs/`.
+   - Commits any changes to `docs/`.
+3. GitHub Pages is configured to serve from the `docs/` folder on the `main` branch (Settings → Pages → Source: `main` / `docs`).
+4. `docs/index.html` is a single-page app that fetches `leaderboard.json` at load time and renders a ranked table with columns: rank, team, total score, sub-scores (diversity, annotation, functionality, size), number of sequences, number of families, and last commit.
+5. Clicking a team name expands to show per-check status and per-sequence issues from `scores/{team}.json`.
+
+### Design constraints
+
+- **No build step.** The site is plain HTML + CSS + vanilla JS. No bundler, no framework, no Node.
+- **Data-driven.** All content comes from the JSON files. The HTML/JS never hard-codes team names or scores.
+- **Accessible.** Semantic HTML table, readable without JS (a `<noscript>` fallback links directly to `leaderboard.json`).
+- **Mobile-friendly.** Responsive table layout via CSS.
+- **Auto-refresh.** The CI keeps `docs/leaderboard.json` up to date; the page always shows the latest data because it fetches from the same repo's GitHub Pages URL.
+
+### CI integration
+
+The pages deployment step should be added to the end of the existing validation workflow:
+
+```yaml
+# After the validation and scoring steps:
+- name: Update GitHub Pages data
+  run: |
+    mkdir -p docs
+    cp leaderboard.json docs/
+    cp scores/*.json docs/scores/ 2>/dev/null || true
+
+- name: Commit docs
+  run: |
+    git add docs/
+    git diff --cached --quiet || git commit -m "Update leaderboard site [skip ci]"
+    git push
+```
+
+The `[skip ci]` tag prevents infinite CI loops from the docs commit.
+
 ## Reuse plan
 
 The validation logic in `ci/checks/` is designed as a library that can be imported and reused. The "big data" leaderboard (Stage 2) will validate entries stored in S3 using the same annotation format and similar checks, extended with:
@@ -349,4 +410,5 @@ When asked to work on this project, Claude should:
 4. **Maintain a clear policy document POLICY.md at the top level, describing the scoring scheme and hard/soft constraints.** The scoring scheme and validation may change, but the current policy should always be transparent.
 5. **Write tests.** The `ci/` directory should include test fixtures (minimal valid and invalid entries) and pytest-based tests for every check.
 6. **Design for reuse.** The Stockholm parser, annotation validator, and protein/DNA consistency checks will be reused for the big data leaderboard. Keep them modular and dependency-light.
-7. **Do not over-engineer.** This is a research tool, not a production service. Clarity and correctness over abstraction.
+7. **Do not over-engineer.** This is a research tool, not a production service. Clarity and correctness over abstraction.
+8. **Keep the GitHub Pages site working.** When changing the score output format or leaderboard.json schema, update `docs/leaderboard.js` to match. The site must always render correctly from the current JSON structure.

POLICY.md

@@ -0,0 +1,80 @@
+# Scoring Policy — ITm Seed Dataset Leaderboard
+
+This document describes the current scoring scheme and validation rules. It is the authoritative reference for what the CI pipeline checks and how scores are computed.
+
+## Hard-fail checks (score = 0 if any fail)
+
+### Format checks
+- `protein.sto` must be valid Stockholm 1.0 with a `#=GC catalytic_triad` line.
+- `dna.sto` must be valid multi-Stockholm with exactly one sequence per block and a `#=GC element_structure` line per block.
+- `provenance.tsv` must be valid TSV with all required columns: `id`, `family`, `host_species`, `host_taxid`, `assembly`, `chrom`, `start`, `end`, `strand`, `source`, `reference`.
+- All IDs must be consistent across `protein.sto`, `dna.sto`, and `provenance.tsv`.
+- Minimum 3 sequences, maximum 300.
+
+### Annotation consistency checks
+- `catalytic_triad` must mark exactly 2–3 positions with D, d, and E (or D for DDD families). Marked columns must contain the expected residue in the majority of sequences.
+- `element_structure` must:
+  - Use only valid characters: `5 3 < > A B 0 1 2 n t .`
+  - Follow the pattern: `5+AA<+[interior]+>+BB3+`
+  - Have `A` and `B` positions (TSD) spelling `TA` in the sequence.
+  - Have TIRs (`<` and `>`) that are approximate reverse complements (>70% match).
+  - Have ORF annotation (`012`) with correct codon phasing and length divisible by 3.
+  - Have ORF translation matching the protein in `protein.sto` at >=90% identity.
+
+## Scored checks (reduce score but do not reject)
+
+### Protein-level
+- Transposase length within expected range for declared family.
+- Catalytic triad spacing matches declared family (e.g. DD34D = 34 residues between 2nd and 3rd).
+
+### DNA-level
+- Element length (excluding flanking) within expected range.
+- TIR length within expected range.
+- ORF GC content between 15% and 75%.
+- No ambiguous bases (N) in the ORF.
+
+### Provenance
+- `host_taxid` is a valid positive integer.
+- `assembly` matches GC[AF]_NNNNNNNNN.N format.
+- Coordinates are consistent (`start` < `end`, `strand` is `+` or `-`).
+
+## Scoring weights
+
+| Component | Weight | What it rewards |
+|-----------|--------|-----------------|
+| Sequence diversity | 40% | Phylogenetic breadth, multi-family coverage |
+| Annotation completeness | 25% | Passing all checks, optional metadata |
+| Evidence of functionality | 20% | Near-identical paralogs, experimental data, literature |
+| Collection size | 15% | Enough sequences to seed a model (target: 64) |
+
+## Scoring details
+
+### Diversity (40%)
+- Mean pairwise protein distance (1 − identity) across all sequence pairs.
+- Multi-family bonus: +10% per additional family (up to +50%).
+- Redundancy penalty: −2% per pair with >95% protein identity.
+
+### Annotation completeness (25%)
+- Base score from check pass/warn/fail rates.
+- Bonuses for optional metadata: `paralog_hits` (+1% per entry), `confidence_tier` (+0.5% per entry), `pdb_file` (+1% per entry).
+
+### Functionality (20%)
+- Per-sequence scoring, averaged:
+  - `max_paralog_identity` >= 0.99: +40%
+  - `max_paralog_identity` >= 0.95: +15%
+  - Experimental PDB: +10%
+  - Predicted PDB: +3%
+  - Literature reference with DOI: +5%
+  - Confidence tier bonus (tier 1 = +10%, tier 2 = +7%, tier 3 = +4%, tier 4 = +2%)
+
+### Size (15%)
+- `min(1, log2(N) / log2(64))`
+- Saturates at 64 sequences. Hard reject if N < 3 or N > 300.
+
+## Tie-breaking
+
+Entries with equal total scores are ranked by annotation completeness, then by diversity.
+
+## Policy changes
+
+This policy may be updated. The leaderboard always reflects the current policy. When the policy changes, all entries are re-scored on the next CI run.