From 7725fa3a9c311d40aa3830d22d3bb0db289098fb Mon Sep 17 00:00:00 2001 From: valgulnecron <39313199+ValgulNecron@users.noreply.github.com> Date: Thu, 8 Oct 2026 05:08:31 +0200 Subject: [PATCH] docs: archive spec 022 as done_022-default-telemetry-dashboard GameplanePanel/Gameplane#617 and GameplanePanel/website#13 are merged and every task is done. Move the spec folder and update the in-repo references (API and telemetryschema comments, module specs, design-export manifest) per CLAUDE.md rule 16, and bump the website submodule to main 299251d, which carries the telemetry statement page and provider guide (T096). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HCEuae9std51zttPLx9ZZf Signed-off-by: valgulnecron <39313199+ValgulNecron@users.noreply.github.com> --- api/internal/telemetry/destination.go | 2 +- api/internal/telemetry/telemetry.go | 2 +- design-export/MANIFEST.md | 2 +- .../OPEN-DECISIONS.md | 0 .../checklists/requirements.md | 0 .../contracts/api-telemetry-http.md | 0 .../contracts/install-config.md | 0 .../contracts/receiver-http.md | 0 .../contracts/report-schema.md | 0 .../data-model.md | 0 .../plan.md | 4 ++-- .../quickstart.md | 0 .../research.md | 0 .../spec.md | 0 .../tasks.md | 14 +++++++------- telemetry-receiver/specs.md | 4 ++-- telemetryschema/doc.go | 2 +- telemetryschema/specs.md | 4 ++-- website | 2 +- 19 files changed, 18 insertions(+), 18 deletions(-) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/OPEN-DECISIONS.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/checklists/requirements.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/contracts/api-telemetry-http.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/contracts/install-config.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/contracts/receiver-http.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/contracts/report-schema.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/data-model.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/plan.md (99%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/quickstart.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/research.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/spec.md (100%) rename specs/{022-default-telemetry-dashboard => done_022-default-telemetry-dashboard}/tasks.md (98%) diff --git a/api/internal/telemetry/destination.go b/api/internal/telemetry/destination.go index ed3e184ce..e5f8b3c7e 100644 --- a/api/internal/telemetry/destination.go +++ b/api/internal/telemetry/destination.go @@ -7,7 +7,7 @@ import ( ) // DefaultEndpoint is the project default telemetry destination, ruled in -// specs/022-default-telemetry-dashboard/OPEN-DECISIONS.md OD-1. It must stay +// specs/done_022-default-telemetry-dashboard/OPEN-DECISIONS.md OD-1. It must stay // an https URL (hack/check-telemetry-default.sh enforces this in CI). const DefaultEndpoint = "https://telemetry.gameplane.net/ingest" diff --git a/api/internal/telemetry/telemetry.go b/api/internal/telemetry/telemetry.go index f040b6951..bb39a105d 100644 --- a/api/internal/telemetry/telemetry.go +++ b/api/internal/telemetry/telemetry.go @@ -1,5 +1,5 @@ // Package telemetry sends the install's usage report to its resolved -// destination (specs/022-default-telemetry-dashboard). +// destination (specs/done_022-default-telemetry-dashboard). // // Privacy: the basic report carries only the control-plane version and // total counts. The extended report adds an install ID and environment diff --git a/design-export/MANIFEST.md b/design-export/MANIFEST.md index 8de051893..401785500 100644 --- a/design-export/MANIFEST.md +++ b/design-export/MANIFEST.md @@ -2502,7 +2502,7 @@ Server Settings gets a "Game configuration" section (edit `spec.config` from the ## Spec 022 telemetry notice and settings (2026-10-07) -T041 and T052 of `specs/022-default-telemetry-dashboard/`. New frames sit in an empty region below the Admin Settings row (x 11480–21120, y 25404–28584); no existing frame changed. Destination hosts are samples while OD-1 is unruled: their text nodes are named `host (SAMPLE, OD-1 unruled)` (default) and `host (SAMPLE)` (bundled). +T041 and T052 of `specs/done_022-default-telemetry-dashboard/`. New frames sit in an empty region below the Admin Settings row (x 11480–21120, y 25404–28584); no existing frame changed. Destination hosts are samples while OD-1 is unruled: their text nodes are named `host (SAMPLE, OD-1 unruled)` (default) and `host (SAMPLE)` (bundled). | Object ID | Name | Change | | --- | --- | --- | diff --git a/specs/022-default-telemetry-dashboard/OPEN-DECISIONS.md b/specs/done_022-default-telemetry-dashboard/OPEN-DECISIONS.md similarity index 100% rename from specs/022-default-telemetry-dashboard/OPEN-DECISIONS.md rename to specs/done_022-default-telemetry-dashboard/OPEN-DECISIONS.md diff --git a/specs/022-default-telemetry-dashboard/checklists/requirements.md b/specs/done_022-default-telemetry-dashboard/checklists/requirements.md similarity index 100% rename from specs/022-default-telemetry-dashboard/checklists/requirements.md rename to specs/done_022-default-telemetry-dashboard/checklists/requirements.md diff --git a/specs/022-default-telemetry-dashboard/contracts/api-telemetry-http.md b/specs/done_022-default-telemetry-dashboard/contracts/api-telemetry-http.md similarity index 100% rename from specs/022-default-telemetry-dashboard/contracts/api-telemetry-http.md rename to specs/done_022-default-telemetry-dashboard/contracts/api-telemetry-http.md diff --git a/specs/022-default-telemetry-dashboard/contracts/install-config.md b/specs/done_022-default-telemetry-dashboard/contracts/install-config.md similarity index 100% rename from specs/022-default-telemetry-dashboard/contracts/install-config.md rename to specs/done_022-default-telemetry-dashboard/contracts/install-config.md diff --git a/specs/022-default-telemetry-dashboard/contracts/receiver-http.md b/specs/done_022-default-telemetry-dashboard/contracts/receiver-http.md similarity index 100% rename from specs/022-default-telemetry-dashboard/contracts/receiver-http.md rename to specs/done_022-default-telemetry-dashboard/contracts/receiver-http.md diff --git a/specs/022-default-telemetry-dashboard/contracts/report-schema.md b/specs/done_022-default-telemetry-dashboard/contracts/report-schema.md similarity index 100% rename from specs/022-default-telemetry-dashboard/contracts/report-schema.md rename to specs/done_022-default-telemetry-dashboard/contracts/report-schema.md diff --git a/specs/022-default-telemetry-dashboard/data-model.md b/specs/done_022-default-telemetry-dashboard/data-model.md similarity index 100% rename from specs/022-default-telemetry-dashboard/data-model.md rename to specs/done_022-default-telemetry-dashboard/data-model.md diff --git a/specs/022-default-telemetry-dashboard/plan.md b/specs/done_022-default-telemetry-dashboard/plan.md similarity index 99% rename from specs/022-default-telemetry-dashboard/plan.md rename to specs/done_022-default-telemetry-dashboard/plan.md index 1d1984f45..30d699e28 100644 --- a/specs/022-default-telemetry-dashboard/plan.md +++ b/specs/done_022-default-telemetry-dashboard/plan.md @@ -2,7 +2,7 @@ **Branch**: `feat/default-telemetry-dashboard` (not yet created; the spec-kit script derived `022-default-telemetry-dashboard`) | **Date**: 2026-10-06 | **Spec**: [spec.md](spec.md) -**Input**: Feature specification from `specs/022-default-telemetry-dashboard/spec.md` +**Input**: Feature specification from `specs/done_022-default-telemetry-dashboard/spec.md` ## Summary @@ -109,7 +109,7 @@ No NEEDS CLARIFICATION remains. Every technical unknown is resolved in [research ### Documentation (this feature) ```text -specs/022-default-telemetry-dashboard/ +specs/done_022-default-telemetry-dashboard/ ├── spec.md ├── OPEN-DECISIONS.md # OD-1..OD-5 ruled ├── plan.md # this file diff --git a/specs/022-default-telemetry-dashboard/quickstart.md b/specs/done_022-default-telemetry-dashboard/quickstart.md similarity index 100% rename from specs/022-default-telemetry-dashboard/quickstart.md rename to specs/done_022-default-telemetry-dashboard/quickstart.md diff --git a/specs/022-default-telemetry-dashboard/research.md b/specs/done_022-default-telemetry-dashboard/research.md similarity index 100% rename from specs/022-default-telemetry-dashboard/research.md rename to specs/done_022-default-telemetry-dashboard/research.md diff --git a/specs/022-default-telemetry-dashboard/spec.md b/specs/done_022-default-telemetry-dashboard/spec.md similarity index 100% rename from specs/022-default-telemetry-dashboard/spec.md rename to specs/done_022-default-telemetry-dashboard/spec.md diff --git a/specs/022-default-telemetry-dashboard/tasks.md b/specs/done_022-default-telemetry-dashboard/tasks.md similarity index 98% rename from specs/022-default-telemetry-dashboard/tasks.md rename to specs/done_022-default-telemetry-dashboard/tasks.md index 22c83e898..b20a398d8 100644 --- a/specs/022-default-telemetry-dashboard/tasks.md +++ b/specs/done_022-default-telemetry-dashboard/tasks.md @@ -5,7 +5,7 @@ description: "Task list for feature 022: default telemetry destination, extended # Tasks: Default telemetry destination, extended telemetry, and telemetry dashboard -**Input**: Design documents from `specs/022-default-telemetry-dashboard/` +**Input**: Design documents from `specs/done_022-default-telemetry-dashboard/` **Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [contracts/](contracts/), [quickstart.md](quickstart.md), [OPEN-DECISIONS.md](OPEN-DECISIONS.md) @@ -33,7 +33,7 @@ description: "Task list for feature 022: default telemetry destination, extended **Purpose**: Create the branch, get test sign-off, and wire the new `telemetryschema` module into the build. -- [X] T001 Create branch `feat/default-telemetry-dashboard` from `master` and commit `specs/022-default-telemetry-dashboard/` (`.specify/feature.json` is git-ignored, so it stays local) as `docs(specs): add 022 default telemetry dashboard spec`. +- [X] T001 Create branch `feat/default-telemetry-dashboard` from `master` and commit `specs/done_022-default-telemetry-dashboard/` (`.specify/feature.json` is git-ignored, so it stays local) as `docs(specs): add 022 default telemetry dashboard spec`. - [X] T002 Get **explicit human sign-off** (system override 1) to rewrite these existing tests so they assert the new behaviour. Rewrites must keep or raise coverage and never delete a case without a replacement: - `api/internal/telemetry/telemetry_test.go`: `TestReportOnce_EnabledPostsAnonymousCounts`, `TestReportOnce_SendsAuthHeader`, `TestReportOnce_DisabledSkipsPost`. The reporter's constructor and send path change (research R12). - `api/internal/telemetry/telemetry_branches_test.go`: `TestNew_DefaultsInterval`, `TestEnabled_Branches`, `TestCount_UnknownKind`, `TestReportOnce_EndpointErrorPropagates`. @@ -48,10 +48,10 @@ description: "Task list for feature 022: default telemetry destination, extended - `api/internal/handlers/config_validators_test.go` `TestValidateTelemetry` (added 2026-10-07): the canonical output gains `"extended":false`, and a new case checks that `{"sendMetrics":false,"extended":true}` normalises to both false. **Signed off 2026-10-06** by the user ("Approve all", then "Approve" for the `/metrics` changes; "Assert the seeded default" for `TestConfig_GetEmpty` and "Assert the new shape" for `TestValidateTelemetry` on 2026-10-07). Record the sign-off in the PR description. -- [X] T003 Create `telemetryschema/go.mod` (`module github.com/GameplanePanel/gameplane/telemetryschema`, `go 1.26.0`, no requires) and `telemetryschema/doc.go` with a package comment: "the shared telemetry report contract used by api and telemetry-receiver; see specs/022-default-telemetry-dashboard/contracts/report-schema.md". +- [X] T003 Create `telemetryschema/go.mod` (`module github.com/GameplanePanel/gameplane/telemetryschema`, `go 1.26.0`, no requires) and `telemetryschema/doc.go` with a package comment: "the shared telemetry report contract used by api and telemetry-receiver; see specs/done_022-default-telemetry-dashboard/contracts/report-schema.md". - [X] T004 Add `./telemetryschema` to the `use` block in `go.work`, and add `telemetryschema` to `GO_MODULES` in `Makefile:43` (after `gameproto`). - [X] T005 [P] Add `telemetryschema` to both Go module matrices in `.github/workflows/ci.yaml` (the `module:` lists at about lines 457 and 549). Add `telemetryschema/**` everywhere `telemetry-receiver/**` appears as a path filter (about line 119), and to the api and telemetry-receiver image path filters in `.github/workflows/publish-edge.yaml`. Add a `gomod` entry for `/telemetryschema` in `.github/dependabot.yml`, copied from the `/telemetry-receiver` entry at about line 176. -- [X] T006 [P] Create `telemetryschema/.testcoverage.yml` (copy the `telemetry-receiver/.testcoverage.yml` format with `total: 90` and an updated header comment) and a non-empty `telemetryschema/specs.md` skeleton with the sections Purpose, Responsibilities, External interface (linking `specs/022-default-telemetry-dashboard/contracts/report-schema.md`), Key invariants, and Testing & coverage, so that `hack/check-specs.sh` passes. +- [X] T006 [P] Create `telemetryschema/.testcoverage.yml` (copy the `telemetry-receiver/.testcoverage.yml` format with `total: 90` and an updated header comment) and a non-empty `telemetryschema/specs.md` skeleton with the sections Purpose, Responsibilities, External interface (linking `specs/done_022-default-telemetry-dashboard/contracts/report-schema.md`), Key invariants, and Testing & coverage, so that `hack/check-specs.sh` passes. - [X] T007 [P] Update the repository docs maps: - `CLAUDE.md`: in the repository map add `telemetryschema/ shared telemetry report contract (api, telemetry-receiver)`; change "links all 15 Go modules" to 16; add `telemetryschema 90` to the coverage minimums; add a row to the Architecture table. - `docs/agent-architecture.md`: add a `telemetryschema/specs.md` row next to Telemetry-Receiver (line 29). @@ -556,7 +556,7 @@ description: "Task list for feature 022: default telemetry destination, extended - [X] T093 [P] Create `docs/telemetry-provider.md`, a runbook for running the project's receiver (OD-2): deploying the image, TLS termination, keeping `:8081` private, the `DASHBOARD_TOKEN` and `ID_PEPPER` Secrets and their rotation, `PUBLIC_SUMMARY=true`, `TRUSTED_PROXY_CIDRS`, retention (`RETENTION_DAYS`, `ACTIVITY_EXPIRY_DAYS`), scraping `/metrics` with the token, and backing up and restoring `telemetry.db`. Link it from `docs/install.md` § Telemetry and `telemetry-receiver/README.md`. (The README link lands with T089.) - [X] T094 [P] Add a `CHANGELOG.md` entry with the FR-008 upgrade notes, breaking-ish behaviour notes ("empty `api.telemetry.endpoint` now means the project default"; "the receiver's `/metrics` moved to the dashboard port and needs the dashboard token"), and links to the docs. - [X] T095 Add a single statement-URL constant for the data-handling statement (OD-2), for example in the module `web/src` already uses for docs links. If there is none, create `web/src/lib/links.ts`. Use it in `TelemetryNotice.tsx` and `TelemetrySection`. -- [ ] T096 Make the website changes in the `website/` submodule, following its own `CLAUDE.md` and PR flow (default branch `main`): +- [X] T096 Make the website changes in the `website/` submodule, following its own `CLAUDE.md` and PR flow (default branch `main`): (2026-10-08: GameplanePanel/website#13 merged; root pointer bumped to website main 299251d.) - a data-handling statement page (OD-2: maintainers operate it; 24-month aggregates, OD-3; 90-day activity expiry, OD-4; signing; no raw reports or IPs) - updates to `src/content/docs/platform-settings-telemetry.mdx`, `helm-values-reference.mdx` and `air-gapped-installation.mdx` (set `api.telemetry.enabled=false`) @@ -566,14 +566,14 @@ description: "Task list for feature 022: default telemetry destination, extended - the OD-1 merge gate - the T002 sign-off list - that `telemetry-default-gate` is expected to fail until OD-1 is ruled -- [X] T099 Once OD-1 is ruled: set `DefaultEndpoint` in `api/internal/telemetry/destination.go`, mark OD-1 RULED in `specs/022-default-telemetry-dashboard/OPEN-DECISIONS.md`, update the destination copy in `design.pen` (with re-export) and the docs, confirm `telemetry-default-gate` passes, and mark the PR ready for review. +- [X] T099 Once OD-1 is ruled: set `DefaultEndpoint` in `api/internal/telemetry/destination.go`, mark OD-1 RULED in `specs/done_022-default-telemetry-dashboard/OPEN-DECISIONS.md`, update the destination copy in `design.pen` (with re-export) and the docs, confirm `telemetry-default-gate` passes, and mark the PR ready for review. The docs written under T091-T094 name no receiver host. Once OD-1 is ruled, add the host to: - `docs/install.md` § Telemetry: the sentence on an empty `api.telemetry.endpoint`, and the Upgrading admonition - `docs/architecture.md`: the "API → telemetry-receiver" bullet - `docs/telemetry-provider.md`: the intro paragraph and the "Public summary" paragraph - `CHANGELOG.md` [Unreleased] > Upgrade Notes: the first three bullets - the statement URL `https://valgulnecron.github.io/gameplane-website/telemetry/` (in `docs/install.md`, `docs/security.md`, `docs/telemetry-provider.md` and `CHANGELOG.md`) if the website gets a custom domain; it must match the T095 constant -- [ ] T100 After merge: `git mv specs/022-default-telemetry-dashboard specs/done_022-default-telemetry-dashboard` and update in-repo references as a `docs:` commit (rule 16, constitution IV). Then delete the remote and local branch (rule 12). +- [X] T100 After merge: `git mv specs/022-default-telemetry-dashboard specs/done_022-default-telemetry-dashboard` and update in-repo references as a `docs:` commit (rule 16, constitution IV). Then delete the remote and local branch (rule 12). (2026-10-08: archived after GameplanePanel/Gameplane#617 merged; branches deleted.) --- diff --git a/telemetry-receiver/specs.md b/telemetry-receiver/specs.md index 863025920..e70d5c764 100644 --- a/telemetry-receiver/specs.md +++ b/telemetry-receiver/specs.md @@ -58,7 +58,7 @@ telemetry-receiver/ ## External interface / contracts -The full contract is `specs/022-default-telemetry-dashboard/contracts/receiver-http.md`; the report format is `contracts/report-schema.md`. +The full contract is `specs/done_022-default-telemetry-dashboard/contracts/receiver-http.md`; the report format is `contracts/report-schema.md`. ### Public listener (`LISTEN_ADDR`) @@ -180,5 +180,5 @@ Untested (main process wiring): `main()` signal handling and server startup erro - **`telemetryschema/specs.md`** — shared report contract, signing and proof-of-work helpers - **`api/internal/telemetry`** — the API's reporter that POSTs to this endpoint - **`charts/gameplane/`** — Helm chart integration (`api.telemetry.receiver.*`) -- **`specs/022-default-telemetry-dashboard/`** — feature spec and contracts +- **`specs/done_022-default-telemetry-dashboard/`** — feature spec and contracts - **`CLAUDE.md`** — project architecture summary diff --git a/telemetryschema/doc.go b/telemetryschema/doc.go index 1aee4814e..777606c39 100644 --- a/telemetryschema/doc.go +++ b/telemetryschema/doc.go @@ -1,4 +1,4 @@ // Package telemetryschema is the shared telemetry report contract used by api // and telemetry-receiver; see -// specs/022-default-telemetry-dashboard/contracts/report-schema.md. +// specs/done_022-default-telemetry-dashboard/contracts/report-schema.md. package telemetryschema diff --git a/telemetryschema/specs.md b/telemetryschema/specs.md index abdebf81b..e6893859a 100644 --- a/telemetryschema/specs.md +++ b/telemetryschema/specs.md @@ -45,7 +45,7 @@ telemetryschema/ ## External interface / contracts -The wire contract is [`specs/022-default-telemetry-dashboard/contracts/report-schema.md`](../specs/022-default-telemetry-dashboard/contracts/report-schema.md); the rules below are what this package enforces. +The wire contract is [`specs/done_022-default-telemetry-dashboard/contracts/report-schema.md`](../specs/done_022-default-telemetry-dashboard/contracts/report-schema.md); the rules below are what this package enforces. ### Types @@ -110,7 +110,7 @@ JSON tags are the camelCase names in the contract (`installId`, `wakeOnConnect`, ### Proof-of-work -The wire contract is research R21 and [`contracts/receiver-http.md`](../specs/022-default-telemetry-dashboard/contracts/receiver-http.md). When a receiver requires proof-of-work, every report carries `Gameplane-Telemetry-PoW: :`. +The wire contract is research R21 and [`contracts/receiver-http.md`](../specs/done_022-default-telemetry-dashboard/contracts/receiver-http.md). When a receiver requires proof-of-work, every report carries `Gameplane-Telemetry-PoW: :`. | Name | Behavior | |---|---| diff --git a/website b/website index 7b28a3bbf..299251d07 160000 --- a/website +++ b/website @@ -1 +1 @@ -Subproject commit 7b28a3bbf6aeca7c77ea9337138628ac95b12d38 +Subproject commit 299251d071818cd9085de95ede86e74539c5e444