.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:

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