ci: run less on each PR push: trim matrices, filter paths, fold one workflow

.github/workflows/changelog.yml

@@ -8,6 +8,10 @@ name: changelog
 # dokimi/pyproject.toml) adds a changelog fragment under dokimi/changelog.d/ instead of editing CHANGELOG.md, so open PRs never
 # conflict there (dokimi/changelog.d/README.md). The skip-changelog label, for
 # a change with no user-visible effect, turns the check off.
+#
+# The same job lists the docs pages to reread (the docs review triggers below):
+# both diff the PR against its base, and as two workflows each waited for a
+# runner of its own on every push.
 on:
   pull_request:
     types: [opened, synchronize, reopened, labeled, unlabeled]
@@ -26,7 +30,7 @@ defaults:
 # intel-ubuntu-latest: see ci.yml.
 jobs:
   fragment:
-    name: Changelog fragment
+    name: Changelog fragment, docs review triggers
     runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
@@ -39,10 +43,30 @@ jobs:
       # The base branch's current tip (fetched by the checkout), as in the
       # other diff-against-base steps.
       - name: Fragment for package changes
+        if: ${{ !cancelled() }}
         env:
           BASE_REF: ${{ github.event.pull_request.base.ref }}
           SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'skip-changelog') }}
         run: |
           skip=()
           if [ "$SKIP" = true ]; then skip=(--skip-label); fi
           python scripts/check_changelog_fragment.py --base "origin/$BASE_REF" --head HEAD "${skip[@]}"
+      # Lists the docs pages whose `depends_on` front matter matches a file this PR
+      # changes while the PR leaves the page alone, in the job summary and as a
+      # warning on each page (scripts/check_docs_review_triggers.py). A prompt to
+      # reread the page, not a gate: findings never fail the step (only a malformed
+      # depends_on or an undiffable base does). It posts no PR comment, so a fork
+      # PR's read-only token is enough. That every glob still matches a file is
+      # checked by tests/test_docs_review_triggers.py in ci.yml. Runs after a
+      # missing fragment too (!cancelled()), so one finding does not hide the other.
+      # PyYAML from the hashed tools lock, like every other install (#135).
+      # `make dev` reads this line through scripts/ci_local.py tools, and its
+      # uv --require-hashes rejects a bare requirement.
+      - name: Install the CI tools (PyYAML)
+        if: ${{ !cancelled() }}
+        run: pip install --require-hashes -r requirements-ci.lock.txt
+      - name: Docs pages to review
+        if: ${{ !cancelled() }}
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: python scripts/check_docs_review_triggers.py --base "origin/$BASE_REF" --head HEAD

.github/workflows/ci.yml

@@ -163,11 +163,21 @@ jobs:
         include:
           - python-version: '3.14'
             coverage: true
+        # A PR runs the two ends, 3.11 (the floor) and 3.14 (the coverage leg);
+        # the middle versions run on main, weekly and on dispatch. A break on
+        # 3.12 or 3.13 alone is rare and shows on main right after the merge.
+        # Excluded by expression, not by a computed list: ci_local.py reads
+        # python-version as a list. On other events the entries match no leg.
+        exclude:
+          - python-version: ${{ github.event_name == 'pull_request' && '3.12' || 'none' }}
+          - python-version: ${{ github.event_name == 'pull_request' && '3.13' || 'none' }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-          fetch-depth: 0
+          # Full history on the coverage leg only: the changed-lines gate diffs
+          # against the base branch. The other legs need the tree alone.
+          fetch-depth: ${{ matrix.coverage && '0' || '1' }}
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
@@ -273,6 +283,10 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ['3.11', '3.13']
+        # A PR runs the floor only, which is what this job is for; 3.13 runs on
+        # main, weekly and on dispatch (see the test matrix above).
+        exclude:
+          - python-version: ${{ github.event_name == 'pull_request' && '3.13' || 'none' }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:

.github/workflows/cli-interface.yml

@@ -12,8 +12,18 @@ name: cli-interface
 # matches the base again. The check reports; it never fails a PR for a change.
 # Fork PRs get a read-only token, so there the label and comment are skipped and
 # the CLI diff is shown only in the job summary.
+# Only for a PR that touches what the surface is dumped from (the package and
+# cli.py), the dump script or the lock it runs on. Once a PR touches one of
+# them the filter keeps matching (it compares the whole PR with its base), so a
+# later push that reverts the change still runs and clears the label.
 on:
   pull_request:
+    paths:
+      - 'dokimi/dokimi/**'
+      - 'dokimi/cli.py'
+      - 'dokimi/scripts/cli_surface.py'
+      - 'dokimi/requirements.lock.txt'
+      - '.github/workflows/cli-interface.yml'
 
 permissions:
   contents: read

.github/workflows/codeql.yml

@@ -11,8 +11,14 @@ name: codeql
 on:
   push:
     branches: [main]
+  # A PR that changes no Python and no workflow has nothing for either language
+  # to analyse; push and the weekly schedule still scan the whole tree.
   pull_request:
     branches: [main]
+    paths:
+      - '**.py'
+      - '.github/workflows/**'
+      - '.github/actions/**'
   schedule:
     - cron: '23 4 * * 1'
 

.github/workflows/docs.yml

@@ -13,7 +13,17 @@ name: docs
 on:
   push:
     branches: [ main ]
+  # Not for a PR that changes only tests, changelog fragments or other workflows:
+  # the site is built from docs/, the package (API and CLI reference) and pages
+  # that link anywhere else in the tree, but never into tests/ or .github/.
+  # (No check is required on main, so a skipped workflow blocks no merge.)
   pull_request:
+    paths:
+      - '**'
+      - '!dokimi/tests/**'
+      - '!dokimi/changelog.d/[0-9]*.md'
+      - '!.github/**'
+      - '.github/workflows/docs.yml'
   workflow_dispatch:
 
 permissions:

dokimi/CONTRIBUTING.md

@@ -226,7 +226,7 @@ When your change touches user-facing behavior, confirm:
 A page in `docs/` names the code it documents in YAML front matter above its
 license header: `depends_on:`, a list of globs from the repository root
 (`dokimi/dokimi/novelty/**`; `**` crosses `/`, while `*` and `?` stay within one
-path segment). The `docs-review-triggers` check is advisory: it lists the page on
+path segment). The docs review triggers step of the `changelog` check is advisory: it lists the page on
 any PR that changes a matching file without touching the page, and those findings
 exit 0. Only a malformed `depends_on` (exit 1) or an undiffable base (exit 2) fails
 the job. `tests/test_docs_review_triggers.py` fails on a glob that matches no