From 39b7b2ef29472342ca0d86ad8789f0a62e0674d4 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Thu, 7 May 2026 09:47:27 +0200
Subject: [PATCH] ci: skip docs-only triggers; document per-stage local-ci gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ui-test workflow gains a `!**/*.md` negation so commits touching only
markdown (READMEs, PLAN.md updates, topic docs) no longer kick off the
full Go + Vitest + Playwright pipeline. Mixed commits keep triggering
because at least one positive path (`ui/**`, `gateway/**`, …) still
matches.

Project CLAUDE.md adds a per-stage CI gate section so the local
Gitea Actions runner is exercised at the close of every stage from
any PLAN.md, with the push step pre-authorised.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .gitea/workflows/ui-test.yaml |  6 ++++++
 CLAUDE.md                     | 27 +++++++++++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/.gitea/workflows/ui-test.yaml b/.gitea/workflows/ui-test.yaml
index b57a455..b48dc6d 100644
--- a/.gitea/workflows/ui-test.yaml
+++ b/.gitea/workflows/ui-test.yaml
@@ -19,6 +19,11 @@ on:
       - 'go.work'
       - 'go.work.sum'
       - '.gitea/workflows/ui-test.yaml'
+      # Skip docs-only commits. Negation removes pure markdown changes;
+      # mixed commits (code + .md) still match a positive pattern above
+      # and trigger the workflow. Image and other binary asset paths
+      # are already outside the positive list.
+      - '!**/*.md'
   pull_request:
     paths:
       - 'ui/**'
@@ -29,6 +34,7 @@ on:
       - 'go.work'
       - 'go.work.sum'
       - '.gitea/workflows/ui-test.yaml'
+      - '!**/*.md'
 
 jobs:
   test:
diff --git a/CLAUDE.md b/CLAUDE.md
index bf731d0..eb0def0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -34,6 +34,33 @@ This repository hosts the Galaxy Game project.
   deeper than what fits in `README.md` (per-feature design notes,
   protocol specs, runbooks). Not stage-by-stage history.
 
+## Per-stage CI gate
+
+Every completed stage from any `PLAN.md` (per-service or `ui/PLAN.md`)
+must be exercised on the local Gitea Actions runner before being
+declared done. The runbook lives in `tools/local-ci/README.md`; the
+short version is:
+
+1. Commit the stage changes.
+2. `make -C tools/local-ci push` — pushes `HEAD` to the local Gitea
+   instance and triggers every workflow that matches the changed
+   paths.
+3. Poll the latest run via the API snippet in `ui/docs/testing.md`
+   (or the Gitea UI on `http://localhost:3000`) until it leaves
+   `running`. Inspect the log on failure.
+4. Only after the run is `success` may the stage be marked done in
+   the corresponding `PLAN.md`.
+
+This applies even when the local unit-test suite is green —
+workflow-only failures (path filters, action-version mismatches,
+missing secrets, runner-only environment differences) are cheap to
+catch here and expensive to catch on a remote PR. The push step is
+implicitly authorised: do not ask for confirmation on every stage.
+
+If `tools/local-ci` is not running, bring it up first
+(`make -C tools/local-ci up`); do not skip this gate. The single
+exception is when the user explicitly waives it for a stage.
+
 ## Decisions during stage implementation
 
 Stages from `PLAN.md` produce decisions. Those decisions never live in a