CI: docs-only pull requests skip the heavy jobs

[gkoch02]

Summary

Deleting one README line ran all of CI, about five minutes of it: lint, mypy, both full pytest legs, coverage, the golden renders, the JS suite and the wheel build. None of those can be affected by a Markdown edit except the tests that read the docs.

• New changes job. It marks a PR docs-only when every changed path is a *.md outside idle_hours/. It diffs the PR merge commit against its first parent, so fetch-depth: 2 is enough.
• Skipped on a docs-only PR: lint, typecheck, coverage, golden-render, web-ui-js, package-build. A job skipped by its if: reports success to a required status check, so the PR still merges.
• test (3.11) / test (3.12) still run, but only the six modules that read the docs (README rosters, documented script invocations, CLAUDE.md size, the font table, Pi setup text, the release tool). The --once smoke step is skipped.
• Fails safe. Every skippable job is gated on ${{ !cancelled() && needs.changes.outputs.docs_only != 'true' }}. If changes fails, the output is empty, and !cancelled() stops the failed dependency from skipping the job, so everything runs in full. A push, a tag or an empty diff also runs everything.
• New TestDocsOnlyFences in tests/test_ci_required_checks.py:
  • It scans each test module's string constants for a tracked repo doc, either named directly or through a scripts/*.py it loads.
  • It fails if a module that reads a doc is missing from the docs-only pytest step.
  • It also pins the gate expression on every skippable job.
• changes is classified as advisory, with its reason recorded in ADVISORY_JOBS.
• The coverage fence was loosened. It used to require no if: at all; it now accepts only the docs-only gate.

Trade-offs

• Docs-only PRs do not skip the tests outright. The README and docs/runtime.md carry fenced rosters, so a docs edit can break the build. Skipping everything would let that merge green.
• The docs-test list is written out by hand in the workflow. The AST scan exists so it can't silently go stale. Two known false positives are listed with reasons: test_render_quote_themes.py (the semiotic README is a package asset) and the fence's own sanity literal.
• Markdown under idle_hours/ counts as code, because it ships in the wheel.
• Code PRs are unchanged. Most of their time goes into the per-job dependency install and the golden renders; that's a separate fix.

Testing

• ruff check . passes
• pytest passes locally, except tests/test_render_quote.py::TestAstrariumSky::test_a_link_is_its_canonical_zone, which fails identically on unmodified main in the dev container (environment, not this change). 5316 passed.
• New behaviour has a test (TestDocsOnlyFences)
• mypy (pinned version) clean
• Needs a live check: on the first docs-only PR after merge, the six gated jobs should show skipped, not pending. This PR itself touches code, so it runs the full suite.

Appliance impact

None.

Docs

• docs/testing.md CI section describes the changes job and the docs-only path
• README.md: no user-facing change

---

Generated by Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-16T21:54:42.366309Z	e0da4d0	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e0da4d035e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".