What

Standardize the directory layout, build system organization, and test infrastructure across all 8 ecosystem systems (common, thread, logger, container, monitoring, database, network, pacs). Today each system follows a different convention — public header location, source organization, test framework, and CMakeLists.txt structure all diverge — making cross-system tooling, contributions, and dependency upgrades harder than they need to be.

• Current: 4 different patterns for public header location; 2 systems lack include/ entirely or scatter headers across 5+ directories; pacs uses Catch2 while the other 7 use GTest; root CMakeLists.txt ranges from ~150 to 1032 lines
• Expected: All 8 systems follow the same skeleton — include/kcenon/<name>/, src/, tests/ (GTest), modular cmake/*.cmake files (pacs_system pattern)
• Scope: Layout migration, header consolidation, CMakeLists.txt decomposition, test framework alignment

Why

• Header path divergence breaks downstream consumers: container has 5+ header locations, database has none, pacs uses non-kcenon:: namespace — every consumer writes different #include lines
• CMakeLists.txt bloat (network 1032L, monitoring 997L, container 750L) is the symptom of legacy/new structure coexistence — pruning the legacy fallbacks recovers maintainability
• Test framework split (Catch2 in pacs, GTest in 7 others) prevents shared fixture libraries and forces dual-framework setup for cross-system integration tests
• pacs_system already proves the modular cmake/*.cmake pattern works — extracting it as the ecosystem template costs once and pays back across 7 systems
• A single standard reduces onboarding friction: contributors learn one layout, not eight

How

Phased migration (leaf → root)

Migrate consumers first so library changes do not cascade:

Sub-issues (cross-repo)

• [EPIC] common_system: layout standard, cmake template, cross-build CI #656 — Phase 0+7: Layout standard, cmake template, cross-build CI
• [Epic] pacs_system: directory structure migration to ecosystem standard pacs_system#1137 — Phase 1: Namespace, samples/examples merge, Catch2 decision
• [EPIC] database_system: introduce include/ directory and standardize layout database_system#577 — Phase 2: Introduce include/ directory
• [EPIC] container_system: consolidate scattered headers and standardize layout container_system#531 — Phase 3: Consolidate scattered headers
• [EPIC] network_system: standardize tests and decompose CMake network_system#1083 — Phase 4: Split unit tests, document libs/
• [EPIC] monitoring_system: remove legacy fallback and decompose CMake monitoring_system#674 — Phase 5: Remove legacy fallback, decompose CMake
• [EPIC] thread_system: absorb legacy directories into standard layout thread_system#683 — Phase 6: Absorb legacy directories
• [EPIC] logger_system: final standard verification logger_system#624 — Phase 7: Final verification

Acceptance Criteria

• kcenon-system-layout.md standard published in common_system (v1.0 — docs(layout): publish kcenon-system-layout.md v1.0 #658, merged via docs(layout): add kcenon-system-layout.md v1.0 #663)
• All 8 systems expose public headers under include/kcenon/<name>/ (or document deviation explicitly)
• All 8 systems have src/ for implementation, tests/ for GTest unit tests, integration_tests/ separate
• All 8 systems decompose root CMakeLists.txt into cmake/*.cmake modules following the pacs_system pattern
• Ecosystem cross-build CI workflow passes — touching any repo verifies the other 7 still build
• No legacy/new-structure dual fallback remaining in any CMakeLists.txt
• Forwarding headers for breaking moves marked [[deprecated]] and removed within one minor release

Non-Goals

• Renaming the systems themselves (common → core, etc.)
• Switching the build system away from CMake
• Forcing identical feature flags across systems — only structural conventions
• pacs_system Catch2 → GTest migration (deferred to a separate decision; default is to keep Catch2 and document the exception)

Risks

• Header path moves break downstream consumers → mitigation: forwarding headers [[deprecated]] for one release before removal
• 8 repos in flight simultaneously → mitigation: leaf-to-root order, one Phase per week, cross-build CI gate
• CMakeLists.txt decomposition may drop options silently → mitigation: diff every option against the pre-migration list, CI verifies the build matrix unchanged