From f13eb47947baa1e55b7f668d75085530d63c8c18 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 22 Oct 2026 22:55:50 +0000 Subject: [PATCH 1/5] ci: run doc gates when AGENTS.md changes AGENTS.md is now the real agent instructions file (spec 027 OD-1); CLAUDE.md is a symlink to it. Co-Authored-By: Claude Haiku 5.5 Signed-off-by: Claude --- .github/workflows/ci.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 26d9ee778..6bf6d38b9 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -30,6 +30,7 @@ on: - "mcp-server/README.md" - "telemetry-receiver/README.md" - "CHANGELOG.md" + - "AGENTS.md" - "CLAUDE.md" - "LICENSE" - "specs/**/outreach.md" @@ -345,10 +346,11 @@ jobs: - 'charts/gameplane/Chart.yaml' # Non-docs/ link targets referenced from the audited files # (docs/dependencies.md -> CHANGELOG.md, docs/contributing.md - # -> CLAUDE.md and specs/012-.../outreach.md, README.md -> + # -> AGENTS.md and specs/012-.../outreach.md, README.md -> # LICENSE, signing/cosign.pub, docs/key-rotation.md -> the legacy key # files) — renaming or moving any of these must run check-links. - 'CHANGELOG.md' + - 'AGENTS.md' - 'CLAUDE.md' - 'LICENSE' - 'signing/cosign.pub' From a79e247e7265b8c098b06088b44256f0816e4c0c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 22 Oct 2026 22:56:01 +0000 Subject: [PATCH 2/5] docs: clarify submodule init and Makefile scope in AGENTS.md Co-Authored-By: Claude Haiku 5.5 Signed-off-by: Claude --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 83a9752e8..605d31a75 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,9 +65,9 @@ go.work links all 17 Go modules (incl. test/e2e) Makefile canonical task runner ``` -After cloning: `git submodule update --init` (`modules/` required for `make dev-up`; `website/` optional). +After cloning: `git submodule update --init modules` (required for `make dev-up`); add `git submodule update --init website` only when working on the website. -## Commands (always via Makefile) +## Commands (via Makefile; compile checks excepted, see rule 8) - **Dev:** `make dev-up` (Kind + OCI registry :5001 + Helm), `make web-dev` (Vite, proxies in-cluster API), `make dev-load` (load built images; run `make images` first), `make dev-install` (Helm upgrade), `make dev-down`. - **Build:** `make build` (all Go + web), `make build-go` (15 modules in GO_MODULES, all but test/e2e), `make build-web` (`npm ci && npm run build`), `make images`. From 51f652f3a285031e8d6be83aebf339653d8998ac Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 25 Oct 2026 00:05:09 +0000 Subject: [PATCH 3/5] chore: bump website submodule Picks up GameplanePanel/website#25 (first-PR guide link, spec 027 T005). Co-Authored-By: Claude Haiku 5.5 Signed-off-by: Claude --- website | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website b/website index ae950983a..88a9229c6 160000 --- a/website +++ b/website @@ -1 +1 @@ -Subproject commit ae950983a4c2e9935f937d68f49e6f3e1c5bffc3 +Subproject commit 88a9229c6a15dc363122c3b073cca0deb3096397 From 610215f370ad69fc634b8b5aaa75c3ee1b1c32a2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 25 Oct 2026 00:05:39 +0000 Subject: [PATCH 4/5] docs(specs): archive spec 027 All tasks T001-T025 done; #795 and website#25 merged. Self-references inside the archived folder stay as written, as in done_024. Co-Authored-By: Claude Opus 5.5 (1M context) Signed-off-by: Claude --- specs/028-split-big-packages/spec.md | 2 +- specs/028-split-big-packages/tasks.md | 2 +- .../OPEN-DECISIONS.md | 0 .../checklists/requirements.md | 0 .../contracts/first-pr-section.md | 0 .../contracts/layout-doc.md | 0 .../data-model.md | 0 .../plan.md | 0 .../research.md | 0 .../spec.md | 0 .../tasks.md | 6 +++--- 11 files changed, 5 insertions(+), 5 deletions(-) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/OPEN-DECISIONS.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/checklists/requirements.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/contracts/first-pr-section.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/contracts/layout-doc.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/data-model.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/plan.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/research.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/spec.md (100%) rename specs/{027-contributor-docs-layout-map => done_027-contributor-docs-layout-map}/tasks.md (97%) diff --git a/specs/028-split-big-packages/spec.md b/specs/028-split-big-packages/spec.md index 357dd06c5..cbcf728d7 100644 --- a/specs/028-split-big-packages/spec.md +++ b/specs/028-split-big-packages/spec.md @@ -15,7 +15,7 @@ v1 is the 20 audit issues #712–#731 plus codebase cleanup, with no new feature defines the target layout; this spec applies it to the code. Spec 029 (faster e2e buckets) waits for spec 023. -Target layout, settled in spec 027 (`specs/027-contributor-docs-layout-map/OPEN-DECISIONS.md`, +Target layout, settled in spec 027 (`specs/done_027-contributor-docs-layout-map/OPEN-DECISIONS.md`, valgul 2026-10-20). This spec applies it and does not reopen it: - **027 OD-3, Go modules.** Long-running services use a thin `cmd/main.go` plus diff --git a/specs/028-split-big-packages/tasks.md b/specs/028-split-big-packages/tasks.md index e0ab684fe..6637ad4a0 100644 --- a/specs/028-split-big-packages/tasks.md +++ b/specs/028-split-big-packages/tasks.md @@ -15,7 +15,7 @@ description: "Task list for 028 split big packages and files" ## Phase 1: Setup - [X] T001 Settle OD-1..OD-10 in `OPEN-DECISIONS.md` and fold them into spec, plan and these tasks (valgul, 2026-10-20/21) -- [ ] T002 Confirm spec 027's `docs/layout.md` has merged to master (027 implementation PR); if not, follow `specs/027-contributor-docs-layout-map/OPEN-DECISIONS.md` and cite it in every brief +- [ ] T002 Confirm spec 027's `docs/layout.md` has merged to master (027 implementation PR); if not, follow `specs/done_027-contributor-docs-layout-map/OPEN-DECISIONS.md` and cite it in every brief - [ ] T003 Re-measure on current master: production files over 500 lines (Go, web), files per package for `api/internal/handlers` and `operator/internal/controller`, and record the SHA and numbers at the top of `research.md` ## Phase 2: Foundational (blocks every move PR) diff --git a/specs/027-contributor-docs-layout-map/OPEN-DECISIONS.md b/specs/done_027-contributor-docs-layout-map/OPEN-DECISIONS.md similarity index 100% rename from specs/027-contributor-docs-layout-map/OPEN-DECISIONS.md rename to specs/done_027-contributor-docs-layout-map/OPEN-DECISIONS.md diff --git a/specs/027-contributor-docs-layout-map/checklists/requirements.md b/specs/done_027-contributor-docs-layout-map/checklists/requirements.md similarity index 100% rename from specs/027-contributor-docs-layout-map/checklists/requirements.md rename to specs/done_027-contributor-docs-layout-map/checklists/requirements.md diff --git a/specs/027-contributor-docs-layout-map/contracts/first-pr-section.md b/specs/done_027-contributor-docs-layout-map/contracts/first-pr-section.md similarity index 100% rename from specs/027-contributor-docs-layout-map/contracts/first-pr-section.md rename to specs/done_027-contributor-docs-layout-map/contracts/first-pr-section.md diff --git a/specs/027-contributor-docs-layout-map/contracts/layout-doc.md b/specs/done_027-contributor-docs-layout-map/contracts/layout-doc.md similarity index 100% rename from specs/027-contributor-docs-layout-map/contracts/layout-doc.md rename to specs/done_027-contributor-docs-layout-map/contracts/layout-doc.md diff --git a/specs/027-contributor-docs-layout-map/data-model.md b/specs/done_027-contributor-docs-layout-map/data-model.md similarity index 100% rename from specs/027-contributor-docs-layout-map/data-model.md rename to specs/done_027-contributor-docs-layout-map/data-model.md diff --git a/specs/027-contributor-docs-layout-map/plan.md b/specs/done_027-contributor-docs-layout-map/plan.md similarity index 100% rename from specs/027-contributor-docs-layout-map/plan.md rename to specs/done_027-contributor-docs-layout-map/plan.md diff --git a/specs/027-contributor-docs-layout-map/research.md b/specs/done_027-contributor-docs-layout-map/research.md similarity index 100% rename from specs/027-contributor-docs-layout-map/research.md rename to specs/done_027-contributor-docs-layout-map/research.md diff --git a/specs/027-contributor-docs-layout-map/spec.md b/specs/done_027-contributor-docs-layout-map/spec.md similarity index 100% rename from specs/027-contributor-docs-layout-map/spec.md rename to specs/done_027-contributor-docs-layout-map/spec.md diff --git a/specs/027-contributor-docs-layout-map/tasks.md b/specs/done_027-contributor-docs-layout-map/tasks.md similarity index 97% rename from specs/027-contributor-docs-layout-map/tasks.md rename to specs/done_027-contributor-docs-layout-map/tasks.md index b026f9442..cffef1637 100644 --- a/specs/027-contributor-docs-layout-map/tasks.md +++ b/specs/done_027-contributor-docs-layout-map/tasks.md @@ -99,9 +99,9 @@ description: "Task list for spec 027: contributor docs and layout map" ## Phase 7: Review and delivery - [X] T022 Tier-up review (`sonnet`) of the combined GP and WEB diffs against spec FR-001..FR-020 and this task list; fixes go to a new `haiku` fix wave -- [ ] T023 Push both branches; open WEB PR (`type: docs`) and GP PR (`type: docs`, `area: specs`, `area: shared`); check CI green and every CodeRabbit finding fixed or settled before calling either ready -- [ ] T024 After the WEB PR merges: bump the `website` submodule pointer in GP (`chore: bump website submodule`) in its own PR -- [ ] T025 After every PR merges: mark tasks `[X]`, `git mv specs/027-contributor-docs-layout-map specs/done_027-contributor-docs-layout-map` and update references in the same commit (rule 16); tell spec 028 that `docs/layout.md` is on `master` +- [X] T023 Push both branches; open WEB PR (`type: docs`) and GP PR (`type: docs`, `area: specs`, `area: shared`); check CI green and every CodeRabbit finding fixed or settled before calling either ready +- [X] T024 After the WEB PR merges: bump the `website` submodule pointer in GP (`chore: bump website submodule`) in its own PR +- [X] T025 After every PR merges: mark tasks `[X]`, `git mv specs/027-contributor-docs-layout-map specs/done_027-contributor-docs-layout-map` and update references in the same commit (rule 16); tell spec 028 that `docs/layout.md` is on `master` --- From 6e11ff1adee695b28c7860493a2cd8d7e793ad32 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 25 Oct 2026 00:12:37 +0000 Subject: [PATCH 5/5] docs(specs): point archived spec 027 at its new path Co-Authored-By: Claude Haiku 5.5 Signed-off-by: Claude --- specs/done_027-contributor-docs-layout-map/plan.md | 4 ++-- specs/done_027-contributor-docs-layout-map/tasks.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/done_027-contributor-docs-layout-map/plan.md b/specs/done_027-contributor-docs-layout-map/plan.md index 55ca169d7..5608adecc 100644 --- a/specs/done_027-contributor-docs-layout-map/plan.md +++ b/specs/done_027-contributor-docs-layout-map/plan.md @@ -2,7 +2,7 @@ **Branch**: `claude/project-thread-yulzhu` (spec docs) | **Date**: 2026-10-20 | **Spec**: [spec.md](./spec.md) -**Input**: Feature specification from `specs/027-contributor-docs-layout-map/spec.md` +**Input**: Feature specification from `specs/done_027-contributor-docs-layout-map/spec.md` ## Summary @@ -87,7 +87,7 @@ New section near the top of `docs/contributing.md` per [contracts/first-pr-secti ### Documentation (this feature) ```text -specs/027-contributor-docs-layout-map/ +specs/done_027-contributor-docs-layout-map/ ├── spec.md ├── OPEN-DECISIONS.md ├── research.md diff --git a/specs/done_027-contributor-docs-layout-map/tasks.md b/specs/done_027-contributor-docs-layout-map/tasks.md index cffef1637..105c33d78 100644 --- a/specs/done_027-contributor-docs-layout-map/tasks.md +++ b/specs/done_027-contributor-docs-layout-map/tasks.md @@ -5,7 +5,7 @@ description: "Task list for spec 027: contributor docs and layout map" # Tasks: Contributor Docs and Layout Map -**Input**: Design documents from `specs/027-contributor-docs-layout-map/` +**Input**: Design documents from `specs/done_027-contributor-docs-layout-map/` **Prerequisites**: [plan.md](./plan.md), [spec.md](./spec.md), [research.md](./research.md), [data-model.md](./data-model.md), [contracts/](./contracts/) @@ -27,7 +27,7 @@ description: "Task list for spec 027: contributor docs and layout map" ## Phase 1: Setup - [X] T001 Create branch `claude/027-contributor-docs` in GP from latest `master` (after the spec docs PR merges) and `claude/027-contributing-pointer` in WEB from latest `main` (done on `claude/project-thread-y09b3k` in both repos, the thread branch) -- [X] T002 Re-measure on the new `master` the facts the docs will state (research R1–R4: symlink modes, `AGENT.md` references, `specs.md` count, module shapes, largest web files) and record the SHA and any drift at the top of `specs/027-contributor-docs-layout-map/research.md` +- [X] T002 Re-measure on the new `master` the facts the docs will state (research R1–R4: symlink modes, `AGENT.md` references, `specs.md` count, module shapes, largest web files) and record the SHA and any drift at the top of `specs/done_027-contributor-docs-layout-map/research.md` ---