docs(416): note shallow-checkout FETCH_HEAD/two-dot fix (ci-cd + decisions)

Refs #416

docs/ci-cd.md

@@ -316,6 +316,15 @@ files) has nothing for the heavy jobs to validate. Before this, such a change ra
 is gated `if: steps.detect.outputs.docs_only != 'true'`. On a docs-only change the job runs only
 checkout + detect and **reports `success` in seconds**.
 
+**Shallow-checkout safe (the change-set diff).** `test`/`migrations` check out `fetch-depth: 1`, and
+a shallow clone has **no `origin/<base>` tracking ref and no merge-base** — so a three-dot
+`origin/main...HEAD` diff *errors*, the fail-safe returns `docs_only=false`, and the skip silently
+never fires (the first cut shipped this bug — every docs-only PR still ran the full matrix; caught by
+#416's "verify on a real PR" box). The script therefore fetches the base and diffs against
+**`FETCH_HEAD`** (always written by `git fetch`, resolves in a shallow clone) with a **two-dot** tree
+diff (`git diff --no-renames FETCH_HEAD HEAD`) — no merge-base required. (`api-docs`/`format` avoided
+the bug only because they check out `fetch-depth: 0`.)
+
 The jobs are **not** `if:`-skipped. That is deliberate and it is the whole trap of this issue:
 
 - `main`'s branch protection requires two checks **by name** — `Build ErsatzTV Image / Build & test

docs/decisions.md

@@ -1522,3 +1522,18 @@ part — is skipped.
 Two adjacent redundancies are deliberately **out of scope**: the whole matrix re-running on a PR and
 again on the merge-to-`main` over identical code (#420), and the within-run triple `dotnet build`
 (#398). Full mechanism in `ci-cd.md` → "Docs-only skip".
+## 2026-07-17 — Docs-only detect must be shallow-checkout safe: FETCH_HEAD + two-dot, not origin/main + three-dot (#416 follow-up)
+
+The #416 docs-only skip shipped (#422) safe but **ineffective**: every docs-only PR still ran the full
+matrix. Root cause — `test`/`migrations` check out `fetch-depth: 1`, and in a shallow clone
+`origin/<base>` has no remote-tracking ref and there is no merge-base, so the detect script's
+three-dot `git diff origin/main...HEAD` errored → `|| true` → empty diff → the fail-safe returned
+`docs_only=false` → full matrix. Confirmed in a real shallow `file://` clone (`origin/main` did not
+resolve; three-dot errored; `git diff FETCH_HEAD HEAD` returned the changed files correctly).
+
+Decision: the detect diffs against **`FETCH_HEAD`** (always written by `git fetch`, resolves in a
+shallow clone) with a **two-dot** tree diff (no merge-base). `api-docs`/`format` were unaffected only
+because they use `fetch-depth: 0` — a difference the first cut missed. Meta-lesson reinforced: a CI
+gating change can pass every local test and merge green while being a complete no-op in CI; only
+real-PR verification that **measures the effect** (job durations, not just a green check) catches it —
+which is exactly what #416's Done-when demanded. Fixed in the #416 follow-up PR.