From d0e99dd73b53bc61daf5292e4960938b72e672e8 Mon Sep 17 00:00:00 2001 From: Paul Keen Date: Sun, 12 Jul 2026 20:14:11 +0200 Subject: [PATCH 1/5] docs(css): archive 36 superseded Oct-2025 consolidation docs (falsified plan) All encode the dead 70-80%-duplication-elimination goal: foundation-extraction ROI math, 'NEVER touch FL layouts' preservation rules, swarm execution prompts, stale baselines. Falsified by compiled+gzip evidence (Phase 1 WP1.2/1.4 + Phase 2 sprint-7 audits). Moved whole into 70-79-archives/superseded-2026-07-12/ with a README stating why. No content edits. Co-Authored-By: Claude Fable 5 --- .../10.07-component-duplication-analysis.md | 0 .../10.08-css-loading-priority-map.md | 0 .../10-19-analysis/10.01-critical-findings.md | 0 .../10.02-optimization-recommendations.md | 0 .../10-19-analysis/10.03-performance-baseline.md | 0 .../10-19-analysis/10.04-duplication-analysis.md | 0 .../10.06-fl-builder-duplication-analysis.md | 0 ...10.09-css-duplication-patterns-6-15-analysis.md | 0 .../10-19-analysis/10.10-css-files-list.txt | 0 ...ritical-css-removal-visual-regression-report.md | 0 .../30.05-hugo-pipeline-enhancement-strategy.md | 0 ...0.06-documentation-update-summary-2025-10-12.md | 0 .../30.07-top-down-consolidation-strategy.md | 0 .../30.08-css-layer-architecture-visual.md | 0 .../30.09-critical-css-migration-plan.md | 0 ....04-revised-goal-css-duplication-elimination.md | 0 ...35.05-sequential-file-consolidation-strategy.md | 0 .../35.06-top-down-strategy-summary.md | 0 .../40.01-layer-by-layer-tactical-guide.md | 0 .../40.01-migration-monitor.sh | 0 .../50-59-execution/50.01-consolidation-log.md | 0 .../50-59-execution/50.02-processed-files.txt | 0 .../50.03-file-6-monitoring-report.md | 0 .../50-59-execution/README.md | 0 .../50-59-testing/50.01-testing-protocol.md | 0 .../50-59-testing/50.02-performance-dashboard.html | 0 .../VISUAL_TESTING_PROTOCOL.md | 0 .../superseded-2026-07-12}/AI-INITIATION-PROMPT.md | 0 .../superseded-2026-07-12}/ANALYST-CONTEXT.md | 0 .../CONSOLIDATION-IMPACT-ANALYSIS.md | 0 .../superseded-2026-07-12}/GOAL-AT-A-GLANCE.md | 0 .../HUGO_TEMPLATE_CSS_PRESERVATION_ANALYSIS.md | 0 .../QUICK_REFERENCE_consolidation_impact.md | 0 .../QUICK_REFERENCE_foundation_integration.md | 0 .../70-79-archives/superseded-2026-07-12/README.md | 14 ++++++++++++++ .../REVISED-CONSOLIDATION-PROCESS.md | 0 .../SWARM-EXECUTION-PROMPT.md | 0 37 files changed, 14 insertions(+) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis-docs/10.07-component-duplication-analysis.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis-docs/10.08-css-loading-priority-map.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.01-critical-findings.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.02-optimization-recommendations.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.03-performance-baseline.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.04-duplication-analysis.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.06-fl-builder-duplication-analysis.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.10-css-files-list.txt (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/10-19-analysis/10.11-critical-css-removal-visual-regression-report.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/30-39-documentation/30.05-hugo-pipeline-enhancement-strategy.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/30-39-documentation/30.06-documentation-update-summary-2025-10-12.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/30-39-documentation/30.07-top-down-consolidation-strategy.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/30-39-documentation/30.08-css-layer-architecture-visual.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/30-39-documentation/30.09-critical-css-migration-plan.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/35-39-project-management/35.04-revised-goal-css-duplication-elimination.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/35-39-project-management/35.05-sequential-file-consolidation-strategy.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/35-39-project-management/35.06-top-down-strategy-summary.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/40-49-implementation/40.01-layer-by-layer-tactical-guide.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/40-49-implementation/40.01-migration-monitor.sh (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/50-59-execution/50.01-consolidation-log.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/50-59-execution/50.02-processed-files.txt (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/50-59-execution/50.03-file-6-monitoring-report.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/50-59-execution/README.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/50-59-testing/50.01-testing-protocol.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/50-59-testing/50.02-performance-dashboard.html (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/50-59-testing/50.03-visual-checkpoints/VISUAL_TESTING_PROTOCOL.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/AI-INITIATION-PROMPT.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/ANALYST-CONTEXT.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/CONSOLIDATION-IMPACT-ANALYSIS.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/GOAL-AT-A-GLANCE.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/HUGO_TEMPLATE_CSS_PRESERVATION_ANALYSIS.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/QUICK_REFERENCE_consolidation_impact.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/QUICK_REFERENCE_foundation_integration.md (100%) create mode 100644 docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/README.md rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/REVISED-CONSOLIDATION-PROCESS.md (100%) rename docs/projects/2509-css-migration/{ => 70-79-archives/superseded-2026-07-12}/SWARM-EXECUTION-PROMPT.md (100%) diff --git a/docs/projects/2509-css-migration/10-19-analysis-docs/10.07-component-duplication-analysis.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis-docs/10.07-component-duplication-analysis.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis-docs/10.07-component-duplication-analysis.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis-docs/10.07-component-duplication-analysis.md diff --git a/docs/projects/2509-css-migration/10-19-analysis-docs/10.08-css-loading-priority-map.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis-docs/10.08-css-loading-priority-map.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis-docs/10.08-css-loading-priority-map.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis-docs/10.08-css-loading-priority-map.md diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.01-critical-findings.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.01-critical-findings.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.01-critical-findings.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.01-critical-findings.md diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.02-optimization-recommendations.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.02-optimization-recommendations.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.02-optimization-recommendations.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.02-optimization-recommendations.md diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.03-performance-baseline.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.03-performance-baseline.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.03-performance-baseline.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.03-performance-baseline.md diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.04-duplication-analysis.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.04-duplication-analysis.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.04-duplication-analysis.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.04-duplication-analysis.md diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.06-fl-builder-duplication-analysis.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.06-fl-builder-duplication-analysis.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.06-fl-builder-duplication-analysis.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.06-fl-builder-duplication-analysis.md diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.10-css-files-list.txt b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.10-css-files-list.txt similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.10-css-files-list.txt rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.10-css-files-list.txt diff --git a/docs/projects/2509-css-migration/10-19-analysis/10.11-critical-css-removal-visual-regression-report.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.11-critical-css-removal-visual-regression-report.md similarity index 100% rename from docs/projects/2509-css-migration/10-19-analysis/10.11-critical-css-removal-visual-regression-report.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/10-19-analysis/10.11-critical-css-removal-visual-regression-report.md diff --git a/docs/projects/2509-css-migration/30-39-documentation/30.05-hugo-pipeline-enhancement-strategy.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.05-hugo-pipeline-enhancement-strategy.md similarity index 100% rename from docs/projects/2509-css-migration/30-39-documentation/30.05-hugo-pipeline-enhancement-strategy.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.05-hugo-pipeline-enhancement-strategy.md diff --git a/docs/projects/2509-css-migration/30-39-documentation/30.06-documentation-update-summary-2025-10-12.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.06-documentation-update-summary-2025-10-12.md similarity index 100% rename from docs/projects/2509-css-migration/30-39-documentation/30.06-documentation-update-summary-2025-10-12.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.06-documentation-update-summary-2025-10-12.md diff --git a/docs/projects/2509-css-migration/30-39-documentation/30.07-top-down-consolidation-strategy.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.07-top-down-consolidation-strategy.md similarity index 100% rename from docs/projects/2509-css-migration/30-39-documentation/30.07-top-down-consolidation-strategy.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.07-top-down-consolidation-strategy.md diff --git a/docs/projects/2509-css-migration/30-39-documentation/30.08-css-layer-architecture-visual.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.08-css-layer-architecture-visual.md similarity index 100% rename from docs/projects/2509-css-migration/30-39-documentation/30.08-css-layer-architecture-visual.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.08-css-layer-architecture-visual.md diff --git a/docs/projects/2509-css-migration/30-39-documentation/30.09-critical-css-migration-plan.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.09-critical-css-migration-plan.md similarity index 100% rename from docs/projects/2509-css-migration/30-39-documentation/30.09-critical-css-migration-plan.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/30-39-documentation/30.09-critical-css-migration-plan.md diff --git a/docs/projects/2509-css-migration/35-39-project-management/35.04-revised-goal-css-duplication-elimination.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/35-39-project-management/35.04-revised-goal-css-duplication-elimination.md similarity index 100% rename from docs/projects/2509-css-migration/35-39-project-management/35.04-revised-goal-css-duplication-elimination.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/35-39-project-management/35.04-revised-goal-css-duplication-elimination.md diff --git a/docs/projects/2509-css-migration/35-39-project-management/35.05-sequential-file-consolidation-strategy.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/35-39-project-management/35.05-sequential-file-consolidation-strategy.md similarity index 100% rename from docs/projects/2509-css-migration/35-39-project-management/35.05-sequential-file-consolidation-strategy.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/35-39-project-management/35.05-sequential-file-consolidation-strategy.md diff --git a/docs/projects/2509-css-migration/35-39-project-management/35.06-top-down-strategy-summary.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/35-39-project-management/35.06-top-down-strategy-summary.md similarity index 100% rename from docs/projects/2509-css-migration/35-39-project-management/35.06-top-down-strategy-summary.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/35-39-project-management/35.06-top-down-strategy-summary.md diff --git a/docs/projects/2509-css-migration/40-49-implementation/40.01-layer-by-layer-tactical-guide.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/40-49-implementation/40.01-layer-by-layer-tactical-guide.md similarity index 100% rename from docs/projects/2509-css-migration/40-49-implementation/40.01-layer-by-layer-tactical-guide.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/40-49-implementation/40.01-layer-by-layer-tactical-guide.md diff --git a/docs/projects/2509-css-migration/40-49-implementation/40.01-migration-monitor.sh b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/40-49-implementation/40.01-migration-monitor.sh similarity index 100% rename from docs/projects/2509-css-migration/40-49-implementation/40.01-migration-monitor.sh rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/40-49-implementation/40.01-migration-monitor.sh diff --git a/docs/projects/2509-css-migration/50-59-execution/50.01-consolidation-log.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/50.01-consolidation-log.md similarity index 100% rename from docs/projects/2509-css-migration/50-59-execution/50.01-consolidation-log.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/50.01-consolidation-log.md diff --git a/docs/projects/2509-css-migration/50-59-execution/50.02-processed-files.txt b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/50.02-processed-files.txt similarity index 100% rename from docs/projects/2509-css-migration/50-59-execution/50.02-processed-files.txt rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/50.02-processed-files.txt diff --git a/docs/projects/2509-css-migration/50-59-execution/50.03-file-6-monitoring-report.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/50.03-file-6-monitoring-report.md similarity index 100% rename from docs/projects/2509-css-migration/50-59-execution/50.03-file-6-monitoring-report.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/50.03-file-6-monitoring-report.md diff --git a/docs/projects/2509-css-migration/50-59-execution/README.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/README.md similarity index 100% rename from docs/projects/2509-css-migration/50-59-execution/README.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-execution/README.md diff --git a/docs/projects/2509-css-migration/50-59-testing/50.01-testing-protocol.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-testing/50.01-testing-protocol.md similarity index 100% rename from docs/projects/2509-css-migration/50-59-testing/50.01-testing-protocol.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-testing/50.01-testing-protocol.md diff --git a/docs/projects/2509-css-migration/50-59-testing/50.02-performance-dashboard.html b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-testing/50.02-performance-dashboard.html similarity index 100% rename from docs/projects/2509-css-migration/50-59-testing/50.02-performance-dashboard.html rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-testing/50.02-performance-dashboard.html diff --git a/docs/projects/2509-css-migration/50-59-testing/50.03-visual-checkpoints/VISUAL_TESTING_PROTOCOL.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-testing/50.03-visual-checkpoints/VISUAL_TESTING_PROTOCOL.md similarity index 100% rename from docs/projects/2509-css-migration/50-59-testing/50.03-visual-checkpoints/VISUAL_TESTING_PROTOCOL.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/50-59-testing/50.03-visual-checkpoints/VISUAL_TESTING_PROTOCOL.md diff --git a/docs/projects/2509-css-migration/AI-INITIATION-PROMPT.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/AI-INITIATION-PROMPT.md similarity index 100% rename from docs/projects/2509-css-migration/AI-INITIATION-PROMPT.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/AI-INITIATION-PROMPT.md diff --git a/docs/projects/2509-css-migration/ANALYST-CONTEXT.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/ANALYST-CONTEXT.md similarity index 100% rename from docs/projects/2509-css-migration/ANALYST-CONTEXT.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/ANALYST-CONTEXT.md diff --git a/docs/projects/2509-css-migration/CONSOLIDATION-IMPACT-ANALYSIS.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/CONSOLIDATION-IMPACT-ANALYSIS.md similarity index 100% rename from docs/projects/2509-css-migration/CONSOLIDATION-IMPACT-ANALYSIS.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/CONSOLIDATION-IMPACT-ANALYSIS.md diff --git a/docs/projects/2509-css-migration/GOAL-AT-A-GLANCE.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/GOAL-AT-A-GLANCE.md similarity index 100% rename from docs/projects/2509-css-migration/GOAL-AT-A-GLANCE.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/GOAL-AT-A-GLANCE.md diff --git a/docs/projects/2509-css-migration/HUGO_TEMPLATE_CSS_PRESERVATION_ANALYSIS.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/HUGO_TEMPLATE_CSS_PRESERVATION_ANALYSIS.md similarity index 100% rename from docs/projects/2509-css-migration/HUGO_TEMPLATE_CSS_PRESERVATION_ANALYSIS.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/HUGO_TEMPLATE_CSS_PRESERVATION_ANALYSIS.md diff --git a/docs/projects/2509-css-migration/QUICK_REFERENCE_consolidation_impact.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/QUICK_REFERENCE_consolidation_impact.md similarity index 100% rename from docs/projects/2509-css-migration/QUICK_REFERENCE_consolidation_impact.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/QUICK_REFERENCE_consolidation_impact.md diff --git a/docs/projects/2509-css-migration/QUICK_REFERENCE_foundation_integration.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/QUICK_REFERENCE_foundation_integration.md similarity index 100% rename from docs/projects/2509-css-migration/QUICK_REFERENCE_foundation_integration.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/QUICK_REFERENCE_foundation_integration.md diff --git a/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/README.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/README.md new file mode 100644 index 000000000..a1958ab7e --- /dev/null +++ b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/README.md @@ -0,0 +1,14 @@ +# Superseded 2026-07-12 + +Everything in this folder encodes the original Oct-2025 plan — "eliminate 70-80% +CSS duplication (27,094–31,536 lines)" via shared-foundation extraction and +consolidation — which was falsified on compiled+gzip evidence during Phase 1 +(WP1.2/WP1.4) and the Phase 2 audits (sprint 7, 2026-07-12): PurgeCSS runs per +bundle, so each page already ships only its own FL subset, and any shared +foundation is net-negative on first-visit transfer size. The `.fl-visible` +duplication claim measured 41.9%, not 90-95%; the "7 FL layout files" count was +actually 17 (16 after the e93d9b85 bundle merge). + +Kept for history only. The current authority is +`../../2026-07-12-css-maintainability-redesign.md` (strangler rewrite plan) and +`../../TASK-TRACKER.md`. diff --git a/docs/projects/2509-css-migration/REVISED-CONSOLIDATION-PROCESS.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/REVISED-CONSOLIDATION-PROCESS.md similarity index 100% rename from docs/projects/2509-css-migration/REVISED-CONSOLIDATION-PROCESS.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/REVISED-CONSOLIDATION-PROCESS.md diff --git a/docs/projects/2509-css-migration/SWARM-EXECUTION-PROMPT.md b/docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/SWARM-EXECUTION-PROMPT.md similarity index 100% rename from docs/projects/2509-css-migration/SWARM-EXECUTION-PROMPT.md rename to docs/projects/2509-css-migration/70-79-archives/superseded-2026-07-12/SWARM-EXECUTION-PROMPT.md From bcaa321d4a2989841cb6ff2eb996333db3fce17f Mon Sep 17 00:00:00 2001 From: Paul Keen Date: Sun, 12 Jul 2026 20:15:04 +0200 Subject: [PATCH 2/5] =?UTF-8?q?docs(css):=20add=20page=E2=86=92bundle=20ow?= =?UTF-8?q?nership=20map=20+=20FL=20burn-down=20(16=E2=86=920)=20=E2=80=94?= =?UTF-8?q?=20Phase=200=20deliverable?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 19 external bundles mapped to owning templates, FL files, and measured gzip sizes (converged production build 2026-07-12); reverse map of all 16 live FL layout files with consuming bundles and retirement status. Includes the easy-to-miss repo-root layouts/course/list.html → course-list bundle. Co-Authored-By: Claude Fable 5 --- .../css-bundle-ownership-map.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/projects/2509-css-migration/css-bundle-ownership-map.md diff --git a/docs/projects/2509-css-migration/css-bundle-ownership-map.md b/docs/projects/2509-css-migration/css-bundle-ownership-map.md new file mode 100644 index 000000000..d4ab0f060 --- /dev/null +++ b/docs/projects/2509-css-migration/css-bundle-ownership-map.md @@ -0,0 +1,78 @@ +# CSS bundle ownership map + FL burn-down + +Answers "which pages does this CSS file affect?" for every bundle and file. +Sizes measured 2026-07-12 from a converged production build (`gzip -c | wc -c`). +Update this map whenever a resource slice changes; flip statuses as rewrite +sprints land (see `2026-07-12-css-maintainability-redesign.md`). + +## External bundles (19) + +Each page type loads ONE fingerprinted bundle, built by concatenating its +template's resource slice through PostCSS (per-bundle PurgeCSS — a page ships +only its own subset; see the evidence rule in the redesign spec). + +| Bundle | Owning template | FL layout files in slice | gzip | Status | +|---|---|---|---|---| +| homepage | `home.html` (partial `homepage-css-resources.html`) | 590-layout | 29.6K | live-FL | +| services | `page/services.html` | 737-layout, bf72bba… | 25.4K | live-FL | +| single-client | `clients/single.html` | 3114-layout, fb2624… | 25.4K | live-FL | +| use-cases | `page/use-cases.html` | 3021-layout, bf72bba… | 25.0K | live-FL | +| single-service | `services/single.html` | 2949-layout, bf72bba… | 23.8K | live-FL | +| clients | `page/clients.html` | 3082-layout, bf72bba… | 23.6K | live-FL | +| careers | `page/careers.html` (partial `careers-css-resources.html`) | 3086-layout2 | 23.4K | live-FL | +| single-use-cases | `use-cases/single.html` | 3027-layout, bf72bba… | 23.3K | live-FL | +| single-career | `careers/single.html` (partial `single-career-css-resources.html`) | 3114-layout, e966db44… | 22.0K | live-FL | +| free-consultation | `page/free-consultation.html` (partial `free-consultation-css-resources.html`) | homepage-layout, services-layout | 20.2K | live-FL | +| about-us | `page/about.html` | 701-layout, bf72bba… | 19.4K | live-FL | +| course-single | `course/single.html` | 3114-layout, bf72bba… | 19.3K | live-FL | +| blog-single | `single.html` | 3114-layout, bf72bba… | 19.3K | live-FL | +| blog-list | `blog/list.html` + `list.html` (shared partial `blog-list-css-resources.html`) | homepage-layout, services-layout | 19.1K | live-FL | +| contact-us | `page/contact-us.html` (partial `contact-us-css-resources.html`) | 706-layout | 18.9K | live-FL | +| course-list | `layouts/course/list.html` (repo root, NOT in theme) | 3059-layout, bf72bba… | 17.6K | live-FL | +| privacy-policy | `page/single.html` (generic pages) | 3059-layout, bf72bba… | 17.1K | live-FL | +| not_found | `404.html` | — (404.css, dynamic-404-590.css) | 16.2K | no-FL | +| pagination | `list.html` (second bundle) | — (pagination.css only) | 0.2K | no-FL | + +Inline bundles (in `` via `css-inline.html`, baseof.html): `navigation` +(css-variables + navigation.css, site-wide) and `components` (components.css, +site-wide). Not FL-affected. + +Shared non-FL slice members loaded by most bundles: `critical/base.css` (pulls +the critical/fl-* trio), `dynamic-icons.css`, `586.css`, `vendors/base-4.min.css`, +`style.css`, `skin-65eda28877e04.css`, `footer.css`, plus per-page extras +(`technologies.css`, `single-post.css`, `use-cases-dynamic.css`, `homepage.css`, +`companies.css`, `careers.css`, `404.css`, `pagination.css`, +`component-bundle.css`, `theme-main.css`). + +## FL layout file burn-down: 16 → 0 + +Generated FL-Builder export CSS under `themes/beaver/assets/css/`. A file is +RETIRED when its last consuming bundle's page is rewritten (semantic HTML + +`css/pages/*.css`) and the file is deleted. + +| FL file | Lines | Consumed by bundles | Status | +|---|---|---|---| +| 590-layout.css | 12,437 | homepage | live | +| 737-layout.css | 6,489 | services | live | +| fb2624e43f3c4277448abe268cde571e-layout-bundle.css | 6,523 | single-client | live | +| 3021-layout.css | 6,409 | use-cases | live | +| 2949-layout.css | 5,407 | single-service | live | +| 3082-layout.css | 5,399 | clients | live | +| 3086-layout2.css | 5,157 | careers | live | +| 3027-layout.css | 5,056 | single-use-cases | live | +| 701-layout.css | 4,462 | about-us | live | +| e966db44b09892b8d7d492247c67e86c-layout-bundle.css | 4,364 | single-career | live | +| homepage-layout.css | 2,678 | blog-list, free-consultation | live | +| 3114-layout.css | 2,272 | blog-single, course-single, single-career, single-client | live | +| 706-layout.css | 2,202 | contact-us | live | +| bf72bba397177a0376baed325bffdc75-layout-bundle.css | 1,969 | 9 bundles: about-us, blog-single, clients, course-list, course-single, privacy-policy, services, single-service, single-use-cases, use-cases | live | +| services-layout.css | 1,678 | blog-list, free-consultation | live | +| 3059-layout.css | 924 | course-list, privacy-policy | live | + +Satellites that retire with their last importer: `foundations/fl-builder-common-base.css` +(imported only by 3021-layout.css), `utilities/fl-builder-grid.css` (imported only +by homepage-layout.css), and the `critical/` FL trio (`fl-layout-grid.css`, +`fl-shape-dividers.css`, `fl-common-modules.css` via `critical/base.css`). + +**Retired so far**: e93d9b85…-layout-bundle.css (merged into superset bf72bba…, +PR #363, 2026-07-12); 6 never-loaded orphans deleted same PR. From 6172fe5e404be909d49ddd5c5d2d95493643f53e Mon Sep 17 00:00:00 2001 From: Paul Keen Date: Sun, 12 Jul 2026 20:19:43 +0200 Subject: [PATCH 3/5] =?UTF-8?q?docs(css):=20rewrite=20TASK-TRACKER=20to=20?= =?UTF-8?q?the=20maintainability=20plan=20=E2=80=94=20Phase=203=20supersed?= =?UTF-8?q?ed,=20Phase=200=20+=20rewrite=20sprints=20added?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GOAL OVERVIEW re-goaled (FL burn-down 16→0 replaces the falsified 70-80% line-count target); CUMULATIVE METRICS → burn-down + historical note; Phase 3 WP definitions closed as superseded (preserved in git history + archives); QUICK ACTIONS + navigation repointed to the spec and ownership map; sprint-8 update-log entry added. Spec count fix: 17→16 live FL files (PR #363 merged e93d9b85 away — reviewer finding). Co-Authored-By: Claude Fable 5 --- ...2026-07-12-css-maintainability-redesign.md | 8 +- .../2509-css-migration/TASK-TRACKER.md | 314 +++++++----------- 2 files changed, 123 insertions(+), 199 deletions(-) diff --git a/docs/projects/2509-css-migration/2026-07-12-css-maintainability-redesign.md b/docs/projects/2509-css-migration/2026-07-12-css-maintainability-redesign.md index 35243d8e7..3ba074103 100644 --- a/docs/projects/2509-css-migration/2026-07-12-css-maintainability-redesign.md +++ b/docs/projects/2509-css-migration/2026-07-12-css-maintainability-redesign.md @@ -23,8 +23,10 @@ pattern), not to optimize in place. ### Success criteria -1. **FL retirement burn-down**: live FL layout files 17 → 0. Each rewritten page - deletes its FL CSS file(s) and its template's `fl-node-*` markup in the same PR. +1. **FL retirement burn-down**: live FL layout files 16 → 0 (17 at audit time; + the e93d9b85 bundle was merged away in PR #363 — see + `css-bundle-ownership-map.md` for the live list). Each rewritten page deletes + its FL CSS file(s) and its template's `fl-node-*` markup in the same PR. 2. **No obfuscated artifacts** at end state: zero hash-named CSS files (`bf72bba…`, `e966db44…`, `fb2624…`), zero generated node-id rules. 3. **No duplication in the hand-maintained layer**: new CSS uses tokens from @@ -126,7 +128,7 @@ sooner; the protocol never changes. - Old Phase 3 (pattern consolidation + Hugo enhancements, 20–45 h) is **closed as superseded** — its premise died with the compiled+gzip evidence. - TASK-TRACKER updates: GOAL OVERVIEW rewritten to this goal; stale CUMULATIVE - METRICS replaced by the FL burn-down table (17 → 0); new phases = Phase 0 + METRICS replaced by the FL burn-down table (16 → 0); new phases = Phase 0 (scaffolding) then rewrite sprints R1…Rn. - Pace: one page per sprint, no fixed calendar. One branch + one bundled PR per sprint, per repo policy. diff --git a/docs/projects/2509-css-migration/TASK-TRACKER.md b/docs/projects/2509-css-migration/TASK-TRACKER.md index 60cfa2c80..fb2314ad3 100644 --- a/docs/projects/2509-css-migration/TASK-TRACKER.md +++ b/docs/projects/2509-css-migration/TASK-TRACKER.md @@ -1,36 +1,40 @@ # CSS Migration Task Tracker -**Purpose**: Real-time work package status tracking for CSS duplication elimination goal -**Update Frequency**: After each work package completion or status change +**Purpose**: Status tracking for the CSS maintainability goal — FL-Builder export CSS retired page-by-page (strangler rewrites) +**Update Frequency**: After each sprint or status change **Last Updated**: 2026-07-12 -**Current Phase**: Phase 1 - Critical CSS Inline Consolidation +**Current Phase**: Phase 0 - Safety scaffolding (test coverage + guards) --- ## 🎯 GOAL OVERVIEW -**Objective**: Eliminate 70-80% CSS duplication (27,094-31,536 lines) -**Approach**: 3-phase execution with micro-commit discipline -**Execution Mode**: Solo autonomous (NO swarm spawning for mechanical work) -**Success Criteria**: 100% test pass rate, zero visual regressions maintained +**Objective**: Every style hand-editable, understood, single-source — FL export CSS 16 files → 0 +**Approach**: Phase 0 scaffolding, then one-page-per-sprint full rewrites (semantic HTML + token-based page CSS), easiest first +**Execution Mode**: One feature branch + one bundled PR per sprint; read-only audit agents allowed, mutations sequential +**Success Criteria**: FL burn-down to zero; no hash-named/obfuscated files; no duplication in the hand-maintained layer; both snapdiff suites green with every non-target page 0.0-diff **Quick Links**: -- 📋 [Full Goal Document](35-39-project-management/35.04-revised-goal-css-duplication-elimination.md) +- 📋 [Approved spec (authority)](2026-07-12-css-maintainability-redesign.md) +- 🗺️ [Bundle ownership map + FL burn-down](css-bundle-ownership-map.md) - 📊 [Project Index](PROJECT-INDEX.md) -- 🔍 [Top 5 Patterns](10-19-analysis/10.06-fl-builder-duplication-analysis.md) -- 🔍 [Patterns #6-#15](10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md) +- 📚 [Superseded Oct-2025 plan (archived)](70-79-archives/superseded-2026-07-12/README.md) --- ## 📊 OVERALL PROGRESS ``` +OLD PLAN (falsified, closed): Phase 1: Critical CSS Inline [✅❌✅❌] 4/4 WPs resolved (2 done, 2 closed with evidence) Phase 2: FL-Builder Foundations [❌❌❌❌] 4/4 WPs resolved (all closed with evidence; cleanup shipped instead) -Phase 3: Additional Patterns [🔲🔲🔲🔲] 0/4 WPs (0% complete) +Phase 3: Additional Patterns SUPERSEDED 2026-07-12 — never started; premise died with Phases 1+2 -Total Progress: 8/12 work packages resolved -Lines Eliminated: ~73,150 (sprints 1-7; orphan deletion + consolidation) +CURRENT PLAN (2026-07-12 spec): +Phase 0: Safety scaffolding [🔲🔲✅🔲] 1/4 items (blog-post test coverage, per-page coverage check, ownership map ✅ 2026-07-12, orphan guard) +Rewrites: FL burn-down 16/16 files live → target 0 (R1 = 3059-layout: course-list + privacy-policy pages) + +Historical: ~73,150 lines eliminated sprints 1-7 (orphan deletion + consolidation) ``` **Status Legend**: @@ -377,139 +381,71 @@ lesson: same as WP1.4 — savings claims must be verified against compiled+gzipp --- -## 📅 PHASE 3: Additional Pattern Consolidation + Hugo Enhancements - -**Phase Status**: 🔲 Not Started -**Duration**: 20-30 hours (base) OR 30-45 hours (with Hugo enhancements) -**Target Impact**: 484-768 lines + optional Hugo pipeline improvements -**Risk Level**: LOW - Cleanup and optimization +## 📅 PHASE 3 (OLD PLAN): Additional Pattern Consolidation + Hugo Enhancements — ❌ SUPERSEDED 2026-07-12 -### Work Package Status +**Phase Status**: ❌ Superseded before start — closed 2026-07-12 (never begun) +**Reason**: Its premise (source-level pattern consolidation into shared foundation +files, measured in raw line counts) is the same methodology falsified by Phase 1 +(WP1.2/WP1.4) and the whole of Phase 2: PurgeCSS runs per bundle, so each page +already ships only its own FL subset — foundation extraction grows shipped bytes. +WP3.1/WP3.2 also proposed `.scss` files in a Sass-less pipeline. WP3.3's Hugo +enhancements (hugo_stats.json, PurgeCSS, safelists) already exist in production. +The WP3.1-3.4 definitions are preserved in git history (commit 2388c437 and +earlier) and the archived plan docs under `70-79-archives/superseded-2026-07-12/`. -#### WP3.1: Background Patterns Consolidation 🔲 NOT STARTED -```yaml -status: 🔲 Not Started -priority: P2 📋 Medium -duration: 10-14 hours -files_affected: 7 FL-Builder layout files -pattern: FL-row background patterns (colors, images, gradients) -impact: 400-600 lines eliminated -micro_commits_target: 30-40 commits - -tasks: - - [ ] Create _fl-background-utilities.scss - - [ ] Extract common background patterns (colors, images) - - [ ] Consolidate gradient definitions - - [ ] Import utilities in layout files - - [ ] Remove duplicated background CSS - - [ ] Validation: bin/rake test:critical (all pass) - - [ ] Validation: Background visual tests (all 7 pages) - -blockers: NONE -dependencies: Phase 2 complete (WP2.1-WP2.4) -assigned_to: TBD -started_date: - -completed_date: - -actual_duration: - -actual_commits: - -notes: Lower priority, can be deferred if needed -``` +**Replaced by**: the strangler rewrite plan in +[2026-07-12-css-maintainability-redesign.md](2026-07-12-css-maintainability-redesign.md). -#### WP3.2: @import Statement Deduplication 🔲 NOT STARTED -```yaml -status: 🔲 Not Started -priority: P2 📋 Medium -duration: 6-8 hours -files_affected: 7 FL-Builder layout files -pattern: Duplicate @import statements -impact: 84-168 lines eliminated -micro_commits_target: 15-20 commits +--- -tasks: - - [ ] Create master _fl-imports.scss - - [ ] Consolidate all foundation imports into master file - - [ ] Replace individual @import statements with master import - - [ ] Validation: Build validation (CSS compilation) - - [ ] Validation: No broken imports +## 📅 PHASE 0 (CURRENT PLAN): Safety scaffolding -blockers: NONE -dependencies: WP3.1 (all foundations extracted and stable) -assigned_to: TBD -started_date: - -completed_date: - -actual_duration: - -actual_commits: - -notes: Cleanup work, enhances maintainability -``` +**Phase Status**: 🔄 In progress (1/4 items) +**Source**: Spec §"Phase 0 — safety scaffolding". No legacy CSS edits in this phase. +**Gate mechanism**: existing snapdiff suites only — `bin/test` (macOS) + `bin/dtest` +(Linux), `FORCE_SCREENSHOT_UPDATE=true` to regenerate baselines. No new custom +baseline/compare scripts; missing coverage is fixed by ADDING TESTS. -#### WP3.3: Hugo Pipeline Enhancements (OPTIONAL) 🔲 NOT STARTED ```yaml -status: 🔲 Not Started -priority: OPTIONAL (can be separate initiative) -duration: 10-15 hours -files_affected: config.toml, postcss.config.js, layouts -impact: 20-40% additional CSS reduction + automated workflows -micro_commits_target: 15-20 commits - -tasks: - - [ ] Enable hugo_stats.json generation (config.toml) - - [ ] Add postcss-purgecss plugin to postcss.config.js - - [ ] Configure safelist for FL-Builder/PowerPack classes - - [ ] Add postcss-critical for automated critical CSS - - [ ] Update layouts to use automated critical CSS - - [ ] Validation: Lighthouse audits (FCP, CLS improvements) - - [ ] Validation: Bundle size comparison (before/after) - -blockers: NONE -dependencies: WP3.2 (SOURCE CSS consolidation complete) -assigned_to: TBD -started_date: - -completed_date: - -actual_duration: - -actual_commits: - -notes: See 30.05-hugo-pipeline-enhancement-strategy.md for details -reference: Can be executed as separate initiative if Phase 3 base completes +items: + - [ ] P0.1 Special-content blog post coverage: desktop+mobile screenshot tests + for one representative post per surface — Mermaid (3 posts exist), + Chroma code-highlight (139 posts), inline style= HTML (3 posts), + youtube shortcode. Revive or replace the skipped + test/system/components/diagram_component_test.rb. + - [ ] P0.2 Rewrite-target coverage check: before each rewrite sprint, confirm + the target page has desktop+mobile snapdiff coverage; add it first if not. + - [x] P0.3 Page→bundle ownership map: css-bundle-ownership-map.md (2026-07-12) — + 19 bundles × owning template × FL files × gzip; FL burn-down table 16→0. + - [ ] P0.4 Orphan guard: check listing CSS files under themes/beaver/assets/css/ + referenced by no template resource slice. ``` -#### WP3.4: PostCSS Final Validation 🔲 NOT STARTED -```yaml -status: 🔲 Not Started -priority: P0 🔥 Critical (Phase gate) -duration: 4-8 hours -files_affected: All compiled CSS files -impact: Runtime validation, final duplication metrics -micro_commits_target: 5-10 commits +--- -tasks: - - [ ] Run PostCSS postcss-delete-duplicate-css plugin - - [ ] Validate remaining duplication < 5% - - [ ] Document any intentional duplication (with justification) - - [ ] Generate final duplication metrics report - - [ ] Validation: Build output analysis - - [ ] Generate Phase 3 completion report +## 📅 REWRITE SPRINTS (CURRENT PLAN): FL burn-down 16 → 0 -blockers: NONE -dependencies: WP3.1, WP3.2 complete (or WP3.3 if Hugo enhancements executed) -assigned_to: TBD -started_date: - -completed_date: - -actual_duration: - -actual_commits: - -notes: MANDATORY - Phase 3 gate and goal completion validation -``` +One page type per sprint: semantic HTML template + one token-based file under +`css/pages/`, FL file(s) deleted in the same PR, design improvements per +JetVelocity (`.stitch/design.md`) with Paul's screenshot approval. Full protocol +in the spec; live status in `css-bundle-ownership-map.md`. -### Phase 3 Summary ```yaml -work_packages_total: 4 (3 base + 1 optional Hugo) -work_packages_completed: 0 -work_packages_blocked: 0 -total_duration_target: 20-30 hours (base) OR 30-45 hours (with Hugo) -total_duration_actual: 0 hours -total_lines_eliminated_target: 484-768 lines (base) + 20-40% (Hugo) -total_lines_eliminated_actual: 0 lines -total_commits_target: 50-70 commits (base) OR 70-100 commits (with Hugo) -total_commits_actual: 0 commits -foundation_files_created: 0 / 2 (_fl-backgrounds, _fl-imports) +order_easiest_first: # ascending FL size; order may flex on business need + - R1: 3059-layout.css (924) → pages: privacy-policy (page/single.html) + course-list (layouts/course/list.html) + - R2: 706-layout.css (2,202) → contact-us + - R3: 3114-layout.css (2,272) → blog-single, course-single (+ feeds single-career, single-client) + - R4: homepage-layout.css + services-layout.css (~4,356) → blog-list, free-consultation + - R5: e966db44…-layout-bundle.css (4,364) → single-career + - R6: 701-layout.css (4,462) → about-us + - R7+: 3027 (5,056), 3086-layout2 (5,157), 3082 (5,399), 2949 (5,407), + 3021 (6,409), fb2624… (6,523), 737 (6,489) — ascending + - Rlast: 590-layout.css (12,437) → homepage +notes: | + bf72bba…-layout-bundle.css (1,969; 9 bundles) and the critical/ FL trio retire + when their last consumer page is rewritten. Satellites fold with their single + importers (fl-builder-common-base.css → 3021; fl-builder-grid.css → homepage-layout). +completed: [] ``` --- @@ -518,11 +454,10 @@ foundation_files_created: 0 / 2 (_fl-backgrounds, _fl-imports) ### Current Blockers ```yaml -phase_1_blockers: NONE - Ready to start immediately -phase_2_blockers: NONE - Waiting for Phase 1 completion -phase_3_blockers: NONE - Phase 2 closed 2026-07-12; Phase 3 WPs must be re-scoped against compiled+gzip output BEFORE any work starts (Phase 1+2 both falsified their specs) +phase_0_blockers: NONE - P0.1/P0.2/P0.4 ready to start (P0.3 shipped 2026-07-12) +rewrite_sprint_blockers: R1 gated on Phase 0 items P0.1 + P0.4 (coverage + orphan guard) -critical_path_risks: NONE - All dependencies clear +critical_path_risks: NONE - old-plan phases all closed; see UPDATE LOG for history ``` ### Risk Mitigation Status @@ -537,38 +472,19 @@ performance_baseline: ✅ YES - FCP, CLS metrics documented ## 📈 CUMULATIVE METRICS -### Lines Eliminated (Running Total) +### FL burn-down (the headline metric) ``` -Phase 1 Target: 300-400 lines | Actual: 0 lines | Progress: 0% -Phase 2 Target: 1,900-2,900 lines| Actual: 0 lines | Progress: 0% -Phase 3 Target: 484-768 lines | Actual: 0 lines | Progress: 0% -───────────────────────────────────────────────────────────────────── -TOTAL Target: 27,394-31,936 | Actual: 0 lines | Progress: 0% +Live FL layout files: 16 / 16 (target: 0) +Retired: e93d9b85…-layout-bundle.css (merged into bf72bba…, PR #363) + + 6 never-loaded orphans (PR #363) +Authoritative table: css-bundle-ownership-map.md ``` -### Micro-Commits (Running Total) +### Historical (old plan, closed) ``` -Phase 1 Target: 78-100 commits | Actual: 0 commits | Progress: 0% -Phase 2 Target: 100-135 commits | Actual: 0 commits | Progress: 0% -Phase 3 Target: 50-70 commits | Actual: 0 commits | Progress: 0% -───────────────────────────────────────────────────────────────────── -TOTAL Target: 300-390 commits | Actual: 0 commits | Progress: 0% -``` - -### Foundation Files Created -``` -Target: 5-7 foundation files -Actual: 0 foundation files created - -Planned: - - _css-variables.scss (WP1.1) - - _reset-utilities.scss (WP1.2) - - _responsive-utilities.scss (WP1.4) - - _fl-row-foundation.scss (WP2.1) - - _fl-col-foundation.scss (WP2.2) - - _fl-responsive-display.scss (WP2.3) - - _fl-background-utilities.scss (WP3.1) - - _fl-imports.scss (WP3.2) +Lines eliminated sprints 1-7: ~73,150 (orphan cleanup + consolidation + dedup) +Old line-count targets (27,394-31,936) retired — methodology falsified; +see 70-79-archives/superseded-2026-07-12/README.md ``` ### Quality Metrics (Maintained Throughout) @@ -598,6 +514,23 @@ fcp_metrics: ## 🔄 UPDATE LOG +### 2026-07-12 (sprint 8 — plan re-wised, project docs realigned) +- **Action**: Goal reframed from line-count elimination to maintainability + (hand-editable, single-source, FL export retired) — approved spec + `2026-07-12-css-maintainability-redesign.md` (brainstormed section-by-section, + merged in PR #363). This tracker rewritten to the new plan: Phase 3 + superseded before start; new Phase 0 (safety scaffolding) + rewrite sprints + R1…Rlast (FL burn-down 16→0, easiest first). +- **Shipped**: `css-bundle-ownership-map.md` (Phase 0 item P0.3) — 19 bundles × + template × FL files × gzip from a converged production build; 36 superseded + Oct-2025 docs moved to `70-79-archives/superseded-2026-07-12/` (audited + file-by-file by a read-only agent); PROJECT-INDEX rewritten; + `css-loading-order-analysis.md` banner + CLAUDE.md pointer updated. +- **Evidence basis**: PR #363 review (independent agent, SAFE-TO-MERGE) + + the sprint-7 compiled+gzip falsification of the extraction plan. +- **Next**: Phase 0 items P0.1 (special-content blog post tests), P0.4 (orphan + guard), then R1 (3059-layout → privacy-policy + course-list pages). + ### 2026-07-12 (sprint 7 — Phase 2 re-scoped and closed) Swarm protocol: two parallel read-only auditors (source inventory + compiled-output @@ -884,48 +817,37 @@ further whole-file merges found. ## 📋 QUICK ACTIONS -### Start Next Work Package +### Start the next sprint ```bash -# Current: WP1.1 CSS Variables Foundation (ready to start) -git checkout -b feat/css-duplication-elimination -# Create themes/beaver/assets/css/foundations/_css-variables.scss -# Update 12 inline critical CSS files -# Test after each file: bin/rake test:critical -# Commit on green (≤3 lines per commit) +# Current: Phase 0 items P0.1 (blog-post coverage) / P0.4 (orphan guard) +git checkout -b css-migration/ +# Follow the spec: 2026-07-12-css-maintainability-redesign.md +# Gates on every commit: bin/test (macOS) AND bin/dtest (Linux) +# Baselines regenerate only intentionally: FORCE_SCREENSHOT_UPDATE=true +# One bundled PR per sprint ``` -### Update This Tracker After WP Completion +### Update this tracker after a sprint ```bash -# Update work package status from 🔲 to ✅ -# Update actual duration, commits, lines eliminated -# Update cumulative metrics -# Add notes/lessons learned -# Update "Last Updated" date at top -# Commit tracker changes +# Flip Phase 0 item / rewrite sprint status; update FL burn-down count +# Update css-bundle-ownership-map.md statuses in the same commit +# Add an UPDATE LOG entry; bump "Last Updated" at top ``` -### Check Goal Completion +### Check goal completion ```bash -# Read goal document for success criteria -Read: 35-39-project-management/35.04-revised-goal-css-duplication-elimination.md - -# Validate all phases complete -All 12 work packages: ✅ Completed - -# Validate metrics targets met -Lines eliminated: 27,394-31,936 ✅ -Foundation files: 5-7 ✅ -Test pass rate: 100% ✅ -Visual regressions: 0 ✅ +# Success criteria live in: 2026-07-12-css-maintainability-redesign.md +# FL layout files: 0 remaining (css-bundle-ownership-map.md burn-down) +# No hash-named CSS files; no fl-node-* markup in templates +# Both snapdiff suites green; per-page payload checked compiled+gzip ``` --- **Navigation**: - 🏠 [Project Index](PROJECT-INDEX.md) -- 🎯 [Current Goal](35-39-project-management/35.04-revised-goal-css-duplication-elimination.md) -- 📊 [Goal At A Glance](GOAL-AT-A-GLANCE.md) -- 🔍 [Analyst Context](ANALYST-CONTEXT.md) +- 🎯 [Approved spec (authority)](2026-07-12-css-maintainability-redesign.md) +- 🗺️ [Bundle ownership map + burn-down](css-bundle-ownership-map.md) -**Last Updated**: 2025-01-27 -**Next Update**: After WP1.1 completion or status change +**Last Updated**: 2026-07-12 +**Next Update**: After Phase 0 item completion or status change From ebbbd0dfc7a17921eaba47d8e8c7ea108d8afa80 Mon Sep 17 00:00:00 2001 From: Paul Keen Date: Sun, 12 Jul 2026 20:21:08 +0200 Subject: [PATCH 4/5] docs(css): rewrite PROJECT-INDEX to current plan; banner loading-order doc; repoint CLAUDE.md CSS row MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PROJECT-INDEX was wall-to-wall dead plan (35.04 as PRIMARY AUTHORITY, 44,420→ 11,884 line targets, WP tables) — replaced with a slim hub: spec, tracker, ownership map, banner'd loading-order reference, standing constraints. css-loading-order-analysis keeps its accurate load-order mechanics but gets a supersede banner on its extraction-strategy framing. CLAUDE.md 'ANY CSS changes' pointer now sends readers to the spec + ownership map instead of the inverted FL-preservation rules. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 3 +- .../2509-css-migration/PROJECT-INDEX.md | 471 +++--------------- .../css-loading-order-analysis.md | 10 + 3 files changed, 71 insertions(+), 413 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 98a311de0..e9498d9b3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,7 +26,8 @@ Always read these files before making changes. They define the project's archite | `@bin/hugo-build` | Build/deploy workflow | | `@Rakefile` | Test workflow | | `@test/test_helper.rb` | Writing new tests | -| `@docs/projects/2509-css-migration/css-loading-order-analysis.md` | ANY CSS changes | +| `@docs/projects/2509-css-migration/2026-07-12-css-maintainability-redesign.md` | ANY CSS changes — the approved plan + evidence rule (compiled+gzip, never raw line counts) | +| `@docs/projects/2509-css-migration/css-bundle-ownership-map.md` | ANY CSS changes — which pages a CSS file affects + FL burn-down | --- diff --git a/docs/projects/2509-css-migration/PROJECT-INDEX.md b/docs/projects/2509-css-migration/PROJECT-INDEX.md index 5b3893e5f..ab7ba4c42 100644 --- a/docs/projects/2509-css-migration/PROJECT-INDEX.md +++ b/docs/projects/2509-css-migration/PROJECT-INDEX.md @@ -1,417 +1,64 @@ # CSS Migration Project 2509 - Master Index -**Quick Start for Agents**: This is your ONE-STOP navigation hub for the CSS migration project. - -**Last Updated**: 2025-01-27 -**Project Status**: ✅ READY FOR EXECUTION - Phase 1 (Critical CSS Inline Consolidation) -**Current Goal**: Eliminate 70-80% CSS duplication (27,094-31,536 lines) - ---- - -## 🚀 IMMEDIATE ACTION - START HERE - -### For Executing Agents (Ready to Work) -```bash -# Step 1: Read the current goal -Read: 35-39-project-management/35.04-revised-goal-css-duplication-elimination.md - -# Step 2: Check current task status -Read: TASK-TRACKER.md - -# Step 3: Understand project context -Read: ANALYST-CONTEXT.md - -# Step 4: Review top duplication patterns -Read: 10-19-analysis/10.06-fl-builder-duplication-analysis.md (Top 5) -Read: 10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md (Patterns #6-#15) -``` - -### For Research/Analysis Agents -```bash -# Step 1: Project overview and context -Read: ANALYST-CONTEXT.md - -# Step 2: Current goal and success criteria -Read: 35-39-project-management/35.04-revised-goal-css-duplication-elimination.md - -# Step 3: Comprehensive duplication analysis -Read: 10-19-analysis/10.06-fl-builder-duplication-analysis.md -Read: 10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md -``` - ---- - -## 📋 CORE PROJECT DOCUMENTS (Priority Order) - -### 🎯 Goals & Planning (MUST READ FIRST) - -1. **CURRENT GOAL** (PRIMARY AUTHORITY) - - File: `35-39-project-management/35.04-revised-goal-css-duplication-elimination.md` - - Purpose: Complete goal statement, SMART criteria, 3-phase execution plan, work packages - - Status: ✅ Active - Ready for Phase 1 execution - - Key Metrics: 27,094-31,536 lines eliminated (70-80% reduction) - -2. **TASK TRACKER** (DAILY REFERENCE) - - File: `TASK-TRACKER.md` - - Purpose: Real-time work package status, current phase progress, blockers - - Update Frequency: After each work package completion - - Format: Phase → Work Package → Tasks → Status - -3. **ANALYST CONTEXT** (NAVIGATION HUB) - - File: `ANALYST-CONTEXT.md` - - Purpose: Must-review documents, project status, documentation structure - - Key Sections: Current Goal, Documentation Structure, Hugo Pipeline Status - -4. **GOAL AT A GLANCE** (QUICK REFERENCE) - - File: `GOAL-AT-A-GLANCE.md` - - Purpose: 1-page executive summary with key metrics and current status - - Use: Quick orientation, status checks, executive updates - -### 📊 Analysis & Findings (REFERENCE) - -5. **Top 5 Duplication Patterns** - - File: `10-19-analysis/10.06-fl-builder-duplication-analysis.md` - - Coverage: Patterns #1-#5 (~2,184-3,368 lines) - - Priorities: All P0 Critical 🔥 - - Key Patterns: FL-Builder Responsive Display, FL-row, FL-col, @imports, Screen Reader - -6. **Patterns #6-#15 Analysis** - - File: `10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md` - - Coverage: Patterns #6-#15 (~5,655 lines) - - Priorities: Mixed P0/P1/P2 - - Key Patterns: Media queries, Typography, Grid/Flexbox, FL-modules, Transitions, Animations - -7. **Critical Findings** - - File: `10-19-analysis/10.01-critical-findings.md` - - Purpose: Known blockers, critical issues, dependencies - - Review: Before starting any work package - -8. **Hugo Pipeline Strategy** - - File: `30-39-documentation/30.05-hugo-pipeline-enhancement-strategy.md` - - Purpose: Hugo integration, PurgeCSS roadmap, critical CSS automation - - Phase: Phase 3 (Optional enhancements) - ---- - -## 📂 DOCUMENTATION STRUCTURE (Johnny Decimal) - -### 10-19: Analysis & Research -``` -10-19-analysis/ -├── 10.01-critical-findings.md # Known blockers and issues -├── 10.02-optimization-recommendations.md # Performance optimization guidance -├── 10.03-performance-baseline.md # Baseline metrics -├── 10.04-duplication-analysis.md # Original duplication analysis -├── 10.06-fl-builder-duplication-analysis.md # TOP 5 PATTERNS (MUST READ) -└── 10.09-css-duplication-patterns-6-15-analysis.md # PATTERNS #6-#15 (MUST READ) -``` - -### 20-29: Components (Reserved) -``` -20-29-components/ -└── [Component-specific migration data - future use] -``` - -### 30-39: Documentation & Strategy -``` -30-39-documentation/ -├── 30.05-hugo-pipeline-enhancement-strategy.md # Hugo integration strategy -└── 30.06-documentation-update-summary-2025-10-12.md # Update log -``` - -### 35-39: Project Management -``` -35-39-project-management/ -└── 35.04-revised-goal-css-duplication-elimination.md # CURRENT GOAL (PRIMARY) -``` - -### 50-59: Testing & Validation -``` -50-59-testing/ -├── 50.01-testing-protocol.md # Testing standards -└── 50.03-visual-checkpoints/ - └── VISUAL_TESTING_PROTOCOL.md # Visual regression protocol -``` - -### 70-79: Archives -``` -70-79-archives/ -├── HISTORICAL-SPRINT-DATA.md # Legacy sprint data -└── legacy-css-migration-data/ # Historical analysis -``` - -### _runtime: Temporary Working Files -``` -_runtime/ -├── DUPLICATION-ELIMINATION-PLAN-2025-10-12.md # Working plan docs -├── CSS-LOADING-ANALYSIS-2025-10-12.md # CSS loading analysis -└── XP-TEAM-DEPLOYMENT-2025-10-12.md # XP team coordination -``` - ---- - -## 🎯 WORK PACKAGE QUICK REFERENCE - -### Phase 1: Critical CSS Inline Consolidation (20-30 hours) -| WP | Pattern | Files | Lines | Priority | Status | -|----|---------|-------|-------|----------|--------| -| WP1.1 | CSS Variables Foundation | 12 | ~50 | P0 🔥 | 🔲 Not Started | -| WP1.2 | Reset Utilities | 12 | ~129 | P0 🔥 | 🔲 Not Started | -| WP1.3 | PowerPack Infobox | 1 | ~30 | P1 ⚠️ | 🔲 Not Started | -| WP1.4 | Media Query Consolidation | 12 | ~100-120 | P1 ⚠️ | 🔲 Not Started | - -**Phase 1 Target**: 300-400 lines eliminated - -### Phase 2: FL-Builder Foundation Extraction (40-50 hours) -| WP | Pattern | Files | Lines | Priority | Status | -|----|---------|-------|----------|----------|--------| -| WP2.1 | FL-Row Foundation | 7 | 800-1,200 | P0 🔥 | 🔲 Not Started | -| WP2.2 | FL-Col Grid | 7 | 600-900 | P0 🔥 | 🔲 Not Started | -| WP2.3 | FL-Visible Responsive | 7 | 500-800 | P0 🔥 | 🔲 Not Started | -| WP2.4 | Foundation Integration | All | - | - | 🔲 Not Started | - -**Phase 2 Target**: 1,900-2,900 lines eliminated - -### Phase 3: Additional Patterns + Hugo (20-45 hours) -| WP | Pattern | Files | Lines | Priority | Status | -|----|---------|-------|-------|----------|--------| -| WP3.1 | Background Patterns | 7 | 400-600 | P2 📋 | 🔲 Not Started | -| WP3.2 | @import Deduplication | 7 | 84-168 | P2 📋 | 🔲 Not Started | -| WP3.3 | Hugo Pipeline (OPTIONAL) | Config | - | - | 🔲 Not Started | -| WP3.4 | PostCSS Final Validation | All | - | - | 🔲 Not Started | - -**Phase 3 Target**: 484-768 lines + Hugo enhancements - ---- - -## 📊 PROJECT METRICS DASHBOARD - -### Current State (Baseline) -```yaml -css_files: - total_lines: 44,420 - duplication: 70-80% (31,094-35,536 lines) - foundation_files: 0 - -inline_critical_css: - total_lines: 1,357 - duplication: 35-40% (450-550 lines) - page_templates: 12 - -top_15_patterns_identified: - total_duplication: 7,839-9,023 lines (17.6-20.3% of total) - potential_reduction: 6,663-8,572 lines (85-95% consolidation) - foundation_files_needed: 7 -``` - -### Target State (Goal Complete) -```yaml -css_files: - total_lines: 11,884-17,326 - reduction: 27,094-31,536 lines (70-80%) - foundation_files: 5-7 - -inline_critical_css: - total_lines: 950-1,050 - reduction: 300-400 lines (30-40%) - -quality_maintained: - test_pass_rate: 100% - visual_regressions: 0 - lighthouse_score: 95+ -``` - ---- - -## 🔍 AGENT SEARCH STRATEGIES - -### Finding Duplication Patterns -```bash -# Semantic search for specific patterns -claude-context search "FL-row foundation pattern CSS" \ - --path "/Users/pftg/dev/jetthoughts.github.io/themes/beaver/assets/css" - -# Search project documentation -claude-context search "media query breakpoints duplication" \ - --path "/Users/pftg/dev/jetthoughts.github.io/docs/projects/2509-css-migration" -``` - -### Finding Work Package Details -```bash -# Direct file reads for work package specs -Read: 35-39-project-management/35.04-revised-goal-css-duplication-elimination.md -# Search for: "WP1.1", "WP2.1", etc. - -# Pattern-specific implementation guidance -Read: 10-19-analysis/10.06-fl-builder-duplication-analysis.md -Read: 10-19-analysis/10.09-css-duplication-patterns-6-15-analysis.md -``` - -### Finding Test Protocols -```bash -# Testing standards -Read: 50-59-testing/50.01-testing-protocol.md - -# Visual regression protocols -Read: 50-59-testing/50.03-visual-checkpoints/VISUAL_TESTING_PROTOCOL.md -``` - ---- - -## 🚨 CRITICAL CONSTRAINTS - -### Zero-Tolerance Policies -- ✅ **100% test pass rate** - ALL tests must pass after every change -- ✅ **Zero visual regressions** - ≤3% screenshot tolerance (0% for refactoring) -- ✅ **Micro-commits** - ≤3 lines per commit, commit on green tests -- ✅ **Solo autonomous execution** - NO swarm spawning for mechanical work -- ✅ **Test-after-each-change** - Run `bin/rake test:critical` after every file change - -### Out of Scope (Deferred) -- ❌ FL-node HTML migration (572 HTML refs + 8,449 CSS rules) -- ❌ BEM class system replacement -- ❌ Complete CSS architecture redesign -- ❌ Visual design changes - -### Hugo Pipeline Status -- ✅ **Already Optimal**: resources.Concat, PostCSS, fingerprinting, minification -- 🎯 **Our Goal**: SOURCE CSS duplication elimination (NOT pipeline changes) -- 📋 **Phase 3 Optional**: PurgeCSS, automated critical CSS (can be separate initiative) - ---- - -## 🛠️ VALIDATION COMMANDS - -### After Each Change -```bash -# Run critical test suite (MANDATORY) -bin/rake test:critical - -# If GREEN → commit and continue -# If RED → rollback immediately, investigate, fix -``` - -### After Each Work Package -```bash -# Full validation protocol -bin/rake test:critical # All tests -bin/rake test:visual # Visual regression -lighthouse http://localhost:1313 # Performance metrics -``` - -### CSS Analysis -```bash -# Check duplication levels -grep -r "FL-row" themes/beaver/assets/css/fl-*.css | wc -l - -# Validate PostCSS compilation -hugo --gc --minify -``` - ---- - -## 📚 CROSS-REFERENCES - -### Global Knowledge Base -- **TDD Methodology**: `/knowledge/20.01-tdd-methodology-reference.md` -- **Shameless Green**: `/knowledge/20.05-shameless-green-flocking-rules-methodology.md` -- **File Management**: `/knowledge/50.01-global-file-management.md` -- **Four-Eyes Principle**: `/knowledge/20.02-four-eyes-principle-global.md` - -### Related Projects -- **elital_search**: `/projects/elital_search/docs/` (AI search patterns) -- **snap_diff-capybara**: `/projects/snap_diff-capybara/docs/` (Visual testing tools) - -### External References -- **Hugo Pipes**: https://gohugo.io/hugo-pipes/introduction/ -- **PostCSS**: https://gohugo.io/hugo-pipes/postcss/ -- **PurgeCSS**: https://purgecss.com/plugins/postcss.html - ---- - -## 🔄 UPDATE PROTOCOL - -### When to Update This Index - -**After each phase completion**: -1. Update work package status in TASK-TRACKER.md -2. Update metrics in GOAL-AT-A-GLANCE.md -3. Update phase status in this index -4. Update "Last Updated" date at top - -**After discovering new patterns**: -1. Add pattern to analysis documents -2. Update duplication metrics -3. Update work package estimates - -**After critical findings**: -1. Update 10-19-analysis/10.01-critical-findings.md -2. Update blockers section in TASK-TRACKER.md -3. Update risk assessment in goal document +**Last Updated**: 2026-07-12 +**Project Status**: Phase 0 (safety scaffolding) of the maintainability plan +**Current Goal**: Every style hand-editable, understood, single-source — FL export CSS retired page-by-page (16 files → 0) --- -## 📞 AGENT COORDINATION - -### For Solo Execution (Recommended) -```yaml -approach: "Autonomous continuous execution" -validation: "bin/rake test:critical after each change" -commit_strategy: "Micro-commits on green tests (≤3 lines)" -approval_gates: "NONE (continuous work to goal completion)" -stop_conditions: "Critical test failures ONLY" -``` - -### For Complex Work (Multi-Agent) -```yaml -trigger: "Complex TDD cycles, >3 component changes, new architecture" -pattern: "XP team with TDD specialists" -coordination: "Via MCP memory tools, NOT custom scripts" -four_eyes: "Required for architectural changes" -``` - -### Memory Coordination Namespaces -```yaml -phase_tracking: "css-migration/phase-{N}-complete" -work_packages: "css-migration/wp-{N}.{M}-status" -pattern_extraction: "css-migration/patterns/{pattern-id}" -validation_results: "css-migration/validation/{timestamp}" -``` - ---- - -## ✅ QUICK START CHECKLIST - -### For New Agents Joining Project -- [ ] Read this PROJECT-INDEX.md (you are here) -- [ ] Read ANALYST-CONTEXT.md (project overview) -- [ ] Read 35.04-revised-goal-css-duplication-elimination.md (current goal) -- [ ] Read TASK-TRACKER.md (current status) -- [ ] Read Top 15 pattern analysis (10.06 + 10.09) -- [ ] Verify test suite works: `bin/rake test:critical` -- [ ] Understand Hugo pipeline status (already optimal) -- [ ] Review out-of-scope items (FL-node HTML deferred) - -### For Executing Phase 1 -- [ ] All checklist items above ✓ -- [ ] Create feature branch: `feat/css-duplication-elimination` -- [ ] Start with WP1.1 (CSS Variables Foundation) -- [ ] Follow micro-commit discipline (≤3 lines per commit) -- [ ] Test after each file change -- [ ] Update TASK-TRACKER.md after each WP completion - ---- - -**Navigation Tip**: Use `claude-context search "[topic]"` to find specific information across project documentation. - -**Status Legend**: -- 🔲 Not Started -- 🔄 In Progress -- ✅ Completed -- ⚠️ Blocked -- 🔥 Critical Priority -- 📋 Medium Priority - -**Last Updated**: 2025-01-27 -**Project Owner**: CSS Migration Project Team -**Contact**: See ANALYST-CONTEXT.md for coordination details +## 🚀 START HERE + +1. **[2026-07-12-css-maintainability-redesign.md](2026-07-12-css-maintainability-redesign.md)** — PRIMARY AUTHORITY. + The approved plan: goal, success criteria, Phase 0, the per-page rewrite + protocol, rewrite order, and the evidence rule (validate on compiled+gzip + per-page payload, never raw source line counts). +2. **[TASK-TRACKER.md](TASK-TRACKER.md)** — live status: Phase 0 items, FL + burn-down, sprint update log (the full history of how the old plan was + falsified lives here). +3. **[css-bundle-ownership-map.md](css-bundle-ownership-map.md)** — "which pages + does this CSS file affect?": 19 bundles × owning template × FL files × gzip, + plus the 16-file FL burn-down table. Update it whenever a resource slice changes. +4. **[css-loading-order-analysis.md](css-loading-order-analysis.md)** — how each + template assembles its bundle and why load order matters. Read the supersede + banner first: its FL-preservation rules predate the strangler plan. + +## 🧭 The plan in one paragraph + +The original Oct-2025 goal ("eliminate 70-80% CSS duplication, 27,094-31,536 +lines" via shared-foundation extraction) was falsified on compiled+gzip +evidence: PurgeCSS runs per bundle, so every page already ships only its own +FL subset, and extraction grows shipped bytes. The replacement plan strangles +the generated FL-Builder CSS instead: Phase 0 adds missing snapdiff coverage +(special-content blog posts: Mermaid, code highlighting, inline styles, +youtube embeds) and an orphan-file guard; then one page per sprint gets a full +rewrite — semantic HTML + one small token-based file under `css/pages/` — with +its FL file deleted in the same PR, every other page proven 0.0-diff on both +suites (`bin/test` + `bin/dtest`), and design improvements per JetVelocity +(`.stitch/design.md`) approved via screenshots. + +## 📂 Structure + +``` +2509-css-migration/ +├── 2026-07-12-css-maintainability-redesign.md # approved spec (authority) +├── TASK-TRACKER.md # live status + sprint log +├── css-bundle-ownership-map.md # bundle map + FL burn-down +├── css-loading-order-analysis.md # load-order reference (banner'd) +├── PROJECT-INDEX.md # this file +└── 70-79-archives/ + ├── superseded-2026-07-12/ # the falsified Oct-2025 plan (36 docs + README why) + ├── 70.01…70.03, HISTORICAL-SPRINT-DATA.md # earlier archives + └── legacy-css-migration-data/ # 2025-09 raw metrics +``` + +## 🚨 Standing constraints + +- Gates on every commit: `bin/test` (macOS) AND `bin/dtest` (Linux); baselines + change only intentionally (`FORCE_SCREENSHOT_UPDATE=true`, both platforms in + the same commit). No new custom baseline/compare scripts — missing coverage + is fixed by adding tests. +- One feature branch + ONE bundled PR per sprint; rollback = revert one PR. +- Evidence rule: any size/perf claim is measured on compiled+gzip per-page + payload. Known build noise: `sw.js?v=` cachebuster, taxonomy term-casing races. +- Production-only pipeline traps (dedup/purge) are documented in the update log + and in `~/.claude` project memory — dev-server checks cannot catch them. diff --git a/docs/projects/2509-css-migration/css-loading-order-analysis.md b/docs/projects/2509-css-migration/css-loading-order-analysis.md index 06d564696..3c0898fff 100644 --- a/docs/projects/2509-css-migration/css-loading-order-analysis.md +++ b/docs/projects/2509-css-migration/css-loading-order-analysis.md @@ -1,5 +1,15 @@ # Hugo CSS Loading Order Architecture Analysis +> **⚠️ PARTIALLY SUPERSEDED 2026-07-12.** This doc's load-order mechanics +> (baseof inline bundles → per-page bundle, concat order inside a bundle) are +> still accurate and useful. Its STRATEGY framing is not: "extraction sequence", +> layer preservation rules, and any "NEVER extract/consolidate FL layouts as a +> transfer-size win" reasoning belong to the falsified Oct-2025 plan. The +> current plan RETIRES FL CSS page-by-page instead — see +> `2026-07-12-css-maintainability-redesign.md` (authority) and +> `css-bundle-ownership-map.md` (current bundle↔template↔file map with sizes). +> Bundle names/hashes below are 2025-10-14 snapshots; trust the ownership map. + **Project**: CSS Migration Project (2509) **Date**: 2025-10-14 **Purpose**: Comprehensive CSS inclusion order mapping to guide component extraction strategy From 91dbf7a89b651b6975ba8617275ad66112c9464b Mon Sep 17 00:00:00 2001 From: Paul Keen Date: Sun, 12 Jul 2026 20:22:12 +0200 Subject: [PATCH 5/5] docs(css): drop stale refs to reorganized 2509 folders (.gitignore entry, dead sprint-3 link) Co-Authored-By: Claude Fable 5 --- .gitignore | 1 - docs/60.06-test-format-requirements-reference.md | 1 - 2 files changed, 2 deletions(-) diff --git a/.gitignore b/.gitignore index 8fe973de8..4f4f4584b 100644 --- a/.gitignore +++ b/.gitignore @@ -103,7 +103,6 @@ scripts/lighthouse/reports/ _dest/ _temp/ _tmp/ -docs/projects/2509-css-migration/50-59-execution/ *.local.* .cache diff --git a/docs/60.06-test-format-requirements-reference.md b/docs/60.06-test-format-requirements-reference.md index e5214e0a6..ea6a44bda 100644 --- a/docs/60.06-test-format-requirements-reference.md +++ b/docs/60.06-test-format-requirements-reference.md @@ -631,7 +631,6 @@ Tests automatically run via CI/CD pipeline on: ### Project-Specific Documentation - `docs/60.03-tdd-quality-enforcement.md` - jt_site TDD practices - `docs/visual_testing_delegation_workflows.md` - Visual testing workflows -- `docs/projects/2509-css-migration/50-59-testing/SPRINT-3-TDD-TESTING-STRATEGY.md` - Sprint 3 TDD strategy ### External Documentation - **Minitest**: https://docs.seattlerb.org/minitest/