release: v0.5.0

Updated sync_wiki.py to use correct Gitea 1.26 wiki API: POST /wiki/new for create, PATCH /wiki/page/{sub_url} for update, GET /wiki/pages returns sub_url. Tests updated to match.

Closes GRM-36

.gitea/workflows/auto-merge.yml

@@ -17,7 +17,7 @@ jobs:
           VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
           PYTHONPATH: src
         run: |
-          python3 scripts/auto_merge.py \
+          python3 scripts/ci/auto_merge.py \
             "${{ github.head_ref }}" \
             "${{ github.event.pull_request.title }}" \
             "${{ github.repository }}" \

.gitea/workflows/ci.yml

@@ -26,19 +26,41 @@ jobs:
         run: |
           . .venv/bin/activate
           python3 scripts/check_test_speed.py --max-seconds 10
-      - name: Release dry-run validation
-        run: |
-          . .venv/bin/activate
-          PYTHONPATH=src python3 scripts/release.py --dry-run || true
       - name: Documentation coverage check
         run: |
           . .venv/bin/activate
-          PYTHONPATH=src python3 scripts/doc_coverage.py
+          PYTHONPATH=src python3 scripts/ci/doc_coverage.py
+
+  release-dry-run:
+    needs: [quality, detect-changes]
+    if: needs.detect-changes.outputs.user-facing-changed == 'true'
+    runs-on: docker
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up environment
+        run: make setup
+      - name: Install git-cliff
+        run: |
+          GIT_CLIFF_VERSION="2.13.0"
+          URL="https://github.com/orhun/git-cliff/releases/download/v${GIT_CLIFF_VERSION}/git-cliff-${GIT_CLIFF_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
+          TMPDIR="$(mktemp -d)"
+          curl -sL "$URL" | tar xz -C "$TMPDIR"
+          mkdir -p "$HOME/.local/bin"
+          mv "$TMPDIR/git-cliff-${GIT_CLIFF_VERSION}/git-cliff" "$HOME/.local/bin/git-cliff"
+          chmod +x "$HOME/.local/bin/git-cliff"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Release dry-run validation
+        run: |
+          . .venv/bin/activate
+          PYTHONPATH=. python3 scripts/ci/release.py --dry-run || true
 
   detect-changes:
     runs-on: docker
     outputs:
       ansible-changed: ${{ steps.detect.outputs.ansible-changed }}
+      user-facing-changed: ${{ steps.detect.outputs.user-facing-changed }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -62,14 +84,77 @@ jobs:
             echo "ansible-changed=false" >> "$GITHUB_OUTPUT"
             echo "No Ansible files changed — skipping molecule tests."
           fi
+          # Check if any user-facing files changed (src/, ansible/, pyproject.toml)
+          USER_FACING=$(git diff --name-only "$BASE" "$HEAD" -- src/gitea_runner_manager/ ansible/ pyproject.toml 2>/dev/null | head -1)
+          if [ -n "$USER_FACING" ]; then
+            echo "user-facing-changed=true" >> "$GITHUB_OUTPUT"
+            echo "User-facing files changed — release dry-run will run."
+          else
+            echo "user-facing-changed=false" >> "$GITHUB_OUTPUT"
+            echo "No user-facing files changed — skipping release dry-run."
+          fi
+
+  validate-merge:
+    if: github.event_name == 'push'
+    runs-on: docker
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Validate commit message format
+        run: |
+          set -euo pipefail
+          MSG=$(git log -1 --pretty=%s)
+          echo "Commit message: $MSG"
+          # Allowed formats:
+          #   GRM-N <type>: <description>     (squash-merge)
+          #   release: vX.Y.Z                  (release commits)
+          #   GRM-N <type>: <description> (#M) (squash-merge with PR ref)
+          if echo "$MSG" | grep -qE '^GRM-[0-9]+ [a-z]+: .+'; then
+            echo "OK: GRM-N <conventional> format"
+          elif echo "$MSG" | grep -qE '^release: v[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "OK: release commit format"
+          else
+            echo "FAIL: commit message does not follow naming convention"
+            echo "Expected: GRM-N <type>: <description> or release: vX.Y.Z"
+            echo "Got:      $MSG"
+            exit 1
+          fi
+
+  discover-runners:
+    needs: [detect-changes]
+    if: needs.detect-changes.outputs.ansible-changed == 'true'
+    runs-on: docker
+    outputs:
+      runner-count: ${{ steps.discover.outputs.runner-count }}
+      runner-indices: ${{ steps.discover.outputs.runner-indices }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        run: make setup
+      - name: Discover available runners
+        id: discover
+        env:
+          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          MOLECULE_RUNNERS: ${{ vars.MOLECULE_RUNNERS }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate
+          OUTPUT=$(python3 scripts/ci/discover_runners.py --owner "${{ github.repository_owner }}" --repo "${{ github.event.repository.name }}")
+          echo "$OUTPUT"
+          # Parse outputs
+          RUNNER_COUNT=$(echo "$OUTPUT" | grep '^count=' | cut -d= -f2)
+          RUNNER_INDICES=$(echo "$OUTPUT" | grep '^indices=' | cut -d= -f2)
+          echo "runner-count=$RUNNER_COUNT" >> "$GITHUB_OUTPUT"
+          echo "runner-indices=$RUNNER_INDICES" >> "$GITHUB_OUTPUT"
 
   molecule-tests:
-    needs: [quality, detect-changes]
+    needs: [quality, detect-changes, discover-runners]
     if: needs.detect-changes.outputs.ansible-changed == 'true'
     runs-on: docker
     strategy:
       matrix:
-        runner-index: [0, 1, 2]
+        runner-index: ${{ fromJSON(needs.discover-runners.outputs.runner-indices) }}
     steps:
       - uses: actions/checkout@v4
       - name: Set up environment
@@ -77,14 +162,14 @@ jobs:
       - name: Discover assigned test pairs
         run: |
           . .venv/bin/activate
-          PAIRS=$(python3 scripts/distribute_molecule.py --runner-index ${{ matrix.runner-index }} --max-runners 3)
+          PAIRS=$(python3 scripts/ci/distribute_molecule.py --runner-index ${{ matrix.runner-index }} --max-runners ${{ needs.discover-runners.outputs.runner-count }})
           echo "Assigned pairs: $PAIRS"
           echo "TEST_PAIRS=$PAIRS" >> $GITHUB_ENV
       - name: Run molecule tests
         run: |
           set -euo pipefail
           . .venv/bin/activate
-          python3 scripts/molecule_ci_guard.py $TEST_PAIRS
+          python3 scripts/ci/molecule_ci_guard.py $TEST_PAIRS
         env:
           GITEA_URL: ${{ github.server_url }}
           REPO_TOKEN: ${{ secrets.REPO_TOKEN }}

.gitea/workflows/post-merge.yml

@@ -18,6 +18,6 @@ jobs:
           VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
           PYTHONPATH: src
         run: |
-          python3 scripts/post_merge.py \
+          python3 scripts/ci/post_merge.py \
             "$(git log -1 --pretty=%B)" \
             --commit-sha "$(git rev-parse HEAD)"

.gitea/workflows/publish.yml

@@ -37,7 +37,7 @@ jobs:
           PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
           PYTHONPATH: src
         run: |
-          python3 scripts/publish.py \
+          python3 scripts/ci/publish.py \
             "${{ github.ref_name }}" \
             "${{ github.repository }}"
       - name: Notify on failure
@@ -46,7 +46,7 @@ jobs:
           REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
           PYTHONPATH: src
         run: |
-          python3 scripts/notify_failure.py \
+          python3 scripts/ci/notify_failure.py \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \
             --workflow "publish" \

.gitea/workflows/release.yml

@@ -31,18 +31,18 @@ jobs:
           git config user.email "grm-ci-bot@oblachno.fyi"
       - name: Run release
         env:
-          PYTHONPATH: src
+          PYTHONPATH: .
         run: |
           . .venv/bin/activate
-          python3 scripts/release.py
+          python3 scripts/ci/release.py
       - name: Notify on failure
         if: failure()
         env:
           REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-          PYTHONPATH: src
+          PYTHONPATH: .
         run: |
           . .venv/bin/activate
-          python3 scripts/notify_failure.py \
+          python3 scripts/ci/notify_failure.py \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \
             --workflow "release" \

.gitea/workflows/sync-wiki.yml

@@ -22,7 +22,7 @@ jobs:
           PYTHONPATH: src
         run: |
           . .venv/bin/activate
-          python3 scripts/sync_wiki.py --repo "${{ github.repository }}"
+          python3 scripts/ci/sync_wiki.py --repo "${{ github.repository }}" --strict
       - name: Tag wiki on release
         if: startsWith(github.ref, 'refs/tags/v')
         env:

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
     hooks:
       - id: validate-commit-msg
         name: validate commit message
-        entry: .venv/bin/python scripts/validate_commit_msg.py
+        entry: .venv/bin/python scripts/ci/validate_commit_msg.py
         language: system
         stages: [commit-msg]
         pass_filenames: true
@@ -58,7 +58,7 @@ repos:
 
       - id: commit-msg
         name: validate commit message
-        entry: .venv/bin/python scripts/validate_commit_msg.py
+        entry: .venv/bin/python scripts/ci/validate_commit_msg.py
         language: system
         stages: [commit-msg]
         pass_filenames: true

AGENTS.md

@@ -83,9 +83,9 @@ Review the full diff (`git diff master...HEAD`) focusing on:
 - **User experience**: Clear error messages, intuitive CLI flags, helpful output
 - **Documentation**: Completeness and relevance of docs, CHANGELOG entries, AGENTS.md updates
 
-Post review comments using `scripts/review_pr.py`:
+Post review comments using `scripts/ci/review_pr.py`:
 ```bash
-REPO_TOKEN=<token> python3 scripts/review_pr.py <pr_number> <owner/repo> \
+REPO_TOKEN=<token> python3 scripts/ci/review_pr.py <pr_number> <owner/repo> \
   --event REQUEST_CHANGES \
   --body "Review summary" \
   --comments-json comments.json
@@ -97,19 +97,25 @@ Fix each comment one by one, commit, and push. Re-review until satisfied.
 ### 8. Approve and Merge
 Once all comments are addressed:
 ```bash
-REPO_TOKEN=<token> python3 scripts/review_pr.py <pr_number> <owner/repo> \
+REPO_TOKEN=<token> python3 scripts/ci/review_pr.py <pr_number> <owner/repo> \
   --event APPROVE \
   --body "All comments addressed. LGTM."
 ```
 
 Then add the `ready-to-merge` label. The auto-merge workflow will:
-1. **Validate** PR title format and match against Vikunja task title
+1. **Validate** PR title format (`GRM-N: <vikunja task title>`) and match against Vikunja task title
 2. **Check** that at least one APPROVE review exists
 3. Wait for all CI checks to pass
-4. Squash-merge with title: `GRM-N <conventional commit message>` (space-separated)
+4. Squash-merge with title: `GRM-N <conventional commit message>` (space-separated, no colon after GRM-N)
 5. The post-merge workflow marks the Vikunja task as done
 6. The release workflow automatically versions, tags, and publishes (see below)
 
+> **IMPORTANT**: Never manually merge PRs via the API. Always use the auto-merge
+> workflow by adding the `ready-to-merge` label. Manual merges bypass the
+> `GRM-N <conventional>` format enforcement, producing incorrectly named commits.
+> The CI `validate-merge` job checks every push to master and will fail if a
+> commit message doesn't match `GRM-N <type>: <description>` or `release: vX.Y.Z`.
+
 ### CI Path Filtering
 
 The CI workflow includes a `detect-changes` job that checks whether any files
@@ -118,6 +124,20 @@ changed, molecule tests are skipped — this prevents non-Ansible changes
 (e.g., Python scripts, workflow YAML, docs) from being blocked by molecule
 test infrastructure flakiness.
 
+### Dynamic Runner Discovery
+
+Molecule tests are distributed across available Gitea Actions runners
+dynamically via `scripts/ci/discover_runners.py`. The `discover-runners`
+job queries the Gitea API for runners at all levels (repo, org, instance)
+and generates a dynamic matrix. If the API can't see instance-level runners
+(no admin scope), it falls back to the `MOLECULE_RUNNERS` repo variable,
+then to a default of 3.
+
+**When adding/removing Gitea runners:**
+1. Repo/org-level runners are auto-detected via the API
+2. For instance-level runners, update the `MOLECULE_RUNNERS` repo variable
+3. The workflow automatically scales the matrix to match available runners
+
 ### Automated Release Pipeline
 
 After a PR is merged to master, the release pipeline runs automatically:
@@ -125,18 +145,65 @@ After a PR is merged to master, the release pipeline runs automatically:
 1. **Release workflow** (`.gitea/workflows/release.yml`):
    - Triggers on push to master
    - Sets up full dev environment (`make setup`) so lint and tests can run
-   - Runs `scripts/release.py` which uses **git-cliff** to:
-     - Calculate the next semver version from conventional commits since the last tag
-     - Update `__version__` in `src/gitea_runner_manager/__init__.py` (single source of truth)
-     - Update `CHANGELOG.md` with the new version section
-     - **Run `make lint-ruff` and `make pytest-cov`** to verify the release is healthy
-     - If lint or tests fail, **abort immediately** — no commit, no tag
-     - Commit with `release: vX.Y.Z` prefix (cleaner than `chore(release):`)
-     - Create an annotated tag `vX.Y.Z` on the release commit
-     - Push both the commit and tag to master
+   - Runs `scripts/ci/release.py` which:
+     - **Checks for user-facing changes** via `scripts/ci/classify_changes.py` — if only
+       workflow/infrastructure files changed (`.gitea/`, `scripts/`, `docs/`, `tests/`,
+       `AGENTS.md`, `Makefile`, etc.), the release is **skipped entirely** — no version
+       bump, no tag, no publish. This prevents unnecessary releases for CI/docs-only changes.
+     - Uses **git-cliff** to calculate the next semver version from conventional commits
+     - Updates `__version__` in `src/gitea_runner_manager/__init__.py` (single source of truth)
+     - Updates `CHANGELOG.md` with the new version section
+     - **Runs `make lint-ruff` and `make pytest-cov`** to verify the release is healthy
+     - If lint or tests fail, **aborts immediately** — no commit, no tag
+     - Commits with `release: vX.Y.Z` prefix (cleaner than `chore(release):`)
+     - Creates an annotated tag `vX.Y.Z` on the release commit
+     - Pushes both the commit and tag to master
    - `--skip-tests` flag bypasses test verification (emergency use only, not recommended)
    - Loops are prevented by `has_unreleased_changes` — after a release commit is tagged, the next run finds no unreleased changes and exits
-   - On failure, creates a Gitea issue via `scripts/notify_failure.py`
+   - On failure, creates a Gitea issue via `scripts/ci/notify_failure.py`
+
+### Smart CI: User-Facing vs Workflow-Only Changes
+
+Not all changes require the full CI pipeline or a new release. The project
+classifies changes into two categories using `scripts/ci/classify_changes.py`:
+
+**Classification strategy (safe-by-default):** Any file NOT in the explicit
+workflow-only allowlist is treated as user-facing. This prevents new file
+types from accidentally skipping releases.
+
+**Workflow-only paths** (infrastructure → no release needed):
+- `.gitea/**` — Gitea Actions workflows
+- `scripts/ci/**` — CI/CD automation scripts
+- `scripts/setup.sh`, `scripts/molecule_all.sh`, `scripts/__init__.py` — Shell scripts and package init
+- `docs/**` — Documentation
+- `tests/**` — Test files
+- `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TROUBLESHOOTING.md` — Project docs
+- `Makefile`, `cliff.toml`, `.pre-commit-config.yaml`, `.ansible-lint` — Config
+- `.env.example`, `.gitignore`, `.ruff.toml` — Config
+- `hooks/**` — Git hooks
+
+**User-facing paths** (tool changes → release needed) — everything else:
+- `src/gitea_runner_manager/**` — Python CLI source
+- `ansible/**` — Ansible role
+- `pyproject.toml` — Package metadata
+- `scripts/check_test_speed.py`, `scripts/configure_repo.py`, `scripts/install_checkmake.py` — Dev tools
+- Any new file type not in the allowlist
+
+**Script directory structure:**
+- `scripts/` — Dev tools (run locally by developers): `check_test_speed.py`, `configure_repo.py`, `install_checkmake.py`, `setup.sh`, `molecule_all.sh`
+- `scripts/ci/` — CI/CD automation (run by workflows): `release.py`, `publish.py`, `auto_merge.py`, `classify_changes.py`, `doc_coverage.py`, `sync_wiki.py`, etc.
+
+**CI behavior based on classification:**
+- **Molecule tests**: Only run when `ansible/` or `.ansible-lint` files change
+- **Release dry-run**: Only runs when user-facing files change
+- **Quality job** (lint, unit tests, coverage, doc-coverage): Always runs
+- **Release workflow**: Skips entirely when no user-facing files changed since last tag
+
+**AI agents must follow these rules:**
+- When working on workflow/CI/docs-only changes, use `ci:` or `docs:` commit prefixes
+- Do NOT bump the version or create tags for workflow-only changes
+- The `classify_changes.py` script enforces this automatically — no manual intervention needed
+- When adding a new CI script, place it in `scripts/ci/`. Dev tools go in `scripts/`.
 
 2. **Publish workflow** (`.gitea/workflows/publish.yml`):
    - Triggers on tag push (`v*`)
@@ -144,7 +211,7 @@ After a PR is merged to master, the release pipeline runs automatically:
    - Builds the Python package
    - Optionally publishes to PyPI (if `PYPI_TOKEN` is set)
    - Creates a Gitea release with git-cliff-generated release notes
-   - On failure, creates a Gitea issue via `scripts/notify_failure.py`
+   - On failure, creates a Gitea issue via `scripts/ci/notify_failure.py`
 
 ### git-cliff Commit Preprocessing
 
@@ -198,7 +265,7 @@ main.yml → systemd_check → user_setup → rootless_docker → install_runner
 
 6 scenarios: `default`, `multi-instance`, `lifecycle`, `template-content`, `deregister`, `update`
 4 platforms: `ubuntu-2204`, `ubuntu-2404`, `debian-12`, `archlinux`
-Platform list is defined in `scripts/distribute_molecule.py` (single source of truth)
+Platform list is defined in `scripts/ci/distribute_molecule.py` (single source of truth)
 
 ## Known Issues
 
@@ -232,14 +299,14 @@ docs/
 
 ### Wiki Sync
 
-- **On merge to master**: `sync-wiki.yml` workflow runs `scripts/sync_wiki.py` which pushes all `/docs/` content to the Gitea wiki via API
+- **On merge to master**: `sync-wiki.yml` workflow runs `scripts/ci/sync_wiki.py` which pushes all `/docs/` content to the Gitea wiki via API
 - **On release tag**: Same sync runs, plus the wiki is tagged with the release version
 - `mapping.json` maps each file path to a wiki page title (e.g., `user/getting-started.md` → `Getting-Started`)
 - README.md is a lean entry point with links to the wiki — no detailed content
 
 ### Documentation Coverage
 
-- `scripts/doc_coverage.py` checks that all CLI commands, Python modules, and CI scripts are documented
+- `scripts/ci/doc_coverage.py` checks that all CLI commands, Python modules, and CI scripts are documented
 - Runs as a CI step in the quality job
 - Goal: 100% coverage for public CLI commands and major architectural components
 

CHANGELOG.md

@@ -2,110 +2,158 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.3.0] - 2026-06-21
+## [0.5.0] - 2026-06-21
 
 ### Features
 
+- Add mandatory PR review step to workflow
+- Add automated semver versioning, tagging, and releases with git-cliff
+- Fix 12 critical workflow gaps in release pipeline
 - Implement documentation-as-code with wiki sync and doc-coverage
-
-## [0.2.2] - 2026-06-21
+- Smart CI and release skipping for workflow-only changes
+- Enforce commit naming conventions and workflow discipline
 
 ### Bug Fixes
 
+- Move release commit skip check into release.py
+- Install git-cliff to user-writable dir and fix archlinux idempotence
+- Use mktemp for git-cliff extraction to avoid file conflicts
+- Use full path for git-cliff version check in install step
+- Handle same-version update in release.py
+- Skip commit when version file unchanged in release.py
+- Release push permission and notify_failure label IDs
+- Strip git-cliff header from CHANGELOG.md updates
 - Enforce tests pass before tagging a release
 - Bypass commit-msg hook for release commits
+- Use correct Gitea 1.26 wiki API endpoints
+- Set PYTHONPATH=. for release.py to find scripts.ci module (#32)
+- Use content_base64 for Gitea wiki API, add --verify flag (#33)
+- Wiki links, add --strict integrity check for wiki sync (#34)
+- Clean up infrastructure-only releases and fix release classification
+- Rewrite changelog and re-tag releases at user-facing milestones
 
-## [0.2.1] - 2026-06-21
+### Refactor
 
-### Bug Fixes
+- Split CI scripts, fix release PYTHONPATH, dynamic runner discovery
 
-- Strip git-cliff header from CHANGELOG.md updates
+## [0.4.0] - 2026-06-21
+
+### Rootless Docker Support
+
+- Full rootless Docker installation and configuration via Ansible
+- `docker_rootless_setup` variable controls whether rootless Docker tasks run
+- User setup tasks (subuid/subgid, lingering, dockerd-rootless)
+- Proper gating of all Docker-dependent and `systemctl --user` tasks
+
+### Runner Labels
+
+- `--labels` option on `grm install` — specify runner labels (e.g., `--labels "ubuntu-latest:docker://node:20"`)
+- Labels passed through to runner config YAML
+
+### Security Fix (CWE-214)
+
+- **Critical**: Registration tokens and admin tokens are no longer passed via `--extra-vars` on the command line
+- Extra-vars are now written to a temporary JSON file with `0600` permissions and passed via `--extra-vars @tempfile`
+- This prevents secrets from being visible in the process list (`ps aux`)
+
+### Configuration via Environment Variables
+
+- API URLs and repo configuration in `config.py` are now overridable via environment variables:
+  - `GRM_GITEA_API_URL`
+  - `GRM_VIKUNJA_API_URL`
+  - `GRM_REPO_OWNER`
+  - `GRM_REPO_NAME`
+  - `GRM_VIKUNJA_PROJECT_ID`
+
+### Ansible Role Improvements
+
+- Dead code cleanup (removed `config.yml`, legacy system-level service, duplicate task includes)
+- `remove-runner.yml` now disables lingering and removes subuid/subgid entries for complete cleanup
+- Arch Linux: `gnupg` package name fix, pacman cache handling
+- Docker APT repository: deb822 format, proper GPG handling, arch mapping
+- Idempotence fixes for user_setup and download tasks
+
+## [0.3.0] - 2026-06-21
+
+### New CLI Options
+
+- `--force` flag on `grm remove` — remove a runner even when the host is unreachable (skips Ansible playbook, only deregisters via API)
+- `--url` option — override the Gitea URL for any command (useful for multiple Gitea instances)
+- `--ask-become-pass` is now the default behavior (no need to pass it explicitly)
+
+### Status Detection Fixes
+
+- `grm list` now correctly retrieves runner status (was showing "unknown" for active runners)
+- Docker mode status detection via `docker inspect`
+- Host/user context added to status output
+
+### Output Improvements
+
+- Colorized output for better visual feedback (green/red/yellow)
+- Translated operation reports for success and failure cases
+- Dual logging: `click.echo()` for user-facing messages, `logging` for debug
+- `GRM_LOG_LEVEL` environment variable for controlling verbosity
+- Full i18n support (all user-facing strings translated)
+
+### Internal Refactoring
+
+- Validation moved from CLI layer to business layer
+- Centralized API clients and HTTP status codes
+- User-friendly Click errors with i18n
 
 ## [0.2.0] - 2026-06-21
 
+### New CLI Commands
+
+- `grm start <host>` — start a runner's systemd service
+- `grm stop <host>` — stop a runner's systemd service
+- `grm enable <host>` — enable a runner to start on boot
+- `grm disable <host>` — disable a runner from starting on boot
+- `grm status <host>` — check runner service status
+- `grm remove <host>` — deregister and remove a runner
+- `grm list-runners` — list all runners from the local registry
+
+### Runner Registry
+
+- Runners are tracked in `~/.config/grm/runners.toml` for simplified CLI usage
+- No need to specify `--url`, `--user`, `--key` for every command — the registry remembers
+
+### Multi-Instance Support
+
+- systemd template units (`gitea-runner@.service`) for running multiple runners per host
+- Per-instance config and data directories
+
+### Ansible Role Improvements
+
+- Parameterized all hardcoded configuration values as Ansible variables
+- Idempotence fixes for repeated runs
+- Runner config converted from TOML to YAML format
+- Registration timeout to prevent indefinite hangs
+- Docker container entrypoint override and working directory fix for `.runner` persistence
+
+## [0.1.0] - 2026-06-21
+
+### Initial Release
+
+The first release of GRM, a lean CLI for managing Gitea Actions runners via SSH.
+
+### CLI Commands
+
+- `grm install <host>` — install and register a Gitea Runner on a remote host via SSH
+- `grm token` — generate a registration token via the Gitea API
+- `grm list` — list all registered runners
+- `grm update <host>` — update a runner to the latest version
+
+### Ansible Role
+
+- Installs Gitea Runner binary in binary or Docker mode
+- Registers runner with Gitea instance
+- Configures systemd service
+- Supports Arch Linux, Ubuntu, and Debian
+
 ### Features
 
-- Fix 12 critical workflow gaps in release pipeline
-
-### Bug Fixes
-
-- Release push permission and notify_failure label IDs
-
-## [Unreleased]
-
-### Added
-
-- **Automated semver versioning and releases**: `scripts/release.py` — CI script that uses git-cliff to calculate the next version from conventional commits, update version files, create a release commit, tag, and push.
-- `cliff.toml` — git-cliff configuration for conventional commit parsing, semver bumping, and changelog generation.
-- Release workflow (`.gitea/workflows/release.yml`) — triggers on push to master, runs `scripts/release.py` to automatically version and tag releases.
-- `publish.py` now uses git-cliff to generate release notes for Gitea releases (falls back to generic message if git-cliff is not available).
-- `pyproject.toml` now uses `dynamic = ["version"]` with setuptools `attr` to source version from `__init__.py` (single source of truth — release script only updates `__init__.py`).
-- **Mandatory PR review step**: `scripts/review_pr.py` — CLI to post Gitea PR reviews (COMMENT, APPROVE, REQUEST_CHANGES) with inline comments via `--comments-json` or `--comments-stdin`.
-- `GiteaClient.get_pr_files`, `GiteaClient.get_pr_commits`, `GiteaClient.create_review` — API methods for PR review workflow.
-- `VikunjaClient.get_task` — fetch a single task by numeric ID.
-- PR title format: `GRM-N: <vikunja task title>` (colon-separated, human-friendly).
-- Merge commit format: `GRM-N <conventional commit message>` (space-separated, conventional).
-- `auto_merge.py` now extracts the conventional commit message from PR commits and constructs the merge title as `GRM-N <conventional commit>`.
-- `post_merge.py` `extract_conventional_msg` now handles both legacy (`GRM-N: <msg>`) and current (`GRM-N <msg>`) merge commit formats.
-- Full PR workflow documented in `AGENTS.md` and `README.md` (Vikunja task → branch → implement → commit → PR → review → address comments → approve → merge).
-
-### Changed
-
-- Parameterized all hardcoded configuration values as Ansible variables in `defaults/main.yml`:
-  - `gitea_runner_data_dir` — Runtime data directory
-  - `gitea_runner_config_dir` — Config directory
-  - `gitea_runner_binary_path` — Binary install path
-  - `gitea_runner_prune_until` — Prune age filter
-  - `gitea_runner_prune_schedule` — Prune timer schedule
-  - `gitea_runner_prune_label` — Docker label for pruning
-  - `gitea_runner_service_restart_sec` — systemd restart interval
-  - `gitea_runner_service_user` — Service user
-  - `gitea_runner_log_level` — Runner log level
-  - `gitea_runner_container_label` — Container label
-  - `gitea_runner_file` — Runner metadata file
-  - `docker_gpg_key_path` — Docker GPG key path
-- Added `console_scripts` entry point in `pyproject.toml` (`grm = "gitea_runner_manager.cli:cli"`).
-- Added shared `molecule/common/prepare.yml` to eliminate duplicated prepare playbooks.
-- Extracted repeated systemd availability check into `tasks/systemd_check.yml`.
-- Added idempotence checks to all Molecule scenarios.
-- Comprehensive README overhaul with Architecture, Configuration, Development, Testing, and Troubleshooting sections.
-- API URLs and repo configuration in `config.py` are now overridable via environment variables (`GRM_GITEA_API_URL`, `GRM_VIKUNJA_API_URL`, `GRM_REPO_OWNER`, `GRM_REPO_NAME`, `GRM_VIKUNJA_PROJECT_ID`).
-- `remove-runner.yml` now disables lingering and removes subuid/subgid entries for complete cleanup.
-
-### Security
-
-- **Critical fix**: Registration tokens and admin tokens are no longer passed via `--extra-vars` on the command line (CWE-214). Extra-vars are now written to a temporary JSON file with `0600` permissions and passed via `--extra-vars @tempfile`, which is deleted after execution. This prevents secrets from being visible in the process list (`ps aux`).
-
-### Changed
-
-- Replaced legacy runner terminology with `gitea_runner` / `gitea-runner` / `Gitea Runner`.
-- Updated default Docker image from `gitea/gitea_runner` to `gitea/runner`.
-- `Makefile` now uses the installed `grm` console script instead of `python grm`.
-- `pyproject.toml` ruff and pyright target versions updated from `py311` to `py312` to match `requires-python = ">=3.12"`.
-- `BRANCH_PROTECTION_CONFIG` updated with correct Gitea Actions status check contexts (including `(pull_request)` suffix) and `required_approvals: 0` for auto-merge.
-- `CONVENTIONAL_RE` no longer matches `BREAKING CHANGE` as a commit type (it is a footer, not a type).
-- `rootless_docker.yml` apt cache update now only runs when the Docker repo file changes (idempotent, but always refreshes on first add).
-- `service.yml` and `prune.yml` template creation tasks are not guarded by `docker_rootless_setup` (templates just create files, they don't need Docker; molecule tests set `docker_rootless_setup: false` but still verify the service file exists).
-- `molecule_all.sh` now sources the platform list from `distribute_molecule.py` to avoid duplication.
-
-### Removed
-
-- Deleted `setup.py` (redundant with `pyproject.toml`).
-- Deleted `grm` shell entrypoint script (replaced by `console_scripts`).
-- Deleted `initial-plan.md` and `tests/integration/test_provision.py` (dead code).
-- Removed empty `__init__.py` files from `tests/` directories.
-- Removed unused `runner_validated` fact from `validate.yml`.
-- Removed duplicate `prune.yml` and `integration_test.yml` includes from `install_runner.yml` (already included from `main.yml`).
-- Removed dead `tasks/config.yml` (never included by any playbook).
-- Removed dead `templates/gitea-runner.service.j2` (legacy system-level service, replaced by rootless `gitea-runner-user.service.j2`).
-- Removed dead "Reload systemd" handler (system-level reload, never notified, wrong scope for user services).
-- Removed dead `scripts/run_molecule_parallel.py` and its test (replaced by `molecule_ci_guard.py`).
-
-### Fixed
-
-- Molecule idempotence failures caused by non-idempotent service restart.
-- Missing `/etc/docker` directory handling in Molecule tests.
-- `ansible-lint` formatting warnings (yaml empty lines).
-- Verify playbooks now explicitly load role defaults so parameterized variables are available during verification.
-- Duplicate execution of prune and integration test tasks during installation (were included from both `main.yml` and `install_runner.yml`).
-- apt cache update reporting `changed` on every run due to `cache_valid_time: 0`.
+- SSH-based remote execution via Ansible
+- Automatic registration token generation
+- Docker and binary installation modes
+- Integration test verification after installation

Makefile

@@ -78,7 +78,7 @@ typecheck:
 lint: lint-ruff lint-format typecheck lint-bandit
 
 lint-bandit:
-	$(BIN)/bandit -r src/ scripts/
+	$(BIN)/bandit -r src/ scripts/ scripts/ci/
 
 ansible-lint:
 	$(BIN)/ansible-lint ansible/
@@ -95,7 +95,7 @@ test-integration:
 	$(BIN)/pytest tests/integration/ -v --no-cov
 
 pytest-cov:
-	$(BIN)/pytest tests/unit/ -v --cov=src/gitea_runner_manager --cov=scripts --cov-report=term-missing --cov-fail-under=100
+	$(BIN)/pytest tests/unit/ -v --cov=src/gitea_runner_manager --cov=scripts --cov=scripts/ci --cov-report=term-missing --cov-fail-under=100
 
 MOLECULE := $(realpath $(BIN))/molecule
 MOLECULE_BASE := cd $(CURDIR)/ansible/roles/gitea-runner && ANSIBLE_ALLOW_BROKEN_CONDITIONALS=true ANSIBLE_INJECT_INVOCATION=1 $(MOLECULE)

cliff.toml

@@ -46,19 +46,20 @@ commit_preprocessors = [
 commit_parsers = [
     { message = "^feat", group = "<!-- 0 -->Features" },
     { message = "^fix", group = "<!-- 1 -->Bug Fixes" },
-    { message = "^doc", group = "<!-- 3 -->Documentation" },
     { message = "^perf", group = "<!-- 4 -->Performance" },
     { message = "^refactor", group = "<!-- 2 -->Refactor" },
-    { message = "^style", group = "<!-- 5 -->Styling" },
-    { message = "^test", group = "<!-- 6 -->Testing" },
-    { message = "^chore\\(release\\): prepare for", skip = true },
-    { message = "^chore\\(deps.*\\)", skip = true },
-    { message = "^chore\\(pr\\)", skip = true },
-    { message = "^chore\\(pull\\)", skip = true },
-    { message = "^chore|^ci", group = "<!-- 7 -->Miscellaneous Tasks" },
+    # Skip infrastructure-only commits — they don't affect users
+    { message = "^doc", skip = true },
+    { message = "^test", skip = true },
+    { message = "^style", skip = true },
+    { message = "^chore", skip = true },
+    { message = "^ci", skip = true },
+    # Skip release commits — they are release artifacts, not features
+    { message = "^release:", skip = true },
     { body = ".*security", group = "<!-- 8 -->Security" },
     { message = "^revert", group = "<!-- 9 -->Revert" },
-    { message = ".*", group = "<!-- 10 -->Other" },
+    # Skip anything that doesn't match above — safe default
+    { message = ".*", skip = true },
 ]
 
 [bump]

docs/index.md

@@ -6,20 +6,20 @@ A lean command-line tool to automate the installation, configuration, and lifecy
 
 ## User Documentation
 
-- [Getting Started](Getting-Started) — Installation, quick start, first run
+- [Getting Started](Getting-Started.-) — Installation, quick start, first run
 - [Installation](Installation) — Prerequisites, setup, multiple instances
-- [CLI Commands](CLI-Commands) — All commands with arguments and options
+- [CLI Commands](CLI-Commands.-) — All commands with arguments and options
 - [Troubleshooting](Troubleshooting) — Common issues and solutions
 - [FAQ](FAQ) — Frequently asked questions
 
 ## Technical Documentation
 
 - [Architecture](Architecture) — High-level design, component interactions, data flow
-- [Development Setup](Development-Setup) — Environment setup, dependencies, local testing
-- [CI/CD Workflow](CI-CD-Workflow) — How CI works, release process, branch protection
-- [Testing Strategy](Testing-Strategy) — Unit, integration, and Molecule tests
-- [Decision Log](Decision-Log) — Key technical decisions and rationale
-- [Contributing Guide](Contributing-Guide) — Coding standards, PR workflow, commit rules
+- [Development Setup](Development-Setup.-) — Environment setup, dependencies, local testing
+- [CI/CD Workflow](CI-CD-Workflow.-) — How CI works, release process, branch protection
+- [Testing Strategy](Testing-Strategy.-) — Unit, integration, and Molecule tests
+- [Decision Log](Decision-Log.-) — Key technical decisions and rationale
+- [Contributing Guide](Contributing-Guide.-) — Coding standards, PR workflow, commit rules
 
 ## Quick Links
 

docs/tech/ci-cd-workflow.md

@@ -60,10 +60,10 @@ Review the full diff (`git diff master...HEAD`) focusing on:
 - **User experience**: Clear error messages, intuitive CLI flags, helpful output
 - **Documentation**: Completeness and relevance of docs, CHANGELOG entries, AGENTS.md updates
 
-Post review comments using `scripts/review_pr.py`:
+Post review comments using `scripts/ci/review_pr.py`:
 
 ```bash
-REPO_TOKEN=<token> python3 scripts/review_pr.py <pr_number> <owner/repo> \
+REPO_TOKEN=<token> python3 scripts/ci/review_pr.py <pr_number> <owner/repo> \
   --event REQUEST_CHANGES \
   --body "Review summary" \
   --comments-json comments.json
@@ -78,7 +78,7 @@ Fix each comment one by one, commit, and push. Re-review until satisfied.
 Once all comments are addressed:
 
 ```bash
-REPO_TOKEN=<token> python3 scripts/review_pr.py <pr_number> <owner/repo> \
+REPO_TOKEN=<token> python3 scripts/ci/review_pr.py <pr_number> <owner/repo> \
   --event APPROVE \
   --body "All comments addressed. LGTM."
 ```
@@ -96,7 +96,7 @@ Then add the `ready-to-merge` label. The auto-merge workflow will:
 
 After the squash-merge:
 
-- The **post-merge workflow** (`.gitea/workflows/post-merge.yml`) triggers on push to `master` and runs `scripts/post_merge.py` to mark the Vikunja task as done, extracting the task ID from the merge commit message.
+- The **post-merge workflow** (`.gitea/workflows/post-merge.yml`) triggers on push to `master` and runs `scripts/ci/post_merge.py` to mark the Vikunja task as done, extracting the task ID from the merge commit message.
 - The **release workflow** (`.gitea/workflows/release.yml`) triggers on push to `master` and automatically versions, tags, and publishes (see below).
 
 ## Branch Protection (Required Gitea Settings)
@@ -132,7 +132,7 @@ The `quality` job in `.gitea/workflows/ci.yml` runs:
 2. `make lint-all` — ruff + pyright + bandit + ansible-lint + checkmake
 3. `make pytest-cov` — unit tests with 100% coverage enforcement
 4. `python3 scripts/check_test_speed.py --max-seconds 10` — verify unit tests run fast
-5. `PYTHONPATH=src python3 scripts/release.py --dry-run` — release dry-run validation
+5. `PYTHONPATH=src python3 scripts/ci/release.py --dry-run` — release dry-run validation
 
 ## Automated Release Pipeline
 
@@ -144,7 +144,7 @@ After a PR is merged to master, the release pipeline runs automatically.
 - Sets up full dev environment (`make setup`) so lint and tests can run
 - Installs git-cliff (version 2.13.0)
 - Configures git as `grm-ci-bot`
-- Runs `scripts/release.py` which uses **git-cliff** to:
+- Runs `scripts/ci/release.py` which uses **git-cliff** to:
   - Calculate the next semver version from conventional commits since the last tag
   - Update `__version__` in `src/gitea_runner_manager/__init__.py` (single source of truth)
   - Update `CHANGELOG.md` with the new version section
@@ -155,7 +155,7 @@ After a PR is merged to master, the release pipeline runs automatically.
   - Push both the commit and tag to master
 - `--skip-tests` flag bypasses test verification (emergency use only, not recommended)
 - Loops are prevented by `has_unreleased_changes` — after a release commit is tagged, the next run finds no unreleased changes and exits
-- On failure, creates a Gitea issue via `scripts/notify_failure.py`
+- On failure, creates a Gitea issue via `scripts/ci/notify_failure.py`
 
 ### Publish Workflow (`.gitea/workflows/publish.yml`)
 
@@ -166,21 +166,61 @@ After a PR is merged to master, the release pipeline runs automatically.
 - Builds the Python package
 - Optionally publishes to PyPI (if `PYPI_TOKEN` is set)
 - Creates a Gitea release with git-cliff-generated release notes
-- Uses `scripts/publish.py` for build and publish orchestration
-- On failure, creates a Gitea issue via `scripts/notify_failure.py`
+- Uses `scripts/ci/publish.py` for build and publish orchestration
+- On failure, creates a Gitea issue via `scripts/ci/notify_failure.py`
 
 ### Auto-Merge Workflow (`.gitea/workflows/auto-merge.yml`)
 
 - Triggers on `pull_request` labeled events
-- Runs `scripts/auto_merge.py` with the branch name, PR title, repository, PR number, and label name
+- Runs `scripts/ci/auto_merge.py` with the branch name, PR title, repository, PR number, and label name
 - Validates PR title format, checks for APPROVE review, waits for CI, and squash-merges
 
 ### Post-Merge Workflow (`.gitea/workflows/post-merge.yml`)
 
 - Triggers on push to `master`
-- Runs `scripts/post_merge.py` with the latest commit message and commit SHA
+- Runs `scripts/ci/post_merge.py` with the latest commit message and commit SHA
 - Marks the corresponding Vikunja task as done
 
+### Smart CI: User-Facing vs Workflow-Only Changes
+
+Not all changes require the full CI pipeline or a new release. The project uses
+`scripts/ci/classify_changes.py` to classify changed files into two categories:
+
+**User-facing paths** (tool changes → release needed):
+- `src/gitea_runner_manager/**` — Python CLI source
+- `ansible/**` — Ansible role
+- `pyproject.toml` — Package metadata
+
+**Workflow-only paths** (infrastructure → no release needed):
+- `.gitea/workflows/**`, `scripts/**`, `docs/**`, `tests/**`
+- `AGENTS.md`, `README.md`, `CHANGELOG.md`, `Makefile`, `cliff.toml`, etc.
+
+**CI behavior based on classification:**
+- **Molecule tests**: Only run when `ansible/` or `.ansible-lint` files change
+- **Release dry-run**: Only runs when user-facing files change (separate `release-dry-run` job)
+- **Quality job** (lint, unit tests, coverage, doc-coverage): Always runs
+- **Release workflow**: `release.py` calls `classify_changes.py` to check if any
+  user-facing files changed since the last tag. If not, the release is skipped
+  entirely — no version bump, no tag, no publish.
+
+### Dynamic Runner Discovery
+
+Molecule tests are distributed across available Gitea Actions runners
+dynamically. The `discover-runners` job runs `scripts/ci/discover_runners.py` which queries the Gitea API for
+registered runners at three levels (repo, org, instance) and generates
+a matrix of runner indices. If the API query fails (e.g., no admin
+access for instance-level runners), it falls back to the
+`MOLECULE_RUNNERS` repo variable, then to a default of 3.
+
+The `molecule-tests` job uses `fromJSON()` to consume the dynamic
+matrix, and passes the runner count to `distribute_molecule.py
+--max-runners` so test pairs are evenly distributed.
+
+When adding or removing Gitea runners:
+1. If runners are registered at the repo/org level, they're auto-detected
+2. If runners are at the instance level, update the `MOLECULE_RUNNERS` repo variable
+3. The workflow automatically scales the matrix to match available runners
+
 ## git-cliff Commit Preprocessing
 
 Merge commits on master have the format `GRM-N <conventional commit>`. The `GRM-N ` prefix is not a valid conventional commit prefix, so `cliff.toml` includes a `commit_preprocessors` entry that strips it before parsing:

scripts/ci/classify_changes.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Classify git changes as user-facing or workflow-only.
+
+Determines whether changes between two git refs (e.g., last tag and HEAD)
+affect the GRM tool itself (user-facing) or only the CI/CD infrastructure
+(workflow-only).  This is used by:
+
+- **release.py** — skips release when only workflow files changed
+- **CI workflow** — skips molecule tests and release dry-run when only
+  workflow files changed
+
+Classification strategy (safe-by-default):
+
+  Any file that is NOT in the explicit workflow-only allowlist is treated
+  as user-facing.  This ensures new file types default to requiring a
+  release rather than silently skipping it.
+
+  Workflow-only paths (infrastructure → no release needed):
+    - .gitea/workflows/**          — Gitea Actions workflows
+    - scripts/**                   — All scripts (CI/CD, dev tools, setup)
+    - src/gitea_runner_manager/__init__.py — Version file (release artifact)
+    - docs/**                      — Documentation
+    - tests/**                     — Test files
+    - hooks/**                     — Git hooks
+    - AGENTS.md                    — Agent conventions
+    - README.md                    — README (lean, links to wiki)
+    - CHANGELOG.md                 — Changelog (generated)
+    - TROUBLESHOOTING.md           — Troubleshooting guide
+    - cliff.toml                   — git-cliff config
+    - Makefile                     — Build automation
+    - .pre-commit-config.yaml      — Pre-commit config
+    - .ansible-lint                — Ansible lint config
+    - .env.example                 — Environment template
+    - .gitignore                   — Git ignore rules
+    - .ruff.toml                   — Ruff config (if separate)
+    - .github/**                   — GitHub config (if present)
+
+  Everything else is user-facing (tool changes → release needed),
+  including but not limited to:
+    - src/gitea_runner_manager/*.py — Python CLI source (except __init__.py)
+    - ansible/**                   — Ansible role
+    - pyproject.toml               — Package metadata
+    - Any new file type not in the allowlist
+
+Usage:
+  python3 scripts/ci/classify_changes.py [--base <ref>] [--head <ref>]
+  python3 scripts/ci/classify_changes.py --base v0.3.0 --head HEAD
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+import sys
+
+import click
+
+from gitea_runner_manager.i18n import _
+
+# Explicit allowlist of workflow-only path patterns.
+# Anything NOT matching these is treated as user-facing (safe default).
+WORKFLOW_ONLY_PATTERNS = frozenset(
+    [
+        # CI/CD infrastructure
+        ".gitea/",
+        # All scripts are infrastructure (CI/CD, dev tools, setup)
+        # User-facing code lives in src/gitea_runner_manager/
+        "scripts/",
+        # Version file — only contains __version__, not user-facing code.
+        # Version bumps are a release artifact, not a feature.
+        "src/gitea_runner_manager/__init__.py",
+        # Documentation
+        "docs/",
+        "AGENTS.md",
+        "README.md",
+        "CHANGELOG.md",
+        "TROUBLESHOOTING.md",
+        # Tests
+        "tests/",
+        # Config / build automation
+        "cliff.toml",
+        "Makefile",
+        ".pre-commit-config.yaml",
+        ".ansible-lint",
+        ".env.example",
+        ".gitignore",
+        ".ruff.toml",
+        # Hooks
+        "hooks/",
+        # GitHub (if ever added)
+        ".github/",
+    ]
+)
+
+
+def run_git(args: list[str]) -> str:
+    """Run a git command and return stdout."""
+    result = subprocess.run(  # nosec B603
+        args,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise click.ClickException(
+            _("git command failed ({cmd}): {stderr}", cmd=" ".join(args), stderr=result.stderr.strip())
+        )
+    return result.stdout.strip()
+
+
+def get_changed_files(base: str, head: str) -> list[str]:
+    """Get list of files changed between base and head refs."""
+    output = run_git(["git", "diff", "--name-only", base, head])
+    if not output:
+        return []
+    return output.split("\n")
+
+
+def is_workflow_only(file_path: str) -> bool:
+    """Check if a file path is workflow-only (infrastructure, not the tool itself).
+
+    Uses an explicit allowlist — anything not in the list is treated as
+    user-facing (safe default that prevents accidental release skips).
+    """
+    return any(file_path.startswith(pattern) or file_path == pattern for pattern in WORKFLOW_ONLY_PATTERNS)
+
+
+def is_user_facing(file_path: str) -> bool:
+    """Check if a file path is user-facing (affects the GRM tool).
+
+    Inverse of is_workflow_only — anything not explicitly workflow-only
+    is treated as user-facing.
+    """
+    return not is_workflow_only(file_path)
+
+
+def classify_changes(files: list[str]) -> dict[str, list[str]]:
+    """Classify changed files into user-facing and workflow-only.
+
+    Returns a dict with keys "user_facing" and "workflow_only".
+    """
+    user_facing: list[str] = []
+    workflow_only: list[str] = []
+    for f in files:
+        if is_user_facing(f):
+            user_facing.append(f)
+        else:
+            workflow_only.append(f)
+    return {"user_facing": user_facing, "workflow_only": workflow_only}
+
+
+def has_user_facing_changes(base: str, head: str) -> bool:
+    """Check if any user-facing files changed between base and head."""
+    files = get_changed_files(base, head)
+    return any(is_user_facing(f) for f in files)
+
+
+def get_latest_tag() -> str:
+    """Get the latest git tag, or empty string if none exists."""
+    result = subprocess.run(  # nosec B603 B607
+        ["git", "describe", "--tags", "--abbrev=0"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return ""
+    return result.stdout.strip()
+
+
+@click.command()
+@click.option("--base", default=None, help="Base ref (default: latest tag).")
+@click.option("--head", default="HEAD", help="Head ref (default: HEAD).")
+@click.option("--quiet", is_flag=True, default=False, help="Only output true/false.")
+def main(base: str | None, head: str, quiet: bool) -> None:
+    if base is None:
+        base = get_latest_tag()
+        if not base:
+            if quiet:
+                click.echo("true")
+            else:
+                click.echo(_("No tags found — treating all changes as user-facing."))
+            return
+
+    files = get_changed_files(base, head)
+    if not files:
+        if quiet:
+            click.echo("false")
+        else:
+            click.echo(_("No changes between {base} and {head}.", base=base, head=head))
+        return
+
+    result = classify_changes(files)
+    has_user = bool(result["user_facing"])
+
+    if quiet:
+        click.echo("true" if has_user else "false")
+        return
+
+    click.echo(_("Comparing {base}..{head} ({count} files changed)", base=base, head=head, count=len(files)))
+    click.echo(_("\nUser-facing changes ({count}):", count=len(result["user_facing"])))
+    for f in result["user_facing"]:
+        click.echo(f"  {f}")
+    click.echo(_("\nWorkflow-only changes ({count}):", count=len(result["workflow_only"])))
+    for f in result["workflow_only"]:
+        click.echo(f"  {f}")
+    if has_user:
+        status = "USER-FACING changes detected — release needed"
+    else:
+        status = "Workflow-only changes — no release needed"
+    click.echo(_("\nResult: {status}", status=status))
+
+    if not has_user:
+        sys.exit(2)  # Exit code 2 = workflow-only (used by CI to skip release)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

scripts/ci/discover_runners.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Discover available Gitea Actions runners for dynamic job distribution.
+
+Queries the Gitea API for registered runners at three levels:
+  1. Repository level: GET /repos/{owner}/{repo}/actions/runners
+  2. Organization level: GET /orgs/{org}/actions/runners
+  3. Instance (admin) level: GET /admin/actions/runners
+
+Falls back to the ``MOLECULE_RUNNERS`` repo variable or environment
+variable, then to ``DEFAULT_MAX_RUNNERS`` (3).
+
+Outputs:
+  - ``--count``: prints the number of available runners
+  - ``--indices``: prints a JSON array [0, 1, ..., N-1] for use as a
+    dynamic matrix in Gitea Actions
+  - (default): prints both as ``count=N`` and ``indices=[0,1,...]``
+
+Usage:
+  python3 scripts/ci/discover_runners.py --owner oblachno-oss --repo grm
+  python3 scripts/ci/discover_runners.py --indices
+  python3 scripts/ci/discover_runners.py --count
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+import click
+import requests
+
+from gitea_runner_manager.config import GITEA_API_URL
+
+DEFAULT_MAX_RUNNERS = 3
+
+
+def query_runners(api_url: str, token: str, owner: str, repo: str) -> int:
+    """Query the Gitea API for registered runners at all levels.
+
+    Returns the total count of active runners.  If the API call fails
+    (e.g., no admin access for instance-level runners), falls back to
+    what we can see.
+    """
+    headers = {"Authorization": f"token {token}"}
+    total = 0
+
+    # 1. Repository-level runners
+    try:
+        r = requests.get(
+            f"{api_url}/repos/{owner}/{repo}/actions/runners",
+            headers=headers,
+            timeout=10,
+        )
+        if r.status_code == 200:
+            data = r.json()
+            total += data.get("total_count", 0)
+    except (requests.RequestException, ValueError):
+        pass
+
+    # 2. Organization-level runners
+    try:
+        r = requests.get(
+            f"{api_url}/orgs/{owner}/actions/runners",
+            headers=headers,
+            timeout=10,
+        )
+        if r.status_code == 200:
+            data = r.json()
+            total += data.get("total_count", 0)
+    except (requests.RequestException, ValueError):
+        pass
+
+    # 3. Instance-level runners (requires admin scope)
+    try:
+        r = requests.get(
+            f"{api_url}/admin/actions/runners",
+            headers=headers,
+            timeout=10,
+        )
+        if r.status_code == 200:
+            data = r.json()
+            total += data.get("total_count", 0)
+    except (requests.RequestException, ValueError):
+        pass
+
+    return total
+
+
+def get_runner_count(api_url: str, token: str, owner: str, repo: str) -> int:
+    """Determine the number of available runners.
+
+    Tries the Gitea API first, then falls back to env vars, then default.
+    """
+    # Try API query if we have a token
+    if token:
+        api_count = query_runners(api_url, token, owner, repo)
+        if api_count > 0:
+            return api_count
+
+    # Fall back to MOLECULE_RUNNERS env var (set by CI from repo variable)
+    env_count = os.environ.get("MOLECULE_RUNNERS")
+    if env_count:
+        try:
+            count = int(env_count)
+            if count > 0:
+                return count
+        except ValueError:
+            pass
+
+    # Fall back to default
+    return DEFAULT_MAX_RUNNERS
+
+
+def generate_indices(count: int) -> list[int]:
+    """Generate a list of runner indices [0, 1, ..., count-1]."""
+    return list(range(count))
+
+
+@click.command()
+@click.option("--owner", default=None, help="Repository owner (for API query).")
+@click.option("--repo", default=None, help="Repository name (for API query).")
+@click.option("--count", "output_count", is_flag=True, help="Output only the count.")
+@click.option("--indices", "output_indices", is_flag=True, help="Output only the JSON indices array.")
+def main(owner: str | None, repo: str | None, output_count: bool, output_indices: bool) -> None:
+    token = os.environ.get("REPO_TOKEN", "")
+
+    if owner is None:
+        owner = os.environ.get("GRM_REPO_OWNER", "oblachno-oss")
+    if repo is None:
+        repo = os.environ.get("GRM_REPO_NAME", "grm")
+
+    count = get_runner_count(GITEA_API_URL, token, owner, repo)
+    indices = generate_indices(count)
+
+    if output_count:
+        click.echo(str(count))
+        return
+
+    if output_indices:
+        click.echo(json.dumps(indices))
+        return
+
+    # Default: output both as key=value pairs for CI consumption
+    click.echo(f"count={count}")
+    click.echo(f"indices={json.dumps(indices)}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

scripts/ci/doc_coverage.py

@@ -6,7 +6,7 @@ has corresponding documentation in the wiki/docs.  Reports missing
 documentation as warnings and exits with non-zero if coverage is below 100%.
 
 Usage:
-  python3 scripts/doc_coverage.py [--docs-dir docs/] [--fail-on-missing]
+  python3 scripts/ci/doc_coverage.py [--docs-dir docs/] [--fail-on-missing]
 """
 
 from __future__ import annotations
@@ -19,8 +19,9 @@ import click
 
 from gitea_runner_manager.i18n import _
 
-DOCS_DIR = Path(__file__).resolve().parent.parent / "docs"
-CLI_FILE = Path(__file__).resolve().parent.parent / "src" / "gitea_runner_manager" / "cli.py"
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+DOCS_DIR = REPO_ROOT / "docs"
+CLI_FILE = REPO_ROOT / "src" / "gitea_runner_manager" / "cli.py"
 
 # Major modules that should be documented in tech/architecture.md
 REQUIRED_MODULES = [
@@ -42,6 +43,8 @@ REQUIRED_SCRIPTS = [
     "review_pr.py",
     "notify_failure.py",
     "post_merge.py",
+    "classify_changes.py",
+    "discover_runners.py",
 ]
 
 

scripts/ci/post_merge.py

@@ -78,8 +78,19 @@ def main(commit_msg: str, commit_sha: str) -> None:
 
     task_id = extract_task_id(commit_msg)
     if not task_id:
-        click.echo(_("No task ID in commit message, skipping Vikunja update. All good — nothing to do here!"))
-        return
+        # Allow release commits without GRM-N prefix
+        first_line = commit_msg.split("\n")[0]
+        if re.match(r"^release: v\d+\.\d+\.\d+", first_line):
+            click.echo(_("Release commit without task ID, skipping Vikunja update."))
+            return
+        # Non-release commits must have GRM-N prefix — fail loudly
+        raise click.ClickException(
+            _(
+                "No task ID (GRM-N) found in commit message: {msg}\n"
+                "All non-release commits on master must follow format: GRM-N <type>: <description>",
+                msg=first_line,
+            )
+        )
 
     client = VikunjaClient(VIKUNJA_API_URL, token)
     vikunja_task_id = 0

scripts/ci/release.py

@@ -36,6 +36,7 @@ import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
 
 from gitea_runner_manager.i18n import _
+from scripts.ci.classify_changes import has_user_facing_changes
 
 load_dotenv(override=True)
 
@@ -256,6 +257,18 @@ def main(dry_run: bool, skip_tests: bool) -> None:
     if branch != "master":
         raise click.ClickException(_("Release must be run on master, currently on '{branch}'.", branch=branch))
 
+    # Check if any user-facing files changed since the last tag.
+    # If only workflow/infra files changed, skip the release entirely.
+    latest_tag = get_latest_tag()
+    if latest_tag and not has_user_facing_changes(latest_tag, "HEAD"):
+        click.echo(
+            _(
+                "No user-facing changes since {tag} — only workflow/infrastructure files changed. Skipping release.",
+                tag=latest_tag,
+            )
+        )
+        return
+
     # Calculate next version (single git-cliff call — Gap 7 fix)
     new_version = get_bumped_version()
 

scripts/ci/sync_wiki.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""Sync documentation from /docs/ to the Gitea wiki via API.
+
+Reads markdown files from the ``docs/`` directory, uses ``mapping.json`` to
+map file paths to wiki page titles, and creates/updates wiki pages via the
+Gitea API.  Pages that exist in the wiki but not in the mapping are left
+untouched (not deleted).
+
+Gitea 1.26 wiki API endpoints (all use content_base64, NOT content):
+  - Create: POST /repos/{owner}/{repo}/wiki/new  {title, content_base64, message}
+  - Update: PATCH /repos/{owner}/{repo}/wiki/page/{sub_url}  {title, content_base64, message}
+  - List:   GET /repos/{owner}/{repo}/wiki/pages  → [{title, sub_url, ...}]
+  - Fetch:  GET /repos/{owner}/{repo}/wiki/page/{sub_url}  → {title, content_base64, ...}
+  - Delete: DELETE /repos/{owner}/{repo}/wiki/page/{sub_url}
+
+Usage:
+  REPO_TOKEN=<token> python3 scripts/ci/sync_wiki.py [--dry-run] [--repo owner/repo]
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
+
+from gitea_runner_manager.api_clients import GiteaClient
+from gitea_runner_manager.config import GITEA_API_URL
+from gitea_runner_manager.exceptions import APIError
+from gitea_runner_manager.i18n import _
+
+load_dotenv(override=True)
+
+DOCS_DIR = Path(__file__).resolve().parent.parent.parent / "docs"
+MAPPING_FILE = DOCS_DIR / "mapping.json"
+
+
+def load_mapping() -> dict[str, str]:
+    """Load the file-to-wiki-page mapping from mapping.json."""
+    with open(MAPPING_FILE) as f:
+        return json.load(f)
+
+
+def read_doc_content(file_path: str) -> str:
+    """Read markdown content from a docs file."""
+    full_path = DOCS_DIR / file_path
+    with open(full_path) as f:
+        return f.read()
+
+
+def encode_content(content: str) -> str:
+    """Encode content as base64 for the Gitea wiki API.
+
+    The Gitea wiki API requires content_base64, not plain content.
+    Sending plain content silently fails (pages are created/updated
+    but with empty content).
+    """
+    return base64.b64encode(content.encode("utf-8")).decode("ascii")
+
+
+def decode_content(content_b64: str) -> str:
+    """Decode base64 content from the Gitea wiki API."""
+    if not content_b64:
+        return ""
+    return base64.b64decode(content_b64).decode("utf-8")
+
+
+def list_wiki_pages(client: GiteaClient) -> dict[str, str]:
+    """List existing wiki pages, returning {title: sub_url}."""
+    try:
+        pages = client._request("GET", "/wiki/pages").json()
+    except APIError:
+        return {}
+    return {page.get("title", ""): page.get("sub_url", page.get("title", "")) for page in pages}
+
+
+def fetch_page_content(client: GiteaClient, sub_url: str) -> str:
+    """Fetch a wiki page's content by sub_url, decoded from base64."""
+    try:
+        page = client._request("GET", f"/wiki/page/{sub_url}").json()
+        return decode_content(page.get("content_base64", ""))
+    except APIError:
+        return ""
+
+
+def sync_page(
+    client: GiteaClient,
+    page_title: str,
+    content: str,
+    existing_pages: dict[str, str],
+    dry_run: bool,
+) -> str:
+    """Create or update a single wiki page.
+
+    Returns "created", "updated", or "skipped" (if dry-run).
+    """
+    if dry_run:
+        click.echo(_("[dry-run] Would sync page: {title} ({chars} chars)", title=page_title, chars=len(content)))
+        return "skipped"
+
+    content_b64 = encode_content(content)
+
+    if page_title in existing_pages:
+        # Update existing page via PATCH
+        sub_url = existing_pages[page_title]
+        client._request(
+            "PATCH",
+            f"/wiki/page/{sub_url}",
+            json={
+                "title": page_title,
+                "content_base64": content_b64,
+                "message": f"Sync from docs/ — update {page_title}",
+            },
+        )
+        return "updated"
+
+    # Create new page via POST /wiki/new
+    client._request(
+        "POST",
+        "/wiki/new",
+        json={
+            "title": page_title,
+            "content_base64": content_b64,
+            "message": f"Sync from docs/ — create {page_title}",
+        },
+    )
+    return "created"
+
+
+def verify_wiki_page(
+    client: GiteaClient, page_title: str, expected_content: str, existing_pages: dict[str, str]
+) -> bool:
+    """Verify that a wiki page has non-empty content matching the docs.
+
+    Returns True if the page content matches, False otherwise.
+    """
+    if page_title not in existing_pages:
+        return False
+    sub_url = existing_pages[page_title]
+    actual = fetch_page_content(client, sub_url)
+    return actual.strip() == expected_content.strip()
+
+
+def verify_wiki_integrity(
+    client: GiteaClient,
+    mapping: dict[str, str],
+    synced: dict[str, str],
+) -> list[str]:
+    """Comprehensive wiki verification.
+
+    Checks:
+    1. Every mapped page exists in the wiki
+    2. Every mapped page has non-empty content
+    3. Every mapped page's content matches the docs
+    4. No stale pages exist in the wiki (pages not in mapping)
+    5. Page count matches
+
+    Returns a list of failure messages (empty if all checks pass).
+    """
+    failures: list[str] = []
+    existing_pages = list_wiki_pages(client)
+    expected_titles = set(mapping.values())
+
+    # Check 1: Page count
+    if len(existing_pages) != len(expected_titles):
+        failures.append(f"Page count mismatch: wiki has {len(existing_pages)}, mapping has {len(expected_titles)}")
+
+    # Check 2: Missing pages (in mapping but not in wiki)
+    missing = expected_titles - set(existing_pages.keys())
+    for title in sorted(missing):
+        failures.append(f"Missing page: {title}")
+
+    # Check 3: Stale pages (in wiki but not in mapping)
+    stale = set(existing_pages.keys()) - expected_titles
+    for title in sorted(stale):
+        failures.append(f"Stale page (not in mapping): {title}")
+
+    # Check 4: Content verification
+    for page_title, expected_content in sorted(synced.items()):
+        ok = verify_wiki_page(client, page_title, expected_content, existing_pages)
+        if not ok:
+            sub_url = existing_pages.get(page_title, "?")
+            actual = fetch_page_content(client, sub_url)
+            if not actual.strip():
+                failures.append(f"Empty content: {page_title}")
+            else:
+                failures.append(f"Content mismatch: {page_title}")
+
+    return failures
+
+
+@click.command()
+@click.option("--dry-run", is_flag=True, default=False, help="Show what would happen without making changes.")
+@click.option("--repo", default=None, help="Repository in owner/name format (auto-detected if omitted).")
+@click.option(
+    "--verify",
+    is_flag=True,
+    default=False,
+    help="After syncing, verify each page has non-empty content. Exit 1 if any page is empty or mismatched.",
+)
+@click.option(
+    "--strict",
+    is_flag=True,
+    default=False,
+    help="Full integrity check: verify page count, missing pages, stale pages, and content. Implies --verify.",
+)
+def main(dry_run: bool, repo: str | None, verify: bool, strict: bool) -> None:
+    token = os.environ.get("REPO_TOKEN", "")
+    if not token:
+        raise click.ClickException(_("ERROR: REPO_TOKEN is not set."))
+
+    if repo is None:
+        owner = os.environ.get("GRM_REPO_OWNER", "oblachno-oss")
+        repo_name = os.environ.get("GRM_REPO_NAME", "grm")
+    else:
+        owner, repo_name = repo.split("/")
+
+    if not MAPPING_FILE.exists():
+        raise click.ClickException(_("ERROR: mapping.json not found at {path}", path=MAPPING_FILE))
+
+    mapping = load_mapping()
+    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
+
+    click.echo(_("Syncing {count} documentation pages to wiki...", count=len(mapping)))
+
+    existing_pages = list_wiki_pages(client)
+    if existing_pages:
+        click.echo(_("Found {count} existing wiki pages.", count=len(existing_pages)))
+
+    created = 0
+    updated = 0
+    skipped = 0
+    synced: dict[str, str] = {}  # title -> content, for verification
+
+    for file_path, page_title in sorted(mapping.items()):
+        try:
+            content = read_doc_content(file_path)
+        except FileNotFoundError:
+            click.echo(_("WARNING: File {file} not found — skipping.", file=file_path))
+            skipped += 1
+            continue
+
+        if not content.strip():
+            click.echo(_("WARNING: File {file} is empty — skipping.", file=file_path))
+            skipped += 1
+            continue
+
+        result = sync_page(client, page_title, content, existing_pages, dry_run)
+        if result == "created":
+            created += 1
+            click.echo(_("  Created: {title}", title=page_title))
+        elif result == "updated":
+            updated += 1
+            click.echo(_("  Updated: {title}", title=page_title))
+        else:
+            skipped += 1
+
+        synced[page_title] = content
+
+    click.echo(
+        _(
+            "\nDone! Created: {created}, Updated: {updated}, Skipped: {skipped}",
+            created=created,
+            updated=updated,
+            skipped=skipped,
+        )
+    )
+
+    # --strict implies --verify
+    do_verify = verify or strict
+
+    if do_verify and not dry_run:
+        if strict:
+            click.echo(_("\nRunning full wiki integrity check..."))
+            failures = verify_wiki_integrity(client, mapping, synced)
+            if failures:
+                click.echo(_("\nIntegrity check FAILED ({count} issues):", count=len(failures)))
+                for f in failures:
+                    click.echo(f"  - {f}")
+                raise click.ClickException(_("Wiki integrity check failed — {count} issue(s)", count=len(failures)))
+            click.echo(_("\nIntegrity check passed — all {count} pages verified.", count=len(synced)))
+        else:
+            click.echo(_("\nVerifying wiki pages have content..."))
+            # Re-fetch the page list to get updated sub_urls
+            existing_pages = list_wiki_pages(client)
+            failures = 0
+            for page_title, expected_content in sorted(synced.items()):
+                ok = verify_wiki_page(client, page_title, expected_content, existing_pages)
+                if ok:
+                    click.echo(_("  OK: {title} ({chars} chars)", title=page_title, chars=len(expected_content)))
+                else:
+                    click.echo(_("  FAIL: {title} — content mismatch or empty!", title=page_title))
+                    failures += 1
+            if failures > 0:
+                click.echo(
+                    _(
+                        "\nVerification FAILED: {failures} page(s) have empty or mismatched content!",
+                        failures=failures,
+                    )
+                )
+                raise click.ClickException(
+                    _("Wiki verification failed — {failures} page(s) empty or mismatched", failures=failures)
+                )
+            click.echo(_("\nVerification passed — all wiki pages have correct content."))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

scripts/sync_wiki.py

@@ -1,148 +0,0 @@
-#!/usr/bin/env python3
-"""Sync documentation from /docs/ to the Gitea wiki via API.
-
-Reads markdown files from the ``docs/`` directory, uses ``mapping.json`` to
-map file paths to wiki page titles, and creates/updates wiki pages via the
-Gitea API.  Pages that exist in the wiki but not in the mapping are left
-untouched (not deleted).
-
-Usage:
-  REPO_TOKEN=<token> python3 scripts/sync_wiki.py [--dry-run] [--repo owner/repo]
-"""
-
-from __future__ import annotations
-
-import json
-import os
-from pathlib import Path
-
-import click
-from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
-
-from gitea_runner_manager.api_clients import GiteaClient
-from gitea_runner_manager.config import GITEA_API_URL
-from gitea_runner_manager.exceptions import APIError
-from gitea_runner_manager.i18n import _
-
-load_dotenv(override=True)
-
-DOCS_DIR = Path(__file__).resolve().parent.parent / "docs"
-MAPPING_FILE = DOCS_DIR / "mapping.json"
-
-
-def load_mapping() -> dict[str, str]:
-    """Load the file-to-wiki-page mapping from mapping.json."""
-    with open(MAPPING_FILE) as f:
-        return json.load(f)
-
-
-def read_doc_content(file_path: str) -> str:
-    """Read markdown content from a docs file."""
-    full_path = DOCS_DIR / file_path
-    with open(full_path) as f:
-        return f.read()
-
-
-def list_wiki_pages(client: GiteaClient) -> dict[str, str]:
-    """List existing wiki pages, returning {title: page_name}."""
-    try:
-        pages = client._request("GET", "/wiki/pages").json()
-    except APIError:
-        return {}
-    return {page.get("title", ""): page.get("page_name", page.get("title", "")) for page in pages}
-
-
-def sync_page(
-    client: GiteaClient,
-    page_title: str,
-    content: str,
-    existing_pages: dict[str, str],
-    dry_run: bool,
-) -> str:
-    """Create or update a single wiki page.
-
-    Returns "created", "updated", or "skipped" (if dry-run).
-    """
-    if dry_run:
-        click.echo(_("[dry-run] Would sync page: {title} ({chars} chars)", title=page_title, chars=len(content)))
-        return "skipped"
-
-    if page_title in existing_pages:
-        # Update existing page
-        page_name = existing_pages[page_title]
-        client._request(
-            "PUT",
-            f"/wiki/page/{page_name}",
-            json={"content": content, "message": f"Sync from docs/ — update {page_title}"},
-        )
-        return "updated"
-
-    # Create new page
-    client._request(
-        "POST",
-        "/wiki/page",
-        json={"title": page_title, "content": content, "message": f"Sync from docs/ — create {page_title}"},
-    )
-    return "created"
-
-
-@click.command()
-@click.option("--dry-run", is_flag=True, default=False, help="Show what would happen without making changes.")
-@click.option("--repo", default=None, help="Repository in owner/name format (auto-detected if omitted).")
-def main(dry_run: bool, repo: str | None) -> None:
-    token = os.environ.get("REPO_TOKEN", "")
-    if not token:
-        raise click.ClickException(_("ERROR: REPO_TOKEN is not set."))
-
-    if repo is None:
-        owner = os.environ.get("GRM_REPO_OWNER", "oblachno-oss")
-        repo_name = os.environ.get("GRM_REPO_NAME", "grm")
-    else:
-        owner, repo_name = repo.split("/")
-
-    if not MAPPING_FILE.exists():
-        raise click.ClickException(_("ERROR: mapping.json not found at {path}", path=MAPPING_FILE))
-
-    mapping = load_mapping()
-    client = GiteaClient(GITEA_API_URL, token, owner, repo_name)
-
-    click.echo(_("Syncing {count} documentation pages to wiki...", count=len(mapping)))
-
-    existing_pages = list_wiki_pages(client)
-    if existing_pages:
-        click.echo(_("Found {count} existing wiki pages.", count=len(existing_pages)))
-
-    created = 0
-    updated = 0
-    skipped = 0
-
-    for file_path, page_title in sorted(mapping.items()):
-        try:
-            content = read_doc_content(file_path)
-        except FileNotFoundError:
-            click.echo(_("WARNING: File {file} not found — skipping.", file=file_path))
-            skipped += 1
-            continue
-
-        result = sync_page(client, page_title, content, existing_pages, dry_run)
-        if result == "created":
-            created += 1
-            click.echo(_("  Created: {title}", title=page_title))
-        elif result == "updated":
-            updated += 1
-            click.echo(_("  Updated: {title}", title=page_title))
-        else:
-            skipped += 1
-
-    click.echo(
-        _(
-            "\nDone! Created: {created}, Updated: {updated}, Skipped: {skipped}",
-            created=created,
-            updated=updated,
-            skipped=skipped,
-        )
-    )
-
-
-if __name__ == "__main__":  # pragma: no cover
-    main()

src/gitea_runner_manager/__init__.py

@@ -1,3 +1,3 @@
 """Gitea Runner Manager — lean CLI for managing Gitea Actions runners."""
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"

tests/unit/test_auto_merge.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/auto_merge.py."""
+"""Unit tests for scripts/ci/auto_merge.py."""
 
 import http
 from unittest.mock import MagicMock, patch
@@ -9,7 +9,7 @@ from click.testing import CliRunner
 
 from gitea_runner_manager.config import CONVENTIONAL_RE, TASK_ID_RE
 from gitea_runner_manager.exceptions import APIError
-from scripts.auto_merge import (
+from scripts.ci.auto_merge import (
     PR_TITLE_RE,
     extract_conventional_msg,
     extract_task_id,
@@ -162,25 +162,25 @@ class TestHasApprovalReview:
 
 
 class TestValidatePrTitleMatchesVikunja:
-    @patch("scripts.auto_merge.get_vikunja_task_title", return_value="")
+    @patch("scripts.ci.auto_merge.get_vikunja_task_title", return_value="")
     @patch.dict("os.environ", {}, clear=True)
     def test_no_vikunja_token_skips(self, mock_get: MagicMock) -> None:
         """Should skip validation when VIKUNJA_TOKEN is not set."""
         validate_pr_title_matches_vikunja("GRM-19: Some title", "GRM-19")
 
-    @patch("scripts.auto_merge.get_vikunja_task_title", return_value="Some task title")
+    @patch("scripts.ci.auto_merge.get_vikunja_task_title", return_value="Some task title")
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"}, clear=True)
     def test_matching_title_passes(self, mock_get: MagicMock) -> None:
         validate_pr_title_matches_vikunja("GRM-19: Some task title", "GRM-19")
 
-    @patch("scripts.auto_merge.get_vikunja_task_title", return_value="Some task title")
+    @patch("scripts.ci.auto_merge.get_vikunja_task_title", return_value="Some task title")
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"}, clear=True)
     def test_mismatched_title_raises(self, mock_get: MagicMock) -> None:
         with pytest.raises(click.ClickException) as exc:
             validate_pr_title_matches_vikunja("GRM-19: Different title", "GRM-19")
         assert "does not match" in str(exc.value)
 
-    @patch("scripts.auto_merge.get_vikunja_task_title", return_value="")
+    @patch("scripts.ci.auto_merge.get_vikunja_task_title", return_value="")
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"}, clear=True)
     def test_task_not_found_skips(self, mock_get: MagicMock) -> None:
         """Should skip validation when Vikunja task is not found."""
@@ -190,14 +190,14 @@ class TestValidatePrTitleMatchesVikunja:
 class TestGetVikunjaTaskTitle:
     @patch.dict("os.environ", {}, clear=True)
     def test_no_token_returns_empty(self) -> None:
-        from scripts.auto_merge import get_vikunja_task_title
+        from scripts.ci.auto_merge import get_vikunja_task_title
 
         assert get_vikunja_task_title("GRM-19") == ""
 
-    @patch("scripts.auto_merge.VikunjaClient")
+    @patch("scripts.ci.auto_merge.VikunjaClient")
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"}, clear=True)
     def test_finds_task(self, mock_client_cls: MagicMock) -> None:
-        from scripts.auto_merge import get_vikunja_task_title
+        from scripts.ci.auto_merge import get_vikunja_task_title
 
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = [
@@ -206,10 +206,10 @@ class TestGetVikunjaTaskTitle:
         mock_client_cls.return_value = mock_client
         assert get_vikunja_task_title("GRM-19") == "Some task title"
 
-    @patch("scripts.auto_merge.VikunjaClient")
+    @patch("scripts.ci.auto_merge.VikunjaClient")
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"}, clear=True)
     def test_task_not_found_returns_empty(self, mock_client_cls: MagicMock) -> None:
-        from scripts.auto_merge import get_vikunja_task_title
+        from scripts.ci.auto_merge import get_vikunja_task_title
 
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = [
@@ -218,10 +218,10 @@ class TestGetVikunjaTaskTitle:
         mock_client_cls.return_value = mock_client
         assert get_vikunja_task_title("GRM-19") == ""
 
-    @patch("scripts.auto_merge.VikunjaClient")
+    @patch("scripts.ci.auto_merge.VikunjaClient")
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"}, clear=True)
     def test_paginates_to_find_task(self, mock_client_cls: MagicMock) -> None:
-        from scripts.auto_merge import get_vikunja_task_title
+        from scripts.ci.auto_merge import get_vikunja_task_title
 
         mock_client = MagicMock()
         # First page: full page of 50 tasks, no match; second page: match
@@ -231,10 +231,10 @@ class TestGetVikunjaTaskTitle:
         mock_client_cls.return_value = mock_client
         assert get_vikunja_task_title("GRM-99") == "Found task"
 
-    @patch("scripts.auto_merge.VikunjaClient")
+    @patch("scripts.ci.auto_merge.VikunjaClient")
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"}, clear=True)
     def test_empty_pages_returns_empty(self, mock_client_cls: MagicMock) -> None:
-        from scripts.auto_merge import get_vikunja_task_title
+        from scripts.ci.auto_merge import get_vikunja_task_title
 
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = []
@@ -257,7 +257,7 @@ class TestWaitForCi:
             [_status("CI / quality (pull_request)", CI_PENDING)],
             [_status("CI / quality (pull_request)", CI_SUCCESS)],
         ]
-        with patch("scripts.auto_merge.time.sleep"):
+        with patch("scripts.ci.auto_merge.time.sleep"):
             assert wait_for_ci(client, "abc123", max_wait=10, poll_interval=5) is True
 
     def test_fails_on_failed_check(self) -> None:
@@ -273,7 +273,7 @@ class TestWaitForCi:
         client.get_commit_status.return_value = [
             _status("CI / quality (pull_request)", CI_PENDING),
         ]
-        with patch("scripts.auto_merge.time.sleep"):
+        with patch("scripts.ci.auto_merge.time.sleep"):
             assert wait_for_ci(client, "abc123", max_wait=5) is False
 
     def test_no_statuses_waits(self) -> None:
@@ -282,7 +282,7 @@ class TestWaitForCi:
             [],
             [_status("CI / quality (pull_request)", CI_SUCCESS)],
         ]
-        with patch("scripts.auto_merge.time.sleep"):
+        with patch("scripts.ci.auto_merge.time.sleep"):
             assert wait_for_ci(client, "abc123", max_wait=10, poll_interval=5) is True
 
     def test_ignores_non_ci_contexts(self) -> None:
@@ -307,7 +307,7 @@ class TestWaitForCi:
             [_status("Auto-merge / merge (pull_request)", CI_PENDING)],
             [_status("CI / quality (pull_request)", CI_SUCCESS)],
         ]
-        with patch("scripts.auto_merge.time.sleep"):
+        with patch("scripts.ci.auto_merge.time.sleep"):
             assert wait_for_ci(client, "abc123", max_wait=10, poll_interval=5) is True
 
 
@@ -325,9 +325,9 @@ def _mock_commits() -> list[dict[str, dict[str, str]]]:
 
 class TestMain:
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_successful_flow_with_label_arg(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -346,9 +346,9 @@ class TestMain:
         mock_client.merge_pr.assert_called_once_with("7", "GRM-19 fix: resolve timeout")
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_successful_flow_label_fallback(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -369,9 +369,9 @@ class TestMain:
         mock_client.merge_pr.assert_called_once_with("7", "GRM-19 fix: resolve timeout")
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_wrong_label_skips_merge(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -389,9 +389,9 @@ class TestMain:
         mock_client.merge_pr.assert_not_called()
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_empty_label_falls_back_to_api(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -418,7 +418,7 @@ class TestMain:
         assert "REPO_TOKEN" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_missing_task_id_exits(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.get_pr_labels.return_value = [{"name": "ready-to-merge"}]
@@ -429,7 +429,7 @@ class TestMain:
         assert "task ID" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_invalid_pr_title_exits(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.get_pr_labels.return_value = [{"name": "ready-to-merge"}]
@@ -440,7 +440,7 @@ class TestMain:
         assert "GRM-N" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_pr_title_task_id_mismatch_exits(self, mock_client_cls: MagicMock) -> None:
         """PR title has a different task ID than the branch."""
         mock_client = MagicMock()
@@ -452,9 +452,9 @@ class TestMain:
         assert "mismatch" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=False)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=False)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_no_approval_review_blocks_merge(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -469,9 +469,9 @@ class TestMain:
         mock_client.merge_pr.assert_not_called()
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_empty_commits_exits(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -489,9 +489,9 @@ class TestMain:
         mock_client.merge_pr.assert_not_called()
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_merge_pr_failure_raises_click(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -508,9 +508,9 @@ class TestMain:
         assert "HTTP" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_merge_pr_json_parse_failure(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -527,9 +527,9 @@ class TestMain:
         assert str(http.HTTPStatus.BAD_GATEWAY) in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_ci_failure_blocks_merge(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:
@@ -548,9 +548,9 @@ class TestMain:
         mock_client.merge_pr.assert_not_called()
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.auto_merge.validate_pr_title_matches_vikunja")
-    @patch("scripts.auto_merge.has_approval_review", return_value=True)
-    @patch("scripts.auto_merge.GiteaClient")
+    @patch("scripts.ci.auto_merge.validate_pr_title_matches_vikunja")
+    @patch("scripts.ci.auto_merge.has_approval_review", return_value=True)
+    @patch("scripts.ci.auto_merge.GiteaClient")
     def test_no_sha_proceeds_without_wait(
         self, mock_client_cls: MagicMock, mock_approval: MagicMock, mock_vikunja: MagicMock
     ) -> None:

tests/unit/test_classify_changes.py

@@ -0,0 +1,246 @@
+"""Unit tests for scripts/ci/classify_changes.py."""
+
+from unittest.mock import MagicMock, patch
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from scripts.ci.classify_changes import (
+    classify_changes,
+    get_changed_files,
+    get_latest_tag,
+    has_user_facing_changes,
+    is_user_facing,
+    is_workflow_only,
+    main,
+    run_git,
+)
+
+
+class TestIsUserFacing:
+    def test_src_is_user_facing(self) -> None:
+        assert is_user_facing("src/gitea_runner_manager/cli.py") is True
+
+    def test_ansible_is_user_facing(self) -> None:
+        assert is_user_facing("ansible/roles/gitea-runner/tasks/main.yml") is True
+
+    def test_pyproject_is_user_facing(self) -> None:
+        assert is_user_facing("pyproject.toml") is True
+
+    def test_workflow_is_not_user_facing(self) -> None:
+        assert is_user_facing(".gitea/workflows/ci.yml") is False
+
+    def test_ci_scripts_are_not_user_facing(self) -> None:
+        assert is_user_facing("scripts/ci/release.py") is False
+
+    def test_dev_scripts_are_not_user_facing(self) -> None:
+        """All scripts under scripts/ are infrastructure (CI/CD, dev tools).
+        User-facing code lives in src/gitea_runner_manager/."""
+        assert is_user_facing("scripts/check_test_speed.py") is False
+        assert is_user_facing("scripts/configure_repo.py") is False
+        assert is_user_facing("scripts/install_checkmake.py") is False
+
+    def test_shell_scripts_are_not_user_facing(self) -> None:
+        assert is_user_facing("scripts/setup.sh") is False
+        assert is_user_facing("scripts/molecule_all.sh") is False
+
+    def test_scripts_init_is_not_user_facing(self) -> None:
+        assert is_user_facing("scripts/__init__.py") is False
+
+    def test_version_file_is_not_user_facing(self) -> None:
+        """__init__.py only contains __version__ — a release artifact,
+        not user-facing code. Version bumps alone should not trigger releases."""
+        assert is_user_facing("src/gitea_runner_manager/__init__.py") is False
+
+    def test_docs_are_not_user_facing(self) -> None:
+        assert is_user_facing("docs/user/getting-started.md") is False
+
+    def test_tests_are_not_user_facing(self) -> None:
+        assert is_user_facing("tests/unit/test_cli.py") is False
+
+    def test_agents_md_is_not_user_facing(self) -> None:
+        assert is_user_facing("AGENTS.md") is False
+
+    def test_makefile_is_not_user_facing(self) -> None:
+        assert is_user_facing("Makefile") is False
+
+    def test_unknown_file_defaults_to_user_facing(self) -> None:
+        """Safe default: unknown files are user-facing (require release)."""
+        assert is_user_facing("some/new/file.type") is True
+        assert is_user_facing("new_root_file.txt") is True
+
+    def test_is_workflow_only_inverse(self) -> None:
+        assert is_workflow_only(".gitea/workflows/ci.yml") is True
+        assert is_workflow_only("src/gitea_runner_manager/cli.py") is False
+        assert is_workflow_only("pyproject.toml") is False
+
+
+class TestClassifyChanges:
+    def test_all_user_facing(self) -> None:
+        files = ["src/gitea_runner_manager/cli.py", "ansible/roles/gitea-runner/tasks/main.yml"]
+        result = classify_changes(files)
+        assert result["user_facing"] == files
+        assert result["workflow_only"] == []
+
+    def test_all_workflow_only(self) -> None:
+        files = [".gitea/workflows/ci.yml", "docs/index.md", "AGENTS.md"]
+        result = classify_changes(files)
+        assert result["user_facing"] == []
+        assert result["workflow_only"] == files
+
+    def test_mixed(self) -> None:
+        files = [
+            "src/gitea_runner_manager/cli.py",
+            ".gitea/workflows/ci.yml",
+            "pyproject.toml",
+            "docs/index.md",
+        ]
+        result = classify_changes(files)
+        assert "src/gitea_runner_manager/cli.py" in result["user_facing"]
+        assert "pyproject.toml" in result["user_facing"]
+        assert ".gitea/workflows/ci.yml" in result["workflow_only"]
+        assert "docs/index.md" in result["workflow_only"]
+
+    def test_empty(self) -> None:
+        result = classify_changes([])
+        assert result == {"user_facing": [], "workflow_only": []}
+
+
+class TestGetChangedFiles:
+    @patch("scripts.ci.classify_changes.run_git")
+    def test_returns_file_list(self, mock_run_git: MagicMock) -> None:
+        mock_run_git.return_value = "file1.py\nfile2.py\nfile3.md"
+        result = get_changed_files("v0.1.0", "HEAD")
+        assert result == ["file1.py", "file2.py", "file3.md"]
+
+    @patch("scripts.ci.classify_changes.run_git")
+    def test_empty_when_no_changes(self, mock_run_git: MagicMock) -> None:
+        mock_run_git.return_value = ""
+        result = get_changed_files("v0.1.0", "HEAD")
+        assert result == []
+
+
+class TestHasUserFacingChanges:
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    def test_true_when_user_facing(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = ["src/gitea_runner_manager/cli.py", "docs/index.md"]
+        assert has_user_facing_changes("v0.1.0", "HEAD") is True
+
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    def test_false_when_workflow_only(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = [".gitea/workflows/ci.yml", "docs/index.md"]
+        assert has_user_facing_changes("v0.1.0", "HEAD") is False
+
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    def test_false_when_no_changes(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = []
+        assert has_user_facing_changes("v0.1.0", "HEAD") is False
+
+
+class TestGetLatestTag:
+    @patch("subprocess.run")
+    def test_returns_tag(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="v0.3.0\n", stderr="")
+        assert get_latest_tag() == "v0.3.0"
+
+    @patch("subprocess.run")
+    def test_returns_empty_when_no_tags(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="error")
+        assert get_latest_tag() == ""
+
+
+class TestRunGit:
+    @patch("scripts.ci.classify_changes.subprocess.run")
+    def test_success(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="file1.py\n", stderr="")
+        result = run_git(["git", "diff", "--name-only", "v0.1.0", "HEAD"])
+        assert result == "file1.py"
+
+    @patch("scripts.ci.classify_changes.subprocess.run")
+    def test_failure_raises(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="git error")
+        with pytest.raises(click.ClickException):
+            run_git(["git", "bad-command"])
+
+
+class TestMain:
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="")
+    def test_no_tags_outputs_true(self, mock_tag: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, ["--quiet"])
+        assert result.exit_code == 0
+        assert "true" in result.output
+
+    @patch("scripts.ci.classify_changes.get_changed_files", return_value=[])
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="v0.3.0")
+    def test_no_changes_outputs_false(self, mock_tag: MagicMock, mock_changes: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, ["--quiet"])
+        assert result.exit_code == 0
+        assert "false" in result.output
+
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="v0.3.0")
+    def test_workflow_only_exits_2(self, mock_tag: MagicMock, mock_changes: MagicMock) -> None:
+        mock_changes.return_value = [".gitea/workflows/ci.yml", "docs/index.md"]
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 2
+        assert "no release needed" in result.output
+
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="v0.3.0")
+    def test_user_facing_exits_0(self, mock_tag: MagicMock, mock_changes: MagicMock) -> None:
+        mock_changes.return_value = ["src/gitea_runner_manager/cli.py", "docs/index.md"]
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 0
+        assert "release needed" in result.output
+
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="")
+    def test_no_tags_non_quiet(self, mock_tag: MagicMock) -> None:
+        """Non-quiet mode with no tags prints user-facing message."""
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 0
+        assert "No tags found" in result.output
+
+    @patch("scripts.ci.classify_changes.get_changed_files", return_value=[])
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="v0.3.0")
+    def test_no_changes_non_quiet(self, mock_tag: MagicMock, mock_changes: MagicMock) -> None:
+        """Non-quiet mode with no changes prints message."""
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 0
+        assert "No changes" in result.output
+
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="v0.3.0")
+    def test_quiet_user_facing(self, mock_tag: MagicMock, mock_changes: MagicMock) -> None:
+        """Quiet mode with user-facing changes outputs true."""
+        mock_changes.return_value = ["src/gitea_runner_manager/cli.py"]
+        runner = CliRunner()
+        result = runner.invoke(main, ["--quiet"])
+        assert result.exit_code == 0
+        assert "true" in result.output
+
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="v0.3.0")
+    def test_quiet_workflow_only(self, mock_tag: MagicMock, mock_changes: MagicMock) -> None:
+        """Quiet mode with workflow-only changes outputs false."""
+        mock_changes.return_value = [".gitea/workflows/ci.yml"]
+        runner = CliRunner()
+        result = runner.invoke(main, ["--quiet"])
+        assert result.exit_code == 0
+        assert "false" in result.output
+
+    @patch("scripts.ci.classify_changes.get_changed_files")
+    @patch("scripts.ci.classify_changes.get_latest_tag", return_value="v0.3.0")
+    def test_with_explicit_base(self, mock_tag: MagicMock, mock_changes: MagicMock) -> None:
+        """Explicit --base overrides latest tag."""
+        mock_changes.return_value = ["src/gitea_runner_manager/cli.py"]
+        runner = CliRunner()
+        result = runner.invoke(main, ["--base", "v0.2.0", "--head", "HEAD"])
+        assert result.exit_code == 0
+        assert "release needed" in result.output

tests/unit/test_discover_runners.py

@@ -0,0 +1,190 @@
+"""Unit tests for scripts/ci/discover_runners.py."""
+
+import json
+from unittest.mock import MagicMock, patch
+
+from click.testing import CliRunner
+
+from scripts.ci.discover_runners import (
+    DEFAULT_MAX_RUNNERS,
+    generate_indices,
+    get_runner_count,
+    main,
+    query_runners,
+)
+
+
+class TestGenerateIndices:
+    def test_zero(self) -> None:
+        assert generate_indices(0) == []
+
+    def test_one(self) -> None:
+        assert generate_indices(1) == [0]
+
+    def test_three(self) -> None:
+        assert generate_indices(3) == [0, 1, 2]
+
+    def test_five(self) -> None:
+        assert generate_indices(5) == [0, 1, 2, 3, 4]
+
+
+class TestQueryRunners:
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_returns_total_from_all_levels(self, mock_get: MagicMock) -> None:
+        """Runners from repo, org, and admin levels are summed."""
+        responses = [
+            MagicMock(status_code=200, json=lambda: {"runners": [], "total_count": 2}),
+            MagicMock(status_code=200, json=lambda: {"runners": [], "total_count": 1}),
+            MagicMock(status_code=200, json=lambda: {"runners": [], "total_count": 3}),
+        ]
+        mock_get.side_effect = responses
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 6
+
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_skips_non_200(self, mock_get: MagicMock) -> None:
+        """Non-200 responses (e.g., 403 for admin) are skipped."""
+        responses = [
+            MagicMock(status_code=200, json=lambda: {"total_count": 2}),
+            MagicMock(status_code=200, json=lambda: {"total_count": 1}),
+            MagicMock(status_code=403, json=lambda: {"message": "forbidden"}),
+        ]
+        mock_get.side_effect = responses
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 3
+
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_handles_request_exception(self, mock_get: MagicMock) -> None:
+        """Network errors are caught and don't crash."""
+        mock_get.side_effect = [
+            MagicMock(status_code=200, json=lambda: {"total_count": 1}),
+            MagicMock(side_effect=__import__("requests").RequestException("network error")),
+            MagicMock(status_code=200, json=lambda: {"total_count": 2}),
+        ]
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 3
+
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_all_failures_return_zero(self, mock_get: MagicMock) -> None:
+        """When all API calls fail, returns 0."""
+        mock_get.side_effect = [
+            MagicMock(status_code=404),
+            MagicMock(status_code=404),
+            MagicMock(status_code=403),
+        ]
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 0
+
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_value_error_on_repo_level(self, mock_get: MagicMock) -> None:
+        """JSON parse error on repo level is caught."""
+        responses = [
+            MagicMock(status_code=200, json=MagicMock(side_effect=ValueError("bad json"))),
+            MagicMock(status_code=200, json=lambda: {"total_count": 2}),
+            MagicMock(status_code=200, json=lambda: {"total_count": 1}),
+        ]
+        mock_get.side_effect = responses
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 3
+
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_value_error_on_org_level(self, mock_get: MagicMock) -> None:
+        """JSON parse error on org level is caught."""
+        responses = [
+            MagicMock(status_code=200, json=lambda: {"total_count": 1}),
+            MagicMock(status_code=200, json=MagicMock(side_effect=ValueError("bad json"))),
+            MagicMock(status_code=200, json=lambda: {"total_count": 2}),
+        ]
+        mock_get.side_effect = responses
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 3
+
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_value_error_on_admin_level(self, mock_get: MagicMock) -> None:
+        """JSON parse error on admin level is caught."""
+        responses = [
+            MagicMock(status_code=200, json=lambda: {"total_count": 1}),
+            MagicMock(status_code=200, json=lambda: {"total_count": 2}),
+            MagicMock(status_code=200, json=MagicMock(side_effect=ValueError("bad json"))),
+        ]
+        mock_get.side_effect = responses
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 3
+
+    @patch("scripts.ci.discover_runners.requests.get")
+    def test_request_exception_on_all_levels(self, mock_get: MagicMock) -> None:
+        """Network errors on all levels return 0."""
+        mock_get.side_effect = __import__("requests").RequestException("network error")
+        result = query_runners("https://api.example.com", "token", "owner", "repo")
+        assert result == 0
+
+
+class TestGetRunnerCount:
+    @patch("scripts.ci.discover_runners.query_runners", return_value=5)
+    def test_uses_api_count_when_positive(self, mock_query: MagicMock) -> None:
+        result = get_runner_count("https://api.example.com", "token", "owner", "repo")
+        assert result == 5
+
+    @patch("scripts.ci.discover_runners.query_runners", return_value=0)
+    @patch.dict("os.environ", {"MOLECULE_RUNNERS": "4"})
+    def test_falls_back_to_env_var(self, mock_query: MagicMock) -> None:
+        result = get_runner_count("https://api.example.com", "token", "owner", "repo")
+        assert result == 4
+
+    @patch("scripts.ci.discover_runners.query_runners", return_value=0)
+    @patch.dict("os.environ", {"MOLECULE_RUNNERS": "invalid"})
+    def test_falls_back_to_default_on_invalid_env(self, mock_query: MagicMock) -> None:
+        result = get_runner_count("https://api.example.com", "token", "owner", "repo")
+        assert result == DEFAULT_MAX_RUNNERS
+
+    @patch("scripts.ci.discover_runners.query_runners", return_value=0)
+    @patch.dict("os.environ", {}, clear=True)
+    def test_falls_back_to_default_when_no_env(self, mock_query: MagicMock) -> None:
+        result = get_runner_count("https://api.example.com", "token", "owner", "repo")
+        assert result == DEFAULT_MAX_RUNNERS
+
+    @patch("scripts.ci.discover_runners.query_runners", return_value=0)
+    @patch.dict("os.environ", {"MOLECULE_RUNNERS": "0"})
+    def test_env_var_zero_falls_back_to_default(self, mock_query: MagicMock) -> None:
+        """MOLECULE_RUNNERS=0 is invalid, falls back to default."""
+        result = get_runner_count("https://api.example.com", "token", "owner", "repo")
+        assert result == DEFAULT_MAX_RUNNERS
+
+    @patch("scripts.ci.discover_runners.query_runners", return_value=0)
+    @patch.dict("os.environ", {}, clear=True)
+    def test_no_token_uses_env_var(self, mock_query: MagicMock) -> None:
+        """When no token, skips API and uses env/default."""
+        with patch.dict("os.environ", {"MOLECULE_RUNNERS": "2"}):
+            result = get_runner_count("https://api.example.com", "", "owner", "repo")
+            assert result == 2
+
+
+class TestMain:
+    @patch("scripts.ci.discover_runners.get_runner_count", return_value=3)
+    def test_default_output(self, mock_count: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 0
+        assert "count=3" in result.output
+        assert "indices=[0, 1, 2]" in result.output
+
+    @patch("scripts.ci.discover_runners.get_runner_count", return_value=5)
+    def test_count_only(self, mock_count: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, ["--count"])
+        assert result.exit_code == 0
+        assert result.output.strip() == "5"
+
+    @patch("scripts.ci.discover_runners.get_runner_count", return_value=4)
+    def test_indices_only(self, mock_count: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, ["--indices"])
+        assert result.exit_code == 0
+        assert json.loads(result.output.strip()) == [0, 1, 2, 3]
+
+    @patch("scripts.ci.discover_runners.get_runner_count", return_value=1)
+    def test_single_runner(self, mock_count: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, ["--indices"])
+        assert result.exit_code == 0
+        assert json.loads(result.output.strip()) == [0]

tests/unit/test_distribute_molecule.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/distribute_molecule.py."""
+"""Unit tests for scripts/ci/distribute_molecule.py."""
 
 from pathlib import Path
 from unittest.mock import patch
@@ -6,7 +6,7 @@ from unittest.mock import patch
 import click
 import pytest
 
-from scripts.distribute_molecule import (
+from scripts.ci.distribute_molecule import (
     MOLECULE_ROOT,
     PLATFORMS,
     TestPair,
@@ -134,12 +134,12 @@ class TestCli:
     def test_list_flag(self, tmp_path: Path) -> None:
         from click.testing import CliRunner
 
-        from scripts.distribute_molecule import cli
+        from scripts.ci.distribute_molecule import cli
 
         root = tmp_path / "molecule"
         (root / "alpha").mkdir(parents=True)
         (root / "beta").mkdir(parents=True)
-        with patch("scripts.distribute_molecule.MOLECULE_ROOT", root):
+        with patch("scripts.ci.distribute_molecule.MOLECULE_ROOT", root):
             runner = CliRunner()
             result = runner.invoke(cli, ["--list"])
             assert result.exit_code == 0
@@ -149,7 +149,7 @@ class TestCli:
     def test_list_platforms_flag(self) -> None:
         from click.testing import CliRunner
 
-        from scripts.distribute_molecule import cli
+        from scripts.ci.distribute_molecule import cli
 
         runner = CliRunner()
         result = runner.invoke(cli, ["--list-platforms"])
@@ -162,12 +162,12 @@ class TestCli:
     def test_no_runner_index_prints_all_groups(self, tmp_path: Path) -> None:
         from click.testing import CliRunner
 
-        from scripts.distribute_molecule import cli
+        from scripts.ci.distribute_molecule import cli
 
         root = tmp_path / "molecule"
         for s in ["a", "b", "c"]:
             (root / s).mkdir(parents=True)
-        with patch("scripts.distribute_molecule.MOLECULE_ROOT", root):
+        with patch("scripts.ci.distribute_molecule.MOLECULE_ROOT", root):
             runner = CliRunner()
             result = runner.invoke(cli, ["--max-runners", "3"])
             assert result.exit_code == 0
@@ -178,11 +178,11 @@ class TestCli:
     def test_runner_index_prints_assigned(self, tmp_path: Path) -> None:
         from click.testing import CliRunner
 
-        from scripts.distribute_molecule import cli
+        from scripts.ci.distribute_molecule import cli
 
         root = tmp_path / "molecule"
         (root / "alpha").mkdir(parents=True)
-        with patch("scripts.distribute_molecule.MOLECULE_ROOT", root):
+        with patch("scripts.ci.distribute_molecule.MOLECULE_ROOT", root):
             runner = CliRunner()
             result = runner.invoke(cli, ["--runner-index", "0", "--max-runners", "3"])
             assert result.exit_code == 0
@@ -192,7 +192,7 @@ class TestCli:
 
 
 def test_main_module_block() -> None:
-    import scripts.distribute_molecule as dm
+    import scripts.ci.distribute_molecule as dm
 
     with open(dm.__file__) as f:
         source = f.read()

tests/unit/test_doc_coverage.py

@@ -1,10 +1,10 @@
-"""Unit tests for scripts/doc_coverage.py."""
+"""Unit tests for scripts/ci/doc_coverage.py."""
 
 from pathlib import Path
 
 from click.testing import CliRunner
 
-from scripts.doc_coverage import (
+from scripts.ci.doc_coverage import (
     check_command_documented,
     check_module_documented,
     extract_cli_commands,
@@ -76,7 +76,8 @@ class TestMain:
         )
         # Write ci-cd-workflow.md with all scripts
         (docs / "tech" / "ci-cd-workflow.md").write_text(
-            "auto_merge.py release.py publish.py review_pr.py notify_failure.py post_merge.py"
+            "auto_merge.py release.py publish.py review_pr.py "
+            "notify_failure.py post_merge.py classify_changes.py discover_runners.py"
         )
         runner = CliRunner()
         result = runner.invoke(main, ["--docs-dir", str(docs)])

tests/unit/test_molecule_ci_guard.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/molecule_ci_guard.py."""
+"""Unit tests for scripts/ci/molecule_ci_guard.py."""
 
 from __future__ import annotations
 
@@ -10,7 +10,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 import requests
 
-from scripts.molecule_ci_guard import (
+from scripts.ci.molecule_ci_guard import (
     any_other_runner_failed,
     build_env_for_pair,
     build_molecule_cmd,
@@ -22,7 +22,7 @@ from scripts.molecule_ci_guard import (
 
 class TestGetRunningJobs:
     def test_returns_jobs(self) -> None:
-        with patch("scripts.molecule_ci_guard.requests.get") as mock_get:
+        with patch("scripts.ci.molecule_ci_guard.requests.get") as mock_get:
             mock_response = MagicMock()
             mock_response.json.return_value = {
                 "jobs": [
@@ -38,7 +38,7 @@ class TestGetRunningJobs:
             mock_get.assert_called_once()
 
     def test_raises_on_request_error(self) -> None:
-        with patch("scripts.molecule_ci_guard.requests.get") as mock_get:
+        with patch("scripts.ci.molecule_ci_guard.requests.get") as mock_get:
             mock_get.side_effect = requests.RequestException("boom")
             with pytest.raises(requests.RequestException):
                 get_running_jobs("https://gitea.example", "owner", "repo", "token", 123)
@@ -107,7 +107,7 @@ class TestPollForOtherFailures:
                 ]
             return []
 
-        with patch("scripts.molecule_ci_guard.get_running_jobs") as mock_get_jobs:
+        with patch("scripts.ci.molecule_ci_guard.get_running_jobs") as mock_get_jobs:
             mock_get_jobs.side_effect = side_effect
             stop_event.is_set.side_effect = [False, False]
             stop_event.wait.return_value = True
@@ -130,7 +130,7 @@ class TestPollForOtherFailures:
         stop_event = MagicMock()
         failed_event = MagicMock()
 
-        with patch("scripts.molecule_ci_guard.get_running_jobs") as mock_get_jobs:
+        with patch("scripts.ci.molecule_ci_guard.get_running_jobs") as mock_get_jobs:
             mock_get_jobs.side_effect = requests.RequestException("boom")
             stop_event.is_set.side_effect = [False, True]
             stop_event.wait.return_value = True
@@ -155,7 +155,7 @@ class TestCli:
         from click.testing import CliRunner
 
         with (
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
             patch("time.sleep"),
         ):
             proc = MagicMock()
@@ -172,7 +172,7 @@ class TestCli:
         from click.testing import CliRunner
 
         with (
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
             patch("time.sleep"),
         ):
             proc = MagicMock()
@@ -202,9 +202,9 @@ class TestCli:
                 },
                 clear=True,
             ),
-            patch("scripts.molecule_ci_guard.POLL_INTERVAL", 0.01),
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
-            patch("scripts.molecule_ci_guard.get_running_jobs") as mock_get_jobs,
+            patch("scripts.ci.molecule_ci_guard.POLL_INTERVAL", 0.01),
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.get_running_jobs") as mock_get_jobs,
             patch("time.sleep"),
         ):
             mock_get_jobs.return_value = [
@@ -225,7 +225,7 @@ class TestCli:
         from click.testing import CliRunner
 
         with (
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
             patch("time.sleep", side_effect=KeyboardInterrupt),
             patch("os.killpg") as mock_killpg,
             patch("os.getpgid") as mock_getpgid,
@@ -270,9 +270,9 @@ class TestCli:
                 },
                 clear=True,
             ),
-            patch("scripts.molecule_ci_guard.POLL_INTERVAL", 0.01),
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
-            patch("scripts.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
+            patch("scripts.ci.molecule_ci_guard.POLL_INTERVAL", 0.01),
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
             patch("os.killpg") as mock_killpg,
             patch("os.getpgid") as mock_getpgid,
             patch("time.sleep", side_effect=lambda x: real_sleep(0.1)),
@@ -307,9 +307,9 @@ class TestCli:
                 },
                 clear=True,
             ),
-            patch("scripts.molecule_ci_guard.POLL_INTERVAL", 0.01),
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
-            patch("scripts.molecule_ci_guard.get_running_jobs") as mock_get_jobs,
+            patch("scripts.ci.molecule_ci_guard.POLL_INTERVAL", 0.01),
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.get_running_jobs") as mock_get_jobs,
             patch("time.sleep", side_effect=lambda x: real_sleep(0.05)),
         ):
             mock_get_jobs.return_value = [{"name": "molecule-tests (1)", "conclusion": "success"}]
@@ -351,9 +351,9 @@ class TestCli:
                 },
                 clear=True,
             ),
-            patch("scripts.molecule_ci_guard.POLL_INTERVAL", 0.01),
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
-            patch("scripts.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
+            patch("scripts.ci.molecule_ci_guard.POLL_INTERVAL", 0.01),
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
             patch("os.killpg") as mock_killpg,
             patch("os.getpgid") as mock_getpgid,
             patch("time.sleep", side_effect=lambda x: real_sleep(0.1)),
@@ -398,9 +398,9 @@ class TestCli:
                 },
                 clear=True,
             ),
-            patch("scripts.molecule_ci_guard.POLL_INTERVAL", 0.01),
-            patch("scripts.molecule_ci_guard.subprocess.Popen") as mock_popen,
-            patch("scripts.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
+            patch("scripts.ci.molecule_ci_guard.POLL_INTERVAL", 0.01),
+            patch("scripts.ci.molecule_ci_guard.subprocess.Popen") as mock_popen,
+            patch("scripts.ci.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
             patch("os.killpg") as mock_killpg,
             patch("os.getpgid") as mock_getpgid,
             patch("time.sleep", side_effect=lambda x: real_sleep(0.1)),
@@ -418,7 +418,7 @@ class TestCli:
 
 
 def test_main_module_block() -> None:
-    import scripts.molecule_ci_guard as mg
+    import scripts.ci.molecule_ci_guard as mg
 
     with open(mg.__file__) as f:
         source = f.read()

tests/unit/test_notify_failure.py

@@ -1,16 +1,16 @@
-"""Unit tests for scripts/notify_failure.py."""
+"""Unit tests for scripts/ci/notify_failure.py."""
 
 from unittest.mock import MagicMock, patch
 
 from click.testing import CliRunner
 
 from gitea_runner_manager.exceptions import APIError
-from scripts.notify_failure import main
+from scripts.ci.notify_failure import main
 
 
 class TestNotifyFailure:
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.notify_failure.GiteaClient")
+    @patch("scripts.ci.notify_failure.GiteaClient")
     def test_creates_issue_with_labels(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.list_labels.return_value = [{"id": 5, "name": "bug"}]
@@ -38,7 +38,7 @@ class TestNotifyFailure:
         assert call_kwargs.kwargs["labels"] == [5]
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.notify_failure.GiteaClient")
+    @patch("scripts.ci.notify_failure.GiteaClient")
     def test_creates_issue_without_bug_label(self, mock_client_cls: MagicMock) -> None:
         """When 'bug' label doesn't exist, create issue without labels."""
         mock_client = MagicMock()
@@ -67,7 +67,7 @@ class TestNotifyFailure:
         assert call_kwargs.kwargs.get("labels") is None
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.notify_failure.GiteaClient")
+    @patch("scripts.ci.notify_failure.GiteaClient")
     def test_api_error_raises(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.list_labels.return_value = []

tests/unit/test_post_merge.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/post_merge.py."""
+"""Unit tests for scripts/ci/post_merge.py."""
 
 import http
 from unittest.mock import MagicMock, patch
@@ -8,7 +8,7 @@ import pytest
 from click.testing import CliRunner
 
 from gitea_runner_manager.exceptions import APIError
-from scripts.post_merge import (
+from scripts.ci.post_merge import (
     build_comment,
     extract_conventional_msg,
     extract_task_id,
@@ -90,7 +90,7 @@ class TestResolveTaskId:
 
 class TestMain:
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"})
-    @patch("scripts.post_merge.VikunjaClient")
+    @patch("scripts.ci.post_merge.VikunjaClient")
     def test_full_flow(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = [
@@ -108,7 +108,7 @@ class TestMain:
         mock_client.update_task.assert_called_once_with(267, done=True)
 
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"})
-    @patch("scripts.post_merge.VikunjaClient")
+    @patch("scripts.ci.post_merge.VikunjaClient")
     def test_no_commit_sha(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = [
@@ -130,14 +130,24 @@ class TestMain:
         assert "VIKUNJA_TOKEN" in result.output
 
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"})
-    def test_no_task_id_skips(self) -> None:
+    def test_no_task_id_non_release_fails(self) -> None:
+        """Non-release commits without GRM-N prefix should fail."""
         runner = CliRunner()
         result = runner.invoke(main, ["fix: resolve bug"])
+        assert result.exit_code == 1
+        assert "No task ID" in result.output
+
+    @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"})
+    def test_release_commit_without_task_id_skips(self) -> None:
+        """Release commits without GRM-N prefix should skip gracefully."""
+        runner = CliRunner()
+        result = runner.invoke(main, ["release: v0.3.2"])
         assert result.exit_code == 0
+        assert "Release commit" in result.output
         assert "skipping" in result.output
 
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"})
-    @patch("scripts.post_merge.VikunjaClient")
+    @patch("scripts.ci.post_merge.VikunjaClient")
     def test_resolve_failure_propagates(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = []
@@ -148,7 +158,7 @@ class TestMain:
         assert "Could not find" in result.output
 
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"})
-    @patch("scripts.post_merge.VikunjaClient")
+    @patch("scripts.ci.post_merge.VikunjaClient")
     def test_post_comment_failure_raises_click(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = [
@@ -162,7 +172,7 @@ class TestMain:
         assert "HTTP" in result.output
 
     @patch.dict("os.environ", {"VIKUNJA_TOKEN": "tok"})
-    @patch("scripts.post_merge.VikunjaClient")
+    @patch("scripts.ci.post_merge.VikunjaClient")
     def test_mark_done_failure_raises_click(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.list_project_tasks.return_value = [

tests/unit/test_publish.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/publish.py."""
+"""Unit tests for scripts/ci/publish.py."""
 
 import http
 from unittest.mock import MagicMock, patch
@@ -7,7 +7,7 @@ import click
 import pytest
 from click.testing import CliRunner
 
-from scripts.publish import (
+from scripts.ci.publish import (
     build_package,
     generate_release_notes,
     main,
@@ -16,44 +16,44 @@ from scripts.publish import (
 
 
 class TestGenerateReleaseNotes:
-    @patch("scripts.publish.subprocess.run")
-    @patch("scripts.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
+    @patch("scripts.ci.publish.subprocess.run")
+    @patch("scripts.ci.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
     def test_generates_from_git_cliff(self, mock_which: MagicMock, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=0, stdout="## v1.0.0\n- feat: x")
         result = generate_release_notes("v1.0.0")
         assert "## v1.0.0" in result
         assert "feat: x" in result
 
-    @patch("scripts.publish.subprocess.run")
-    @patch("scripts.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
+    @patch("scripts.ci.publish.subprocess.run")
+    @patch("scripts.ci.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
     def test_strips_whitespace(self, mock_which: MagicMock, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=0, stdout="  changelog  \n")
         result = generate_release_notes("v1.0.0")
         assert result == "changelog"
 
-    @patch("scripts.publish.subprocess.run")
-    @patch("scripts.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
+    @patch("scripts.ci.publish.subprocess.run")
+    @patch("scripts.ci.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
     def test_falls_back_on_failure(self, mock_which: MagicMock, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=1, stdout="")
         result = generate_release_notes("v1.0.0")
         assert "Release v1.0.0" in result
         assert "CHANGELOG.md" in result
 
-    @patch("scripts.publish.subprocess.run")
-    @patch("scripts.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
+    @patch("scripts.ci.publish.subprocess.run")
+    @patch("scripts.ci.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
     def test_falls_back_on_empty_output(self, mock_which: MagicMock, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=0, stdout="   ")
         result = generate_release_notes("v1.0.0")
         assert "Release v1.0.0" in result
 
-    @patch("scripts.publish.subprocess.run", side_effect=FileNotFoundError)
-    @patch("scripts.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
+    @patch("scripts.ci.publish.subprocess.run", side_effect=FileNotFoundError)
+    @patch("scripts.ci.publish.shutil.which", return_value="/usr/local/bin/git-cliff")
     def test_falls_back_on_file_not_found(self, mock_which: MagicMock, mock_run: MagicMock) -> None:
         result = generate_release_notes("v1.0.0")
         assert "Release v1.0.0" in result
         assert "CHANGELOG.md" in result
 
-    @patch("scripts.publish.shutil.which", return_value=None)
+    @patch("scripts.ci.publish.shutil.which", return_value=None)
     def test_falls_back_when_not_installed(self, mock_which: MagicMock) -> None:
         result = generate_release_notes("v1.0.0")
         assert "Release v1.0.0" in result
@@ -61,7 +61,7 @@ class TestGenerateReleaseNotes:
 
 
 class TestBuildPackage:
-    @patch("scripts.publish.subprocess.run")
+    @patch("scripts.ci.publish.subprocess.run")
     def test_success(self, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=0, stderr="")
         build_package()
@@ -69,7 +69,7 @@ class TestBuildPackage:
         assert args[0][1] == "-m"
         assert args[0][2] == "build"
 
-    @patch("scripts.publish.subprocess.run")
+    @patch("scripts.ci.publish.subprocess.run")
     def test_failure_raises(self, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=1, stderr="build error")
         with pytest.raises(click.ClickException) as exc:
@@ -78,7 +78,7 @@ class TestBuildPackage:
 
 
 class TestPublishToPypi:
-    @patch("scripts.publish.subprocess.run")
+    @patch("scripts.ci.publish.subprocess.run")
     def test_success(self, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=0, stderr="")
         publish_to_pypi("pypi-tok")
@@ -86,7 +86,7 @@ class TestPublishToPypi:
         assert "twine" in args[0]
         assert "pypi-tok" in args[0]
 
-    @patch("scripts.publish.subprocess.run")
+    @patch("scripts.ci.publish.subprocess.run")
     def test_failure_raises(self, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=1, stderr="upload failed")
         with pytest.raises(click.ClickException) as exc:
@@ -96,10 +96,10 @@ class TestPublishToPypi:
 
 class TestMain:
     @patch.dict("os.environ", {"REPO_TOKEN": "gitea-tok", "PYPI_TOKEN": "pypi-tok"})
-    @patch("scripts.publish.generate_release_notes", return_value="Release notes")
-    @patch("scripts.publish.GiteaClient")
-    @patch("scripts.publish.publish_to_pypi")
-    @patch("scripts.publish.build_package")
+    @patch("scripts.ci.publish.generate_release_notes", return_value="Release notes")
+    @patch("scripts.ci.publish.GiteaClient")
+    @patch("scripts.ci.publish.publish_to_pypi")
+    @patch("scripts.ci.publish.build_package")
     def test_full_flow_with_pypi(
         self,
         mock_build: MagicMock,
@@ -119,9 +119,9 @@ class TestMain:
         assert call_args.kwargs["body"] == "Release notes"
 
     @patch.dict("os.environ", {"REPO_TOKEN": "gitea-tok"}, clear=True)
-    @patch("scripts.publish.generate_release_notes", return_value="Release notes")
-    @patch("scripts.publish.GiteaClient")
-    @patch("scripts.publish.build_package")
+    @patch("scripts.ci.publish.generate_release_notes", return_value="Release notes")
+    @patch("scripts.ci.publish.GiteaClient")
+    @patch("scripts.ci.publish.build_package")
     def test_without_pypi(
         self,
         mock_build: MagicMock,
@@ -143,10 +143,10 @@ class TestMain:
         assert "REPO_TOKEN" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "gitea-tok", "PYPI_TOKEN": "pypi-tok"})
-    @patch("scripts.publish.generate_release_notes", return_value="Release notes")
-    @patch("scripts.publish.GiteaClient")
-    @patch("scripts.publish.publish_to_pypi")
-    @patch("scripts.publish.build_package")
+    @patch("scripts.ci.publish.generate_release_notes", return_value="Release notes")
+    @patch("scripts.ci.publish.GiteaClient")
+    @patch("scripts.ci.publish.publish_to_pypi")
+    @patch("scripts.ci.publish.build_package")
     def test_build_failure_raises_click(
         self, mock_build: MagicMock, mock_publish: MagicMock, mock_client_cls: MagicMock, mock_notes: MagicMock
     ) -> None:
@@ -157,10 +157,10 @@ class TestMain:
         assert "build" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "gitea-tok", "PYPI_TOKEN": "pypi-tok"})
-    @patch("scripts.publish.generate_release_notes", return_value="Release notes")
-    @patch("scripts.publish.GiteaClient")
-    @patch("scripts.publish.publish_to_pypi")
-    @patch("scripts.publish.build_package")
+    @patch("scripts.ci.publish.generate_release_notes", return_value="Release notes")
+    @patch("scripts.ci.publish.GiteaClient")
+    @patch("scripts.ci.publish.publish_to_pypi")
+    @patch("scripts.ci.publish.build_package")
     def test_publish_failure_raises_click(
         self, mock_build: MagicMock, mock_publish: MagicMock, mock_client_cls: MagicMock, mock_notes: MagicMock
     ) -> None:
@@ -171,10 +171,10 @@ class TestMain:
         assert "publish" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "gitea-tok", "PYPI_TOKEN": "pypi-tok"})
-    @patch("scripts.publish.generate_release_notes", return_value="Release notes")
-    @patch("scripts.publish.GiteaClient")
-    @patch("scripts.publish.publish_to_pypi")
-    @patch("scripts.publish.build_package")
+    @patch("scripts.ci.publish.generate_release_notes", return_value="Release notes")
+    @patch("scripts.ci.publish.GiteaClient")
+    @patch("scripts.ci.publish.publish_to_pypi")
+    @patch("scripts.ci.publish.build_package")
     def test_release_failure_raises_click(
         self, mock_build: MagicMock, mock_publish: MagicMock, mock_client_cls: MagicMock, mock_notes: MagicMock
     ) -> None:
@@ -189,10 +189,10 @@ class TestMain:
         assert "HTTP" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "gitea-tok", "PYPI_TOKEN": "pypi-tok"})
-    @patch("scripts.publish.generate_release_notes", return_value="Release notes")
-    @patch("scripts.publish.GiteaClient")
-    @patch("scripts.publish.publish_to_pypi")
-    @patch("scripts.publish.build_package")
+    @patch("scripts.ci.publish.generate_release_notes", return_value="Release notes")
+    @patch("scripts.ci.publish.GiteaClient")
+    @patch("scripts.ci.publish.publish_to_pypi")
+    @patch("scripts.ci.publish.build_package")
     def test_release_json_parse_failure(
         self, mock_build: MagicMock, mock_publish: MagicMock, mock_client_cls: MagicMock, mock_notes: MagicMock
     ) -> None:

tests/unit/test_release.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/release.py."""
+"""Unit tests for scripts/ci/release.py."""
 
 from unittest.mock import MagicMock, patch
 
@@ -6,7 +6,7 @@ import click
 import pytest
 from click.testing import CliRunner
 
-from scripts.release import (
+from scripts.ci.release import (
     commit_release_changes,
     create_and_push_tag,
     get_bumped_version,
@@ -23,20 +23,20 @@ from scripts.release import (
 
 
 class TestRunCmd:
-    @patch("scripts.release.subprocess.run")
+    @patch("scripts.ci.release.subprocess.run")
     def test_success(self, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=0, stderr="", stdout="")
         result = run_cmd(["echo", "hi"])
         assert result.returncode == 0
         mock_run.assert_called_once()
 
-    @patch("scripts.release.subprocess.run")
+    @patch("scripts.ci.release.subprocess.run")
     def test_failure_raises(self, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=1, stderr="err", stdout="")
         with pytest.raises(click.ClickException):
             run_cmd(["false"])
 
-    @patch("scripts.release.subprocess.run")
+    @patch("scripts.ci.release.subprocess.run")
     def test_check_false_no_raise(self, mock_run: MagicMock) -> None:
         mock_run.return_value = MagicMock(returncode=1, stderr="err", stdout="")
         result = run_cmd(["false"], check=False)
@@ -44,41 +44,41 @@ class TestRunCmd:
 
 
 class TestGetLatestTag:
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_returns_tag(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="v0.1.0\n")
         assert get_latest_tag() == "v0.1.0"
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_no_tags_returns_empty(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=1, stdout="")
         assert get_latest_tag() == ""
 
 
 class TestTagExists:
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_exists(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="v0.1.0\n")
         assert tag_exists("v0.1.0") is True
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_not_exists(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="")
         assert tag_exists("v0.2.0") is False
 
 
 class TestGetBumpedVersion:
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_returns_version(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="0.2.0\n")
         assert get_bumped_version() == "0.2.0"
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_strips_v_prefix(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="v0.2.0\n")
         assert get_bumped_version() == "0.2.0"
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_empty_raises(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="")
         with pytest.raises(click.ClickException):
@@ -86,48 +86,48 @@ class TestGetBumpedVersion:
 
 
 class TestGetChangelog:
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_returns_changelog(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="## 0.2.0\n- fix\n")
         assert get_changelog("0.2.0") == "## 0.2.0\n- fix"
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_strips_whitespace(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="  text  \n")
         assert get_changelog("0.2.0") == "text"
 
 
 class TestHasUnreleasedChanges:
-    @patch("scripts.release.get_latest_tag")
+    @patch("scripts.ci.release.get_latest_tag")
     def test_with_bumped_version_no_changes(self, mock_latest: MagicMock) -> None:
         mock_latest.return_value = "v0.2.0"
         assert has_unreleased_changes(bumped_version="0.2.0") is False
 
-    @patch("scripts.release.get_latest_tag")
+    @patch("scripts.ci.release.get_latest_tag")
     def test_with_bumped_version_has_changes(self, mock_latest: MagicMock) -> None:
         mock_latest.return_value = "v0.2.0"
         assert has_unreleased_changes(bumped_version="0.3.0") is True
 
-    @patch("scripts.release.get_latest_tag")
+    @patch("scripts.ci.release.get_latest_tag")
     def test_with_bumped_version_no_tags(self, mock_latest: MagicMock) -> None:
         mock_latest.return_value = ""
         assert has_unreleased_changes(bumped_version="0.1.0") is True
 
-    @patch("scripts.release.get_latest_tag")
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.get_latest_tag")
+    @patch("scripts.ci.release.run_cmd")
     def test_without_bumped_version_no_changes(self, mock_run_cmd: MagicMock, mock_latest: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="v0.2.0\n")
         mock_latest.return_value = "v0.2.0"
         assert has_unreleased_changes() is False
 
-    @patch("scripts.release.get_latest_tag")
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.get_latest_tag")
+    @patch("scripts.ci.release.run_cmd")
     def test_without_bumped_version_has_changes(self, mock_run_cmd: MagicMock, mock_latest: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="v0.3.0\n")
         mock_latest.return_value = "v0.2.0"
         assert has_unreleased_changes() is True
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_cliff_fails_returns_false(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=1, stdout="")
         assert has_unreleased_changes() is False
@@ -137,7 +137,7 @@ class TestUpdateInitVersion:
     def test_updates_version(self, tmp_path, monkeypatch) -> None:
         init_file = tmp_path / "__init__.py"
         init_file.write_text('__version__ = "0.1.0"\n')
-        monkeypatch.setattr("scripts.release.INIT_FILE", str(init_file))
+        monkeypatch.setattr("scripts.ci.release.INIT_FILE", str(init_file))
         update_init_version("0.2.0")
         assert '__version__ = "0.2.0"' in init_file.read_text()
 
@@ -145,14 +145,14 @@ class TestUpdateInitVersion:
         """Updating to the same version should not raise."""
         init_file = tmp_path / "__init__.py"
         init_file.write_text('__version__ = "0.1.0"\n')
-        monkeypatch.setattr("scripts.release.INIT_FILE", str(init_file))
+        monkeypatch.setattr("scripts.ci.release.INIT_FILE", str(init_file))
         update_init_version("0.1.0")
         assert '__version__ = "0.1.0"' in init_file.read_text()
 
     def test_no_version_raises(self, tmp_path, monkeypatch) -> None:
         init_file = tmp_path / "__init__.py"
         init_file.write_text('"""module"""\n')
-        monkeypatch.setattr("scripts.release.INIT_FILE", str(init_file))
+        monkeypatch.setattr("scripts.ci.release.INIT_FILE", str(init_file))
         with pytest.raises(click.ClickException):
             update_init_version("0.2.0")
 
@@ -160,7 +160,7 @@ class TestUpdateInitVersion:
 class TestUpdateChangelog:
     def test_creates_new_file(self, tmp_path, monkeypatch) -> None:
         changelog_file = tmp_path / "CHANGELOG.md"
-        monkeypatch.setattr("scripts.release.CHANGELOG_FILE", str(changelog_file))
+        monkeypatch.setattr("scripts.ci.release.CHANGELOG_FILE", str(changelog_file))
         update_changelog("## [0.2.0] - 2026-06-21\n\n### Features\n- new thing")
         content = changelog_file.read_text()
         assert "## [0.2.0]" in content
@@ -169,7 +169,7 @@ class TestUpdateChangelog:
     def test_prepends_to_existing(self, tmp_path, monkeypatch) -> None:
         changelog_file = tmp_path / "CHANGELOG.md"
         changelog_file.write_text("# Changelog\n\n## [0.1.0] - 2026-06-20\n\n### Features\n- old thing\n")
-        monkeypatch.setattr("scripts.release.CHANGELOG_FILE", str(changelog_file))
+        monkeypatch.setattr("scripts.ci.release.CHANGELOG_FILE", str(changelog_file))
         update_changelog("## [0.2.0] - 2026-06-21\n\n### Features\n- new thing")
         content = changelog_file.read_text()
         assert "# Changelog" in content
@@ -181,7 +181,7 @@ class TestUpdateChangelog:
     def test_appends_when_no_version_sections(self, tmp_path, monkeypatch) -> None:
         changelog_file = tmp_path / "CHANGELOG.md"
         changelog_file.write_text("# Changelog\n\nSome intro text.\n")
-        monkeypatch.setattr("scripts.release.CHANGELOG_FILE", str(changelog_file))
+        monkeypatch.setattr("scripts.ci.release.CHANGELOG_FILE", str(changelog_file))
         update_changelog("## [0.2.0] - 2026-06-21\n\n### Features\n- new thing")
         content = changelog_file.read_text()
         assert "Some intro text" in content
@@ -191,7 +191,7 @@ class TestUpdateChangelog:
         """git-cliff output includes a header — should be stripped before inserting."""
         changelog_file = tmp_path / "CHANGELOG.md"
         changelog_file.write_text("# Changelog\n\n## [0.1.0] - 2026-06-20\n\n### Features\n- old thing\n")
-        monkeypatch.setattr("scripts.release.CHANGELOG_FILE", str(changelog_file))
+        monkeypatch.setattr("scripts.ci.release.CHANGELOG_FILE", str(changelog_file))
         # Simulate git-cliff output with header
         cliff_output = "# Changelog\n\nAll notable changes...\n\n## [0.2.0] - 2026-06-21\n\n### Features\n- new thing"
         update_changelog(cliff_output)
@@ -204,7 +204,7 @@ class TestUpdateChangelog:
     def test_strips_header_when_creating_new_file(self, tmp_path, monkeypatch) -> None:
         """When creating a new file, strip the git-cliff header."""
         changelog_file = tmp_path / "CHANGELOG.md"
-        monkeypatch.setattr("scripts.release.CHANGELOG_FILE", str(changelog_file))
+        monkeypatch.setattr("scripts.ci.release.CHANGELOG_FILE", str(changelog_file))
         cliff_output = "# Changelog\n\nAll notable changes...\n\n## [0.2.0] - 2026-06-21\n\n### Features\n- new thing"
         update_changelog(cliff_output)
         content = changelog_file.read_text()
@@ -213,7 +213,7 @@ class TestUpdateChangelog:
 
 
 class TestCommitReleaseChanges:
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_commits_when_changes(self, mock_run_cmd: MagicMock) -> None:
         # git diff --cached --quiet returns 1 (changes exist)
         mock_run_cmd.return_value = MagicMock(returncode=1, stdout="", stderr="")
@@ -223,7 +223,7 @@ class TestCommitReleaseChanges:
         assert ["git", "add", "src/gitea_runner_manager/__init__.py", "CHANGELOG.md"] in calls
         assert ["git", "commit", "--no-verify", "-m", "release: v0.2.0"] in calls
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_skips_when_no_changes(self, mock_run_cmd: MagicMock) -> None:
         # git diff --cached --quiet returns 0 (no changes)
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="", stderr="")
@@ -234,16 +234,16 @@ class TestCommitReleaseChanges:
 
 
 class TestCreateAndPushTag:
-    @patch("scripts.release.tag_exists", return_value=False)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.tag_exists", return_value=False)
+    @patch("scripts.ci.release.run_cmd")
     def test_creates_tag(self, mock_run_cmd: MagicMock, mock_tag_exists: MagicMock) -> None:
         create_and_push_tag("0.2.0", "changelog", dry_run=False)
         calls = [c.args[0] for c in mock_run_cmd.call_args_list]
         assert ["git", "tag", "-a", "v0.2.0", "-m", "Release v0.2.0\n\nchangelog"] in calls
         assert ["git", "push", "origin", "v0.2.0"] in calls
 
-    @patch("scripts.release.tag_exists", return_value=False)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.tag_exists", return_value=False)
+    @patch("scripts.ci.release.run_cmd")
     def test_dry_run_no_push(self, mock_run_cmd: MagicMock, mock_tag_exists: MagicMock) -> None:
         result = create_and_push_tag("0.2.0", "changelog", dry_run=True)
         assert result is True
@@ -251,8 +251,8 @@ class TestCreateAndPushTag:
             assert call.args[0][0:2] != ["git", "push"]
             assert call.args[0][0:2] != ["git", "tag"]
 
-    @patch("scripts.release.tag_exists", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.tag_exists", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_tag_exists_skips_creation(self, mock_run_cmd: MagicMock, mock_tag_exists: MagicMock) -> None:
         result = create_and_push_tag("0.1.0", "changelog", dry_run=False)
         assert result is False
@@ -261,8 +261,8 @@ class TestCreateAndPushTag:
         assert ["git", "tag", "-a"] not in [c[:3] for c in calls]
         assert ["git", "push", "origin", "v0.1.0"] in calls
 
-    @patch("scripts.release.tag_exists", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.tag_exists", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_tag_exists_dry_run_no_push(self, mock_run_cmd: MagicMock, mock_tag_exists: MagicMock) -> None:
         result = create_and_push_tag("0.1.0", "changelog", dry_run=True)
         assert result is False
@@ -271,18 +271,18 @@ class TestCreateAndPushTag:
 
 
 class TestRunTests:
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_lint_and_tests_pass(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="", stderr="")
         run_tests()  # should not raise
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_lint_fails_raises(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=1, stdout="", stderr="lint error")
         with pytest.raises(click.ClickException, match="Lint failed"):
             run_tests()
 
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_tests_fail_raises(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.side_effect = [
             MagicMock(returncode=0, stdout="", stderr=""),  # lint passes
@@ -294,7 +294,7 @@ class TestRunTests:
 
 class TestMain:
     @patch.dict("os.environ", {})
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.run_cmd")
     def test_not_on_master_exits(self, mock_run_cmd: MagicMock) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="feature-branch\n", stderr="")
         runner = CliRunner()
@@ -303,10 +303,17 @@ class TestMain:
         assert "master" in result.output
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.has_unreleased_changes", return_value=False)
-    @patch("scripts.release.get_bumped_version", return_value="0.2.0")
-    @patch("scripts.release.run_cmd")
-    def test_no_unreleased_changes(self, mock_run_cmd: MagicMock, mock_bumped: MagicMock, mock_has: MagicMock) -> None:
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=False)
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.2.0")
+    @patch("scripts.ci.release.run_cmd")
+    def test_no_unreleased_changes(
+        self,
+        mock_run_cmd: MagicMock,
+        mock_bumped: MagicMock,
+        mock_has: MagicMock,
+        mock_user: MagicMock,
+    ) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="master\n", stderr="")
         runner = CliRunner()
         result = runner.invoke(main, [])
@@ -314,15 +321,16 @@ class TestMain:
         assert "No unreleased changes" in result.output
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.create_and_push_tag")
-    @patch("scripts.release.commit_release_changes")
-    @patch("scripts.release.update_changelog")
-    @patch("scripts.release.update_init_version")
-    @patch("scripts.release.get_changelog", return_value="")
-    @patch("scripts.release.get_latest_tag", return_value="v0.1.0")
-    @patch("scripts.release.get_bumped_version", return_value="0.2.0")
-    @patch("scripts.release.has_unreleased_changes", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.create_and_push_tag")
+    @patch("scripts.ci.release.commit_release_changes")
+    @patch("scripts.ci.release.update_changelog")
+    @patch("scripts.ci.release.update_init_version")
+    @patch("scripts.ci.release.get_changelog", return_value="")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.1.0")
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.2.0")
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_dry_run_empty_changelog(
         self,
         mock_run_cmd: MagicMock,
@@ -334,6 +342,7 @@ class TestMain:
         mock_update_changelog: MagicMock,
         mock_commit: MagicMock,
         mock_tag: MagicMock,
+        mock_user: MagicMock,
     ) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="master\n", stderr="")
         runner = CliRunner()
@@ -342,15 +351,16 @@ class TestMain:
         assert "empty changelog" in result.output
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.create_and_push_tag")
-    @patch("scripts.release.commit_release_changes")
-    @patch("scripts.release.update_changelog")
-    @patch("scripts.release.update_init_version")
-    @patch("scripts.release.get_changelog", return_value="changelog")
-    @patch("scripts.release.get_latest_tag", return_value="v0.1.0")
-    @patch("scripts.release.get_bumped_version", return_value="0.2.0")
-    @patch("scripts.release.has_unreleased_changes", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.create_and_push_tag")
+    @patch("scripts.ci.release.commit_release_changes")
+    @patch("scripts.ci.release.update_changelog")
+    @patch("scripts.ci.release.update_init_version")
+    @patch("scripts.ci.release.get_changelog", return_value="changelog")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.1.0")
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.2.0")
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_dry_run(
         self,
         mock_run_cmd: MagicMock,
@@ -362,6 +372,7 @@ class TestMain:
         mock_update_changelog: MagicMock,
         mock_commit: MagicMock,
         mock_tag: MagicMock,
+        mock_user: MagicMock,
     ) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="master\n", stderr="")
         runner = CliRunner()
@@ -374,16 +385,35 @@ class TestMain:
         mock_tag.assert_not_called()
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.run_tests")
-    @patch("scripts.release.create_and_push_tag", return_value=True)
-    @patch("scripts.release.commit_release_changes", return_value=True)
-    @patch("scripts.release.update_changelog")
-    @patch("scripts.release.update_init_version")
-    @patch("scripts.release.get_changelog", return_value="changelog")
-    @patch("scripts.release.get_latest_tag", return_value="v0.1.0")
-    @patch("scripts.release.get_bumped_version", return_value="0.2.0")
-    @patch("scripts.release.has_unreleased_changes", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.3.0")
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=False)
+    @patch("scripts.ci.release.run_cmd")
+    def test_skips_release_when_workflow_only(
+        self,
+        mock_run_cmd: MagicMock,
+        mock_user_facing: MagicMock,
+        mock_latest: MagicMock,
+    ) -> None:
+        """Release is skipped when only workflow/infra files changed."""
+        mock_run_cmd.return_value = MagicMock(returncode=0, stdout="master\n", stderr="")
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 0
+        assert "No user-facing changes" in result.output
+        assert "Skipping release" in result.output
+
+    @patch.dict("os.environ", {})
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.run_tests")
+    @patch("scripts.ci.release.create_and_push_tag", return_value=True)
+    @patch("scripts.ci.release.commit_release_changes", return_value=True)
+    @patch("scripts.ci.release.update_changelog")
+    @patch("scripts.ci.release.update_init_version")
+    @patch("scripts.ci.release.get_changelog", return_value="changelog")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.1.0")
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.2.0")
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_full_flow(
         self,
         mock_run_cmd: MagicMock,
@@ -396,6 +426,7 @@ class TestMain:
         mock_commit: MagicMock,
         mock_tag: MagicMock,
         mock_run_tests: MagicMock,
+        mock_user: MagicMock,
     ) -> None:
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="master\n", stderr="")
         runner = CliRunner()
@@ -409,16 +440,17 @@ class TestMain:
         mock_tag.assert_called_once_with("0.2.0", "changelog", False)
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.run_tests")
-    @patch("scripts.release.create_and_push_tag", return_value=False)
-    @patch("scripts.release.commit_release_changes", return_value=False)
-    @patch("scripts.release.update_changelog")
-    @patch("scripts.release.update_init_version")
-    @patch("scripts.release.get_changelog", return_value="changelog")
-    @patch("scripts.release.get_latest_tag", return_value="v0.1.0")
-    @patch("scripts.release.get_bumped_version", return_value="0.1.0")
-    @patch("scripts.release.has_unreleased_changes", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.run_tests")
+    @patch("scripts.ci.release.create_and_push_tag", return_value=False)
+    @patch("scripts.ci.release.commit_release_changes", return_value=False)
+    @patch("scripts.ci.release.update_changelog")
+    @patch("scripts.ci.release.update_init_version")
+    @patch("scripts.ci.release.get_changelog", return_value="changelog")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.1.0")
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.1.0")
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_full_flow_tag_exists(
         self,
         mock_run_cmd: MagicMock,
@@ -431,6 +463,7 @@ class TestMain:
         mock_commit: MagicMock,
         mock_tag: MagicMock,
         mock_run_tests: MagicMock,
+        mock_user: MagicMock,
     ) -> None:
         """When tag already exists, still update files but report existing tag."""
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="master\n", stderr="")
@@ -441,15 +474,16 @@ class TestMain:
         mock_tag.assert_called_once_with("0.1.0", "changelog", False)
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.create_and_push_tag", return_value=True)
-    @patch("scripts.release.commit_release_changes", return_value=True)
-    @patch("scripts.release.update_changelog")
-    @patch("scripts.release.update_init_version")
-    @patch("scripts.release.get_changelog", return_value="changelog")
-    @patch("scripts.release.get_latest_tag", return_value="v0.1.0")
-    @patch("scripts.release.get_bumped_version", return_value="0.2.0")
-    @patch("scripts.release.has_unreleased_changes", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.create_and_push_tag", return_value=True)
+    @patch("scripts.ci.release.commit_release_changes", return_value=True)
+    @patch("scripts.ci.release.update_changelog")
+    @patch("scripts.ci.release.update_init_version")
+    @patch("scripts.ci.release.get_changelog", return_value="changelog")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.1.0")
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.2.0")
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_full_flow_skip_tests(
         self,
         mock_run_cmd: MagicMock,
@@ -461,6 +495,7 @@ class TestMain:
         mock_update_changelog: MagicMock,
         mock_commit: MagicMock,
         mock_tag: MagicMock,
+        mock_user: MagicMock,
     ) -> None:
         """--skip-tests bypasses test verification."""
         mock_run_cmd.return_value = MagicMock(returncode=0, stdout="master\n", stderr="")
@@ -473,15 +508,16 @@ class TestMain:
         assert make_calls == []
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.create_and_push_tag")
-    @patch("scripts.release.commit_release_changes")
-    @patch("scripts.release.update_changelog")
-    @patch("scripts.release.update_init_version")
-    @patch("scripts.release.get_changelog", return_value="changelog")
-    @patch("scripts.release.get_latest_tag", return_value="v0.1.0")
-    @patch("scripts.release.get_bumped_version", return_value="0.2.0")
-    @patch("scripts.release.has_unreleased_changes", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.create_and_push_tag")
+    @patch("scripts.ci.release.commit_release_changes")
+    @patch("scripts.ci.release.update_changelog")
+    @patch("scripts.ci.release.update_init_version")
+    @patch("scripts.ci.release.get_changelog", return_value="changelog")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.1.0")
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.2.0")
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_tests_fail_aborts_before_tag(
         self,
         mock_run_cmd: MagicMock,
@@ -493,6 +529,7 @@ class TestMain:
         mock_update_changelog: MagicMock,
         mock_commit: MagicMock,
         mock_tag: MagicMock,
+        mock_user: MagicMock,
     ) -> None:
         """If tests fail, release aborts — no commit, no tag."""
         # First call: git rev-parse (master), then make lint-ruff (success),
@@ -510,15 +547,16 @@ class TestMain:
         mock_tag.assert_not_called()
 
     @patch.dict("os.environ", {})
-    @patch("scripts.release.create_and_push_tag")
-    @patch("scripts.release.commit_release_changes")
-    @patch("scripts.release.update_changelog")
-    @patch("scripts.release.update_init_version")
-    @patch("scripts.release.get_changelog", return_value="changelog")
-    @patch("scripts.release.get_latest_tag", return_value="v0.1.0")
-    @patch("scripts.release.get_bumped_version", return_value="0.2.0")
-    @patch("scripts.release.has_unreleased_changes", return_value=True)
-    @patch("scripts.release.run_cmd")
+    @patch("scripts.ci.release.has_user_facing_changes", return_value=True)
+    @patch("scripts.ci.release.create_and_push_tag")
+    @patch("scripts.ci.release.commit_release_changes")
+    @patch("scripts.ci.release.update_changelog")
+    @patch("scripts.ci.release.update_init_version")
+    @patch("scripts.ci.release.get_changelog", return_value="changelog")
+    @patch("scripts.ci.release.get_latest_tag", return_value="v0.1.0")
+    @patch("scripts.ci.release.get_bumped_version", return_value="0.2.0")
+    @patch("scripts.ci.release.has_unreleased_changes", return_value=True)
+    @patch("scripts.ci.release.run_cmd")
     def test_lint_fail_aborts_before_tag(
         self,
         mock_run_cmd: MagicMock,
@@ -530,6 +568,7 @@ class TestMain:
         mock_update_changelog: MagicMock,
         mock_commit: MagicMock,
         mock_tag: MagicMock,
+        mock_user: MagicMock,
     ) -> None:
         """If lint fails, release aborts — no commit, no tag."""
         mock_run_cmd.side_effect = [

tests/unit/test_review_pr.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/review_pr.py."""
+"""Unit tests for scripts/ci/review_pr.py."""
 
 import http
 import json
@@ -9,7 +9,7 @@ import pytest
 from click.testing import CliRunner
 
 from gitea_runner_manager.exceptions import APIError
-from scripts.review_pr import main, parse_comments
+from scripts.ci.review_pr import main, parse_comments
 
 
 class TestParseComments:
@@ -21,7 +21,7 @@ class TestParseComments:
 
     def test_parse_from_stdin(self) -> None:
         comments = [{"path": "a.py", "body": "fix", "new_position": 1}]
-        with patch("scripts.review_pr.sys.stdin") as mock_stdin:
+        with patch("scripts.ci.review_pr.sys.stdin") as mock_stdin:
             mock_stdin.read.return_value = json.dumps(comments)
             assert parse_comments(None, True) == comments
 
@@ -41,26 +41,26 @@ class TestParseComments:
             parse_comments(str(f), False)
 
     def test_stdin_non_list_raises(self) -> None:
-        with patch("scripts.review_pr.sys.stdin") as mock_stdin:
+        with patch("scripts.ci.review_pr.sys.stdin") as mock_stdin:
             mock_stdin.read.return_value = json.dumps({"path": "a.py"})
             with pytest.raises(click.ClickException):
                 parse_comments(None, True)
 
     def test_stdin_invalid_json_raises(self) -> None:
-        with patch("scripts.review_pr.sys.stdin") as mock_stdin:
+        with patch("scripts.ci.review_pr.sys.stdin") as mock_stdin:
             mock_stdin.read.return_value = "not json{"
             with pytest.raises(click.ClickException):
                 parse_comments(None, True)
 
     def test_stdin_empty_returns_empty(self) -> None:
-        with patch("scripts.review_pr.sys.stdin") as mock_stdin:
+        with patch("scripts.ci.review_pr.sys.stdin") as mock_stdin:
             mock_stdin.read.return_value = "   "
             assert parse_comments(None, True) == []
 
 
 class TestMain:
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_successful_comment_review(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.create_review.return_value = {"id": 42}
@@ -75,7 +75,7 @@ class TestMain:
         mock_client.create_review.assert_called_once_with("5", event="COMMENT", body="LGTM", comments=[])
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_successful_approve_review(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.create_review.return_value = {"id": 7}
@@ -87,7 +87,7 @@ class TestMain:
         mock_client.create_review.assert_called_once_with("5", event="APPROVE", body="", comments=[])
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_successful_with_inline_comments(self, mock_client_cls: MagicMock, tmp_path) -> None:
         comments = [{"path": "a.py", "body": "fix", "new_position": 1}]
         f = tmp_path / "comments.json"
@@ -104,7 +104,7 @@ class TestMain:
         mock_client.create_review.assert_called_once_with("5", event="COMMENT", body="", comments=comments)
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_successful_with_stdin_comments(self, mock_client_cls: MagicMock) -> None:
         comments = [{"path": "a.py", "body": "fix", "new_position": 1}]
         mock_client = MagicMock()
@@ -127,7 +127,7 @@ class TestMain:
         assert "REPO_TOKEN" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_no_body_or_comments_for_comment_event(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client_cls.return_value = mock_client
@@ -138,7 +138,7 @@ class TestMain:
         mock_client.create_review.assert_not_called()
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_no_body_or_comments_for_request_changes(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client_cls.return_value = mock_client
@@ -149,7 +149,7 @@ class TestMain:
         mock_client.create_review.assert_not_called()
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_api_error_raises_click(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client.create_review.side_effect = APIError(http.HTTPStatus.INTERNAL_SERVER_ERROR, "server error")
@@ -160,7 +160,7 @@ class TestMain:
         assert "HTTP" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.review_pr.GiteaClient")
+    @patch("scripts.ci.review_pr.GiteaClient")
     def test_invalid_event_choice(self, mock_client_cls: MagicMock) -> None:
         mock_client = MagicMock()
         mock_client_cls.return_value = mock_client

tests/unit/test_sync_wiki.py

@@ -1,5 +1,6 @@
-"""Unit tests for scripts/sync_wiki.py."""
+"""Unit tests for scripts/ci/sync_wiki.py."""
 
+import base64
 import json
 from pathlib import Path
 from unittest.mock import MagicMock, patch
@@ -7,25 +8,58 @@ from unittest.mock import MagicMock, patch
 import pytest
 from click.testing import CliRunner
 
-from scripts.sync_wiki import (
+from scripts.ci.sync_wiki import (
+    decode_content,
+    encode_content,
+    fetch_page_content,
     list_wiki_pages,
     load_mapping,
     main,
     read_doc_content,
     sync_page,
+    verify_wiki_integrity,
+    verify_wiki_page,
 )
 
 
+class TestEncodeContent:
+    def test_encodes_utf8_to_base64(self) -> None:
+        result = encode_content("# Hello World")
+        assert result == base64.b64encode(b"# Hello World").decode("ascii")
+
+    def test_encodes_empty_string(self) -> None:
+        assert encode_content("") == ""
+
+    def test_encodes_unicode(self) -> None:
+        result = encode_content("# Café — résumé")
+        decoded = base64.b64decode(result).decode("utf-8")
+        assert decoded == "# Café — résumé"
+
+
+class TestDecodeContent:
+    def test_decodes_base64_to_utf8(self) -> None:
+        encoded = base64.b64encode(b"# Hello").decode("ascii")
+        assert decode_content(encoded) == "# Hello"
+
+    def test_empty_string_returns_empty(self) -> None:
+        assert decode_content("") == ""
+
+    def test_roundtrip(self) -> None:
+        original = "# Wiki Page\n\nContent with **markdown**."
+        encoded = encode_content(original)
+        assert decode_content(encoded) == original
+
+
 class TestLoadMapping:
     def test_loads_mapping(self, tmp_path: Path) -> None:
         mapping_file = tmp_path / "mapping.json"
         mapping_file.write_text(json.dumps({"user/getting-started.md": "Getting-Started"}))
-        with patch("scripts.sync_wiki.MAPPING_FILE", mapping_file):
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE", mapping_file):
             result = load_mapping()
         assert result == {"user/getting-started.md": "Getting-Started"}
 
     def test_missing_mapping_raises(self, tmp_path: Path) -> None:
-        with patch("scripts.sync_wiki.MAPPING_FILE", tmp_path / "nonexistent.json"):
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE", tmp_path / "nonexistent.json"):
             with pytest.raises(FileNotFoundError):
                 load_mapping()
 
@@ -35,12 +69,12 @@ class TestReadDocContent:
         docs_dir = tmp_path / "docs"
         docs_dir.mkdir()
         (docs_dir / "test.md").write_text("# Test\n\nContent")
-        with patch("scripts.sync_wiki.DOCS_DIR", docs_dir):
+        with patch("scripts.ci.sync_wiki.DOCS_DIR", docs_dir):
             content = read_doc_content("test.md")
         assert content == "# Test\n\nContent"
 
     def test_missing_file_raises(self, tmp_path: Path) -> None:
-        with patch("scripts.sync_wiki.DOCS_DIR", tmp_path):
+        with patch("scripts.ci.sync_wiki.DOCS_DIR", tmp_path):
             with pytest.raises(FileNotFoundError):
                 read_doc_content("nonexistent.md")
 
@@ -57,11 +91,32 @@ class TestListWikiPages:
     def test_returns_page_dict(self) -> None:
         client = MagicMock()
         client._request.return_value.json.return_value = [
-            {"title": "Home", "page_name": "Home"},
-            {"title": "Getting-Started", "page_name": "Getting-Started"},
+            {"title": "Home", "sub_url": "Home"},
+            {"title": "Getting-Started", "sub_url": "Getting-Started.-"},
         ]
         result = list_wiki_pages(client)
-        assert result == {"Home": "Home", "Getting-Started": "Getting-Started"}
+        assert result == {"Home": "Home", "Getting-Started": "Getting-Started.-"}
+
+
+class TestFetchPageContent:
+    def test_fetches_and_decodes_content(self) -> None:
+        client = MagicMock()
+        encoded = base64.b64encode(b"# Hello Wiki").decode("ascii")
+        client._request.return_value.json.return_value = {"content_base64": encoded}
+        result = fetch_page_content(client, "Home")
+        assert result == "# Hello Wiki"
+
+    def test_returns_empty_on_api_error(self) -> None:
+        from gitea_runner_manager.exceptions import APIError
+
+        client = MagicMock()
+        client._request.side_effect = APIError(404, "not found")
+        assert fetch_page_content(client, "Missing") == ""
+
+    def test_returns_empty_for_empty_content(self) -> None:
+        client = MagicMock()
+        client._request.return_value.json.return_value = {"content_base64": ""}
+        assert fetch_page_content(client, "Home") == ""
 
 
 class TestSyncPage:
@@ -71,36 +126,159 @@ class TestSyncPage:
         assert result == "skipped"
         client._request.assert_not_called()
 
-    def test_creates_new_page(self) -> None:
+    def test_creates_new_page_with_base64(self) -> None:
         client = MagicMock()
         result = sync_page(client, "New-Page", "# Content", {}, dry_run=False)
         assert result == "created"
         client._request.assert_called_once()
         call_args = client._request.call_args
         assert call_args.args[0] == "POST"
-        assert call_args.args[1] == "/wiki/page"
+        assert call_args.args[1] == "/wiki/new"
+        # Verify content_base64 is used, not content
+        payload = call_args.kwargs["json"]
+        assert "content_base64" in payload
+        assert "content" not in payload
+        assert base64.b64decode(payload["content_base64"]).decode("utf-8") == "# Content"
 
-    def test_updates_existing_page(self) -> None:
+    def test_updates_existing_page_with_base64(self) -> None:
         client = MagicMock()
-        existing = {"Existing-Page": "Existing-Page"}
+        existing = {"Existing-Page": "Existing-Page.-"}
         result = sync_page(client, "Existing-Page", "# Updated", existing, dry_run=False)
         assert result == "updated"
         client._request.assert_called_once()
         call_args = client._request.call_args
-        assert call_args.args[0] == "PUT"
+        assert call_args.args[0] == "PATCH"
+        assert "/wiki/page/Existing-Page.-" in call_args.args[1]
+        # Verify content_base64 is used
+        payload = call_args.kwargs["json"]
+        assert "content_base64" in payload
+        assert "content" not in payload
+        assert base64.b64decode(payload["content_base64"]).decode("utf-8") == "# Updated"
+
+
+class TestVerifyWikiPage:
+    def test_verifies_matching_content(self) -> None:
+        client = MagicMock()
+        encoded = base64.b64encode(b"# Hello Wiki").decode("ascii")
+        client._request.return_value.json.return_value = {"content_base64": encoded}
+        existing = {"Home": "Home"}
+        assert verify_wiki_page(client, "Home", "# Hello Wiki", existing) is True
+
+    def test_fails_on_mismatch(self) -> None:
+        client = MagicMock()
+        encoded = base64.b64encode(b"# Old Content").decode("ascii")
+        client._request.return_value.json.return_value = {"content_base64": encoded}
+        existing = {"Home": "Home"}
+        assert verify_wiki_page(client, "Home", "# New Content", existing) is False
+
+    def test_fails_on_empty_wiki_content(self) -> None:
+        client = MagicMock()
+        client._request.return_value.json.return_value = {"content_base64": ""}
+        existing = {"Home": "Home"}
+        assert verify_wiki_page(client, "Home", "# Expected", existing) is False
+
+    def test_fails_when_page_not_in_existing(self) -> None:
+        client = MagicMock()
+        assert verify_wiki_page(client, "Missing", "# Content", {}) is False
+
+
+class TestVerifyWikiIntegrity:
+    def _make_client(self, pages: dict[str, str], contents: dict[str, str]) -> MagicMock:
+        """Create a mock client that returns the given pages and contents."""
+        client = MagicMock()
+        # list_wiki_pages calls GET /wiki/pages
+        page_list = [{"title": t, "sub_url": s} for t, s in pages.items()]
+
+        # fetch_page_content calls GET /wiki/page/{sub_url}
+        def mock_request(method, path, **kwargs):
+            resp = MagicMock()
+            if path == "/wiki/pages":
+                resp.json.return_value = page_list
+            elif path.startswith("/wiki/page/"):
+                sub_url = path.replace("/wiki/page/", "")
+                content = contents.get(sub_url, "")
+                encoded = base64.b64encode(content.encode()).decode("ascii") if content else ""
+                resp.json.return_value = {"content_base64": encoded}
+            return resp
+
+        client._request.side_effect = mock_request
+        return client
+
+    def test_all_good_no_failures(self) -> None:
+        pages = {"Home": "Home", "FAQ": "FAQ"}
+        contents = {"Home": "# Home", "FAQ": "# FAQ"}
+        client = self._make_client(pages, contents)
+        mapping = {"index.md": "Home", "faq.md": "FAQ"}
+        synced = {"Home": "# Home", "FAQ": "# FAQ"}
+        failures = verify_wiki_integrity(client, mapping, synced)
+        assert failures == []
+
+    def test_missing_page_detected(self) -> None:
+        pages = {"Home": "Home"}  # FAQ missing from wiki
+        contents = {"Home": "# Home"}
+        client = self._make_client(pages, contents)
+        mapping = {"index.md": "Home", "faq.md": "FAQ"}
+        synced = {"Home": "# Home"}
+        failures = verify_wiki_integrity(client, mapping, synced)
+        assert any("Missing page: FAQ" in f for f in failures)
+
+    def test_stale_page_detected(self) -> None:
+        pages = {"Home": "Home", "Old-Page": "Old-Page"}  # Old-Page not in mapping
+        contents = {"Home": "# Home", "Old-Page": "# Old"}
+        client = self._make_client(pages, contents)
+        mapping = {"index.md": "Home"}
+        synced = {"Home": "# Home"}
+        failures = verify_wiki_integrity(client, mapping, synced)
+        assert any("Stale page" in f and "Old-Page" in f for f in failures)
+
+    def test_page_count_mismatch_detected(self) -> None:
+        pages = {"Home": "Home", "Extra": "Extra"}
+        contents = {"Home": "# Home", "Extra": "# Extra"}
+        client = self._make_client(pages, contents)
+        mapping = {"index.md": "Home"}
+        synced = {"Home": "# Home"}
+        failures = verify_wiki_integrity(client, mapping, synced)
+        assert any("Page count mismatch" in f for f in failures)
+
+    def test_empty_content_detected(self) -> None:
+        pages = {"Home": "Home"}
+        contents = {"Home": ""}  # Empty content
+        client = self._make_client(pages, contents)
+        mapping = {"index.md": "Home"}
+        synced = {"Home": "# Expected Content"}
+        failures = verify_wiki_integrity(client, mapping, synced)
+        assert any("Empty content: Home" in f for f in failures)
+
+    def test_content_mismatch_detected(self) -> None:
+        pages = {"Home": "Home"}
+        contents = {"Home": "# Wrong Content"}
+        client = self._make_client(pages, contents)
+        mapping = {"index.md": "Home"}
+        synced = {"Home": "# Correct Content"}
+        failures = verify_wiki_integrity(client, mapping, synced)
+        assert any("Content mismatch: Home" in f for f in failures)
+
+    def test_multiple_failures_all_reported(self) -> None:
+        pages = {"Home": "Home", "Stale": "Stale"}
+        contents = {"Home": "", "Stale": "# Stale"}
+        client = self._make_client(pages, contents)
+        mapping = {"index.md": "Home", "faq.md": "FAQ"}  # FAQ missing
+        synced = {"Home": "# Home Content"}
+        failures = verify_wiki_integrity(client, mapping, synced)
+        assert len(failures) >= 3  # count mismatch, missing FAQ, stale Stale, empty Home
 
 
 class TestMain:
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"})
-    @patch("scripts.sync_wiki.MAPPING_FILE")
-    @patch("scripts.sync_wiki.DOCS_DIR")
-    @patch("scripts.sync_wiki.GiteaClient")
+    @patch("scripts.ci.sync_wiki.MAPPING_FILE")
+    @patch("scripts.ci.sync_wiki.DOCS_DIR")
+    @patch("scripts.ci.sync_wiki.GiteaClient")
     def test_dry_run(self, mock_client_cls: MagicMock, mock_docs_dir: Path, mock_mapping_file: Path) -> None:
         mock_mapping_file.exists.return_value = True
         mock_mapping_file.__str__ = lambda _: "/docs/mapping.json"
-        with patch("scripts.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
-            with patch("scripts.sync_wiki.read_doc_content", return_value="# Home"):
-                with patch("scripts.sync_wiki.list_wiki_pages", return_value={}):
+        with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+            with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home"):
+                with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={}):
                     runner = CliRunner()
                     result = runner.invoke(main, ["--dry-run", "--repo", "owner/repo"])
         assert result.exit_code == 0
@@ -114,24 +292,24 @@ class TestMain:
         assert "REPO_TOKEN" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok", "GRM_REPO_OWNER": "me", "GRM_REPO_NAME": "myrepo"}, clear=True)
-    @patch("scripts.sync_wiki.GiteaClient")
+    @patch("scripts.ci.sync_wiki.GiteaClient")
     def test_auto_detect_repo(self, mock_client_cls: MagicMock) -> None:
         """Test that repo is auto-detected from env vars when --repo is not passed."""
-        with patch("scripts.sync_wiki.MAPPING_FILE") as mock_mapping:
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
             mock_mapping.exists.return_value = True
-            with patch("scripts.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
-                with patch("scripts.sync_wiki.read_doc_content", return_value="# Home"):
-                    with patch("scripts.sync_wiki.list_wiki_pages", return_value={}):
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={}):
                         runner = CliRunner()
                         result = runner.invoke(main, ["--dry-run"])
         assert result.exit_code == 0
         mock_client_cls.assert_called_once()
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
-    @patch("scripts.sync_wiki.GiteaClient")
+    @patch("scripts.ci.sync_wiki.GiteaClient")
     def test_missing_mapping_file(self, mock_client_cls: MagicMock) -> None:
         """Test that missing mapping.json exits with error."""
-        with patch("scripts.sync_wiki.MAPPING_FILE") as mock_mapping:
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
             mock_mapping.exists.return_value = False
             runner = CliRunner()
             result = runner.invoke(main, ["--repo", "owner/repo"])
@@ -139,28 +317,28 @@ class TestMain:
         assert "mapping.json" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
-    @patch("scripts.sync_wiki.GiteaClient")
+    @patch("scripts.ci.sync_wiki.GiteaClient")
     def test_existing_pages_message(self, mock_client_cls: MagicMock) -> None:
         """Test that existing wiki pages are reported."""
-        with patch("scripts.sync_wiki.MAPPING_FILE") as mock_mapping:
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
             mock_mapping.exists.return_value = True
-            with patch("scripts.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
-                with patch("scripts.sync_wiki.read_doc_content", return_value="# Home"):
-                    with patch("scripts.sync_wiki.list_wiki_pages", return_value={"Home": "Home"}):
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={"Home": "Home"}):
                         runner = CliRunner()
                         result = runner.invoke(main, ["--dry-run", "--repo", "owner/repo"])
         assert result.exit_code == 0
         assert "existing wiki pages" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
-    @patch("scripts.sync_wiki.GiteaClient")
+    @patch("scripts.ci.sync_wiki.GiteaClient")
     def test_file_not_found_warning(self, mock_client_cls: MagicMock) -> None:
         """Test that missing doc files are skipped with a warning."""
-        with patch("scripts.sync_wiki.MAPPING_FILE") as mock_mapping:
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
             mock_mapping.exists.return_value = True
-            with patch("scripts.sync_wiki.load_mapping", return_value={"missing.md": "Missing"}):
-                with patch("scripts.sync_wiki.read_doc_content", side_effect=FileNotFoundError):
-                    with patch("scripts.sync_wiki.list_wiki_pages", return_value={}):
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"missing.md": "Missing"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", side_effect=FileNotFoundError):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={}):
                         runner = CliRunner()
                         result = runner.invoke(main, ["--dry-run", "--repo", "owner/repo"])
         assert result.exit_code == 0
@@ -168,19 +346,138 @@ class TestMain:
         assert "Skipped: 1" in result.output
 
     @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
-    @patch("scripts.sync_wiki.GiteaClient")
+    @patch("scripts.ci.sync_wiki.GiteaClient")
+    def test_empty_doc_file_skipped(self, mock_client_cls: MagicMock) -> None:
+        """Test that empty doc files are skipped with a warning."""
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
+            mock_mapping.exists.return_value = True
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"empty.md": "Empty-Page"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="   \n  "):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={}):
+                        runner = CliRunner()
+                        result = runner.invoke(main, ["--dry-run", "--repo", "owner/repo"])
+        assert result.exit_code == 0
+        assert "empty" in result.output.lower()
+        assert "Skipped: 1" in result.output
+
+    @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
+    @patch("scripts.ci.sync_wiki.GiteaClient")
     def test_create_and_update(self, mock_client_cls: MagicMock) -> None:
         """Test that pages are created and updated correctly (non-dry-run)."""
         mock_client = MagicMock()
         mock_client_cls.return_value = mock_client
-        with patch("scripts.sync_wiki.MAPPING_FILE") as mock_mapping:
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
             mock_mapping.exists.return_value = True
             mapping = {"new.md": "New-Page", "existing.md": "Existing-Page"}
-            with patch("scripts.sync_wiki.load_mapping", return_value=mapping):
-                with patch("scripts.sync_wiki.read_doc_content", return_value="# Content"):
-                    with patch("scripts.sync_wiki.list_wiki_pages", return_value={"Existing-Page": "Existing-Page"}):
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value=mapping):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Content"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={"Existing-Page": "Existing-Page"}):
                         runner = CliRunner()
                         result = runner.invoke(main, ["--repo", "owner/repo"])
         assert result.exit_code == 0
         assert "Created: 1" in result.output
         assert "Updated: 1" in result.output
+
+    @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
+    @patch("scripts.ci.sync_wiki.GiteaClient")
+    def test_verify_passes(self, mock_client_cls: MagicMock) -> None:
+        """Test that --verify passes when content matches."""
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+        encoded = base64.b64encode(b"# Home Content").decode("ascii")
+        # list_wiki_pages returns {"Home": "Home"}, fetch returns encoded content
+        mock_client._request.return_value.json.return_value = {"content_base64": encoded}
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
+            mock_mapping.exists.return_value = True
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home Content"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={"Home": "Home"}):
+                        with patch("scripts.ci.sync_wiki.verify_wiki_page", return_value=True):
+                            runner = CliRunner()
+                            result = runner.invoke(main, ["--repo", "owner/repo", "--verify"])
+        assert result.exit_code == 0
+        assert "Verification passed" in result.output
+
+    @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
+    @patch("scripts.ci.sync_wiki.GiteaClient")
+    def test_verify_fails_on_empty_content(self, mock_client_cls: MagicMock) -> None:
+        """Test that --verify fails when wiki pages have empty content."""
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
+            mock_mapping.exists.return_value = True
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home Content"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={"Home": "Home"}):
+                        with patch("scripts.ci.sync_wiki.verify_wiki_page", return_value=False):
+                            runner = CliRunner()
+                            result = runner.invoke(main, ["--repo", "owner/repo", "--verify"])
+        assert result.exit_code == 1
+        assert "FAIL" in result.output
+
+    @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
+    @patch("scripts.ci.sync_wiki.GiteaClient")
+    def test_verify_skipped_in_dry_run(self, mock_client_cls: MagicMock) -> None:
+        """Test that --verify is skipped during dry-run."""
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
+            mock_mapping.exists.return_value = True
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={}):
+                        runner = CliRunner()
+                        result = runner.invoke(main, ["--dry-run", "--verify", "--repo", "owner/repo"])
+        assert result.exit_code == 0
+        assert "Verification" not in result.output
+
+    @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
+    @patch("scripts.ci.sync_wiki.GiteaClient")
+    def test_strict_passes(self, mock_client_cls: MagicMock) -> None:
+        """Test that --strict passes when integrity check succeeds."""
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
+            mock_mapping.exists.return_value = True
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={"Home": "Home"}):
+                        with patch("scripts.ci.sync_wiki.verify_wiki_integrity", return_value=[]):
+                            runner = CliRunner()
+                            result = runner.invoke(main, ["--repo", "owner/repo", "--strict"])
+        assert result.exit_code == 0
+        assert "Integrity check passed" in result.output
+
+    @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
+    @patch("scripts.ci.sync_wiki.GiteaClient")
+    def test_strict_fails_on_integrity_issues(self, mock_client_cls: MagicMock) -> None:
+        """Test that --strict fails when integrity check finds issues."""
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
+            mock_mapping.exists.return_value = True
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={"Home": "Home"}):
+                        with patch(
+                            "scripts.ci.sync_wiki.verify_wiki_integrity",
+                            return_value=["Missing page: FAQ", "Stale page: Old-Page"],
+                        ):
+                            runner = CliRunner()
+                            result = runner.invoke(main, ["--repo", "owner/repo", "--strict"])
+        assert result.exit_code == 1
+        assert "Integrity check FAILED" in result.output
+        assert "Missing page: FAQ" in result.output
+        assert "Stale page: Old-Page" in result.output
+
+    @patch.dict("os.environ", {"REPO_TOKEN": "tok"}, clear=True)
+    @patch("scripts.ci.sync_wiki.GiteaClient")
+    def test_strict_skipped_in_dry_run(self, mock_client_cls: MagicMock) -> None:
+        """Test that --strict verification is skipped during dry-run."""
+        with patch("scripts.ci.sync_wiki.MAPPING_FILE") as mock_mapping:
+            mock_mapping.exists.return_value = True
+            with patch("scripts.ci.sync_wiki.load_mapping", return_value={"index.md": "Home"}):
+                with patch("scripts.ci.sync_wiki.read_doc_content", return_value="# Home"):
+                    with patch("scripts.ci.sync_wiki.list_wiki_pages", return_value={}):
+                        runner = CliRunner()
+                        result = runner.invoke(main, ["--dry-run", "--strict", "--repo", "owner/repo"])
+        assert result.exit_code == 0
+        assert "Integrity check" not in result.output

tests/unit/test_validate_commit_msg.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/validate_commit_msg.py."""
+"""Unit tests for scripts/ci/validate_commit_msg.py."""
 
 import os
 import subprocess
@@ -8,7 +8,7 @@ from unittest.mock import patch
 from click.testing import CliRunner
 
 from gitea_runner_manager.config import CONVENTIONAL_RE, TASK_ID_RE
-from scripts.validate_commit_msg import first_line, get_branch, main
+from scripts.ci.validate_commit_msg import first_line, get_branch, main
 
 
 class TestHelpers:
@@ -72,7 +72,7 @@ class TestMain:
 
     def test_rejects_task_id_on_feature_branch(self) -> None:
         msg_path = self._write_msg("GRM-19: feat: add feature")
-        with patch("scripts.validate_commit_msg.get_branch", return_value="GRM-19"):
+        with patch("scripts.ci.validate_commit_msg.get_branch", return_value="GRM-19"):
             runner = CliRunner()
             result = runner.invoke(main, [msg_path])
             assert result.exit_code == 1
@@ -80,21 +80,21 @@ class TestMain:
 
     def test_accepts_conventional_on_feature_branch(self) -> None:
         msg_path = self._write_msg("feat: add feature")
-        with patch("scripts.validate_commit_msg.get_branch", return_value="GRM-19"):
+        with patch("scripts.ci.validate_commit_msg.get_branch", return_value="GRM-19"):
             runner = CliRunner()
             result = runner.invoke(main, [msg_path])
             assert result.exit_code == 0
 
     def test_accepts_valid_master_commit(self) -> None:
         msg_path = self._write_msg("GRM-19: feat: add feature")
-        with patch("scripts.validate_commit_msg.get_branch", return_value="master"):
+        with patch("scripts.ci.validate_commit_msg.get_branch", return_value="master"):
             runner = CliRunner()
             result = runner.invoke(main, [msg_path])
             assert result.exit_code == 0
 
     def test_rejects_master_without_task_id(self) -> None:
         msg_path = self._write_msg("feat: add feature")
-        with patch("scripts.validate_commit_msg.get_branch", return_value="master"):
+        with patch("scripts.ci.validate_commit_msg.get_branch", return_value="master"):
             runner = CliRunner()
             result = runner.invoke(main, [msg_path])
             assert result.exit_code == 1
@@ -102,7 +102,7 @@ class TestMain:
 
     def test_rejects_master_with_non_conventional_after_task_id(self) -> None:
         msg_path = self._write_msg("GRM-19: random message")
-        with patch("scripts.validate_commit_msg.get_branch", return_value="master"):
+        with patch("scripts.ci.validate_commit_msg.get_branch", return_value="master"):
             runner = CliRunner()
             result = runner.invoke(main, [msg_path])
             assert result.exit_code == 1
@@ -110,7 +110,7 @@ class TestMain:
 
     def test_rejects_non_conventional_on_feature_branch(self) -> None:
         msg_path = self._write_msg("random message")
-        with patch("scripts.validate_commit_msg.get_branch", return_value="feature"):
+        with patch("scripts.ci.validate_commit_msg.get_branch", return_value="feature"):
             runner = CliRunner()
             result = runner.invoke(main, [msg_path])
             assert result.exit_code == 1
@@ -118,7 +118,7 @@ class TestMain:
 
     def test_accepts_multiline_conventional(self) -> None:
         msg_path = self._write_msg("feat: add feature\n\nBody text.\nMore text.")
-        with patch("scripts.validate_commit_msg.get_branch", return_value="feature"):
+        with patch("scripts.ci.validate_commit_msg.get_branch", return_value="feature"):
             runner = CliRunner()
             result = runner.invoke(main, [msg_path])
             assert result.exit_code == 0
@@ -136,8 +136,8 @@ def test_main_module_block() -> None:
         f.write("GRM-1: feat: test")
         msg_path = f.name
 
-    with patch("scripts.validate_commit_msg.get_branch", return_value="master"):
-        import scripts.validate_commit_msg as vcm
+    with patch("scripts.ci.validate_commit_msg.get_branch", return_value="master"):
+        import scripts.ci.validate_commit_msg as vcm
 
         with open(vcm.__file__) as f:
             source = f.read()