From 31c5b81012765dfc937853e036dc369397ea350f Mon Sep 17 00:00:00 2001 From: Ana Laura Ferraz Date: Tue, 20 Oct 2026 16:46:38 -0300 Subject: [PATCH] docs: amend the constitution to v1.1.0 and align CLAUDE.md --- .specify/memory/constitution.md | 40 ++++++++++++++++++++++++++++----- CLAUDE.md | 4 ++-- 2 files changed, 37 insertions(+), 7 deletions(-) diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index e4f0c90..919df84 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,3 +1,32 @@ + + # TelemetryF1_API Constitution This constitution was written after the fact, from the code that already existed when Spec Driven Development was adopted. It records rules the codebase already follows plus the development process adopted from that point on; it does not describe aspirations. @@ -32,7 +61,7 @@ The REST and WebSocket payloads are a contract consumed by the Telemetry-F1 fron ## Technology and Quality Constraints -- Node.js ≥ 22.6, TypeScript in `strict` mode, CommonJS. +- Node.js ≥ 22.17, declared in `engines.node`: the test-discovery guard uses `fs.globSync`, stable only from 22.17. The major in use, locally and in the CI, is the one pinned in `.nvmrc`. TypeScript in `strict` mode, CommonJS. - Express 5 for REST, `ws` for WebSocket, `dgram` for UDP, `better-sqlite3` for persistence, `@anthropic-ai/sdk` for the coach. - Tests use Node's built-in runner (`node:test`, `node:assert/strict`) with synthetic fixtures. Pure logic — analysis, decimation, lap completion detection, message building — is covered by unit tests, and new pure logic follows the same rule. - Identifiers, file names and commit messages are in English. Logs, test names and comments are in Portuguese. Comments are minimal and explain only a non-obvious *why*. @@ -41,11 +70,12 @@ The REST and WebSocket payloads are a contract consumed by the Telemetry-F1 fron ## Development Workflow - New features follow Spec Driven Development: the spec, plan and tasks are committed before the implementation, in separate commits. -- `npm test` and `npx tsc --noEmit` pass before every commit. A failure is reported, never committed around. -- Commits are small Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`) with no `Co-Authored-By` trailer. +- `npm test` and `npm run typecheck`, the same scripts the CI runs, pass locally before every commit. A failure is reported, never committed around. +- The CI is the merge gate of `main`: a pull request merges only with the `typecheck` and `test` checks green. `main` is protected by the GitHub ruleset described in `README.md`: changes arrive only through a pull request, the branch must be up to date with `main`, history stays linear, the bypass list is empty (administrators included), and "Rebase and merge" is the only merge method allowed. The only exception is the last-resort procedure in `README.md` for a GitHub Actions outage (disable the ruleset, merge, re-enable it at once), always recorded in the pull request. +- Commits are small Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, and `ci:` for changes to the GitHub Actions workflow) with no `Co-Authored-By` trailer. - Known limitations are listed in both `CLAUDE.md` and `README.md`. The change that fixes a limitation removes it from both. - Decisions with trade-offs are presented as options before being made. -- Published git history is never rewritten. +- Published git history is never rewritten. One exception was made, on 2026-10-18: `main` was rewritten with `git filter-repo` to remove a `Co-Authored-By` trailer from one already-published commit. The rule otherwise still stands; that exception is not a precedent for rewriting history. ## Governance @@ -53,4 +83,4 @@ This constitution takes precedence over other practices in this repository. `CLA Amendments are made through a pull request that updates this file and states the reason. Versions follow semantic versioning: MAJOR for removing or redefining a principle, MINOR for adding a principle or section, PATCH for clarifications. Every plan produced with `/speckit-plan` includes a constitution check, and reviews verify compliance. -**Version**: 1.0.0 | **Ratified**: 2026-10-16 | **Last Amended**: 2026-10-16 +**Version**: 1.1.0 | **Ratified**: 2026-10-16 | **Last Amended**: 2026-10-20 diff --git a/CLAUDE.md b/CLAUDE.md index 01d3c79..ddd5f47 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ Backend that ingests the F1 24 game's UDP telemetry, persists it to SQLite, stre ## Stack -- Node.js: major 22 pinned in `.nvmrc`, minimum 22.17 declared in `engines` (the constitution still says ≥ 22.6 until its amendment PR). TypeScript (CommonJS, `strict`), run with `ts-node-dev` (no build step yet) +- Node.js: major 22 pinned in `.nvmrc`, minimum 22.17 declared in `engines`. TypeScript (CommonJS, `strict`), run with `ts-node-dev` (no build step yet) - `dgram` (UDP), `ws` (WebSocket), Express 5 (REST), `better-sqlite3` (SQLite, WAL) - `@anthropic-ai/sdk` for the coach - Tests: Node's built-in runner (`node:test` + `node:assert/strict`) via `ts-node/register` @@ -56,7 +56,7 @@ The REST and WebSocket payloads are a contract consumed by the frontend, which m - Repositories use prepared statements created at module load and map snake_case rows to camelCase objects. - Unknown values are stored as `NULL`, never invented (see `lapCompletionDetector`). - Tests: flat `test()` calls, synthetic data from a `testFixtures.ts` per folder (`src/analysis/`, `src/replay/`), mostly pure functions. The handful of tests that need a real SQLite connection (sample repositories, the replay integration test) use `src/persistence/testDb.ts` to open an isolated, disposable database via `DB_PATH` — never `data/telemetry.db`. A new test file under `src/` is picked up by the `test` script with no edit. -- Commits: small, Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`), English subject, **no `Co-Authored-By` trailer**. +- Commits: small, Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `ci:`), English subject, **no `Co-Authored-By` trailer**. - **Check names are a contract:** renaming a CI job (`typecheck`, `test`) requires updating the required checks of the ruleset on `main` in the same piece of work, and renaming `ci.yml` requires updating the README badge in the same piece of work. - **Actions:** first-party `actions/*` by major tag; any third-party action by full commit SHA with a trailing version comment.