docs/ci: snapshot core roadmap metrics and validate against index

[Krilliac]

Motivation

• Keep roadmap recommendation docs in sync with the canonical project metrics in .claude/index.md so readers and tooling see consistent core counts (tests, files, LOC).
• Make snapshot provenance explicit and machine-readable so CI can detect stale or mismatched metrics in docs.

Description

• Updated .claude/knowledge/engine-recommendations-2026-04-04.md to reflect current core counts and added a Snapshot Source/Date block referencing .claude/index.md and human/machine-readable metadata.
• Added machine-readable snapshot metadata comments: SNAPSHOT_SOURCE, SNAPSHOT_DATE, and CORE_METRICS inside the roadmap doc for automated validation.
• Added a lightweight validation script tools/check-roadmap-core-metrics.sh that parses core metrics from .claude/index.md, scans .claude/knowledge/*recommendations-*.md for snapshot metadata, and fails on mismatches or malformed metadata while skipping docs that have not opted in.
• Wired the new check into CI by calling ./tools/check-roadmap-core-metrics.sh in the existing validate-prompts job in .github/workflows/build.yml.

Testing

• Ran ./tools/check-roadmap-core-metrics.sh locally; it completed successfully and reported matching metrics for engine-recommendations-2026-04-04.md.
• Ran ./tools/validate-prompts.sh --ci locally to exercise the surrounding validation job; it completed successfully with zero errors.
• The roadmap check is opt-in for docs that include the snapshot metadata comments; documents without metadata are explicitly skipped by the script.

---

Codex Task

[github-actions]

Code Coverage (GCC + lcov)

Utils/MemoryMonitor.h                          |85.7%    14| 0.0%  12|    -    0
Utils/MultiISA.h                               |42.9%    14| 0.0%   6|    -    0
Utils/NetworkHealthMonitor.cpp                 | 113%    15| 0.0%   2|    -    0
Utils/NetworkHealthMonitor.h                   |    -     0|    -   0|    -    0
Utils/OpaqueHandle.h                           | 282%    11| 0.0%  15|    -    0
Utils/ProcessLinux.cpp                         |16.5%   182| 0.0%  28|    -    0
Utils/Profiler.cpp                             |14.2%   113| 0.0%  15|    -    0
Utils/Profiler.h                               |36.4%    33| 0.0%  12|    -    0
Utils/RandomEngine.h                           |29.3%    41| 0.0%  12|    -    0
Utils/Result.h                                 | 100%    29| 0.0%  28|    -    0
Utils/RingBuffer.h                             | 108%    59| 0.0%  64|    -    0
Utils/ScopeGuard.h                             | 142%    36| 0.0%  51|    -    0
Utils/ScopedTimer.h                            |25.0%    12| 0.0%   3|    -    0
Utils/Serializer.h                             | 100%    48| 0.0%  42|    -    0
Utils/SparkConsole.cpp                         |28.5%   144| 0.0%  17|    -    0
Utils/SparkConsole.h                           | 100%     2| 0.0%   2|    -    0
Utils/SparkError.h                             |10.9%    55| 0.0%   6|    -    0
Utils/SplinePath.h                             |    -     0|    -   0|    -    0
Utils/StackTrace.h                             |10.8%    74| 0.0%   8|    -    0
Utils/StateMachine.h                           |54.0%    63| 0.0%  32|    -    0
Utils/StringUtils.h                            |18.1%   116| 0.0%  21|    -    0
Utils/Telemetry.h                              |20.7%   135| 0.0%  22|    -    0
Utils/ThreadDebugger.h                         |11.6%   199| 0.0%  23|    -    0
Utils/ThreadSafeQueue.h                        |27.5%    40| 0.0%  11|    -    0
Utils/TimerManager.h                           |19.8%    96| 0.0%  19|    -    0
Utils/UUID.h                                   |43.2%    37| 0.0%  16|    -    0
Utils/Validate.h                               |    -     0|    -   0|    -    0

[/home/runner/work/SparkEngine/SparkEngine/SparkSDK/Include/Spark/]
IEngineContext.h                               |7300%     1| 0.0%   1|    -    0
ServiceInterfaces.h                            | 200%     3| 0.0%   3|    -    0
Version.h                                      |    -     0|    -   0|    -    0
================================================================================
                                         Total:|29.2% 23726| 0.0%  4k|    -    0

Per-Subsystem Coverage

Subsystem	Lines	Hit	Coverage	Threshold	Status
AI	2776	694	25%	35%	❌
Animation	160	154	96.2%	35%	✅
Audio	0	0	0%	30%	✅
Camera	0	0	0%	40%	✅
Core	2248	1394	62%	40%	✅
ECS	190	114	60%	40%	✅
Editor	6082	1864	30.6%	25%	✅
GameModules	6244	3133	50.2%	30%	✅
Graphics	7202	3792	52.7%	30%	✅
Networking	3379	2247	66.5%	35%	✅
Physics	0	0	0%	35%	✅
Scripting	0	0	0%	30%	✅
Utils	7687	4865	63.3%	60%	✅

Total: 50.8% (18257/35968 lines)

[github-actions]

❌ CI Error Report

Failed jobs: windows-vs2022-Release
Errors: 0 | Test failures: 3 | Warnings: 0

Test Failures

Test	Jobs
1/1 Test #1: SparkEngineTests .................***Failed 12.35 sec	windows-vs2022-Release
[ FAILED ] Integration_NetworkingECS_ReplicationLatencyJitterPredictionReconciliation (546us, 8 assertions)	windows-vs2022-Release
0% tests passed, 1 tests failed out of 1	windows-vs2022-Release

Updated: 2026-04-09T20:12:51Z — this comment is updated in-place, not duplicated.