docs: complete project research for SummerCMS

Files: - STACK.md - ZIO ecosystem recommendations (Scala 3.3.7 LTS, ZIO HTTP 3.8.1, Quill 4.8.6, Mill 1.0) - FEATURES.md - CMF feature inventory from WinterCMS reference (table stakes, differentiators, anti-features) - ARCHITECTURE.md - ZIO layer-based architecture with plugin system patterns - PITFALLS.md - 23 identified pitfalls across Scala/ZIO, CMF rewrite, scope, and team dimensions - SUMMARY.md - Executive synthesis with 7-phase roadmap recommendations Key findings: - Stack: ZIO ecosystem production-ready, Quill endorsed as only maintained database library - Architecture: Plugin System is critical bottleneck, build 3-5 plugins before finalizing API - Critical pitfall: Big Rewrite Anti-Pattern - define MVP as "build new site" not "full WinterCMS parity" Ready for roadmap creation.
2026-02-04 02:46:18 +01:00
parent a185132635
commit 834dd51bcc
1 changed files with 445 additions and 0 deletions
--- a/.planning/research/SUMMARY.md
+++ b/.planning/research/SUMMARY.md
@@ -0,0 +1,445 @@
+# Project Research Summary
+
+**Project:** SummerCMS - Scala/ZIO rewrite of WinterCMS
+**Domain:** Content Management Framework (CMF)
+**Researched:** 2026-02-04
+**Confidence:** HIGH
+
+## Executive Summary
+
+SummerCMS aims to rewrite WinterCMS, a mature PHP CMF, using Scala 3 and the ZIO ecosystem. Research confirms this is architecturally sound: ZIO HTTP 3.x, Quill 4.8.6, and Mill 1.0 provide a production-ready foundation for building a type-safe, high-performance CMF. The plugin architecture pattern from WinterCMS is well-understood and translates cleanly to ZIO's layer-based dependency injection.
+
+The recommended approach follows WinterCMS's core patterns (plugin dependencies via manifests, YAML-driven backend forms, component-based frontend) while leveraging Scala's type safety to eliminate entire classes of runtime errors. ScalaTags + HTMX replaces WinterCMS's problematic Snowboard/Alpine.js frontend, providing server-rendered HTML with progressive enhancement. The ZIO effect system's compile-time guarantees ensure plugin interdependencies and database queries are validated before deployment.
+
+**Key risks are manageable but must be addressed explicitly:** The most dangerous pitfall is the "Big Rewrite Anti-Pattern" - attempting full WinterCMS parity before shipping. Research shows successful rewrites deliver value in vertical slices rather than horizontal layers. Additional risks include ZIO's learning curve for PHP developers (40.5% onboarding slowdown), Quill compile-time explosion with large query counts, and plugin API lock-in if the extension mechanism is finalized before building real plugins. Mitigation strategies include freezing WinterCMS reference version, defining MVP as "build a new site" not "full parity," and building 3-5 diverse plugins before finalizing the plugin API.
+
+## Key Findings
+
+### Recommended Stack
+
+The ZIO ecosystem has matured significantly in 2025-2026. All major dependencies have reached stable 1.0+ releases with production deployment patterns well-documented. The stack prioritizes developer experience and compile-time safety over bleeding-edge features.
+
+**Core technologies:**
+
+- **Scala 3.3.7 LTS** (language) - LTS stability for multi-year project, not bleeding-edge 3.8.x which requires newer JDKs
+- **ZIO 2.1.24** (effect system) - Binary compatibility guarantees in 2.x critical for plugin ecosystem; typed errors eliminate WinterCMS's exception chaos
+- **ZIO HTTP 3.8.1** (HTTP server) - Production-ready, Netty-based, native ZIO integration with OpenAPI generation for plugin APIs
+- **Quill 4.8.6** (database) - Compile-time SQL validation catches query errors before deployment; zio-sql/zio-jdbc deprecated per 2025 roadmap
+- **ScalaTags 0.13.1** (template) - Type-safe HTML generation, 4x faster than Twirl; integrates with HTMX for server-rendered interactivity
+- **htmx4s 0.3.0** (frontend) - Type-safe HTMX attributes replace WinterCMS's problematic Snowboard/Alpine.js frontend
+- **Mill 1.0.0** (build tool) - 3-7x faster than sbt, simpler model scales to hundreds of plugin modules
+- **ZIO Config 4.0.5** (configuration) - YAML/HOCON support with type-safe derivation for WinterCMS-style config files
+- **ZIO Schema 1.7.5** (serialization) - Critical for YAML-driven forms; schema describes fields, validation, automatic JSON codec derivation
+
+**Critical stack decision:** Quill over alternatives because it's the only maintained ZIO database library (zio-sql deprecated). Compile-time query generation is essential for plugin stability but creates compilation challenges that must be addressed via module architecture (see Pitfalls #5).
+
+**Frontend strategy:** HTMX as primary interaction model (server returns HTML fragments), Vue.js for complex admin UI widgets (media manager, form builder). This avoids WinterCMS's "messy" Snowboard+Alpine pattern while maintaining progressive enhancement.
+
+**Template engine hybrid:** ScalaTags for core/admin (type-safe, developer maintains), Twirl for theme templates (familiar syntax for non-Scala developers). Open question: invest in Twig-to-ScalaTags compiler for WinterCMS theme compatibility?
+
+### Expected Features
+
+WinterCMS reference implementation (19 Golem15 plugins) demonstrates the feature surface area. CMFs in 2025-2026 have converged on table-stakes features with differentiation through performance and API-first architecture.
+
+**Must have (table stakes):**
+
+- Plugin system with dependency resolution (`$require` equivalent)
+- YAML-driven backend forms (`fields.yaml`, `columns.yaml` pattern)
+- Component architecture for frontend (reusable UI elements with properties)
+- Theme system with layouts/partials/pages
+- User/Auth with RBAC permissions
+- Content management (pages, posts, media library)
+- Database/ORM layer with relations and migrations
+- CLI tools for scaffolding (project setup, plugin creation)
+
+**Should have (competitive advantages):**
+
+- Type-safe plugin development - compile-time checks eliminate PHP's runtime failures
+- HTMX+Vue modern frontend - better UX than WinterCMS without JavaScript fatigue
+- Superior performance - JVM 10-100x faster than PHP baseline
+- API-first architecture - REST/GraphQL built-in for headless use cases
+- Compile-time SQL validation - Quill catches query errors before deployment
+
+**Defer (v2+):**
+
+- Real-time collaboration (WebSocket complexity, infrastructure requirements)
+- Multisite/multi-tenant (complex data isolation, defer until core proven)
+- AI integration beyond MVP (AI-assist content writing can wait)
+- GraphQL by default (REST sufficient for v1, GraphQL as optional plugin)
+- Visual page builders (complex, fragile; component-based approach simpler)
+
+**Critical feature dependencies discovered:**
+
+```
+[Foundation] Database/ORM + User/Auth → Plugin System → Everything Else
+[Core CMS] Plugin System → Theme System → Frontend Components
+         Plugin System → Backend Admin → YAML Forms → Content Management
+[Advanced] Content Management → Versioning → Workflow → Scheduling
+```
+
+Plugin System is the critical bottleneck - everything builds on it. Getting the plugin API right is THE architectural decision.
+
+### Architecture Approach
+
+ZIO's layer-based architecture maps cleanly to CMF requirements. Effect system provides type-safe plugin lifecycle, resource safety for database connections, and explicit error handling replacing WinterCMS's exception chaos.
+
+**Layered architecture (bottom-up):**
+
+1. **Data Layer** - PostgreSQL via Quill, connection pooling, migrations
+2. **Core Services** - Config, EventBus, AuthService, PluginRegistry
+3. **Domain Layer** - Repositories (pure business logic, no effects)
+4. **HTTP Layer** - Routes (public, admin, API), middleware stack
+5. **Application Layer** - Plugin loading, theme rendering, component resolution
+
+**Major components:**
+
+1. **Plugin System** - Lifecycle management, dependency resolution, extension registry. Uses ZLayer for DI, event bus for plugin interactions, type classes for model extensions. Pattern: plugins define extensions via traits, core discovers and wires them.
+
+2. **Theme Engine** - Template loading/rendering, asset management, layout composition. Parses YAML frontmatter from `.htm` files (WinterCMS compatibility), translates Twig-like syntax to ScalaTags, supports component embedding via `{% component 'alias' %}`.
+
+3. **Component System** - Reusable UI elements with lifecycle (`init`, `onRun`), properties (YAML-defined), AJAX/HTMX handlers. Components register via plugin `registerComponents`, instantiated per-request, provide data to templates.
+
+4. **Admin Backend** - YAML-driven forms/lists. `fields.yaml` → FormConfig case class with field definitions, validation rules, conditional visibility. ZIO Schema derives JSON codecs for API endpoints.
+
+5. **Database Layer** - Quill for compile-time SQL, Repository pattern with ZIO effects. Each plugin defines migrations as versioned ZIO effects. Schema registry tracks versions.
+
+6. **Auth Service** - JWT tokens, permission-based access control, middleware for protected routes. Separate backend admin auth from frontend user auth.
+
+**Request pipeline flow:**
+
+```
+Request → RouteResolver (lookup page by URL)
+       → ThemeResolver (load layout/template)
+       → ComponentResolver (instantiate components, call onRun, gather data)
+       → PageRenderer (merge layout + page + component data → HTML)
+       → Response (with HTMX attributes for interactivity)
+```
+
+**HTMX integration pattern:** Components define handlers (e.g., `onLoadMore`) that become routes (`POST /component/{alias}/onLoadMore`). HTMX attributes (`hx-post`, `hx-target`) trigger handlers, server returns HTML fragments, HTMX swaps into DOM.
+
+**Build order based on dependencies:**
+
+- Phase 1 (parallel): Database Layer, Config Service, Event Bus
+- Phase 2: Plugin System (blocks everything else)
+- Phase 3 (parallel): Component System, Auth Service
+- Phase 4: Theme Engine, Template Parser
+- Phase 5: Request Pipeline, Routes
+- Phase 6: Admin Backend, Form/List Widgets
+- Phase 7: Core Plugins (User, Blog, Pages)
+
+**Critical architectural decision:** Plugin extension mechanism. Research identifies three patterns WinterCMS uses:
+
+1. Event-based extension (primary) - plugins emit/subscribe to typed events
+2. Model extension via type classes - plugins add relations, attributes, behaviors
+3. Form field injection - plugins extend `FormDefinition` via events
+
+SummerCMS must support all three, but with type-safe APIs.
+
+### Critical Pitfalls
+
+Research identified 23 pitfalls across four dimensions. Top 5 by severity:
+
+1. **The Big Rewrite Anti-Pattern** - Attempting full WinterCMS parity before shipping. Successful rewrites deliver value in vertical slices, not horizontal layers. Mitigation: Define MVP as "build a new site" not "migrate complex WinterCMS site." Freeze WinterCMS reference version. Accept 80/20 rule: 80% of value from 20% of features. Document what's explicitly NOT in v1.0.
+
+2. **Plugin API Lock-in** - Designing plugin API early but proving inadequate. Changing it later breaks all plugins. Mitigation: Study multiple plugin systems (WordPress, WinterCMS, Discourse, VSCode). Build 3-5 diverse plugins BEFORE finalizing API. Use semantic versioning from day 1. Design for extension points (hooks, filters, traits). Plan for plugin API v2 from the start.
+
+3. **ZIO Quill Compile-Time Explosion** - Projects with many Quill queries see compile times grow exponentially (5+ minutes per query, 5GB+ heap). Mitigation: Split database layer into separate Mill module. Limit queries per file (10-15 max). Use `scalacOptions += "-Yretain-trees"`. Configure CI with 8GB+ memory. Consider Doobie for complex query scenarios.
+
+4. **AI Agent Quality Debt** - Research shows AI-assisted coding creates "substantial but transient velocity gains alongside persistent increases in technical debt." Mitigation: Mandatory human review for all AI code. AI agents work on tests FIRST, then implementation. Static analysis gates in CI (no warning increase allowed). Limit AI to well-defined, isolated tasks.
+
+5. **Scala Learning Curve for PHP Developers** - Target users are "web developers who may not know Scala deeply" but codebase uses advanced ZIO patterns. 40.5% onboarding slowdown observed. Mitigation: Create "SummerCMS Style Guide" limiting advanced patterns. Use simple, explicit types over clever abstractions. Extensive inline documentation. "Stepping project" for new contributors.
+
+**Additional high-impact pitfalls:**
+
+- **ZIO HTTP Client Performance** - 2s initialization overhead, 300ms per-request without pooling. Must configure connection pooling at startup.
+- **YAML Parser Edge Cases** - WinterCMS YAML has subtle behaviors (validation cascades, conditional visibility, translation lookups). Build comprehensive test suite from WinterCMS examples before implementation.
+- **Authentication Complexity** - Auth seems simple until: password reset, account lockout, session management, remember-me, OAuth, JWT refresh, GDPR deletion, audit logging. Use battle-tested library, don't DIY.
+- **Migration Tool Neglect** - Users can't adopt without migration from WinterCMS. Include migration as Phase 2/3 requirement, not post-launch. Test with 3-5 real WinterCMS sites during development.
+
+**Pitfall timeline:**
+
+- Phase 1: ZIO effect wrapping patterns, FiberFailure handling, layer architecture
+- Phase 2: Database compile times, HTTP client pooling, auth security
+- Phase 3: Plugin API stability, YAML edge cases
+- All phases: AI quality gates, learning curve, scope discipline
+
+## Implications for Roadmap
+
+Based on combined research, recommended phase structure prioritizes proving the foundation before expanding scope. Vertical slices over horizontal layers.
+
+### Phase 1: Foundation & Prototype
+**Rationale:** Validate stack integration end-to-end before "real" development. Uncover tooling issues early.
+
+**Delivers:**
+- Working CLI → HTTP → Database → Response flow
+- Mill build configured with proper modules
+- ZIO layer architecture proven
+- Basic ZIO patterns documented (effect wrapping, error handling)
+
+**Addresses:**
+- Pitfall #1 (Big Rewrite) - proves concept before expanding scope
+- Pitfall #3 (Quill compilation) - establishes module architecture
+- Pitfall #8 (ZIO environment misuse) - sets patterns early
+
+**Features:** None user-visible. This is pure technical validation.
+
+**Duration:** 2-3 weeks (assuming experienced Scala developer)
+
+**Research needs:** NONE - standard prototype patterns
+
+### Phase 2: Plugin System Core
+**Rationale:** Plugin System is the architectural bottleneck. Everything depends on it. Getting the API right is critical to avoid lock-in.
+
+**Delivers:**
+- Plugin discovery and lifecycle (register, boot, shutdown)
+- Dependency resolution (`$require` equivalent)
+- Event bus for plugin communication
+- Extension registry (components, settings, permissions)
+- Database migration system (per-plugin migrations)
+
+**Addresses:**
+- Pitfall #11 (Plugin API lock-in) - build plugins before finalizing
+- Pitfall #9 (Iceberg underestimation) - this IS the hidden 90%
+- Architecture component #2 - foundational system
+
+**Features (to build as validation):**
+- Create 3-5 test plugins demonstrating diverse use cases:
+  - Simple plugin (FAQ, Quote)
+  - Plugin with dependencies (Blog requires User)
+  - Plugin extending core models
+  - Plugin with scheduled tasks
+  - Plugin with form field injection
+
+**Duration:** 8-12 weeks (very high complexity)
+
+**Research needs:** DEEP - plugin architecture patterns, WinterCMS extension mechanisms, dependency resolution algorithms
+
+### Phase 3: Database & Auth
+**Rationale:** Builds in parallel on Phase 1 foundation. Auth required for backend. Database required for content.
+
+**Delivers:**
+- Repository pattern with ZIO effects
+- Quill query layer with compile-time validation
+- Model relations (hasMany, belongsTo)
+- Migration runner (Flyway integration)
+- JWT-based authentication
+- Permission-based authorization
+- User/role/permission models
+
+**Addresses:**
+- Pitfall #13 (Auth complexity) - use proven patterns
+- Pitfall #2 (FiberFailure wrapping) - database error handling
+- Stack: Quill, PostgreSQL, Flyway
+
+**Features:**
+- User registration/login
+- Password reset flows
+- Session management
+- Basic RBAC permissions
+
+**Duration:** 6-8 weeks (medium-high complexity)
+
+**Research needs:** MEDIUM - Auth best practices, GDPR compliance checklist
+
+### Phase 4: Theme Engine & Components
+**Rationale:** Requires Plugin System (Phase 2) for component registration. Proves frontend rendering works.
+
+**Delivers:**
+- Theme loading from filesystem
+- YAML frontmatter parsing
+- Layout/page/partial composition
+- Component lifecycle (init, onRun, data)
+- ScalaTags rendering
+- HTMX integration (component handlers)
+
+**Addresses:**
+- Pitfall #12 (YAML edge cases) - test suite from WinterCMS
+- Architecture component #3 (Theme Engine)
+- Stack: ScalaTags, htmx4s
+
+**Features:**
+- Basic theme with layout
+- 2-3 example components (BlogPosts, ContactForm)
+- HTMX-driven pagination/filtering
+
+**Duration:** 8-10 weeks (high complexity)
+
+**Research needs:** MEDIUM - YAML parsing edge cases, component lifecycle patterns
+
+### Phase 5: Admin Backend & Forms
+**Rationale:** Needs Plugin System (Phase 2), Auth (Phase 3), Components (Phase 4). This is the "visible" part that looks simple but is 90% hidden complexity.
+
+**Delivers:**
+- Backend authentication/authorization
+- YAML-driven form rendering (`fields.yaml`)
+- YAML-driven list rendering (`columns.yaml`)
+- Form widgets (text, textarea, dropdown, relation, file upload)
+- CRUD scaffolding for models
+- Settings management UI
+
+**Addresses:**
+- Pitfall #12 (YAML parser edge cases) - comprehensive validation
+- Pitfall #9 (Iceberg underestimation) - form field types, conditional visibility, widget loading
+- Stack: ZIO Schema (form field validation)
+
+**Features:**
+- Admin dashboard
+- User management CRUD
+- Settings editor
+
+**Duration:** 10-14 weeks (high complexity)
+
+**Research needs:** DEEP - WinterCMS form/list patterns, widget system, validation cascades
+
+### Phase 6: Content Management
+**Rationale:** Builds on all previous phases. Proves the system works for actual CMS use case.
+
+**Delivers:**
+- Pages plugin (hierarchical pages, slugs, SEO)
+- Blog plugin (posts, categories, tags)
+- Media library (upload, organize, image transforms)
+- Rich text editor integration (TipTap/ProseMirror)
+- Content versioning (basic)
+- Draft/published workflow
+
+**Addresses:**
+- Features: Core CMS functionality (table stakes)
+- Validates plugin API from Phase 2 works for real plugins
+
+**Features:**
+- Create/edit pages
+- Create/edit blog posts
+- Upload/manage media
+- Basic workflow
+
+**Duration:** 8-10 weeks (medium-high complexity)
+
+**Research needs:** LOW - standard CMS patterns
+
+### Phase 7: Migration & Launch Prep
+**Rationale:** Users can't adopt without migration path from WinterCMS.
+
+**Delivers:**
+- WinterCMS database import tool
+- Theme compatibility analyzer
+- Plugin mapping guide (which WinterCMS plugins → SummerCMS equivalents)
+- Migration documentation
+- Performance benchmarks
+- Security audit
+
+**Addresses:**
+- Pitfall #14 (Migration tool neglect)
+- Pitfall #27 (Defer security)
+
+**Features:**
+- CLI: `summer migrate:wintercms <path>`
+- Migration validation/testing
+
+**Duration:** 6-8 weeks
+
+**Research needs:** LOW - data migration patterns
+
+### Phase Ordering Rationale
+
+**Dependency chain:** Phase 1 (foundation) → Phase 2 (plugin system) is the critical path. Phases 3-4 can partially overlap once Plugin System API stabilizes. Phase 5 requires all previous. Phase 6 validates the platform. Phase 7 enables real adoption.
+
+**Vertical slice strategy:** Each phase delivers something testable. Avoids "horizontal layers" anti-pattern (all DB, then all API, then all UI). Phase 2 builds complete plugins. Phase 4 renders complete pages. Phase 6 manages complete content.
+
+**Pitfall avoidance:** Early phases address foundational pitfalls (ZIO patterns, plugin API, compile times). Later phases build on stable foundation. Migration deferred until core proven but included in v1.0 scope.
+
+**Scope discipline:** MVP = Phase 1-6 (build a new site). WinterCMS migration = Phase 7 adds adoption path. Multisite, AI, real-time collaboration explicitly deferred to v2+.
+
+### Research Flags
+
+**Needs deep research during phase planning:**
+
+- **Phase 2 (Plugin System):** Complex architectural decisions. Study WordPress, WinterCMS, Discourse, VSCode plugin systems. Dependency resolution algorithms. Event vs trait-based extension patterns.
+- **Phase 5 (Admin Backend):** YAML form/list parsing edge cases. Widget system architecture. Conditional field visibility logic.
+
+**Standard patterns (skip research-phase):**
+
+- **Phase 1 (Foundation):** Prototype patterns well-documented
+- **Phase 3 (Database/Auth):** ZIO + Quill patterns established, auth patterns standard
+- **Phase 6 (Content Management):** Straightforward CRUD on proven foundation
+- **Phase 7 (Migration):** Data migration patterns standard
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | **HIGH** | All major dependencies verified via official releases. ZIO HTTP 3.8.1, Quill 4.8.6, Mill 1.0 are production-ready with documented deployment patterns. |
+| Features | **HIGH** | WinterCMS reference implementation provides complete feature inventory. CMF patterns well-established. Table stakes vs differentiators clearly defined. |
+| Architecture | **MEDIUM-HIGH** | ZIO layer-based architecture proven in production. Plugin system pattern from WinterCMS translates cleanly. Some uncertainty around YAML parser hybrid strategy and theme compatibility. |
+| Pitfalls | **MEDIUM-HIGH** | Scala/ZIO pitfalls verified via multiple sources. Rewrite anti-patterns documented in literature. AI quality debt confirmed by 2025 research. Some uncertainty around magnitude of learning curve impact. |
+
+**Overall confidence:** **HIGH**
+
+The research successfully identified:
+- Production-ready stack with stable dependencies
+- Complete feature inventory from reference implementation
+- Clear architectural patterns with proven foundations
+- Well-documented pitfalls with concrete mitigation strategies
+
+### Gaps to Address
+
+**Template engine final decision:** ScalaTags + Twirl hybrid recommended, but open question on Twig-to-ScalaTags compiler for WinterCMS theme compatibility. Decision required by Phase 4. Recommendation: Start with ScalaTags+Twirl, assess migration pain with real themes, invest in Twig compiler only if migration blockers discovered.
+
+**Plugin dependency resolution algorithm:** WinterCMS uses Composer-like resolution. Need to decide: reimplement Composer algorithm, use SemVer with simpler resolution, or delegate to Mill's dependency system. Decision required by Phase 2. Recommendation: Deeper research during Phase 2 planning.
+
+**Hot reload development experience:** JVM startup is slow. Investigate JRebel, Bloop, or compile daemon for plugin hot-reload. Not blocking for v1.0 but affects developer experience. Decision required by Phase 2. Recommendation: Accept slower iteration in Phase 1-2, optimize in Phase 3 once patterns stable.
+
+**YAML parsing performance:** Scala YAML libraries need benchmarking for large config files. Not researched in detail. Recommendation: Load test during Phase 5 (Admin Backend) with real WinterCMS `fields.yaml` examples.
+
+**Plugin isolation/sandboxing:** How to safely load third-party plugins without security risks. Classloader isolation? OSGi? Flat classpath with trust model? Decision required by Phase 2. Recommendation: Start with flat classpath + code review model (like WinterCMS), investigate sandboxing for v2 if marketplace emerges.
+
+**WebSocket vs SSE for real-time:** Project context mentions "websockets scale poorly." ZIO HTTP has WebSocket support. Should real-time features use SSE instead? Decision required by Phase 3+ (deferred from v1.0). Recommendation: Skip real-time for v1.0, research when actually needed.
+
+## Sources
+
+### Primary (HIGH confidence)
+
+**Stack research:**
+- [ZIO Releases](https://github.com/zio/zio/releases) - v2.1.24 verification
+- [ZIO HTTP Releases](https://github.com/zio/zio-http/releases) - v3.8.1 verification
+- [Scala All Versions](https://www.scala-lang.org/download/all.html) - 3.3.7 LTS verification
+- [Ziverge: ZIO in 2025](https://www.ziverge.com/post/zio-in-2025) - Quill as endorsed ZIO database library
+- [ZIO Quill Documentation](https://zio.dev/zio-quill/getting-started/) - Official patterns
+- [Mill 1.0.0 Release](https://mill-build.org/blog/13-mill-build-tool-v1-0-0.html) - Build tool maturity
+
+**Features research:**
+- [WinterCMS Official Documentation](https://wintercms.com/docs) - Feature inventory
+- [WinterCMS Features](https://wintercms.com/features) - Product capabilities
+- [October CMS Forms](https://docs.octobercms.com/3.x/backend/forms.html) - YAML form patterns
+- Golem15 WinterCMS Starter CLAUDE.md - Local reference implementation
+
+**Architecture research:**
+- [ZIO Architectural Patterns](https://zio.dev/reference/architecture/architectural-patterns/) - Official patterns
+- [ZIO Service Pattern](https://zio.dev/reference/service-pattern/) - DI patterns
+- [Structuring ZIO 2 Applications](https://softwaremill.com/structuring-zio-2-applications/) - Production patterns
+- [WinterCMS Plugin Extension](https://wintercms.com/docs/v1.2/docs/plugin/extending) - Extension mechanisms
+
+**Pitfalls research:**
+- [5 More ZIO Pitfalls - Wix Engineering](https://medium.com/wix-engineering/5-more-pitfalls-to-avoid-when-starting-to-work-with-zio-d0cdd44fa439) - Production experience
+- [ZIO Quill Compiler Performance](https://zio.dev/zio-quill/compiler-performance/) - Official compilation warnings
+- [Speed at Cost of Quality Study](https://arxiv.org/abs/2511.04427) - AI quality debt research
+- [Why Rewrites Fail - Swizec](https://swizec.com/blog/you-can-t-stop-the-business-or-why-rewrites-fail/) - Rewrite anti-patterns
+
+### Secondary (MEDIUM confidence)
+
+- [ScalaTags Documentation](https://com-lihaoyi.github.io/scalatags/) - Template performance claims
+- [htmx4s GitHub](https://github.com/eikek/htmx4s) - Integration library
+- [Onboarding Juniors into Scala - Xebia](https://xebia.com/blog/6-tips-for-onboarding-juniors-into-scala/) - Learning curve data
+- [State of Scala Survey](https://www.jvm-weekly.com/p/the-state-of-scala-and-clojure-surveys) - 40.5% onboarding slowdown
+
+### Tertiary (LOW confidence, needs validation)
+
+- Various CMF comparison articles (2025) - Market trends
+- Hacker News threads on CMS architecture - Community patterns
+- Plugin architecture blog posts - General patterns
+
+---
+
+*Research completed: 2026-02-04*
+*Ready for roadmap: YES*
+
+**Next step:** Roadmapper agent can use this synthesis to structure detailed phase plans with tasks, dependencies, and success criteria.