1

part2-dev/planning/04-roadmap.md

@@ -85,4 +85,100 @@ Mitigations described in `02-workflows.md` (UX guardrails) and `03-phase-reports
 - Detailed workflows: `02-workflows.md`
 - Historical reports: `03-phase-reports.md`
 
+---
 
+## 6. Stage Implementation Details
+
+### Stage 1 – Data & Services Foundation
+**Goal:** Ship all schema + backend building blocks so later stages can focus on UX.
+
+**Backend**
+- Migrations for `SiteBlueprintCluster`, `SiteBlueprintTaxonomy`, `WorkflowState`, writer mapping tables.
+- `WorkflowStateService` with REST endpoints for fetching/updating step status.
+- `TaxonomyService` (CRUD/import/export) and `ClusteringService` prompt upgrade for multi-dimensional clusters.
+- API validation hooks (`validate_clusters_attached`, `validate_taxonomies_ready`, etc.) consumed by wizard gating.
+- Serializer updates exposing entity metadata to frontend.
+
+**Frontend**
+- Minimal work (feature flags + API clients) to prepare for new endpoints; no user-facing change yet.
+
+**Testing/Acceptance**
+- Migration dry run, rollback verified.
+- Unit/integration tests for services and validators.
+- API documentation updated; Postman suite green.
+
+### Stage 2 – Planner + Wizard UX
+**Goal:** Deliver the guided, state-aware planning experience.
+
+**Backend**
+- Ensure planner endpoints return cluster metrics, taxonomy suggestions, validation errors.
+- Audit logging for workflow transitions.
+
+**Frontend**
+- Implement `builderWorkflowStore` (Zustand) with resume capability, blocking logic, telemetry.
+- Build wizard steps:
+  1. Business details + hosting detection.
+  2. Cluster assignment (coverage metrics, filters).
+  3. Taxonomy builder (create/import/match clusters).
+  4. AI sitemap review with checklist + edits.
+  5. Coverage validation summary.
+  6. Ideas hand-off with secondary prompt.
+- Update planner cluster/taxonomy management screens (matrix view, inline warnings).
+
+**UX Guardrails**
+- Progress indicator with completion badges.
+- Disabled buttons explain “what’s missing”.
+- CTAs back to Planner when prerequisites unmet.
+
+**Testing/Acceptance**
+- Manual script for full wizard flow (new IGNY8 site + WP-linked site).
+- Cypress/e2e coverage for gating + resume behavior.
+- Telemetry events for step completion firing.
+
+### Stage 3 – Writer / Linker / Optimizer Enhancements
+**Goal:** Propagate metadata end-to-end and enforce validation.
+
+**Backend**
+- Ensure ideas/tasks/content writer pipeline populates `entity_type`, `taxonomy_id`, `cluster_role`, `product_data`.
+- Linker/optimizer services consume mapping tables and expose coverage metrics via APIs.
+- Progress dashboard endpoints (per site/cluster) for frontend widgets.
+
+**Frontend**
+- Planner Ideas + Writer Tasks lists show entity/taxonomy chips and warnings.
+- Writer editor sidebar summarizing target cluster, taxonomy, attribute requirements; validation prompts before publish.
+- Linker UI grouped by cluster role; Optimizer dashboards show dimension scorecards and “next actions”.
+- Sites module progress bars summarizing blueprint completion.
+
+**Testing/Acceptance**
+- Regression on task/content creation flows.
+- QA verifies publish blocked when metadata missing.
+- Performance profiling on linker/optimizer queries with new joins.
+
+### Stage 4 – Publishing & Sync Integration
+**Goal:** Achieve parity between IGNY8-hosted and WordPress-hosted sites.
+
+**Backend**
+- Complete WordPress taxonomy/product attribute import/export in `ContentSyncService`.
+- Enhance `SitesRendererAdapter` to include cluster/taxonomy metadata for navigation + internal linking.
+- Sync health endpoints (last sync, mismatched taxonomies, errors) and deployment logs/rollback hooks.
+
+**Frontend**
+- Sync dashboard showing taxonomy parity, cluster coverage, last sync status, manual retry/reconcile actions.
+- Deployment panel summarizing readiness (clusters covered, content publish state) before enabling deploy.
+- Notifications/toasts for sync success/failure and deployments.
+
+**Testing/Acceptance**
+- End-to-end tests: IGNY8 deployment, WP publish for posts/products/services (blog/ecom/company templates).
+- Fallback behavior validated (auto-creating missing taxonomies).
+- Final QA checklist signed off; release notes + training updates distributed.
+
+---
+
+## 7. Stage Exit Criteria
+
+| Stage | Exit Criteria |
+| --- | --- |
+| 1 | Migrations live, services stable, existing Planner/Writer flows unaffected, docs updated. |
+| 2 | Wizard fully usable with telemetry + QA sign-off; planner UIs reflect new taxonomy data. |
+| 3 | Writer/linker/optimizer using metadata, publishing blocked without required info, dashboards live. |
+| 4 | WordPress parity achieved, deployments verified, sync dashboards green, release announced. |