DEVX-155: refactor: extract wait_for_checks, consolidate ansible_checks, deprecate ci/discover_runners

docs/tech/architecture.md

@@ -33,7 +33,8 @@ src/devx/
 │   ├── notify_failure.py    # Create Gitea issues on CI failures
 │   ├── distribute_files.py  # Distribute files across parallel runners
 │   ├── integration_guard.py # Run pytest with cross-runner fail-fast
-│   ├── discover_runners.py  # Dynamic Gitea runner discovery
+│   ├── discover_runners.py  # Deprecated wrapper → molecule/discover_runners
+│   ├── wait_for_checks.py  # Poll Gitea Actions for job completion
 │   ├── check_translations.py  # Translation completeness check
 │   └── doc_coverage.py      # Documentation coverage check
 ├── tools/                   # Developer tooling modules (run locally or by CI)
@@ -48,7 +49,7 @@ src/devx/
 │   └── install_checkmake.py # Install checkmake (Makefile linter)
 └── molecule/                # Optional molecule testing helpers (Ansible projects)
     ├── __init__.py
-    ├── discover_runners.py      # Dynamic Gitea runner discovery
+    ├── discover_runners.py      # Dynamic Gitea runner discovery (canonical)
     ├── distribute_molecule.py   # Distribute scenarios across runners
     ├── molecule_ci_guard.py     # Run molecule with cross-runner fail-fast
     ├── molecule_all.py          # Run all molecule scenarios locally
@@ -285,13 +286,24 @@ Click commands from `cli.py` and verifies each has documentation in
 `architecture.md` and CI scripts in `ci-cd-workflow.md`. Supports
 `--fail-on-missing` to enforce 100% coverage.
 
-### `discover_runners.py`
+### `discover_runners.py` (deprecated wrapper)
+
+> **Deprecated:** Use `devx.molecule.discover_runners` instead. This
+> module is a thin wrapper that re-exports the canonical implementation.
 
 Discovers available Gitea Actions runners at three levels: repository,
 organization, and instance (administrator). Falls back to the `MOLECULE_RUNNERS` repo
 variable or `DEFAULT_MAX_RUNNERS` (3). Outputs runner count or a JSON index
 array for use as a dynamic matrix in Gitea Actions.
 
+### `wait_for_checks.py`
+
+Polls the Gitea Actions API for job completion status. Used by auto-merge
+jobs that need to wait for parallel jobs (for example molecule-tests) before
+proceeding. Replaces inline shell polling in workflow YAML with a
+reusable, testable Python module. Exit codes: 0 (success), 1 (job
+failure), 2 (timeout), 3 (API error or no matching jobs).
+
 ### `distribute_files.py`
 
 Distributes files matching a glob pattern across N parallel runners
@@ -396,8 +408,13 @@ Intended for local development; CI uses the parallel matrix instead.
 
 ### `molecule/discover_runners.py`
 
-Discovers available Gitea Actions runners for molecule tests. Same logic as
-`devx.ci.discover_runners` but intended for molecule-specific workflows.
+Discovers available Gitea Actions runners for molecule tests. This is the
+canonical implementation; `devx.ci.discover_runners` is a deprecated wrapper
+that re-exports from this module. Queries runners at repository,
+organization, and instance (administrator) levels, with warnings logged
+to stderr on non-200 responses (except 403 on instance-level, which is
+expected without admin scope). Falls back to `MOLECULE_RUNNERS` env var
+or `DEFAULT_MAX_RUNNERS` (3).
 
 ### `start_docker.py`