From 9624e685afbd6ca13b010767d802aa80724ae930 Mon Sep 17 00:00:00 2001 From: sami Date: Tue, 15 Sep 2026 17:46:48 +0400 Subject: [PATCH] docs: cmake/platform.cmake belongs to PKG/QA, not PORT (ADR 0020 amendment) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As written, ADR 0020 gave PORT ownership of cmake/platform*.cmake while also making PORT wait for Phase 0 — but Phase 0's seams are exactly what needs velox_platform_sources() to select platform/linux/*.cpp. PORT cannot start until Phase 0 lands, and Phase 0 cannot land without the file PORT owns. PKG/QA caught the circularity before writing anything, which was the right call. Central OS detection is root build infrastructure, so it stays with PKG/QA and lands during Phase 0. PORT keeps the per-OS backend directories and the macOS and Windows packaging, and owns no part of cmake/. Also drops a hardcoded test count from the PORT definition of done; the suite number moves every round and the gate is that it stays green. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 2 +- docs/adr/0020-cross-platform-strategy.md | 11 +++++++---- docs/agents/AGENT-PORT.md | 9 +++++---- 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 69910ea..41418e5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,7 +12,7 @@ Read this before touching anything. Then read your lane brief in [docs/agents/]( | GUI | `gui/` | everything else | | EXT | `extension/` | everything else | | PKG/QA | `packaging/`, `.github/`, `tools/testserver/`, `tests/integration/`, `tests/e2e/`, root build files | any lane's feature code | -| PORT | `**/platform//**`, `cmake/platform*.cmake`, `packaging/macos/`, `packaging/windows/` | all logic — see [ADR 0020](docs/adr/0020-cross-platform-strategy.md) | +| PORT | `**/platform//**`, `packaging/macos/`, `packaging/windows/` | all logic, and `cmake/` — see [ADR 0020](docs/adr/0020-cross-platform-strategy.md) | If your task seems to require editing another lane's files, that is a signal the interface is wrong. **File the request; don't reach across.** diff --git a/docs/adr/0020-cross-platform-strategy.md b/docs/adr/0020-cross-platform-strategy.md index 69fa086..ee60d2d 100644 --- a/docs/adr/0020-cross-platform-strategy.md +++ b/docs/adr/0020-cross-platform-strategy.md @@ -38,12 +38,15 @@ Node, `tools/testserver` is stdlib Python, and the extension is a WebExtension. 3. **Seams are introduced by the owning lane, on Linux, before any port work.** CORE introduces `core`'s seams; DAEMON introduces `daemon`'s. This is a pure refactor: move the existing Linux code behind the interface unchanged, prove the suite is still green. -4. **A new lane, PORT, owns only the per-OS backends** — `**/platform//**` and - `cmake/platform*.cmake`. It never writes logic. That keeps CLAUDE.md §1 intact: CORE +4. **A new lane, PORT, owns only the per-OS backends** — `**/platform//**`. It never + writes logic, and it does not own `cmake/`: the central OS detection module is root + build infrastructure and stays with PKG/QA, who must land it during Phase 0 because + Phase 0's own seams consume it. PORT owning it would deadlock — PORT cannot start until + Phase 0 lands, and Phase 0 cannot select platform sources without it. That keeps CLAUDE.md §1 intact: CORE still owns `core/`'s logic, DAEMON still owns `daemon/`'s, and macOS work can proceed in parallel without cross-lane writes. -5. **`VELOX_OS_*` is set once, centrally**, in `cmake/platform.cmake`, and platform sources - are selected there — not by globbing, and not per-target ad hoc. +5. **`VELOX_OS_*` is set once, centrally**, in `cmake/platform.cmake` (owned by PKG/QA), + and platform sources are selected there — not by globbing, not per-target ad hoc. 6. **Optional dependencies are gated, never removed.** `libsecret` stays `REQUIRED` on Linux and is replaced by Keychain on macOS behind the same credential-store seam. diff --git a/docs/agents/AGENT-PORT.md b/docs/agents/AGENT-PORT.md index fc3da70..37e9fb7 100644 --- a/docs/agents/AGENT-PORT.md +++ b/docs/agents/AGENT-PORT.md @@ -5,7 +5,7 @@ ## You own ``` core/src/**/platform//** daemon/src/**/platform//** -cmake/platform*.cmake packaging/macos/** packaging/windows/** +packaging/macos/** packaging/windows/** ``` You may read everything. **You never write logic** — not in `core/src/io/*.cpp`, not in `daemon/src/rpc/*.cpp`, not in `gui/`, never in `contracts/`. @@ -22,8 +22,9 @@ quietly edits shared logic is how one tree becomes two. ## Build order (macOS) 1. **Configure at all.** The root `CMakeLists.txt` requires `libsecret-1` unconditionally; - that must be Linux-gated before anything else compiles. File it with PKG/QA — root build - files are theirs. + that must be Linux-gated before anything else compiles. PKG/QA owns that, and also owns + `cmake/platform.cmake` (the `VELOX_OS_*` detection and `velox_platform_sources()`); both + land in Phase 0, before you start. File anything else you need with them. 2. `core/` — `preallocate`, `advise_dontneed`, `flush_durable`. Use `F_FULLFSYNC`, not `fsync`: `.veloxpart` resume correctness depends on a real flush. 3. `daemon/` — `Wakeup` (self-pipe), `peer_of` (`getpeereid`), `instance_lock` (socket file @@ -41,7 +42,7 @@ quietly edits shared logic is how one tree becomes two. - One real download completes on macOS against `tools/testserver` with a SHA-256 that matches the server's reference — the same gate the Linux vertical slice passed. - `kill -9` mid-download, restart, resume completes and the checksum still matches. -- The Ubuntu suite is **still** 57/57 from the same commit. +- The Ubuntu suite is **still** green from the same commit. ## Do not - Do not add `#ifdef` outside a `platform//` file.