docs: clarify test:counts and standalone gateway prerequisites

AI_HANDOVER.md

@@ -55,7 +55,7 @@ Milestone progress spans foundational core engines through active production har
 ## Test Verification & CI
 
 - **Suite execution**: Run `npm test` across all root workspaces via `node --test`.
-- **Live metrics**: `npm run test:counts` aggregates test and skip counts across package and service suites; consult [`docs/PROJECT_STATE.md`](docs/PROJECT_STATE.md) for current tooling caveats and measured validation status.
+- **Live metrics**: After the host setup below, `npm run test:counts` aggregates test and skip counts across root workspace packages and the standalone gateway service. Skipped integration tests are not passes; consult [`docs/PROJECT_STATE.md`](docs/PROJECT_STATE.md) for measured validation status and active defects.
 - **Hermetic defaults**: Unit and domain suites run offline without external infrastructure. Integration suites gate on environment variables: `DATABASE_URL` (PostgreSQL persistence), `REDIS_URL` (gateway Redis integration and scaling), and provider API keys (live AI features).
 - **Continuous Integration (`.github/workflows`)**:
   - Multi-version Node matrix (Node 22 / 24) with strict typechecking, linting, and ADR claim validation (`npm run check:adr-claims`).
@@ -71,14 +71,16 @@ Milestone progress spans foundational core engines through active production har
 ## Build & Run
 
 ```bash
-npm ci               # reproducible install (root package-lock.json is committed)
-npm run build        # builds all root workspace packages in dependency order
-npm test             # executes workspace package test suites via node --test
-npm run lint         # strict typecheck across all root workspaces
-npm run test:counts  # aggregates test and skip counts across suites (see PROJECT_STATE caveats)
+npm ci                           # install root workspace dependencies from the root lockfile
+npm run build                    # build root workspace packages in dependency order
+npm ci --prefix services/gateway # install the standalone service from its own lockfile
+npm test                         # execute root workspace package test suites
+npm run lint                     # strict typecheck across root workspaces
+npm run test:counts              # execute and count workspace + gateway service tests
 ```
 
 - **Build order**: Run **`npm run build` before `lint` or `test` on a fresh clone** — downstream packages resolve upstream types from built `dist/`.
+- **Standalone gateway**: Root `npm ci` and `npm run build` exclude `services/gateway`. Its separate install is required before `test:counts` or direct gateway tests, even without `REDIS_URL`. The test command compiles its own `dist-test/`; a gateway production build is only needed for its `dist/` output. See [`docs/RUNNING.md`](docs/RUNNING.md#host-build-tests-and-live-counts) for host setup and troubleshooting.
 - **Local full stack**: `docker compose up --build` (see [`docs/RUNNING.md`](docs/RUNNING.md)).
 - **Helm chart validation**: `bash scripts/helm-snapshot-test.sh` (or lint with test secrets: `helm lint deploy/helm/gambit --set secrets.accessTokenSecret=test-only-access-token-secret-32-bytes-minimum --set secrets.postgresPassword=test-only-postgres-password --set config.nodeEnv=development --set email.provider=console`).
 

README.md

@@ -70,6 +70,10 @@ chess-platform/
 production adapters (Postgres event log, Redis pub/sub, `ws`). Deployment
 assets live under `deploy/`; see the roadmap for remaining infrastructure work.
 
+For a fresh clone, follow the [host build and test setup](docs/RUNNING.md#host-build-tests-and-live-counts).
+It covers the root workspace build and the separate gateway dependency install required by
+`npm run test:counts`.
+
 ## `@chess-platform/core`
 
 A dependency-free, fully-typed chess engine.

docs/CI_SETUP.md

@@ -65,8 +65,12 @@ ADR-0121 is additionally guarded in seconds by
 
 ## Notes
 
-- Installs use `npm ci` against the committed root `package-lock.json` for
-  reproducible builds.
+- Root workspace installs use `npm ci` against the committed root `package-lock.json`.
+  The `gateway-service` job then builds the root packages and runs a second `npm ci`
+  in `services/gateway`, using that service's own committed `package-lock.json`,
+  before building, typechecking, and testing the service. Root install/build commands
+  exclude the standalone service. Host preparation for these checks is documented in
+  [RUNNING.md](RUNNING.md#host-build-tests-and-live-counts).
 - The deeper chart-wiring checks (env-var ordering, gateway `replicas: 2`,
   secret sourcing, the search kill switches, and search indexer isolation) live
   in `scripts/helm-snapshot-test.sh`. The default of 2 gateway replicas enables

docs/PROJECT_STATE.md

@@ -4,7 +4,78 @@
 > to read **only this file** and continue immediately. Updated after every
 > milestone and every significant architectural step.
 
-_Last updated: 2026-09-05 — M15 Increment 49: the durable analysis-cache suite establishes its own database._
+_Last updated: 2026-09-05 — M15 Increment 50: test:counts / standalone gateway host setup contract._
+
+## M15 Increment 50 — test:counts / standalone gateway host setup contract
+
+**Status: RESOLVED — SETUP / DOCUMENTATION CONTRACT DRIFT CORRECTED.** The bounded
+gateway setup investigation recorded in Increments 48 and 49 is closed. The gateway
+intentionally remains outside the root `packages/*` workspaces. No gateway implementation
+defect was proven, and no workspace topology, script, lockfile, CI, Docker or runtime change
+is required. Increment 49's durable analysis-cache database-ownership defect remains resolved.
+
+**Supported host preparation, from the repository root with Node.js 22+:**
+
+```sh
+npm ci
+npm run build
+npm ci --prefix services/gateway
+npm run test:counts
+```
+
+Root `npm ci` installs the root workspaces, but not the standalone gateway dependencies.
+Root build establishes the workspace public `dist` outputs used by the gateway's local
+`file:` dependencies; installing those links does not build their targets. The gateway has
+its own manifest, lockfile and install lifecycle. `test:counts` includes the 19 root workspace
+suites and the standalone gateway suite, but neither installs dependencies nor establishes
+the workspace public outputs. Gateway tests compile `dist-test`; a prior gateway production
+build is not required. The sequence above follows the existing CI preparation order.
+
+**Controlled evidence on historical main `771b1f93c05585294474e95fcb24bf116766db3d`.**
+Four independent archives began without dependency trees or build outputs. Root install
+alone (A) failed with missing workspace outputs and gateway dependencies. Root install plus
+root build (B) left only the gateway failing, with six `TS2307` diagnostics for `ioredis`.
+Root plus gateway installs without root build (C) resolved `ioredis`, but failed on missing
+workspace public outputs. Full preparation (D) made the gateway pass: 16 tests, 11 passed,
+5 skipped. D's aggregate still exited 1 because `openapi.test.js` produced a bare file-level
+`test failed`; its isolated rerun passed all 18 tests. The failure did not reproduce in that
+isolated run, and the observation does not identify its mechanism.
+
+Adding only the gateway install to B made its direct test pass, with no root rebuild or
+gateway production build. Repeating root `npm ci` then preserved both the gateway dependency
+tree and existing workspace outputs, and the direct gateway test still passed. A root clean
+install in an already prepared checkout is therefore not a wholly clean repository state.
+This explains the setup-dependent exit-1 versus exit-0 observations: host preparation and
+documentation had drifted, rather than the gateway needing to become a root workspace.
+The exact sequence on the original historical machine cannot be recovered. An independent
+prepared acceptance tree subsequently measured `test:counts` exit 0, 3269 total, 115 skipped;
+those numbers predate PR #43 and are historical, not current counts.
+
+**Documentation correction.** `AI_HANDOVER.md`, `README.md`, `docs/RUNNING.md` and
+`docs/CI_SETUP.md` now state or link the complete host setup. This entry and `docs/ROADMAP.md`
+synchronize the canonical record after PR #43, without changing the counting implementation.
+Both lockfiles were unchanged throughout the controlled investigation.
+
+**Current measurement after synchronizing PR #43's main
+`026005b2420006e04028bff4c69a16f30c78a905`, on 2026-09-05.** On Windows with Node
+24.15.0 and npm 11.12.1, root `npm ci`, root build and gateway `npm ci` each exited 0.
+`npm run test:counts` then exited **0: 3272 tests, 118 skipped**. The root subtotal was
+**3256 tests, 113 skipped** across 19 workspaces; gateway was **16 tests, 11 passed,
+5 skipped**. Root `npm test` also exited 0. This remeasurement used the task's previously
+prepared checkout with both installs repeated; the independent clean-state proof is above.
+`DATABASE_URL` and `REDIS_URL` were unset. Redis-backed tests were **NOT RUN**; skipped
+database/Redis coverage is not a passing integration result. These current counts supersede
+the historical 3269/115 measurement for this revision only.
+
+**Signature B remains UNRESOLVED and under separate investigation.** The D observation above
+is retained independently of the resolved setup defect. No mechanism or unmerged findings
+from the separate diagnostic PR are adopted here. Successful later runs do not resolve it.
+During the post-review verification repeat, `learning-api.test.js` also produced a bare
+file-level `test failed`: API reported 975 tests, 927 passed, 1 failed and 47 skipped.
+Its isolated rerun passed all 22 tests. This is another observation of the failure shape,
+not proof of a mechanism or a gateway setup failure; the earlier successful aggregate
+measurement above is retained as a separate run.
+Environment-gated skips are not passes; Redis-backed tests require a separate Redis-enabled run.
 
 
 ## M15 Increment 49 — the durable analysis-cache suite establishes its own database