added filter to decide what challenges to include

README.md

@@ -5,10 +5,11 @@ GitLab challenges group, works out each challenge's status, category and
 difficulty from its `README.md`, and checks that challenges marked as ready
 really are. The result goes to:
 
-- **a HedgeDoc note**: an overview of all challenges, refreshed every 30 minutes
+- **a HedgeDoc note**: an overview of the challenges included in the CTF,
+  refreshed every 30 minutes
 - **`challs.txt` in the deployment repo**: the clone URLs of every challenge
-  ready for infra testing, updated daily
-- **the terminal**: the same overview, for a quick look
+  included in the CTF and ready for infra testing, updated daily
+- **the terminal**: the same overview, plus the repos left out of the CTF
 
 ## Requirements
 
@@ -38,6 +39,34 @@ repo, and permission to push to the branch if it is protected.
 
 Environment variables override the values in `.env`.
 
+## Choosing what is in the CTF
+
+[`challenges.yml`](challenges.yml) maps each repo path to its state:
+
+```yaml
+challenges:
+  baby_rsa: included          # part of this CTF
+  static_antivirus: abandoned # dropped for good
+  some_chall: postponed       # left to be finished for another CTF
+
+skip_checks:
+  whoami: [has_solve_script]  # OSINT: there is nothing to script
+```
+
+- Only **included** challenges appear in the HedgeDoc note and the counts, and
+  only they can end up in `challs.txt`.
+- **Abandoned** and **postponed** challenges are only listed in the terminal.
+- A repo that is **not listed** is also only listed in the terminal, in its own
+  section, and is not tracked or deployed until somebody decides. The timers run
+  quietly, so run `./ctf_status.py` by hand to see new repos.
+- **`skip_checks`** exempts a repo from individual repo checks, named after their
+  functions in [`tracker/checks.py`](tracker/checks.py).
+
+Entries for repos that do not exist are flagged under *Needs attention*. If the
+file is missing or invalid, the run stops rather than committing an empty
+`challs.txt`. The server reads the file from its checkout, so changes must be
+pulled there.
+
 ## Usage
 
 ```sh
@@ -101,6 +130,7 @@ Two kinds of finding are reported:
   actually finished: `description.yml` is missing or still the template, its
   category or flag is wrong, a `deploy_dir` or its `Dockerfile` is missing, or
   there is no `solve.py`. A blocked challenge (⛔) is kept out of `challs.txt`.
+  `skip_checks` in `challenges.yml` can exempt a challenge from a check.
 
 Passing every check does not prove that a challenge builds or solves. That is
 what testing is for.
@@ -111,10 +141,12 @@ All rules are in [`tracker/checks.py`](tracker/checks.py), one function each.
 
 ```
 ctf_status.py          command line entry point
+challenges.yml         what is part of this CTF, and check exceptions
 tracker/
   checks.py            the rules: README problems and repo blockers
   challenge.py         reads a README header into a Challenge
   gitlab.py            GitLab API access
+  selection.py         reads challenges.yml
   overview.py          runs parsing and checks over all repos
   terminal.py          terminal output
   markdown.py          HedgeDoc note