Merge pull request #1115 from re-cinq/1106-webui-framework-research

feat: webui framework research spec and design artifacts (#1106)

Author: nextlevelshit

specs/1106-webui-framework-research/checklists/matrix-quality.md

@@ -0,0 +1,38 @@
+# Checklist: Comparison Matrix Requirements Quality
+
+**Feature**: WebUI Framework Research (`1106-webui-framework-research`)  
+**Date**: 2026-04-14  
+**Scope**: Requirements quality for the comparison matrix deliverable  
+**Validates**: FR-001, FR-002, FR-007, FR-008, FR-010, SC-001, SC-003
+
+---
+
+## Completeness
+
+- [ ] CHK101 - Is each of the 9 evaluation criteria in FR-002 paired with a measurement method (what to measure, how to rate it) in either the spec, research.md criterion weights table, or matrix contract — rather than requiring researcher inference? [Completeness]
+- [ ] CHK102 - Does the spec require an elimination section in the matrix even when no candidate is eliminated, or does the elimination section only exist when needed? Is this distinction explicit? [Completeness]
+- [ ] CHK103 - Is the categorization scheme for handler impact (No change / Template removal / Adapter needed) defined in a functional requirement or contract, not only in research.md's "Technology Assessment"? [Completeness]
+- [ ] CHK104 - Does FR-007 or SC-003 require both raw and gzipped bundle size measurements, or only one? (Research.md U3 specifies both, but is this requirement binding?) [Completeness]
+
+---
+
+## Clarity
+
+- [ ] CHK105 - Is the minimum evidence standard per matrix cell (at minimum 2 sentences, as specified in the matrix contract) captured as a requirement in the spec itself, or only in the contract document that implementers may not consult until Phase 6 validation? [Clarity]
+- [ ] CHK106 - Does the spec define what "concrete examples" means for the SSE row (acceptance scenario US1-3 says "concrete examples or code snippets") — is a prose description sufficient, or is code required? [Clarity]
+- [ ] CHK107 - Is the rating scale (Strong / Good / Adequate / Weak / Fail) defined with anchoring descriptions for each level, or is the scale defined only by its labels — leaving subjective interpretation open? [Clarity]
+
+---
+
+## Consistency
+
+- [ ] CHK108 - Does the bundle size baseline in `contracts/matrix-contract.md` item 6 (JS ~127 KB, CSS ~156 KB, total ~283 KB) agree with the corrected values in spec C4 clarification (JS ~124 KB, CSS ~152 KB, total ~276 KB) and research.md U3? [Consistency]
+- [ ] CHK109 - Is the "Strong / Good / Adequate / Weak / Fail" scale defined in exactly one authoritative place and referenced (not redefined) elsewhere — or is it defined in multiple places with potential for divergence? [Consistency]
+
+---
+
+## Coverage
+
+- [ ] CHK110 - Does any matrix criterion or handler impact section explicitly require documenting each candidate's Node.js build-time dependency (not just runtime), so that CI environment impact is captured in the matrix? [Coverage]
+- [ ] CHK111 - Does the component reuse criterion (FR-010) require documenting migration complexity for the 30 custom template functions in `embed.go`, or only for the 6 HTML partials listed in the requirement? [Coverage]
+- [ ] CHK112 - Does the matrix cover all 5 edge cases from the spec — either as dedicated rows, subsections, or explicit callouts within relevant criteria rows — rather than leaving edge cases to be addressed only in the recommendation? [Coverage]

specs/1106-webui-framework-research/checklists/poc-quality.md

@@ -0,0 +1,38 @@
+# Checklist: Proof-of-Concept Requirements Quality
+
+**Feature**: WebUI Framework Research (`1106-webui-framework-research`)  
+**Date**: 2026-04-14  
+**Scope**: Requirements quality for the proof-of-concept deliverable  
+**Validates**: FR-003, FR-004, FR-005, SC-002, SC-007
+
+---
+
+## Completeness
+
+- [ ] CHK201 - Does FR-003 define the minimum required demonstration scope for the PoC (which specific features must work) rather than just naming the page being reimplemented? [Completeness]
+- [ ] CHK202 - Are the 7 SSE event types (started, running, completed, failed, step_progress, stream_activity, eta_updated) that FR-005 implies the PoC must handle enumerated in a requirement, or only in tasks.md (T022) as implementation detail? [Completeness]
+- [ ] CHK203 - Is artifact viewing status in PoC acceptance criteria unambiguous? FR-003 lists it as a feature of run_detail; SC-002 does not list it as a required PoC success criterion — is this intentional scoping or an omission? [Completeness]
+- [ ] CHK204 - Does FR-004 specify a required verification method for go:embed compatibility (e.g., a build command that must succeed), or does it only require that the output "be embeddable" without defining the acceptance test? [Completeness]
+
+---
+
+## Clarity
+
+- [ ] CHK205 - Is the PoC scope boundary between "core integration behaviors" and "full feature parity" defined in requirements with enough specificity that a researcher knows what is out of scope without reading research.md U2? [Clarity]
+- [ ] CHK206 - Is "follow/pause scroll behavior" in the log streaming requirement (User Story 2, acceptance scenario 2) defined with a behavioral specification — specifically when auto-scroll activates and when it freezes? [Clarity]
+- [ ] CHK207 - Does any requirement specify whether the PoC must connect to a real running Wave instance or whether mock/stub SSE data is acceptable for demonstration purposes? [Clarity]
+
+---
+
+## Consistency
+
+- [ ] CHK208 - Do the 16 acceptance criteria in `contracts/poc-contract.md` fully align with the 3 acceptance scenarios in User Story 2 — specifically: does the contract add requirements not in the spec, or omit requirements that are in the spec? [Consistency]
+- [ ] CHK209 - Is the `embed_server.go` approach described in tasks.md T021 consistent with FR-004's requirement for go:embed compatibility, or does FR-004 leave the integration approach open (which could allow a different valid implementation)? [Consistency]
+
+---
+
+## Coverage
+
+- [ ] CHK210 - Does any requirement distinguish between compile-time go:embed compatibility (the `go build` succeeds) and runtime correctness (the embedded page serves correctly), or is "go:embed compatibility" defined only at the build level? [Coverage]
+- [ ] CHK211 - Is the SSE connection status indicator (FR-005 implies it; poc-contract.md item 10 requires it) traceable to an explicit requirement in the spec's functional requirements — or is it only captured in the contract? [Coverage]
+- [ ] CHK212 - If the second PoC candidate fails go:embed compatibility after candidate-1 is built, does any requirement define whether the feature is still considered a research success or whether a replacement candidate must be found? [Coverage]

specs/1106-webui-framework-research/checklists/recommendation-quality.md

@@ -0,0 +1,38 @@
+# Checklist: Recommendation Document Requirements Quality
+
+**Feature**: WebUI Framework Research (`1106-webui-framework-research`)  
+**Date**: 2026-04-14  
+**Scope**: Requirements quality for the recommendation deliverable  
+**Validates**: FR-006, SC-004, SC-005, SC-006, SC-007
+
+---
+
+## Completeness
+
+- [ ] CHK301 - Does FR-006 require exactly one named winner (as SC-004 specifies), or does it allow for a "conditional recommendation" (e.g., "Framework A if X, Framework B if Y") — and is this distinction explicit in requirements? [Completeness]
+- [ ] CHK302 - Is the required format for risk assessment entries defined in a requirement (e.g., title, severity, likelihood, description, mitigation), or only in the recommendation contract — which is a validation artifact, not a specification? [Completeness]
+- [ ] CHK303 - Are the minimum required risk topics (build pipeline + CI impact, Node.js build toolchain, developer learning curve) enumerated as required fields in a functional requirement, or only listed as spec edge cases? [Completeness]
+- [ ] CHK304 - Is the runner-up section (naming a non-selected candidate with rationale) explicitly scoped as optional in requirements — so that an implementer is not penalized for omitting it? [Completeness]
+
+---
+
+## Clarity
+
+- [ ] CHK305 - Is "migration phase" defined clearly enough in requirements to distinguish a phase from a single page migration — specifically: does a phase boundary represent a time period, a coherent set of pages, a feature milestone, or something else? [Clarity]
+- [ ] CHK306 - Is the effort estimate format for migration phases specified in requirements (person-days, story points, t-shirt sizes, weeks), or is any estimate format acceptable? [Clarity]
+- [ ] CHK307 - Is "coexistence strategy" (how Go templates and new framework coexist page-by-page during incremental migration) defined distinctly from "migration strategy" in requirements, so that implementers know both sections are required for an incremental approach? [Clarity]
+
+---
+
+## Consistency
+
+- [ ] CHK308 - Do SC-005 ("first 3 pages to migrate in priority order") and the recommendation contract item 6 ("specifies at least 3 pages to migrate first") agree on both quantity (3) and whether rationale is required per page? [Consistency]
+- [ ] CHK309 - Is the template function migration strategy (T034: how the 30 functions in `embed.go` migrate) traceable to any functional requirement in the spec, or is it only specified in tasks.md — making it a task artifact rather than a requirement? [Consistency]
+
+---
+
+## Coverage
+
+- [ ] CHK310 - Does FR-006 or any success criterion explicitly require the recommendation to assess handler test suite impact (~1,900 lines), or is this only addressed as an edge case — making it ambiguous whether the recommendation must include a test impact section? [Coverage]
+- [ ] CHK311 - Does the recommendation requirement address the CI environment build dependency: specifically whether contributors without Node.js installed can build the project after migration? [Coverage]
+- [ ] CHK312 - Does FR-006 or the recommendation success criteria require assessing all 4 authentication modes (none, bearer, JWT, mTLS) for the recommended framework, or only CSRF-relevant scenarios — and is this scope explicitly stated? [Coverage]

specs/1106-webui-framework-research/checklists/requirements.md

@@ -0,0 +1,54 @@
+# Quality Checklist: 1106-webui-framework-research
+
+## Specification Structure
+
+- [x] Feature name, branch, date, and status are populated
+- [x] All template placeholders are replaced with real content
+- [x] No leftover `[PLACEHOLDER]` or `[ACTION REQUIRED]` markers remain
+
+## User Stories
+
+- [x] Each user story has a clear priority (P1–P3)
+- [x] Each user story explains WHY it has that priority
+- [x] Each user story has an Independent Test description
+- [x] Each acceptance scenario uses Given/When/Then format
+- [x] User stories are independently testable and deliverable
+- [x] At least 3 user stories are defined (4 defined)
+- [x] Stories cover all issue deliverables: matrix, PoC, recommendation
+
+## Edge Cases
+
+- [x] At least 4 edge cases are identified (5 identified)
+- [x] Edge cases are specific to this feature (not generic)
+- [x] Edge cases reference concrete elements of the current architecture
+
+## Functional Requirements
+
+- [x] Every requirement uses MUST/SHOULD/MAY language
+- [x] Every requirement is testable and unambiguous
+- [x] No implementation details (references to current files are context, not prescriptions)
+- [x] Requirements cover all 9 evaluation criteria from the issue
+- [x] Requirements cover all 3 deliverables from the issue (matrix, PoC, recommendation)
+- [x] Non-goal constraint is captured (no backend API changes — FR-009)
+- [x] Maximum 3 `[NEEDS CLARIFICATION]` markers (0 present)
+
+## Key Entities
+
+- [x] Key entities are defined with relationships
+- [x] Entities are technology-agnostic (no implementation details)
+
+## Success Criteria
+
+- [x] Every criterion is measurable (numeric or binary)
+- [x] Criteria are technology-agnostic
+- [x] Criteria map to the functional requirements
+- [x] At least 5 success criteria are defined (7 defined)
+
+## Overall Quality
+
+- [x] Spec focuses on WHAT and WHY, not HOW
+- [x] Spec is internally consistent (no contradictions)
+- [x] Spec aligns with the source issue (re-cinq/wave#1106)
+- [x] Scope matches issue non-goals (research only, no implementation rewrite)
+
+**Result: PASS** — All 26 checklist items satisfied.

specs/1106-webui-framework-research/checklists/review.md

@@ -0,0 +1,50 @@
+# Checklist: Requirements Quality Review
+
+**Feature**: WebUI Framework Research (`1106-webui-framework-research`)  
+**Date**: 2026-04-14  
+**Scope**: Overall requirements quality across all spec artifacts  
+**Purpose**: Unit tests for requirements — each item tests requirement quality, not implementation
+
+---
+
+## Completeness
+
+- [ ] CHK001 - Do the 10 functional requirements collectively cover all 4 research deliverables (matrix, PoC, recommendation, elimination section) without gaps? [Completeness]
+- [ ] CHK002 - Is each of the 9 evaluation criteria (FR-002) paired with a defined measurement method — either in the spec text, Key Entities section, or referenced contract? [Completeness]
+- [ ] CHK003 - Are candidate elimination thresholds quantitatively specified (e.g., minimum GitHub stars ≥100, last release within 12 months) in the requirements so they are objectively testable? [Completeness]
+- [ ] CHK004 - Does the spec define the rating scale for the comparison matrix (Strong / Good / Adequate / Weak / Fail) with enough context that two different researchers would apply it consistently? [Completeness]
+- [ ] CHK005 - Are baseline bundle size metrics specified with per-type precision (JS KB, CSS KB, total KB) in both FR-007 and SC-003, not just as a combined total? [Completeness]
+- [ ] CHK006 - Are the 7 SSE event types that the PoC must handle enumerated somewhere in the requirements, not left to be inferred from the Go codebase? [Completeness]
+- [ ] CHK007 - Does FR-003 fully specify the minimum required PoC deliverable structure (README, source code, build config, go:embed integration) beyond just listing the features to demonstrate? [Completeness]
+- [ ] CHK008 - Is each of the 5 edge cases from the spec addressed by at least one functional requirement or explicitly scoped out of requirements as a known non-goal? [Completeness]
+
+---
+
+## Clarity
+
+- [ ] CHK009 - Is "evidence-based" — applied to comparison matrix ratings — defined with an objective standard that distinguishes it from opinion? [Clarity]
+- [ ] CHK010 - Is the term "viable" (used in C1/FR-003 to condition whether a second PoC is built) defined with specific, testable criteria rather than left to researcher judgment? [Clarity]
+- [ ] CHK011 - Is the "no backend API changes" constraint (FR-009) scoped precisely enough to distinguish between (a) modifying existing handlers, (b) adding new API endpoints, and (c) changing response formats? [Clarity]
+- [ ] CHK012 - Are the 4 authentication modes referenced in Edge Case 4 and FR-016 (none, bearer, JWT, mTLS) described with enough detail in the spec for a researcher unfamiliar with `middleware.go` to evaluate each candidate against them? [Clarity]
+- [ ] CHK013 - Is the PoC scope boundary (core integration behaviors vs. full feature parity) defined in the requirements so that a PoC implementing only core features is clearly distinguishable from an incomplete PoC? [Clarity]
+
+---
+
+## Consistency
+
+- [ ] CHK014 - Do the bundle size baseline values in FR-007, SC-003, and `contracts/matrix-contract.md` all agree? (Known discrepancy: spec C4 corrected values to JS ~124 KB / CSS ~152 KB / total ~276 KB, but `matrix-contract.md` item 6 still references JS ~127 KB / CSS ~156 KB / total ~283 KB.) [Consistency]
+- [ ] CHK015 - Is the PoC minimum quantity consistent across all artifacts: FR-003 says "at least one," User Story 2 says "top 1–2," and SC-002 says "at least one PoC" — do these form a coherent requirement without contradicting each other? [Consistency]
+- [ ] CHK016 - Does SC-001's cell count (36) match FR-001 × FR-002 (4 candidates × 9 criteria = 36) with no ambiguity about whether eliminated candidates still occupy matrix columns? [Consistency]
+- [ ] CHK017 - Is the handler file count consistent across all artifacts? (spec section FR-008 says "~6,700 lines across 23 handler files"; plan.md Technical Context lists "21 handler files"; tasks.md T017 says "~21 handler files") [Consistency]
+- [ ] CHK018 - Are the 6 partials listed in FR-010 (step_card, dag_svg, run_row, child_run_row, artifact_viewer, resume_dialog) consistent with the actual `templates/partials/` directory, not enumerated from memory? [Consistency]
+
+---
+
+## Coverage
+
+- [ ] CHK019 - Does at least one requirement explicitly address the scenario where Ripple (or another candidate) is eliminated early — specifically that the elimination still satisfies FR-001's requirement to "evaluate" all four candidates? [Coverage]
+- [ ] CHK020 - Does at least one requirement or edge case treatment address the CI environment Node.js build dependency and what "build-time only" means for developer machines without Node.js installed? [Coverage]
+- [ ] CHK021 - Does the recommendation requirement (FR-006) specify an expected format for effort estimates in the migration strategy, or is the format left undefined? [Coverage]
+- [ ] CHK022 - Is artifact viewing explicitly required in PoC acceptance criteria? (FR-003 lists it as a feature of run_detail, but SC-002 acceptance criteria for PoC success do not explicitly list artifact viewing as a required demonstration.) [Coverage]
+- [ ] CHK023 - Does any requirement specify behavior or recovery path if both selected PoC candidates fail the go:embed compatibility verification after implementation? [Coverage]
+- [ ] CHK024 - Is the impact on the existing handler test suite (~1,900 lines) addressed by a functional requirement, or only mentioned as an edge case — making it unclear whether it is required research output? [Coverage]

specs/1106-webui-framework-research/contracts/matrix-contract.md

@@ -0,0 +1,44 @@
+# Contract: Comparison Matrix
+
+**Deliverable**: `specs/1106-webui-framework-research/matrix.md`  
+**Type**: Structural (document completeness)  
+**Validates**: FR-001, FR-002, FR-007, FR-008, FR-010, SC-001, SC-003
+
+## Acceptance Criteria
+
+### Structure Requirements
+
+1. **Document contains a matrix table** with candidates as columns and criteria as rows
+2. **Exactly 4 candidate columns**: Svelte/SvelteKit, Ripple, Astro, htmx (FR-001)
+3. **Exactly 9 criteria rows**: embedding, migration, SSE, bundle size, devexp, build complexity, community, component reuse, auth integration (FR-002)
+4. **36 cells populated** — zero empty cells (SC-001)
+
+### Content Requirements
+
+5. **Each cell contains**:
+   - A rating: one of Strong / Good / Adequate / Weak / Fail
+   - Evidence text: minimum 2 sentences of supporting analysis
+   - Code snippet or technical reference where applicable
+
+6. **Bundle size row** includes numeric KB measurements for each candidate compared to baseline (JS: ~127 KB, CSS: ~156 KB, total: ~283 KB) (FR-007, SC-003)
+
+7. **Embedding row** describes how each candidate's build output maps to `go:embed` and what pipeline changes are needed (spec acceptance scenario US1-2)
+
+8. **SSE row** addresses real-time streaming patterns with concrete examples (spec acceptance scenario US1-3)
+
+9. **Handler impact section** assesses impact on Go handler layer per candidate (FR-008):
+   - Category: No change / Template removal / Adapter needed
+   - Specific files affected (if any)
+
+10. **Component reuse section** evaluates extraction feasibility for all 6 partials: step_card, dag_svg, run_row, child_run_row, artifact_viewer, resume_dialog (FR-010)
+
+### Elimination Documentation
+
+11. If any candidate is eliminated, the matrix includes:
+    - Which hard constraint failed
+    - Specific technical evidence for the failure
+    - At minimum: ecosystem maturity data (stars, contributors, release cadence)
+
+## Validation Method
+
+Manual review checklist — verify all 11 criteria above. Automated: count table cells to confirm 36 populated intersections.