ci: scope PR workflow runs by changed paths (#1067)

## Description

Makes PR workflow runs more selective by routing docs-only changes to
docs validation instead of the full CI workflow, while preserving
workflow validation and existing code/e2e/release gates for applicable
changes.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Added `pull_request.paths-ignore` to `.github/workflows/ci.yml` so
docs/wiki/markdown-only PRs do not queue the general CI workflow.
- Removed `.github/workflows/ci.yml` from the CI internal `code` path
filter so CI-only workflow edits can run workflow validation without
forcing Python/Rust code jobs.
- Added a docs PR validation job to `.github/workflows/docs.yml` for
`docs/**`, `wiki/**`, `mkdocs.yml`, and docs workflow changes.
- Reduced default docs workflow token permissions to `contents: read`,
with `contents: write` scoped only to the deploy job.
- Added docs workflow dry-runs to `scripts/validate-workflows.sh` so
local/CI workflow validation covers the new PR and manual docs paths.

## Testing

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ actionlint .github/workflows/ci.yml .github/workflows/docs.yml
# no output

$ act pull_request -W .github/workflows/docs.yml -n
*DRYRUN* [Deploy Documentation/validate] 🏁  Job succeeded

$ act workflow_dispatch -W .github/workflows/docs.yml -n
*DRYRUN* [Deploy Documentation/deploy] 🏁  Job succeeded

$ act pull_request -W .github/workflows/ci.yml -n
*DRYRUN* [CI/changes] 🏁  Job succeeded
*DRYRUN* [CI/commitlint] 🏁  Job succeeded

$ python -m mkdocs build
INFO    -  Documentation built in 1.28 seconds

$ bash scripts/validate-workflows.sh
# completed successfully; act dry-runs passed. Some unsupported runner-platform matrix entries are skipped by local act, as before.

$ git diff --check
# no output
```

## Real Behavior Proof

- Environment: Windows local checkout, branch `smart-pr-runs`, `act`
0.2.87, temporary local `actionlint` installed via `go install`.
- Exact command / steps: Ran `actionlint` against changed workflows,
`act` dry-runs for docs PR/manual paths and CI PR path, actual `python
-m mkdocs build`, full `scripts/validate-workflows.sh`, and `git diff
--check`.
- Observed result: Changed workflows lint cleanly; docs PR and manual
docs workflow paths dry-run successfully; CI PR dry-run still covers
`changes` and `commitlint`; MkDocs builds; repository workflow
validation script completes with the new docs dry-runs included.
- Not tested: Full non-dry-run GitHub Actions execution on hosted
runners before PR creation.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A.

## Additional Notes

- No issue is linked because this PR was not opened for a specific
tracked issue.
- `mkdocs build` reports existing docs/nav warnings but exits
successfully; strict mode currently fails on existing warnings, so the
PR validation uses the deploy-compatible non-strict build.
- Python unit/lint/type checks are not applicable to this workflow-only
change.

Author: JerrettDavis

.github/workflows/ci.yml

@@ -16,6 +16,10 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - 'wiki/**'
+      - '**/*.md'
   workflow_dispatch:
 
 permissions:
@@ -54,7 +58,6 @@ jobs:
               - 'Cargo.lock'
               - 'tests/**'
               - 'scripts/**'
-              - '.github/workflows/ci.yml'
             e2e:
               - 'headroom/**'
               - 'crates/**'

.github/workflows/docs.yml

@@ -1,6 +1,13 @@
 name: Deploy Documentation
 
 on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'wiki/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
   push:
     branches:
       - main
@@ -11,11 +18,39 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
+  validate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Cache pip
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-docs-${{ hashFiles('mkdocs.yml') }}
+          restore-keys: ${{ runner.os }}-pip-docs-
+
+      - name: Install dependencies
+        run: pip install mkdocs-material
+
+      - name: Build docs
+        run: mkdocs build
+
   deploy:
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v6
         with:

scripts/validate-workflows.sh

@@ -34,4 +34,6 @@ run_act act release -W .github/workflows/release.yml -e .github/act/release-publ
 run_act act push -W .github/workflows/release-please.yml -e .github/act/push-feat.json -n
 run_act act pull_request_target -W .github/workflows/pr-health.yml -e .github/act/pr-governance-invalid.json -n
 run_act act pull_request_target -W .github/workflows/pr-health.yml -e .github/act/pr-governance-valid.json -n
+run_act act pull_request -W .github/workflows/docs.yml -n
+run_act act workflow_dispatch -W .github/workflows/docs.yml -n
 run_act act workflow_dispatch -W .github/workflows/docker.yml -e .github/act/docker-version.json -n