ci: exclude comment-only prose from touched-requirements scan; gate.yml -> make -C ci gate

HAND-OFF 1 (make -C ci gate parity).

touched-requirements.sh gained a third scoping rule: after stripping the diff
marker, whole-line YAML/shell `#` comments are dropped BEFORE the R-ID grep. A
requirement cited only in a code-file comment is prose (a REFERENCE), not a
declaration -- the same logic rule 2 already applies to `*.md`. This unblocks the
self-referential trap where editing gate.yml's header (which cites R-TEST-06, a
known-uncovered ID enforced by the spec-immutability STAGE, not a Chainsaw test)
re-attributed R-TEST-06 so the coverage `--require` check false-blocked the merge.
Conservative: only whole-line comments are dropped; an R-ID on a real code/spec
line is still detected, and authoritative declarations never live in a bare comment.

gate.yml now invokes the aggregate `make -C ci gate` (ci/gate.sh) instead of the
individual stage scripts, so CI runs byte-for-byte the same gate a human runs in the
devcontainer (R-TEST-02) and applies the R-TEST-03 decision. A BLOCKED gate exits
non-zero and fails the job. The cluster-gated L2/L3 stage SKIPS honestly (no
CLUSTER_AVAILABLE). spec-immutability is retained as an explicit early UI step.

Adds ci/tests/touched-requirements.test.sh (+ `make -C ci test`) asserting rule 3:
comment-only R-IDs (added or removed) are not attributed while real-line R-IDs are.
ci/lib.sh REPO_ROOT is now env-overridable so tests can run the real script against a
throwaway git repo (default unchanged).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

ci/touched-requirements.sh

@@ -49,7 +49,7 @@ changed_files() {
 # The ADDED/REMOVED lines of the change, for the R-ID content scan — excluding
 # documentation.
 #
-# TWO scoping rules, both learned from the gate blocking merges it should not have:
+# THREE scoping rules, all learned from the gate blocking merges it should not have:
 #
 #  1. Scan the DIFF, not whole file contents. Grepping whole files meant a change
 #     inherited every requirement those files had EVER mentioned, on lines the author
@@ -66,14 +66,36 @@ changed_files() {
 #     that matter (conformance/, schemas/, catalog/, clusters/, ci/) are covered by
 #     the path->requirement fallback regardless of file type.
 #
+#  3. Skip COMMENT-ONLY lines in non-Markdown files — rule 2's logic, applied to the
+#     prose that lives INSIDE code files. A requirement ID cited in a YAML/shell `#`
+#     comment is documentation, not a declaration, exactly like an ID in a `*.md` file.
+#     Rule 2 drops whole Markdown files, but a `.gitea/workflows/*.yml` or `ci/*.sh`
+#     HEADER that explains a requirement would otherwise re-attribute it. Concretely:
+#     gate.yml's header cites R-TEST-06 (enforced by the spec-immutability STAGE, not by
+#     any Chainsaw test, so a known-uncovered ID); before this rule, editing that comment
+#     re-attributed R-TEST-06 and the coverage `--require` check false-blocked the merge —
+#     the same self-referential trap rule 2 fixed for `*.md`. Applied in main()'s content
+#     scan (see there): after the diff marker is stripped, a line whose first non-blank
+#     character is `#` is dropped BEFORE the R-ID grep. Deliberately conservative — only
+#     WHOLE-LINE comments are dropped; an R-ID on a real code/spec line is still detected
+#     (authoritative declarations — test tags, policies, ServiceDefinitions — are never a
+#     bare comment), so this only narrows PROSE, never a declaration.
+#
 # Removed lines count: deleting a test's requirement tag, or a policy's self-declared
 # ID, touches that requirement just as much as adding one.
-# `:(exclude)*.md` drops Markdown from the content scan (rule 2 above). Three-dot to
-# match changed_files(): changes on this branch since it diverged from base.
+# `:(exclude)*.md` drops Markdown from the content scan (rule 2 above).
+# `:(exclude)ci/tests/` drops this dir's OWN unit-test fixtures: those files embed example
+#   R-IDs as DATA (asserting the scan's behaviour), never as declarations — the same
+#   "reference, not declaration" logic as rule 2. Their gate coverage is unaffected: any
+#   ci/ change (ci/tests/ included) still attributes R-GITOPS-01/R-TEST-02/R-TEST-03 via the
+#   path->requirement map below. NOTE: this excludes ci/tests/ only — conformance/tests/
+#   carry AUTHORITATIVE `conformance.home.k3s/R-*` labels and are deliberately still scanned.
+# Three-dot to match changed_files(): changes on this branch since it diverged from base.
 changed_diff() {
   local base; base="$(resolve_base)"
-  if git -C "$REPO_ROOT" diff -U0 "${base}...HEAD" -- . ':(exclude)*.md' 2>/dev/null; then return; fi
-  git -C "$REPO_ROOT" diff -U0 "${base}" -- . ':(exclude)*.md' 2>/dev/null || true
+  local -a excl=(':(exclude)*.md' ':(exclude)ci/tests/')
+  if git -C "$REPO_ROOT" diff -U0 "${base}...HEAD" -- . "${excl[@]}" 2>/dev/null; then return; fi
+  git -C "$REPO_ROOT" diff -U0 "${base}" -- . "${excl[@]}" 2>/dev/null || true
 }
 
 # Coarse path -> requirement map. Deliberately conservative; extend as subtrees
@@ -109,9 +131,15 @@ main() {
 
   # Self-declared R-IDs on the ADDED/REMOVED lines of the change (see changed_diff).
   # `^[+-]` keeps hunk headers (`@@`) and the `+++`/`---` file headers out of scope.
+  # `sed 's/^[+-]//'` then strips the single-char diff marker (safe: -U0 emits one), so
+  #   what remains is the SOURCE line, and `grep -vE '^[[:space:]]*#'` drops whole-line
+  #   YAML/shell comments (rule 3 in changed_diff's header) BEFORE the R-ID grep — a
+  #   requirement cited only in a `#` comment is prose, not a declaration.
   reqs+=" $(changed_diff \
     | grep -E '^[+-]' \
     | grep -vE '^(\+\+\+|---)' \
+    | sed -E 's/^[+-]//' \
+    | grep -vE '^[[:space:]]*#' \
     | grep -hoE 'R-[A-Z]+-[0-9]+' \
     | tr '\n' ' ' || true)"