diff --git a/specs/024-docs-feature-list-refresh/OPEN-DECISIONS.md b/specs/024-docs-feature-list-refresh/OPEN-DECISIONS.md new file mode 100644 index 000000000..cf737b284 --- /dev/null +++ b/specs/024-docs-feature-list-refresh/OPEN-DECISIONS.md @@ -0,0 +1,11 @@ +# Open Decisions: 024-docs-feature-list-refresh + +Unsettled items. Do not treat any of the below as decided until a maintainer rules on it here. + +## Settled (user, 2026-10-12) +OD-1 (FR-001): the feature catalog is a root `FEATURES.md` next to `README.md`; the website gets a features docs page with the same content, and the README links to it. +OD-2 (FR-005, FR-013): the roadmap has an "In progress" section with one line per open spec (002, 009, 013, 019, 021, 023 at the time of writing), each with its plain-words status and blocker. +OD-3 (FR-009): the website change is docs-page text only (new features page, roadmap page, stale-fact fixes); the landing page is untouched. +OD-4 (plan Constitution Check, Principle I): no Go e2e test; this spec takes the documented docs exception spec 012 used, verified by the sync check's fixture tests and the existing doc gates in CI. + +No open decisions remain. diff --git a/specs/024-docs-feature-list-refresh/checklists/requirements.md b/specs/024-docs-feature-list-refresh/checklists/requirements.md new file mode 100644 index 000000000..afecd0b75 --- /dev/null +++ b/specs/024-docs-feature-list-refresh/checklists/requirements.md @@ -0,0 +1,35 @@ +# Specification Quality Checklist: Documentation Refresh, Feature Catalog, and Roadmap Status + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-10-12 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- All three scope decisions are settled in `OPEN-DECISIONS.md` (OD-1 root `FEATURES.md`, OD-2 every open spec on the roadmap, OD-3 website docs text only). Ready for `/speckit-plan`. +- File paths (`docs/roadmap.md`, `README.md`) appear because the user named them; they are deliverables, not implementation choices. diff --git a/specs/024-docs-feature-list-refresh/contracts/features-catalog.md b/specs/024-docs-feature-list-refresh/contracts/features-catalog.md new file mode 100644 index 000000000..41a650b4c --- /dev/null +++ b/specs/024-docs-feature-list-refresh/contracts/features-catalog.md @@ -0,0 +1,40 @@ +# Contract: Feature catalog format + +Applies to `FEATURES.md` (main repo root) and `src/content/docs/features.mdx` (website). The sync check ([features-sync-check.md](./features-sync-check.md)) relies on this grammar. + +## FEATURES.md + +```markdown +# Gameplane features + + + +## + +| Capability | Maturity | Default | Description | Docs | +|---|---|---|---|---| +| | | | | []() | +``` + +Rules: +- Area headings are level-2 (`## `) and appear in the same order in both files. Level-1 and level-3+ headings are ignored by the check. +- Exactly one catalog table per area, header row exactly as above (column names and order). Any other table in the file is outside an area heading or is ignored only if it does not use this header. +- Cell values for Maturity and Default are lower-case, from the fixed sets, with no extra text or markup. +- Capability cells are plain text: no links, no backticks, no `|`. +- Rows appear in the same order in both files. + +## features.mdx (website) + +Frontmatter (website content schema): + +```yaml +title: Features +description: Every Gameplane capability with its maturity and default. +section: reference +group: releases-roadmap +order: 0 +icon: list # an icon already in src/components/icons.ts +eyebrow: DOCUMENTATION +``` + +Body: same intro meaning, then the same `##` area headings and tables with the same Capability, Maturity and Default cells. Description and Docs cells may differ (website links are relative docs links per the website CLAUDE.md). MDX imports and components are allowed outside the tables. diff --git a/specs/024-docs-feature-list-refresh/contracts/features-sync-check.md b/specs/024-docs-feature-list-refresh/contracts/features-sync-check.md new file mode 100644 index 000000000..52c6dac1e --- /dev/null +++ b/specs/024-docs-feature-list-refresh/contracts/features-sync-check.md @@ -0,0 +1,49 @@ +# Contract: features sync check + +## Command + +```sh +make check-features-sync # runs hack/check-features-sync.sh +make test-features-sync # runs hack/test-check-features-sync.sh (fixture tests) +``` + +| Env var | Default | Purpose | +|---|---|---| +| `FEATURES_MD` | `FEATURES.md` | Repo catalog path (fixtures override). | +| `FEATURES_MDX` | `website/src/content/docs/features.mdx` | Website page path (fixtures override). | + +## Behaviour + +1. If either file is missing, exit 2 with `features-sync: missing ` (a missing website submodule checkout is an error, never a pass). +2. Parse each file into an ordered list of `(area, capability, maturity, default)` per the [catalog format](./features-catalog.md). Lines inside fenced code blocks are skipped. +3. Validate each row: maturity and default in their fixed sets; `stable` with `default` other than `on` is an error. +4. Compare the two lists in order. Report every difference, not just the first. +5. Exit 0 when both files parse, validate and match; exit 1 otherwise. + +## Output on failure (one line per problem) + +``` +features-sync: :: invalid maturity "" +features-sync: :: stable row must have default "on" +features-sync: area mismatch at position : "" vs "" +features-sync: only in FEATURES.md: / +features-sync: only in features.mdx: / +features-sync: / : maturity "" vs "" +features-sync: / : default "" vs "" +features-sync: / : order differs +``` + +## Fixture tests (FR-015, SC-005) + +`hack/testdata/check-features-sync/` holds one directory per case with a `FEATURES.md`, a `features.mdx` and, for failing cases, an `.expected` file containing the expected output lines. + +- `pass/in-sync`: matching files with differing Description and Docs cells (must pass). +- `pass/code-fence`: a table-looking block inside a code fence is ignored. +- `fail/missing-row-website`, `fail/missing-row-repo`, `fail/maturity-mismatch`, `fail/default-mismatch`, `fail/area-mismatch`, `fail/order-differs`, `fail/invalid-label`, `fail/stable-off`, `fail/missing-file`. + +## CI wiring + +- `docs and repository checks` job: new step `git submodule update --init website` (only the website submodule), then `make check-features-sync` and `make test-features-sync`. +- `docs` path filter adds `FEATURES.md`, `website`, `hack/check-features-sync.sh`, `hack/test-check-features-sync.sh`, `hack/testdata/check-features-sync/**`. +- `make lint` gains `check-features-sync`. +- If spec 023's change-based selection has landed, the same paths are mapped to the docs job there. diff --git a/specs/024-docs-feature-list-refresh/data-model.md b/specs/024-docs-feature-list-refresh/data-model.md new file mode 100644 index 000000000..6937745a1 --- /dev/null +++ b/specs/024-docs-feature-list-refresh/data-model.md @@ -0,0 +1,41 @@ +# Data Model: 024 Documentation Refresh, Feature Catalog, and Roadmap Status + +No runtime data. The "entities" are structured documentation records. + +## Feature catalog entry (row in `FEATURES.md` and `features.mdx`) + +| Field | Rule | +|---|---| +| area | The `##` heading the row sits under; one of the areas in [research R6](./research.md#r6-building-the-capability-inventory). | +| capability | Short name of one thing a user or operator can do. Unique within its area. Plain text, no links, no pipe character. | +| maturity | Exactly one of `stable`, `beta`, `experimental`, `planned`, `in progress`. | +| default | `on`, `off` (opt-in), or `n/a` (planned / in progress / tooling with no install default). | +| description | One sentence. May differ between repo and website. | +| docs | Link to the page documenting it. Repo: relative path (`docs/x.md#anchor`). Website: relative docs link (`./x/`). Planned and in-progress rows link to the roadmap. | + +Validation (from spec FR-002, Clarification Q1): +- `stable` requires `default = on` and a bucketed e2e test (recorded in `feature-evidence.md`). +- `default = off` forbids `stable`. +- `planned` / `in progress` require `default = n/a` and a roadmap link. +- A withdrawn feature has no row. + +## Feature evidence record (`feature-evidence.md`, review aid) + +area, capability, maturity, e2e test name or `none`, default source (`values.yaml` key, build tag, module field), notes. One record per catalog row. + +## Roadmap item (`docs/roadmap.md`, website `roadmap.mdx`) + +| Field | Rule | +|---|---| +| title | Plain words. | +| status | `shipped ()`, `in progress`, `blocked`, `planned`, `out of scope`. | +| reference | Release, spec folder or PR. | +| blocker | Required when status is `blocked`: what blocks it and what unblocks it. | + +The roadmap carries one status date. Sections in order: current release and status date; shipped in v0.3.0 and since; in progress (one line per open spec, OD-2); blocking v1; wanted for v1; known gaps; out of scope; join protocol coverage. Historical entries keep their `doc-versions: historical` markers. + +State transitions: `planned → in progress → shipped`; `in progress ↔ blocked`; any → `out of scope` only on a maintainer decision. + +## Stale fact record (`stale-facts.md`, review aid) + +page (repo and path), old value, new value, confirming source (file:line, command output or spec). One record per correction (FR-012). diff --git a/specs/024-docs-feature-list-refresh/plan.md b/specs/024-docs-feature-list-refresh/plan.md new file mode 100644 index 000000000..56e64b185 --- /dev/null +++ b/specs/024-docs-feature-list-refresh/plan.md @@ -0,0 +1,110 @@ +# Implementation Plan: Documentation Refresh, Feature Catalog, and Roadmap Status + +**Branch**: `claude/project-thread-6pzhf7` | **Date**: 2026-10-12 | **Spec**: [spec.md](./spec.md) + +**Input**: Feature specification from `specs/024-docs-feature-list-refresh/spec.md` + +## Summary + +Write a root `FEATURES.md` that lists every Gameplane capability, one row per capability, grouped by area, each with an evidence-based maturity label, its install default and a docs link. Mirror it as a website docs page and add a CI check that fails when the two drift. Refresh `docs/roadmap.md` (and the website roadmap page) to the current release, with what shipped in `v0.3.0` and since, and one line per open spec. Sweep the README, `docs/`, component READMEs, the module README and the website docs for stale facts. Website changes are docs text only. Research: [research.md](./research.md). + +## Technical Context + +**Language/Version**: Markdown (GFM) in the main and module repos; MDX in the website (Astro, strict TypeScript); Bash + awk for the sync check + +**Primary Dependencies**: existing doc gates `hack/check-links.sh`, `hack/check-doc-versions.sh`; website content collection schema `src/content.config.ts` and nav `src/lib/docs-nav.ts`; GitHub Actions `ci.yaml` `docs and repository checks` job + +**Storage**: N/A + +**Testing**: fixture tests `hack/test-check-features-sync.sh` (`make test-features-sync`) in CI; existing `make check-links`, `make check-doc-versions` in CI; website CI `npm run lint`, `check`, `build`. No `test/e2e/` test: Principle I docs exception (OD-4). + +**Target Platform**: GitHub (rendered Markdown), GitHub Pages website, GitHub Actions `ubuntu-latest` + +**Project Type**: documentation plus one repository tooling script + +**Performance Goals**: sync check runs in a few seconds inside the existing 10-minute docs job + +**Constraints**: no doc gate relaxed (FR-011); competitor comparison columns unchanged (FR-014); CHANGELOG not rewritten; no `.pen` edits and no landing page change (OD-3); only compile/build checks locally (rule 8); submodule pointers bumped only after their PRs merge + +**Scale/Scope**: about 100 to 150 catalog rows across ~18 areas; 22 `docs/*.md` files, root README, 4 component READMEs, the module README, ~90 website docs pages (only those carrying stale facts change, plus new `features.mdx` and `roadmap.mdx`); 6 open specs on the roadmap + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +| Principle | Status | Notes | +|---|---|---| +| I. E2E-Tested Delivery | PASS-WITH-JUSTIFICATION | Docs feature plus a CI-only text check. valgul ruled OD-4 (2026-10-12): no Go e2e test; the spec 012 docs exception applies, verified by the sync check's fixture tests and the existing doc gates in CI (see Complexity Tracking). | +| II. Design-First | PASS | No dashboard change. Website change is docs-page text only (OD-3); a new docs page is frontmatter-only per the website CLAUDE.md, so no `website.pen` change. No `.pen` file is read or touched. | +| III. Ecosystem Best Practice | PASS | Bash script follows the sibling doc gates; no suppressions; no lint config change. | +| IV. Spec-Driven | PASS | spec → clarify → plan done; tasks next. No module behaviour changes, so no `specs.md` updates. Archive to `done_024` after all PRs merge. | +| V. Delegate | PASS | Inventory and stale-fact sweep run as a Workflow: one `haiku` scout per area/fact class writes rows and evidence, one `sonnet` reviewer checks the combined diff against sources; every `agent()` sets `model`. | +| VI. CI Bears the Load | PASS | Sync check, its fixtures and doc gates are verified in CI only. Locally: website `npm run build`/`check` only. | + +## Project Structure + +### Documentation (this feature) + +```text +specs/024-docs-feature-list-refresh/ +├── spec.md +├── OPEN-DECISIONS.md +├── plan.md # this file +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +│ ├── features-catalog.md +│ └── features-sync-check.md +├── checklists/requirements.md +├── feature-evidence.md # implementation output: evidence per catalog row +├── stale-facts.md # implementation output: one record per correction +└── tasks.md # /speckit-tasks +``` + +### Source files touched + +```text +GameplanePanel/Gameplane +├── FEATURES.md # NEW catalog (OD-1) +├── README.md # stale facts; Features → summary + link +├── docs/roadmap.md # status refresh (OD-2) +├── docs/*.md # stale-fact fixes where found +├── audit-syslog-bridge/README.md, containers/README.md, +│ mcp-server/README.md, telemetry-receiver/README.md +├── hack/check-features-sync.sh # NEW (FR-015) +├── hack/test-check-features-sync.sh # NEW fixture runner +├── hack/testdata/check-features-sync/{pass,fail}/ # NEW fixtures +├── hack/check-links.sh, hack/check-doc-versions.sh # add FEATURES.md to audited lists +├── Makefile # check-features-sync, test-features-sync, lint +├── .github/workflows/ci.yaml # docs job: init website submodule, run check; path filter +└── website, modules # submodule pointer bumps (after their PRs merge) + +GameplanePanel/website +├── src/content/docs/features.mdx # NEW mirror page +├── src/content/docs/roadmap.mdx # status refresh +└── src/content/docs/*.mdx # stale-fact fixes where found + +GameplanePanel/module +└── README.md # only if module list/count is stale +``` + +**Structure Decision**: no new code project; one Bash tool joins the existing `hack/` doc gates, and content changes land in the three existing repos. + +## Delivery + +1. Spec docs PR (spec, plan, tasks) to `master`. +2. Draft `FEATURES.md`, `feature-evidence.md` and `stale-facts.md` on the main branch (not yet merged). +3. Module repo PR if needed; website PR with `features.mdx` copied from the draft catalog, roadmap page and stale fixes. Both merge first. +4. Main repo PR: everything else plus both pointer bumps. CI runs the sync check against the merged website page. +5. Archive `specs/024-…` to `specs/done_024-…` after merge. + +Coordination: spec 023 is reshaping CI job selection; whichever lands second maps the new files into the other's structure (research R10). + +## Complexity Tracking + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| Principle I exception (OD-4, ruled 2026-10-12) | The feature changes no runtime path: catalog, roadmap and doc fixes describe shipped code, and the sync check is a repo lint that has no cluster behaviour to exercise. Verification is the fixture tests (every mismatch kind rejected, in-sync accepted) plus the existing doc gates in CI. | A Go e2e test in `test/e2e/` would boot a kind cluster to run a text comparison; it would test nothing the fixture tests do not. Same reasoning as `specs/done_012-docs-refresh-and-outreach/plan.md`. | + +**Constitution re-check (post-Phase 1)**: Principles I–VI satisfied; the Principle I exception is ruled (OD-4) and recorded above. No other violations. diff --git a/specs/024-docs-feature-list-refresh/quickstart.md b/specs/024-docs-feature-list-refresh/quickstart.md new file mode 100644 index 000000000..ab54773e5 --- /dev/null +++ b/specs/024-docs-feature-list-refresh/quickstart.md @@ -0,0 +1,19 @@ +# Quickstart: validating spec 024 + +Local work is limited to compile/build checks (CLAUDE.md rule 8; website: `npm run build` / `npm run check` only). Everything below marked **CI** is verified by the pushed PR's CI run, not locally. + +## Prerequisites + +- Main repo branch with `FEATURES.md`, refreshed docs and the sync check. +- Website PR merged to `main`, and the main repo `website` pointer bumped to it. + +## Scenarios + +1. **Catalog is complete and correct (SC-001)**: pick 10 random rows of `FEATURES.md`; for each, confirm the matching record in `feature-evidence.md` names real evidence (bucketed e2e test or `none`, default source) and that the label follows [data-model.md](./data-model.md) validation; follow the Docs link and confirm it documents the capability. +2. **Roadmap matches the specs (SC-002)**: for every folder in `specs/` without `done_`, find its line in the "In progress" section of `docs/roadmap.md`; compare with that spec's `tasks.md` on `master` on the status date. +3. **No stale counts (SC-003)**: `grep -rn "30 ready\|30 game\|30 templates" README.md docs website/src` from the GP root (website submodule initialised) finds nothing; every module count equals the number of game directories in the module repo; every registry count equals the registries in the code. Each fix is listed in `stale-facts.md`. +4. **Repo and website agree (SC-004)** **CI**: `make check-features-sync` passes in the `docs and repository checks` job; the website roadmap page and `docs/roadmap.md` list the same items with the same statuses (manual comparison). +5. **Sync check catches drift (SC-005)** **CI**: `make test-features-sync` passes, meaning every `fail/` fixture in [contracts/features-sync-check.md](./contracts/features-sync-check.md) is rejected with its expected message and every `pass/` fixture is accepted. +6. **Existing doc gates still pass (FR-011)** **CI**: `make check-links` and `make check-doc-versions` pass with `FEATURES.md` added to their audited lists; no rule in either script was relaxed (review the diff). +7. **Website builds** (local allowed): `npm run build` in the website repo succeeds and the Features page appears in the Reference → Releases & Roadmap sidebar group. Website CI (`npm run lint`, `check`, `build`) is green on its PR. +8. **README points to the catalog (US3)**: README Features section is a short summary with a link to `FEATURES.md`; the comparison table's competitor columns are unchanged (`git diff` shows only Gameplane-column edits). diff --git a/specs/024-docs-feature-list-refresh/research.md b/specs/024-docs-feature-list-refresh/research.md new file mode 100644 index 000000000..43aa2591c --- /dev/null +++ b/specs/024-docs-feature-list-refresh/research.md @@ -0,0 +1,86 @@ +# Research: 024 Documentation Refresh, Feature Catalog, and Roadmap Status + +All decisions below rest on the spec, its Clarifications (2026-10-12) and the settled entries in [OPEN-DECISIONS.md](./OPEN-DECISIONS.md). Facts were read from `master` at `798b295` and the website `main` at `87b64a9` on 2026-10-12. + +## R1. Feature catalog format + +- **Decision**: `FEATURES.md` at the repo root has one `##` heading per area and, under each, one GitHub-flavoured Markdown table with the columns `Capability | Maturity | Default | Description | Docs`. One row per capability (Clarification Q3). Full grammar in [contracts/features-catalog.md](./contracts/features-catalog.md). +- **Rationale**: Tables render on GitHub and in Astro MDX unchanged (the website already uses GFM tables, e.g. `src/content/docs/comparison.mdx`), they are easy to parse line by line from a shell script, and 100 to 150 rows stay scannable when grouped by area. +- **Alternatives considered**: bullet lists (harder to parse labels reliably); a YAML/JSON data file rendered into both places (adds a generator and build step neither repo has; the user chose a CI check, not generation); one file per area (more link targets, nothing gained). + +## R2. What the sync check compares + +- **Decision**: For each row the check compares the tuple *(area heading, capability name, maturity, default)* between `FEATURES.md` and `website/src/content/docs/features.mdx`, in order. It does **not** compare the Description or Docs columns. +- **Rationale**: FR-015 names names, areas and labels. Docs links must differ (repo-relative `docs/x.md` versus website `./x/` links per the website CLAUDE.md), and descriptions may be lightly reworded for the site's MDX components; comparing them would force byte-identical files and fail on every legitimate link difference. +- **Alternatives considered**: whole-file diff after link rewriting (brittle); comparing names only (would miss a maturity label drifting, the main risk). + +## R3. Where the sync check runs + +- **Decision**: In the main repo as `hack/check-features-sync.sh`, reading the website page through the `website/` submodule. The `docs and repository checks` job in `.github/workflows/ci.yaml` gains a step that initialises only the `website` submodule (`git submodule update --init website`) before running the check. The `docs` path filter gains `FEATURES.md`, `website`, and the new hack files. +- **Rationale**: The main repo already holds both sides at a pinned revision (submodule pointer), so the check is deterministic, needs no network fetch of a moving branch, and runs where the other doc gates run. The website is a public repo, so the checkout needs no extra token. +- **Alternatives considered**: a check in the website repo that downloads `FEATURES.md` from `master` (network-dependent, compares against a moving target, and the website has no hack/ tooling); checking out all submodules (`modules` is large and not needed). +- **Consequence**: the website PR carrying `features.mdx` must merge first; the main repo PR then bumps the `website` pointer in the same change that adds `FEATURES.md` and the check. This matches the project rule that a pointer bump happens only after the submodule PR merges. + +## R4. Sync check implementation and tests + +- **Decision**: Bash plus `awk`, matching `hack/check-links.sh` and `hack/check-doc-versions.sh`. Fixture tests in `hack/test-check-features-sync.sh` with fixtures under `hack/testdata/check-features-sync/{pass,fail}/`, following the `hack/test-check-doc-versions.sh` harness (each `pass/` case exits 0, each `fail/` case exits non-zero with output matching its `.expected` file). Paths are overridable by env vars (`FEATURES_MD`, `FEATURES_MDX`) so fixtures can point at test files. Makefile targets `check-features-sync` and `test-features-sync`; `check-features-sync` joins the `lint` target. +- **Rationale**: Same language, harness shape and override pattern reviewers already know; no new runtime dependency in the docs job. +- **Alternatives considered**: Python (as `hack/ci_scope.py`): fine too, but the doc gates are all Bash and the job does not set up Python. + +## R5. Evidence behind each maturity label + +- **Decision**: The rule from Clarification Q1 is applied with these sources: + - *Shipped*: present on `master` (code, chart, module repo). + - *CI end-to-end coverage*: a test in `test/e2e/` that is registered in a bucket in `test/e2e/buckets.sh` (tests excluded from every bucket do not count). + - *On by default*: `charts/gameplane/values.yaml` defaults and the module/CRD defaults; anything needing an opt-in value, a build tag (`-tags postgres`) or a separately installed component is off by default. + - *Experimental*: the docs already label it experimental (today: the PostgreSQL driver). + - Planned / in progress: listed on the roadmap; never given a shipped label. +- Each row's evidence (e2e test name or "none", default source) is recorded in the review list `feature-evidence.md` in this spec folder, so a reviewer can check any label (SC-001). +- **Alternatives considered**: maintainer judgment per row (not reproducible). + +## R6. Building the capability inventory + +- **Decision**: Inventory from these sources, deduplicated into capability rows: README Features and Mod Management, every `docs/*.md`, every website docs page, `CHANGELOG.md` (0.2.x, 0.3.0, Unreleased), finished `specs/done_*` folders, dashboard routes (`web/src/router/tree.tsx`), CRDs (`operator/api/v1alpha1/`), Helm values, API routes (`api/cmd/main.go`), the module catalog (29 directories in `GameplanePanel/module`) and the `gp-module` CLI commands. Areas: servers and lifecycle; console and admin actions; files; players; mods; backups and restore; game modules and catalog; module authoring; networking and tunnels; idle sleep and wake; multi-cluster; users, auth and access; audit and security; notifications; telemetry; observability and admin; localization; developer and operator tooling. +- **Rationale**: Covers every place a feature can be described or implemented, which is what SC-001 measures against. +- **Execution**: per CLAUDE.md rules 13 and 18, one scout per area at `haiku` writes rows plus evidence; one `sonnet` reviewer checks the combined diff against the sources. + +## R7. Roadmap status sources + +- **Decision**: Status date = the day the main docs PR opens. Open specs are those without the `done_` prefix on `master`; their status comes from their `tasks.md` counts and notes plus their open PRs. Snapshot on 2026-10-12 (to be refreshed at PR time): + + | Spec | Tasks done on master | Plain status | + |---|---|---| + | 002 Nuclear Option + IP pool | 136 / 143 | Shipped except 7 join tests waiting for a real-client packet capture | + | 009 Dependabot remediation | 80 / 82 | Blocked: TypeScript 7 waits on `@typescript-eslint` accepting TS 7 (Dependabot #272) | + | 013 Test coverage | 11 / 62 | In progress: setup merged, CI gate PRs open | + | 019 Language packs | 0 / 105 on master | In progress on an open PR; French translation and the language picker still to come | + | 021 Settings / game config | 20 / 24 | The 4 open tasks (T017–T019, T024) were built in PR 652 but not ticked; verify, tick and archive | + | 023 Change-based test selection | 0 / 52 | Specified and planned; implementation not started | + +- `v0.3.0` content comes from its CHANGELOG section; "since v0.3.0" comes from `[Unreleased]`. +- Stale roadmap items are corrected, e.g. "Game module template specifications (planned)" is re-checked against the module repo's `specs.md` files. + +## R8. Existing doc gates must cover the new files + +- **Decision**: Add `FEATURES.md` to the fixed audited-file lists in `hack/check-links.sh` and `hack/check-doc-versions.sh` (and their header comments), and to the `docs` path filter in `ci.yaml`. This only widens what is checked; no rule is relaxed (FR-011). +- **Rationale**: Both scripts check a fixed list of 18 files; without this, `FEATURES.md` links and version strings would go unchecked. + +## R9. Stale-fact sweep method + +- **Decision**: A fixed list of fact classes is grepped across the main repo docs, component READMEs, website docs and module README: module count (29), mod registry count (10), built-in role names, release/version strings, "beta" status wording versus "pre-v1 release", optional-component defaults, removed games (Hell Let Loose), component counts (15 Go modules in `GO_MODULES`, 16 in `go.work`), and dashboard page names. Each finding is recorded in `stale-facts.md` in this spec folder (page, old value, new value, source), satisfying FR-012. Already found: README and `docs/comparison-sources.md` say 30 templates (actual 29); the website roadmap headline says "Beta status". +- Competitor columns of the comparison table are not touched (FR-014). `CHANGELOG.md` is not rewritten. + +## R10. Delivery order and pull requests + +- **Decision**: + 1. Spec docs PR (spec, plan, tasks) to `master`, as for specs 019 and 023. + 2. Module repo PR, only if its README is stale. + 3. Website PR: `features.mdx` (new, section `reference`, group `releases-roadmap`), roadmap page, stale-fact fixes. Text only (OD-3). + 4. Main repo PR after 2 and 3 merge: `FEATURES.md`, `docs/roadmap.md`, README, `docs/`, component READMEs, sync check + fixtures + Makefile + CI wiring, and the `website`/`modules` pointer bumps. +- **Rationale**: The sync check in PR 4 needs the merged website page behind the bumped pointer. +- **Coordination**: spec 023 is changing CI job selection (`hack/ci_scope.py`, `ci.yaml`). Whichever lands second maps the new hack files and `FEATURES.md` into the other's structure. + +## R11. Principle I (E2E-tested delivery) + +- **Decision**: No Go e2e test (OD-4, valgul 2026-10-12). The spec takes the documented docs exception spec 012 used; verification is the sync check's fixture tests plus the existing doc gates in CI. +- **Alternatives considered**: a `test/e2e/` test running the sync check, as spec 023 OD-4 required for CI-only work; rejected by the ruling because the check compares two text files and has no cluster behaviour to exercise. diff --git a/specs/024-docs-feature-list-refresh/spec.md b/specs/024-docs-feature-list-refresh/spec.md new file mode 100644 index 000000000..4250b7cf6 --- /dev/null +++ b/specs/024-docs-feature-list-refresh/spec.md @@ -0,0 +1,151 @@ +# Feature Specification: Documentation Refresh, Feature Catalog, and Roadmap Status + +**Feature Branch**: `claude/project-thread-6pzhf7` + +**Created**: 2026-10-12 + +**Status**: Draft + +**Input**: User description: "Update the docs on both website, /docs, readme.md etc..... Create a feature.md with all feature. update the roadmap.md with new status." + +## Context + +Spec 012 (archived as `specs/done_012-docs-refresh-and-outreach/`) last refreshed the docs for `v0.2.0-beta.8`. Since then `v0.3.0` shipped, several specs finished (014–018, 020, 022) and more work is in flight (002, 009, 013, 019, 021, 023). The docs have drifted. Examples found while writing this spec: + +- `README.md` says "30 ready-to-use game templates" (Features list and comparison table) and `docs/comparison-sources.md` repeats it, while the module catalog holds 29 games since Hell Let Loose was withdrawn (spec 015). +- `docs/roadmap.md` lists only items shipped up to `v0.2.0-beta.8` under "Shipped toward v1" and says nothing about the `v0.3.0` release or the specs in progress. +- The project has no single list of everything Gameplane can do; features are described in scattered places (README Features, website pages, 20+ docs files, CHANGELOG). + +## Clarifications + +### Session 2026-10-12 + +- Q: How should FEATURES.md decide which maturity label a feature gets? → A: Evidence rule: stable = shipped, on by default and covered by CI e2e tests; beta = shipped with documented caveats or no e2e test; experimental = the docs already call it experimental. +- Q: How should FEATURES.md and the website features page stay in sync? → A: A CI check: a new script fails CI when the two lists differ in feature names or labels; it ships with its own fixture tests. +- Q: How detailed should each FEATURES.md entry be? → A: One entry per capability (roughly 100 to 150 rows, one per thing a user or operator can do), grouped under area headings. + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Evaluator reads one complete feature list (Priority: P1) + +Someone deciding whether to use Gameplane wants one page that lists every capability the product has today, grouped by area (servers and lifecycle, console and admin actions, files, players, mods, backups, game modules, networking and tunnels, idle sleep and wake, multi-cluster, users and access, audit and security, notifications, telemetry, observability, localization, developer tooling), with each feature's maturity (stable, beta, experimental, optional/off by default, planned) and a link to where it is documented. + +**Why this priority**: This is the new artifact the user asked for and the one evaluators and contributors will use most. Every other page can link to it instead of repeating feature lists. + +**Independent Test**: Open the feature catalog, pick any 10 entries at random, and confirm each one exists in the shipped product with the stated maturity and that its documentation link resolves. + +**Acceptance Scenarios**: + +1. **Given** the feature catalog, **When** a reader looks for a capability that ships in the current release (for example wake-on-connect or audit log integrity), **Then** it is listed under the right area with its maturity label and a working link to its docs. +2. **Given** a feature that is opt-in or off by default (relay tunnels, packet capture, telemetry extended tier, PostgreSQL driver), **When** it appears in the catalog, **Then** its label says so, matching what the installer actually ships. +3. **Given** a capability that is planned but not shipped (service accounts, Users page identity-provider tab), **When** it appears in the catalog, **Then** it is clearly marked planned and links to the roadmap, never shown as available. +4. **Given** a feature in progress on an unmerged spec (for example language packs from spec 019), **When** the catalog is written, **Then** it is listed as in progress only if the roadmap lists it, and never as shipped before it is merged to the default branch. + +--- + +### User Story 2 - Maintainer and users see the current roadmap status (Priority: P1) + +A user or contributor opens the roadmap and sees where the project stands now: current release, what shipped in `v0.3.0` and since, what is in progress (each open spec with its state), what is blocked and on what, what stands between now and v1, and what is out of scope. + +**Why this priority**: The user explicitly asked for the roadmap to carry the new status; the current one stops at `v0.2.0-beta.8`. + +**Independent Test**: Compare each roadmap entry against the specs folder, the CHANGELOG and the merged history of the default branch on the day of the update; every entry's status must match. + +**Acceptance Scenarios**: + +1. **Given** the refreshed roadmap, **When** a reader looks for the `v0.3.0` release, **Then** it lists what shipped in it and links to the CHANGELOG. +2. **Given** an open spec (002, 009, 013, 019, 021, 023 at the time of writing), **When** a reader looks it up on the roadmap, **Then** it shows a plain-words status (in progress, blocked on X, waiting on packet capture) consistent with that spec's `tasks.md`. +3. **Given** an item that the old roadmap called planned or missing and that has since shipped, **When** the roadmap is refreshed, **Then** it moves to the shipped section with the release it shipped in. +4. **Given** the main repo roadmap and the website roadmap page, **When** both are read, **Then** they state the same status for every item. + +--- + +### User Story 3 - Self-hoster follows docs that match the product (Priority: P2) + +A self-hoster follows the README, the `docs/` guides, component READMEs and the website docs. Counts, version strings, feature descriptions, links and maturity labels all match what the current release does. + +**Why this priority**: Stale facts cause failed installs and lost trust, but the existing docs are mostly right; this story corrects drift rather than writing new material. + +**Independent Test**: Run the project's existing doc checks (version strings, internal links) in CI, and review a fixed list of known facts (module count, registry count, role names, defaults) against the code and the module catalog. + +**Acceptance Scenarios**: + +1. **Given** any page that states the number of shipped game modules or mod registries, **When** it is checked against the module catalog and the code, **Then** the number matches. +2. **Given** any page that describes a feature's default (on/off) or maturity, **When** it is checked against the shipped install defaults, **Then** it matches and uses the same label as the feature catalog. +3. **Given** the README, **When** a reader reaches its Features section, **Then** it gives a short summary and links to the full feature catalog instead of a second, diverging list. +4. **Given** every internal doc link and anchor in the main repo and the website, **When** CI link checks run, **Then** they all resolve. + +--- + +### User Story 4 - Website visitor finds the same information (Priority: P2) + +A visitor to the public website reads its docs pages and finds the same feature list, roadmap status and facts as the repository docs. + +**Why this priority**: The website is the public face; a mismatch with the repo makes the project look abandoned or inaccurate. + +**Independent Test**: For each fact checked in Story 3 and each roadmap item in Story 2, compare the website page and the repo page; they agree. + +**Acceptance Scenarios**: + +1. **Given** the website docs, **When** a visitor looks for a feature list, **Then** a features page exists in the docs navigation carrying the same content as the repo feature catalog. +2. **Given** the website roadmap page, **When** compared to `docs/roadmap.md`, **Then** statuses match. +3. **Given** website docs pages that cover the same topic as a `docs/` file, **When** both are read, **Then** they do not contradict each other. + +--- + +### Edge Cases + +- A feature exists in code but is hidden or unfinished in the dashboard (placeholder tabs): it is listed as planned, not shipped. +- A feature was withdrawn (Hell Let Loose module): it is removed from counts and lists; history stays only in the CHANGELOG. +- A spec merges while this refresh is in progress: the roadmap and catalog reflect the state of the default branch on the day the docs PR is opened, and the status date is printed on the roadmap. +- A fact cannot be verified from the code or docs (for example a competitor claim in the comparison table): it keeps its existing dated source and is not changed by this spec. +- Historical entries tagged `doc-versions: historical` keep their original version strings. +- A website page that needs a visual or layout change beyond text: the change is designed first in the website design file before any code, per the website rules. + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: The project MUST have one feature catalog file listing every shipped capability of Gameplane, with one entry per capability (one per thing a user or operator can do, roughly 100 to 150 entries) grouped under area headings, as a root `FEATURES.md` next to `README.md` (OD-1), mirrored by a features page on the website. +- **FR-002**: Each catalog entry MUST carry a one-line description, a maturity label from a fixed set (stable, beta, experimental, planned, in progress), a default (on, off, or n/a), and a link to the page that documents it. Maturity follows an evidence rule: **stable** = shipped, on by default and covered by a CI end-to-end test; **beta** = shipped but with documented caveats or no end-to-end test; **experimental** = the docs already call it experimental. An optional feature (one the install ships disabled) is never stable: it gets maturity beta or experimental with default **off**. +- **FR-003**: The catalog MUST cover the dashboard, operator, API, agent, optional components (sentinel, capture sidecar, tunnels, audit syslog bridge, telemetry receiver, MCP server, agent gateway), the game module catalog, and the module authoring tool. +- **FR-004**: The catalog MUST NOT list as shipped anything that is not merged to the default branch; planned and in-progress items MUST link to the roadmap. +- **FR-005**: `docs/roadmap.md` MUST state the current release, the date of the status, what shipped in `v0.3.0` and since (linking the CHANGELOG), each open spec with a plain-words status, blockers with what unblocks them, what remains for v1, and what is out of scope. +- **FR-006**: Roadmap items that have shipped MUST move to the shipped section with their release; stale "planned" claims MUST be corrected or removed. +- **FR-007**: The README MUST be corrected for stale facts (module count, status text, links) and its Features section MUST become a short summary linking to the feature catalog. +- **FR-008**: Every file under `docs/` and every component README in the main repo MUST be reviewed against the shipped product; stale counts, defaults, maturity labels, names and links MUST be fixed. +- **FR-009**: The website docs MUST be updated to match: a features page mirroring the catalog, the roadmap page mirroring `docs/roadmap.md`, and fixes to any website page carrying the same stale facts, as docs-page text only; the landing page is not changed (OD-3). +- **FR-010**: The module repository README MUST be checked for the module list and count and fixed if stale. +- **FR-011**: Every change MUST pass the project's existing documentation checks in CI (version strings, internal links and anchors, spec checks), with no checks loosened or skipped. +- **FR-012**: Each fact corrected MUST be traceable: the docs PR description or a review list in the spec folder MUST note what was stale, where, and what source confirmed the new value. +- **FR-013**: The roadmap MUST have an "In progress" section with one line per open spec in `specs/` on the status date, each with its plain-words status and blocker (OD-2). +- **FR-014**: The comparison table's competitor columns MUST NOT change unless re-verified with a dated source; only Gameplane-column facts are corrected. +- **FR-015**: A new CI check MUST fail when `FEATURES.md` and the website features page differ in their feature names, areas or maturity labels, and MUST ship with fixture tests covering the in-sync case and at least one mismatch of each kind. Existing checks are not loosened to make it pass. + +### Key Entities + +- **Feature catalog entry**: one capability (a single thing a user or operator can do); fields: area, name, one-line description, maturity label, default (on/off), documentation link, release first shipped (when known). +- **Roadmap item**: title, status (shipped, in progress, blocked, planned, out of scope), release or spec reference, blocker and what unblocks it, status date. +- **Stale fact record**: page, old value, new value, confirming source. + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 100% of shipped capabilities found in the docs, CHANGELOG and finished specs appear in the feature catalog, and a reviewer sampling 10 entries finds 10 correct (exists, right label, link resolves). +- **SC-002**: Every open spec in `specs/` on the status date appears on the roadmap with a status matching its `tasks.md`. +- **SC-003**: Zero known stale counts remain: every page stating the module count says 29 (or the catalog's count on the status date), and every page stating the registry count matches the code. +- **SC-004**: The repo roadmap and the website roadmap agree on 100% of item statuses; the repo catalog and the website features page list the same entries, enforced by the FR-015 check passing in CI. +- **SC-005**: The project's existing documentation checks pass in CI on the docs PRs with no rule changes, and the new sync check fails on a deliberately mismatched fixture in its own tests. +- **SC-006**: A new reader can answer "does Gameplane do X, and is it stable?" for any listed capability from the catalog alone in under one minute. + +## Assumptions + +- "Website" means the `GameplanePanel/website` docs pages (text content). Docs pages are added with frontmatter only, so adding a features page needs no design change. Landing page visuals are out of scope (OD-3). +- "/docs" means the main repo `docs/` folder, including `docs/design`, `docs/examples` and `docs/outreach` text where facts are stated; `docs/superpowers` and archived spec folders are not edited. +- "readme.md etc." means the root README, component READMEs (`audit-syslog-bridge`, `containers`, `mcp-server`, `telemetry-receiver`) and the module repo README. +- The CHANGELOG is a historical record and is not rewritten; only its link targets are checked. +- Dashboard screenshots are not retaken in this spec; capturing them needs the local design/frontend setup. +- Outreach and external publishing are out of scope (the maintainer does all outreach). +- Work lands as one PR per repository (main, website, module if needed), with the main repo submodule pointer bumped only after the website and module PRs merge. +- Status is measured against the default branch on the day the docs PRs are opened; specs that merge later are picked up by a follow-up edit, not by this spec. diff --git a/specs/024-docs-feature-list-refresh/tasks.md b/specs/024-docs-feature-list-refresh/tasks.md new file mode 100644 index 000000000..3812fe5c5 --- /dev/null +++ b/specs/024-docs-feature-list-refresh/tasks.md @@ -0,0 +1,168 @@ +--- + +description: "Task list for spec 024: documentation refresh, feature catalog and roadmap status" +--- + +# Tasks: Documentation Refresh, Feature Catalog, and Roadmap Status + +**Input**: Design documents from `specs/024-docs-feature-list-refresh/` + +**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) + +**Tests**: FR-015 requires fixture tests for the new sync check; those are included (US4). No `test/e2e/` test: Principle I docs exception (OD-4). Tests and lint run in CI only (CLAUDE.md rule 8); locally only `npm run build` / `npm run check` in the website and `bash -n` syntax checks. + +**Organization**: Grouped by user story. Repos: **GP** = `GameplanePanel/Gameplane`, **WEB** = `GameplanePanel/website`, **MOD** = `GameplanePanel/module`. Paths without a prefix are in GP. + +**Execution rules (every helper agent repeats these)**: follow the repo CLAUDE.md; implementation runs through `Workflow` scripts with `model:` set on every `agent()` call, starting at `haiku`, one tier-up `sonnet` review of the combined diff (rules 13, 18); signed commits (`git commit -s`), one branch per repo; never edit `.pen` files; never edit or weaken existing tests; competitor columns of the comparison table and `CHANGELOG.md` history are not changed (FR-014); website internal links use `withBase()` / relative docs links; submodule pointers are bumped only after the WEB/MOD PRs merge. + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (US1–US4) + +--- + +## Phase 1: Setup + +**Purpose**: Branches and the status snapshot every story reads from. + +- [ ] T001 Create branch `claude/024-docs-refresh` in GP from latest `master` (after the spec docs PR merges) and branch `claude/024-docs-refresh` in WEB from latest `main` +- [ ] T002 Record the status date and source revisions (GP `master` SHA, WEB `main` SHA, MOD `master` SHA, chart `appVersion` from `charts/gameplane/Chart.yaml`) at the top of `specs/024-docs-feature-list-refresh/stale-facts.md` +- [ ] T003 [P] Create `specs/024-docs-feature-list-refresh/feature-evidence.md` with the record header from [data-model.md](./data-model.md) (area, capability, maturity, e2e test, default source, notes) + +--- + +## Phase 2: Foundational (blocks all stories) + +**Purpose**: The fact base the catalog, roadmap and sweep all use. Each task writes a section of `specs/024-docs-feature-list-refresh/research-notes.md` (scratch input, committed for review). + +- [ ] T004 [P] List every e2e test registered in a bucket: parse `test/e2e/buckets.sh` and `test/e2e/*_test.go` into a table test name → bucket; note tests excluded from all buckets (they do not count as CI coverage, research R5) +- [ ] T005 [P] List install defaults: every enable/disable toggle in `charts/gameplane/values.yaml` with its default, plus build-tag features (`-tags postgres`) and separately installed components (sentinel, capture sidecar, tunnels, audit-syslog-bridge, telemetry-receiver, mcp-server, agent gateway) +- [ ] T006 [P] List the module catalog: game directories in MOD (expected 29, Hell Let Loose withdrawn) and the mod registries implemented in code (expected 10: Modrinth, CurseForge, Thunderstore, Hangar, Factorio Mod Portal, Steam Workshop, SpigotMC, GitHub Releases, uMod, Nexus Mods), citing the code location of the registry list +- [ ] T007 [P] Snapshot open specs: for each `specs/-*` folder without `done_` in GP `master`, record done/open task counts from its `tasks.md`, blockers named in it, and its open PRs (research R7 table refreshed) +- [ ] T008 [P] Summarise shipped work: `CHANGELOG.md` sections `[0.3.0]` and `[Unreleased]`, plus each `specs/done_*` folder's one-line outcome + +**Checkpoint**: research-notes.md complete; stories can start in parallel. + +--- + +## Phase 3: User Story 1 - Evaluator reads one complete feature list (Priority: P1) 🎯 MVP + +**Goal**: Root `FEATURES.md` lists every shipped capability, one row per capability, grouped by area, with evidence-based maturity, default and docs link (FR-001–FR-004, OD-1, Clarifications Q1/Q3). + +**Independent Test**: [quickstart.md](./quickstart.md) scenario 1: 10 random rows each have a matching evidence record, a label that obeys the data-model validation, and a docs link that documents the capability. + +- [ ] T009 [US1] Write the `FEATURES.md` skeleton per [contracts/features-catalog.md](./contracts/features-catalog.md): title, intro explaining the labels (stable / beta / experimental / planned / in progress, and the on/off/n/a default column), status date, link to `docs/roadmap.md`, and the 18 area `##` headings from research R6, each with the catalog table header +- [ ] T010 [P] [US1] Inventory rows for areas *Servers and lifecycle*, *Console and admin actions*, *Files*, *Players* from `web/src/router/tree.tsx`, `web/src/routes/`, `api/cmd/main.go`, README Features, `docs/architecture.md` and website pages `server-operations.mdx`, `console-events-logs.mdx`, `file-manager.mdx`, `player-administration.mdx`; write rows and evidence records to `specs/024-docs-feature-list-refresh/catalog-drafts/servers-console-files-players.md` +- [ ] T011 [P] [US1] Inventory rows for *Mods*, *Backups and restore*, *Game modules and catalog*, *Module authoring* from README Mod Management, `docs/module-authoring.md`, `gp-module/`, `operator/api/v1alpha1/` (ModuleSource, GameTemplate, Backup*, Restore), website `mods-modpacks.mdx`, `backups-recovery.mdx`, `modules-sources.mdx`; write rows and evidence records to `specs/024-docs-feature-list-refresh/catalog-drafts/mods-backups-modules-authoring.md` +- [ ] T012 [P] [US1] Inventory rows for *Networking and tunnels*, *Idle sleep and wake*, *Multi-cluster* from `docs/networking.md`, `docs/tunnels.md`, `docs/multicluster-*.md`, `docs/unified-dashboard.md`, `docs/remote-parity.md`, `sentinel/`, `tunnel/`; write rows and evidence records to `specs/024-docs-feature-list-refresh/catalog-drafts/networking-sleep-multicluster.md` +- [ ] T013 [P] [US1] Inventory rows for *Users, auth and access*, *Audit and security*, *Notifications*, *Telemetry* from `docs/oidc.md`, `docs/security.md`, `docs/notifications.md`, `docs/telemetry-provider.md`, `docs/key-rotation.md`, `api/internal/rbac/`, `audit-syslog-bridge/README.md`, `telemetry-receiver/README.md`; write rows and evidence records to `specs/024-docs-feature-list-refresh/catalog-drafts/access-audit-notify-telemetry.md` +- [ ] T014 [P] [US1] Inventory rows for *Observability and admin*, *Localization*, *Developer and operator tooling* from `docs/install.md`, `docs/gateway-install.md`, `mcp-server/README.md`, `capture-sidecar/`, `charts/gameplane/`, website `metrics-alerts-dashboards.mdx`, `system-log-viewer.mdx`; localization rows reflect only what is merged on `master` (spec 019 work is `in progress`, FR-004); write rows and evidence records to `specs/024-docs-feature-list-refresh/catalog-drafts/observability-l10n-tooling.md` +- [ ] T015 [US1] Merge the five `catalog-drafts/*.md` files into `FEATURES.md` (rows under their area headings) and `feature-evidence.md` (single owner of both files; delete `catalog-drafts/` afterwards), then apply the maturity rule to every row using T004/T005 facts: `stable` only with `default = on` and a bucketed e2e test; `default = off` rows are `beta` or `experimental`; `experimental` only where docs already say so (PostgreSQL driver); planned/in-progress rows get `default = n/a` and a roadmap link; fill each evidence record (`FEATURES.md`, `feature-evidence.md`) +- [ ] T016 [US1] Deduplicate and order rows within each area, check every Docs link target exists in GP, and confirm the row count is in the 100–150 range or note why not in `feature-evidence.md` +- [ ] T017 [US1] Tier-up review (`sonnet`): check the combined `FEATURES.md` + `feature-evidence.md` diff against research-notes.md and the sources; fixes go to a new `haiku` fix wave + +**Checkpoint**: `FEATURES.md` draft complete on the GP branch (not yet merged). + +--- + +## Phase 4: User Story 2 - Current roadmap status (Priority: P1) + +**Goal**: `docs/roadmap.md` states current release, status date, what shipped in v0.3.0 and since, one line per open spec, blockers, v1 items and out-of-scope (FR-005, FR-006, FR-013, OD-2). + +**Independent Test**: quickstart scenario 2: every non-`done_` spec folder has a roadmap line whose status matches its `tasks.md` on the status date. + +- [ ] T018 [US2] Restructure `docs/roadmap.md` into the section order from [data-model.md](./data-model.md) (current release + status date; shipped in v0.3.0 and since; in progress; blocking v1; wanted for v1; known gaps; out of scope; join protocol coverage), keeping existing `` markers on historical headings +- [ ] T019 [US2] Add the "Shipped in v0.3.0" and "Since v0.3.0" entries to `docs/roadmap.md` from T008, each linking `CHANGELOG.md` +- [ ] T020 [US2] Add the "In progress" section to `docs/roadmap.md` with one line per open spec from T007 (002, 009, 013, 019, 021, 023 unless the snapshot differs): plain-words status, blocker and what unblocks it +- [ ] T021 [US2] Re-check every existing "planned" / "known gap" item in `docs/roadmap.md` against `master` and MOD (e.g. "Game module template specifications" against `modules//specs.md` presence; Users page service-accounts / IdP tabs against `web/src/routes/Users.tsx`); move shipped items to the shipped section with their release, correct or remove stale ones, and log each change in `stale-facts.md` +- [ ] T022 [US2] Update the join-coverage counts in the roadmap's last section from `docs/game-coverage.md` so they total 29 modules + +**Checkpoint**: repo roadmap complete on the GP branch. + +--- + +## Phase 5: User Story 3 - Docs match the product (Priority: P2) + +**Goal**: README, `docs/`, component READMEs and the MOD README carry no stale facts; README Features becomes a summary linking `FEATURES.md` (FR-007, FR-008, FR-010, FR-012, FR-014). + +**Independent Test**: quickstart scenarios 3 and 8: no stale counts remain, every fix is in `stale-facts.md`, README links the catalog, competitor columns unchanged. + +- [ ] T023 [US3] Grep GP (`README.md`, `docs/**/*.md` except `docs/superpowers/`, component READMEs) and MOD `README.md` for each fact class in research R9 (module count, registry count, role names, release/status wording, optional defaults, Hell Let Loose, Go module counts, page names); write every hit with its correct value and source into `stale-facts.md` +- [ ] T024 [US3] Fix `README.md`: "30" → "29" templates in the Features list and the comparison table's Gameplane column, status wording, and replace the Features section with a short summary plus a link to `FEATURES.md`; leave competitor columns untouched +- [ ] T025 [P] [US3] Fix `docs/comparison-sources.md` Gameplane-row facts (the "30 ready-to-use templates" claim → 29) without changing any competitor entry or its dated source +- [ ] T026 [P] [US3] Apply the remaining `stale-facts.md` fixes in `docs/*.md` (one commit per logical group) +- [ ] T027 [P] [US3] Apply the `stale-facts.md` fixes in `audit-syslog-bridge/README.md`, `containers/README.md`, `mcp-server/README.md`, `telemetry-receiver/README.md` +- [ ] T028 [US3] MOD: if `README.md` module list or count is stale, branch `claude/024-readme-catalog` in MOD, fix it, open the MOD PR (signed commits); otherwise record "MOD README current" in `stale-facts.md` +- [ ] T029 [US3] Add `FEATURES.md` to the audited-file lists and header comments in `hack/check-links.sh` and `hack/check-doc-versions.sh`, and to the `docs` path filter in `.github/workflows/ci.yaml` (research R8; widens coverage, relaxes nothing) +- [ ] T030 [US3] Tier-up review (`sonnet`) of the combined US2 + US3 GP diff against `stale-facts.md` and research-notes.md; fixes in a new `haiku` wave + +**Checkpoint**: GP docs refreshed on the branch. + +--- + +## Phase 6: User Story 4 - Website shows the same information (Priority: P2) + +**Goal**: WEB features page mirrors `FEATURES.md`, roadmap page mirrors `docs/roadmap.md`, stale facts fixed in docs pages only (FR-009, OD-3); GP sync check enforces catalog parity in CI (FR-015, Clarification Q2). + +**Independent Test**: quickstart scenarios 4, 5 and 7: website builds with the Features page in Reference → Releases & Roadmap; `make test-features-sync` and `make check-features-sync` pass in CI; roadmaps agree. + +### Website PR (WEB, merges before the GP PR) + +- [ ] T031 [US4] Create `src/content/docs/features.mdx` in WEB with the frontmatter from [contracts/features-catalog.md](./contracts/features-catalog.md) and the same area headings and tables as `FEATURES.md` (Capability, Maturity, Default identical; Docs cells rewritten to relative website docs links per the WEB CLAUDE.md); depends on T017 +- [ ] T032 [US4] Rewrite `src/content/docs/roadmap.mdx` in WEB to the same items and statuses as `docs/roadmap.md` (replace the "Beta status" headline with the current pre-v1 release wording); keep existing components (`DocsCallout`, `IconList`, `VERSION`); depends on T022 +- [ ] T033 [P] [US4] Grep WEB `src/content/docs/*.mdx` and `src/config.ts` for the R9 fact classes, add hits to `stale-facts.md`, and fix them in the docs pages (no landing page or component changes, OD-3) +- [ ] T034 [US4] Run `npm run build` and `npm run check` in WEB (allowed locally); fix build errors only +- [ ] T035 [US4] Open the WEB PR to `main` (signed commits), get WEB CI (`lint`, `check`, `build`) green, and wait for it to merge + +### Sync check (GP) + +- [ ] T036 [P] [US4] Write fixtures in `hack/testdata/check-features-sync/` per [contracts/features-sync-check.md](./contracts/features-sync-check.md): `pass/in-sync`, `pass/code-fence`, and `fail/{missing-row-website,missing-row-repo,maturity-mismatch,default-mismatch,area-mismatch,order-differs,invalid-label,stable-off,missing-file}` each with `.expected` output +- [ ] T037 [P] [US4] Write `hack/check-features-sync.sh` (Bash + awk, `set -euo pipefail`, env overrides `FEATURES_MD` / `FEATURES_MDX`, exit 0/1/2 and messages exactly as the contract), header comment citing spec 024 FR-015 +- [ ] T038 [US4] Write `hack/test-check-features-sync.sh` following the `hack/test-check-doc-versions.sh` harness (pass cases exit 0; fail cases exit non-zero with output equal to `.expected`); check both scripts with `bash -n` only +- [ ] T039 [US4] Add Makefile targets `check-features-sync` and `test-features-sync` (with `##` help text) and add `check-features-sync` to the `lint` target in `Makefile` +- [ ] T040 [US4] After T029 (both edit the `docs` path filter; extend T029's list, never replace it), in `.github/workflows/ci.yaml` `docs` job: add a step `git submodule update --init website` before the checks, then steps running `make check-features-sync` and `make test-features-sync`; add `FEATURES.md`, `website`, `hack/check-features-sync.sh`, `hack/test-check-features-sync.sh`, `hack/testdata/check-features-sync/**` to the `docs` path filter; if spec 023's selection script has landed, map the same paths to the docs job in `hack/ci_scope.py` +- [ ] T041 [US4] Tier-up review (`sonnet`) of T036–T040 against the contract; fixes in a new `haiku` wave + +**Checkpoint**: WEB merged; sync check ready on the GP branch. + +--- + +## Phase 7: Polish & delivery + +- [ ] T042 Bump the `website` submodule pointer to the merged WEB commit (and `modules` if T028 merged a MOD PR) on the GP branch; after the bump, copy any final `FEATURES.md` edits into `features.mdx` via a WEB follow-up PR before bumping again, so the two stay identical +- [ ] T043 Open the GP PR (signed commits, labels `type: docs`, `area: specs`, plus `area: shared` for the hack/CI change), body without attribution block or session links; drive CI green, including `check-links`, `check-doc-versions`, `check-features-sync`, `test-features-sync` +- [ ] T044 Run quickstart scenarios 1–8 against the merged state and record results in `specs/024-docs-feature-list-refresh/stale-facts.md` (final section) +- [ ] T045 After the GP PR merges: tick all tasks, `git mv specs/024-docs-feature-list-refresh specs/done_024-docs-feature-list-refresh`, update in-repo references, in its own `docs:` commit and PR (Constitution IV, CLAUDE.md rule 16) + +--- + +## Dependencies & Execution Order + +- **Setup (T001–T003)** → **Foundational (T004–T008)** → stories. +- **US1 (T009–T017)** and **US2 (T018–T022)** can run in parallel after Foundational. +- **US3 (T023–T030)** can start after Foundational; T024 needs `FEATURES.md` to exist (T009) for the link. +- **US4 website (T031–T035)** needs US1 (T017) and US2 (T022) done; T033 can start any time after Foundational. +- **US4 sync check (T036–T041)**: T036–T039 need only the contract and can run in parallel with everything else; T040 runs after T029 because both edit the `docs` path filter in `ci.yaml`; T041 reviews T036–T040. +- **Shared files**: T010–T014 each write their own `catalog-drafts/*.md` file; only T015 writes `FEATURES.md` and `feature-evidence.md`. +- **Polish (T042–T045)** needs the WEB PR merged (T035) and all GP work done. + +Story order by value: US1 → US2 → US3 → US4. Delivery order is fixed by the submodule rule: MOD PR (if any) and WEB PR merge first, then the GP PR. + +## Parallel Example + +```text +After T008: + Workflow wave A (haiku): T010, T011, T012, T013, T014 # catalog areas, separate sections + Workflow wave B (haiku): T018–T022 (roadmap, one agent), T023 (grep sweep), T033 (website grep) + Workflow wave C (haiku): T036, T037 # fixtures and script +Then one sonnet review per wave (T017, T030, T041). +``` + +## Implementation Strategy + +- **MVP**: Phases 1–3 (US1): a reviewed `FEATURES.md` with evidence. It is useful on its own and everything else links to it. +- **Increment 2**: US2 roadmap. +- **Increment 3**: US3 stale-fact sweep and doc-gate coverage. +- **Increment 4**: US4 website mirror, then the sync check lands in the GP PR together with the pointer bump. +- One GP PR for all GP changes (plus the separate archive PR), one WEB PR, at most one MOD PR (research R10).