.planning/ROADMAP.md

@@ -462,3 +462,28 @@ Plans:
 Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.17: CI — let doc-only PRs skip the slow api + harness jobs (BACKLOG)
+
+**Goal:** [Captured for future planning] Make doc-only PRs to `main` mergeable without running the slow `harness` (Playwright e2e + dev-stack bring-up, ~5 min) and `api` (MariaDB integration) jobs, while keeping `fast-checks` (which must run on docs — Phase 13's `format:check` is `prettier --check .` and covers markdown; ~1–2 min).
+
+**The footgun:** branch protection currently requires three contexts — `CI / fast-checks`, `CI / api`, `CI / harness`. The naive fix (`paths-ignore` on the workflow, or path-filtering `harness`) **deadlocks**: on a docs-only PR the required `harness`/`api` contexts never report, so the PR can never merge. A required check that never reports is worse than a slow one.
+
+**Solution (Option A — aggregate gate):**
+- Add a cheap `changes` detector job: `git diff --name-only base...HEAD`, set `code=true` unless every changed path matches `docs/` or `*.md`.
+- Gate the heavy jobs: `api` and `harness` get `needs: changes` + `if: needs.changes.outputs.code == 'true'`.
+- Add an always-running `gate` job: `needs: [fast-checks, api, harness]`, `if: always()`, passes when each dependency `result` is `success` OR `skipped`.
+- Change Gitea branch protection to require `CI / fast-checks` + `CI / gate` (drop the direct `api`/`harness` requirements).
+- Result: docs PR → `api`/`harness` skip, `gate` passes; code PR → all run, `gate` passes only if they succeed. No deadlock because `gate` always reports.
+
+**Gitea caveat:** historically Gitea may not emit a commit-status for a `skipped` job — the always-running `gate` sidesteps that entirely (don't rely on marking `api`/`harness` themselves as skipped-but-required).
+
+**Files:** `.gitea/workflows/ci.yml` + Gitea branch-protection settings.
+**Context:** Surfaced 2026-06-12 while opening the docs-only PR #9, which had to run the full harness. Tags: ci, gitea, branch-protection, docs, performance.
+
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)