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]>

.gitea/workflows/gate.yml

@@ -1,19 +1,27 @@
 # .gitea/workflows/gate.yml — the ENFORCED PR merge gate (Phase 6, WS-GITOSS).
 #
 # This is the LIVE gate wired to the in-cluster Gitea Actions runner (ns gitea-actions,
-# Docker executor + DinD). It runs the STATIC layers of the conformance gate — the ones
-# docs/14 says run "without a cluster": spec-immutability (best-effort), lint, Kyverno L0,
-# the render==golden reproducibility check, and L1 offline render checks. It is the single
-# required status check on `main`
-# (see branch protection). `make -C ci lint l0 render-golden l1` here is byte-identical to a laptop run
-# (R-TEST-02) — the runner just installs the pinned tools from ci/versions.env first.
+# Docker executor + DinD). It invokes the AGGREGATE merge gate — `make -C ci gate` — so CI
+# runs BYTE-FOR-BYTE the same command a human runs in the devcontainer (R-TEST-02): the
+# runner just installs the pinned tools from ci/versions.env first. `make -C ci gate`
+# (ci/gate.sh) runs every stage in order — spec-immutability, lint, Kyverno L0,
+# render==golden, L1 offline render — and applies the R-TEST-03 decision, printing
+# "MERGE GATE: PASS" / "MERGE GATE: BLOCKED". It is the single required status check on
+# `main` (see branch protection). A non-zero exit fails the job, so a BLOCKED gate blocks
+# the merge.
 #
-# The L2/L3 CONFORMANCE layer (behavioural + fault-injection, needs a live cluster) is
-# NOT wired yet — it is a deliberate design decision (a CI toolchain image + a scoped
-# in-cluster kubeconfig/RBAC for the runner). It is present below as an `if: false`
-# placeholder so the shape is visible and the wiring is a one-line flip once decided.
-# The full pipeline blueprint (spec-checkout, per-layer jobs, decision job) is retained
-# dormant in merge-gate.yaml.
+# The cluster-gated L2/L3 conformance stage SKIPS honestly here (exit 3, surfaced not faked
+# — HARD RULE 4) because this runner declares no cluster: `make -C ci gate` does not set
+# CLUSTER_AVAILABLE, so gate.sh reports the touched requirements UNVERIFIED without blocking
+# Phase-0/6 static work. L2/L3 run as an IN-CLUSTER Chainsaw Job (its own scoped SA; CI holds
+# no broad kubeconfig) driven by the separate `conformance` job below.
+#
+# NOTE (R-TEST-06 / gate-semantics): spec-immutability is ALSO surfaced as its own explicit
+# early step (below) so its result is a distinct, tolerant status in the Gitea UI; gate.sh
+# re-runs it as its first stage, which is the authoritative one. `make -C ci gate` here is
+# the byte-identical laptop gate; the extra pre-step is a read-only git-diff check and is
+# purely additive. The full pipeline blueprint (spec-checkout, per-layer jobs, decision job)
+# is retained dormant in merge-gate.yaml.
 ---
 name: gate
 
@@ -47,19 +55,27 @@ jobs:
           ./.gitea/workflows/scripts/install-tools.sh l0
           ./.gitea/workflows/scripts/install-tools.sh l1
 
-      # R-TEST-06: the spec is read-only to agents. The spec repo is NOT checked out into
-      # CI here (it is a separate repo; SPEC_REPO_SLUG is not wired into this runner), so
-      # the guard honestly SKIPS (exit 3) rather than faking green. A real drift/edit of a
-      # co-located spec would exit 1 and fail. Tolerated: exit 3 only.
-      # Call the script DIRECTLY, not via `make`: GNU make masks a recipe's exit code as
-      # its own 2 on failure, so `make spec-immutability || [ $? -eq 3 ]` would see 2 and
-      # fail. The script itself exits 3 on an honest skip (spec repo not checked out here),
-      # which we tolerate; a real drift/edit exits 1 and fails the gate.
+      # R-TEST-06: the spec is read-only to agents. An EXPLICIT early surfacing of the
+      # spec-immutability check, so its result is a distinct, tolerant status line in the
+      # Gitea UI before the (longer) aggregate gate log. The spec repo is NOT checked out
+      # into CI here (separate repo; SPEC_REPO_SLUG not wired into this runner), so the guard
+      # honestly SKIPS (exit 3) rather than faking green; a real drift/edit of a co-located
+      # spec exits 1 and fails. Tolerated: exit 3 only. Call the script DIRECTLY, not via
+      # `make spec-immutability`: GNU make masks a recipe's exit code as its own 2, so
+      # `make spec-immutability || [ $? -eq 3 ]` would see 2 and fail. The AUTHORITATIVE
+      # spec-immutability run is the FIRST stage of `make -C ci gate` below (gate.sh calls
+      # the script directly, so it sees exit 3 → SKIP, not a mask); this pre-step is a cheap,
+      # read-only git-diff duplicate that only adds early UI signal.
       - name: Spec immutability (R-TEST-06, skips if spec repo absent)
         run: ./ci/spec-immutability.sh || [ "$?" -eq 3 ]
 
-      - name: Static gate — lint + Kyverno L0 + render==golden + L1 render
-        run: make -C ci lint l0 render-golden l1
+      # Aggregate merge gate: byte-for-byte the command a human runs in the devcontainer
+      # (`make -C ci gate` -> ci/gate.sh). Runs spec-immutability, lint, Kyverno L0,
+      # render==golden and L1 render, then the R-TEST-03 decision. Exits non-zero on a
+      # BLOCKED gate, which fails this job. The cluster-gated L2/L3 stage SKIPS here (no
+      # CLUSTER_AVAILABLE) — surfaced as UNVERIFIED, never faked green (see header).
+      - name: Merge gate — make -C ci gate
+        run: make -C ci gate
 
       # NOTE: no actions/upload-artifact step. Gitea Actions rejects upload-artifact@v4
       # ("not supported on GHES" — Gitea does not implement the artifact-v2 backend), which