📝 docs(demo): point the SIGPIPE reasoning at the backlog story, not a missing file

Both comments cited hack/test/hyg_sigpipe_pipefail_test.sh for why a large fixture is
required. That gate is parked as its own story and does not exist on main, so the citation
would be a dead path for the first reader who followed it.

The reasoning stays — it is exactly what a future reader needs to not "simplify" the
predicate back to grep -q. Only the pointer changes: lib.sh now says what the smoke test
actually does, and the smoke test names the sharpest remaining instance in the tree
(hack/kind/common.sh's kubectl logs pipeline) and the story that will sweep for it,
GATE-SIGPIPE-02.

Author: konih

hack/demo/hero/lib.sh

@@ -86,7 +86,9 @@ _hero_assert_git_connection_verified() {
 # writing when grep exits, which large output makes near-certain but small output does not
 # make impossible (reproduced here at ~21 KB, well under one 64 KiB pipe buffer). Do not
 # read "it's only a few files" as safe. A small clone usually behaves correctly, which is
-# why only a large fixture reliably catches it — see hack/test/hyg_sigpipe_pipefail_test.sh.
+# why only a large fixture reliably catches it: the smoke test seeds 4000 files precisely
+# so this predicate is exercised past the point where the race is reliably lost. A repo-wide
+# gate for this shape is backlog story GATE-SIGPIPE-02.
 #
 # `wc -l` reads to EOF, so find never sees SIGPIPE. It is preferred over `grep -c` because
 # it exits 0 on a zero count and so needs no `|| true` — and `|| true` would also swallow a

hack/test/demo_03_hero_smoke_test.sh

@@ -138,7 +138,10 @@ pass "job '${JOB_ID}' name='${NAME:-$JOB_ID}' is not the required check"
 # ~21 KB of find output, a third of a pipe buffer — but small output usually wins the race,
 # which is exactly why a one-file fixture passed with either implementation and so tested
 # nothing at all. `wc -l` reads to EOF, so the producer never sees SIGPIPE.
-# See hack/test/hyg_sigpipe_pipefail_test.sh.
+#
+# The same shape exists elsewhere in the tree (`kubectl logs --tail=400 | grep -Eq …` in
+# hack/kind/common.sh is the sharpest). Sweeping for it repo-wide is backlog story
+# GATE-SIGPIPE-02; this file only locks the hero demo's own predicate.
 readonly FIXTURE_FILES=4000
 # Not a safety threshold — see above. It is a floor that keeps the fixture in the range
 # where the race is reliably lost, so this self-check cannot quietly stop testing anything.