docs(engine): remove stale test and deployment claims

[edwardnewgate710]

Summary

Eliminates stale test counts, outdated forward-looking milestone claims, and obsolete architecture status from packages/engine/README.md. Synchronized with current main (748f5d8dda87e7a5ce2c567492a21b9d795e40b7).

Base and Synchronization Metadata

• Historical Base: df930198fb7707dbd7fa137b66109bf557c748b6
• Current Synchronized main: 748f5d8dda87e7a5ce2c567492a21b9d795e40b7 (incorporating PR fix(persistence-test): give each suite ownership of the rows it creates #38, PR test(api-diagnostics): harden Signature B correlator against cross-directory false attribution and signed NTSTATUS codes #35, PR fix(api-test): enforce shared database ownership in pg-security integration tests #41, PR docs(ci): align CI setup with current workflow and Helm contract #40)
• Exact New Final HEAD: cfe1555672d941fdfb2c0d1e4af212e84480a012
• PR Status: OPEN, non-draft, MERGEABLE / CLEAN (Explicitly NOT MERGED)
• Review Threads: 0 unresolved

PR-Specific Changes and Diff Stats

• Changed Files: packages/engine/README.md (only)
• Diff Stats:

  packages/engine/README.md | 11 ++++++++---
  1 file changed, 8 insertions(+), 3 deletions(-)
  

Exact Stale Claims Found and Resolved

1. Hard-coded test count: "The test suite (51 tests) is hermetic." (Obsolete count from M5; unit suite now has 111 tests; replaced with durable prose without hard-coded test count).
2. Analysis cache backend: "Redis/Postgres are future drop-ins" (PostgreSQL durable cache was implemented in M15 via PgAnalysisCache in @chess-platform/persistence, wired to production in @chess-platform/api, and hot-tiered with an LRU; Redis analysis caching was never built; updated to "persistent backends like PostgreSQL implement this interface").
3. Real-engine tests: "A real-engine 'golden' test is env-gated and lands with the deployable service (M14)" (Real-engine tests did not land in M14 or in packages/engine; semantic smoke tests against pinned Stockfish 16 and Fairy-Stockfish 14 landed in M15 in @chess-platform/api/test/ and run under CI job analysis-smoke).
4. Authority wiring: "...along with distributed workers and authority wiring" (Engine-backed bot play was wired to the game authority in M14 Inc 13 and Inc 36 via EngineBotMover in services/gateway).
5. Distributed workers: "...along with distributed workers and authority wiring" (Distributed remote workers did not land in M14 and remain deferred).

Current Repository Evidence

• packages/engine/test/: 111 tests across 3 suites, 100% hermetic using FakeEngineTransport and Clock.
• .github/workflows/ci.yml (analysis-smoke job): runs npm run test:analysis-smoke --workspace @chess-platform/api with pinned Stockfish 16, Fairy-Stockfish 14, and PostgreSQL.
• services/gateway/src/serve.ts and services/gateway/src/engine-bot.ts: EngineBotMover wires engine moves to CommandRouter -> GameAuthority.
• packages/api/src/analysis/: wires AnalysisService with PgAnalysisCache and hot LRU cache to POST /v1/analysis.
• packages/engine/src/: implements ChildProcessTransport and FakeEngineTransport; zero runtime dependencies; no remote/distributed worker implementation exists.

What Wording Changed

• Updated AnalysisCache pluggable seam description from "Redis/Postgres are future drop-ins" to "persistent backends like PostgreSQL implement this interface".
• Replaced stale 51-test count and outdated M14 deferral text with durable prose explaining:
  • The package test suite is hermetic (FakeEngineTransport + Clock, no binaries);
  • Real-engine integration is tested via env-gated smoke tests in CI under @chess-platform/api with pinned Stockfish and Fairy-Stockfish against a real database;
  • Production runtime wiring powers bot play in the gateway and analysis in the API;
  • Distributed remote engine workers remain deferred.

What Remains Genuinely Deferred

• Distributed remote engine workers remain deferred (engine execution is strictly local child processes).

Validation

• npm run build -w @chess-platform/engine (exit code 0)
• npm test -w @chess-platform/engine (111 passed, 0 failed, 3 suites, exit code 0)
• npm run lint -w @chess-platform/engine (exit code 0)
• npm run check:adr-claims (exit code 0)
• npm run check:ci-parity (exit code 0)
• npm run check:engine-pin-parity (exit code 0)
• git diff --check (clean, exit code 0)
• Temporary executable & typecheck test for README usage snippet against TypeScript API and FakeEngineTransport (passed, 0 errors)

Worktree and Git Status

• Local HEAD == Remote HEAD == cfe1555672d941fdfb2c0d1e4af212e84480a012
• Divergence: 0 0 against origin/gemini/engine-readme-truth
• Worktree clean

Summary by CodeRabbit

• Documentation
  • Updated engine documentation to list PostgreSQL as a supported persistent analysis-cache backend.
  • Added current details about full-stack testing, CI smoke tests, and production analysis integrations.
  • Clarified that distributed remote workers are not yet available.
  • Documented the use of controlled test environments and pinned components for reliable validation.

[edwardnewgate710]

/review

[edwardnewgate710]

@coderabbitai full review

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can route each action level your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Correct engine README test and deployment claims

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Removes obsolete engine test counts and milestone promises.
• Documents current hermetic tests, real-engine CI coverage, and production integrations.
• Clarifies PostgreSQL cache support and deferred distributed workers.

Diagram

graph TD
  README["Engine README"] --> Engine["Engine Package"] --> API["Analysis API"] --> PG[("PostgreSQL")]
  Engine --> Gateway["Bot Gateway"]
  Engine --> Fake["Fake Transport"]
  CI["Smoke Tests"] --> API

Loading

High-Level Assessment

The focused documentation correction is the appropriate approach. Durable capability descriptions are preferable to hard-coded test counts or milestone promises, which quickly become stale; no runtime changes are needed.

Files changed (1) +8 / -3

Documentation (1) +8 / -3

README.mdReplace stale engine testing and deployment claims +8/-3

Replace stale engine testing and deployment claims

• Removes the obsolete test count and unfulfilled milestone language. Documents hermetic package testing, API-owned real-engine smoke tests, PostgreSQL cache support, current gateway and API integrations, and the continued deferral of distributed workers.

packages/engine/README.md

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: e96da9f4-e3a0-4570-82f7-2c0051fbfd70

📥 Commits

Reviewing files that changed from the base of the PR and between 748f5d8 and cfe1555.

📒 Files selected for processing (1)

• packages/engine/README.md

Included review availability: Your plan provides up to 8 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The engine README documents PostgreSQL cache support, current test strategies, CI smoke tests, production integrations, and deferred distributed workers.

Changes

Engine documentation

Layer / File(s)	Summary
Capabilities and validation documentation packages/engine/README.md	The README identifies PostgreSQL as a supported persistent AnalysisCache backend. It documents hermetic tests, real-engine CI smoke tests, production analysis wiring, and deferred distributed workers.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to cfe15

The engine documentation now reflects current cache, testing, CI, and deployment status without changing runtime behavior. No merge-readiness risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: removing stale testing and deployment claims from the engine documentation.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch gemini/engine-readme-truth

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

✅ Action performed

Full review finished.

[edwardnewgate710]

/review

[edwardnewgate710]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[qodo-code-review]

No code changes since the last review — review skipped