Add implementation roadmap and milestone workplans

docs/ImplementationRoadmap.md

@@ -0,0 +1,113 @@
+# Adaptive Pricing Implementation Roadmap
+
+Status: draft, implementation-facing.
+
+## Purpose
+
+This roadmap translates the strategic goals in `INTENT.md` into an executable
+implementation sequence for the current repository state.
+
+The root research roadmap in `research/PricingResearchRoadmap.md` remains the
+conceptual and research-first planning artifact. This document starts from the
+current implementation reality: a Coulomb-specific economic observatory MVP
+under `projects/coulomb-pricing/observatory/`.
+
+## Current Baseline
+
+The repository already provides:
+
+- ledger-backed economics and liquidity tracking
+- cost-floor, value-range, and market-context views
+- file-based Stripe / Bubble / OpenRouter imports
+- scenario comparison for a small set of candidate pricing models
+- rules-based pricing recommendations
+- a local dashboard API and UI
+
+The repository does not yet provide:
+
+- a canonical, generic pricing-model schema
+- a validation engine for pricing constraints and commitments
+- comparable customer LTV estimation
+- a customer-tuning solver
+- outbound payment-provider execution
+- governance workflows for publishing and changing pricing
+
+## Sequencing Principles
+
+- Preserve the observatory MVP as a proving ground while extracting generic core logic.
+- Build schema and validation before solver or provider execution.
+- Keep the internal pricing model as the source of truth; execution adapters come later.
+- Require explainability at each stage: validation, simulation, tuning, and publish.
+- Convert repository planning into milestone workplans rather than one large umbrella plan.
+
+## Milestones
+
+| Milestone | Goal | Primary workplan | Dependencies | Exit signal |
+| --- | --- | --- | --- | --- |
+| M0 | Economic observatory baseline | `ADAPTIVE-WP-0002` | done | Coulomb ledger, dashboard, simulator, recommendations |
+| M1 | Extract canonical pricing core and schema | `ADAPTIVE-WP-0003` | M0 | Generic schema and validator adopted by Coulomb data |
+| M2 | Add boundary engine and explainable validation | `ADAPTIVE-WP-0004` | M1 | Pricing configurations are validated against explicit constraints |
+| M3 | Upgrade economics to comparable-customer LTV and richer simulation | `ADAPTIVE-WP-0005` | M1, M2 | Simulations compare models using segment/risk-aware economics |
+| M4 | Implement customer-tuning solver prototype | `ADAPTIVE-WP-0006` | M2, M3 | Tuned configurations can be proposed, evaluated, and explained |
+| M5 | Add provider abstraction and Stripe publication flow | `ADAPTIVE-WP-0007` | M1, M2, M3 | Internal pricing definitions can publish Stripe artifacts safely |
+| M6 | Add governance and recommendation workflows | `ADAPTIVE-WP-0008` | M4, M5 | Pricing changes become auditable, explainable, and operational |
+
+## Milestone Details
+
+### M1 — Canonical Pricing Core And Schema
+
+Create a reusable pricing core that can represent more than the current
+subscription-only observatory model. Expand beyond the current narrow
+`PricingModel` structure to include charge components, commitments, tunable
+parameters, eligibility, and provider-mapping metadata.
+
+### M2 — Boundary Engine And Explainable Validation
+
+Turn strategic boundary conditions into testable rules. A pricing configuration
+must be accepted or rejected by explicit logic, not only by dashboard review.
+This milestone defines hard and soft constraints, invalid-configuration reasons,
+and commitment-backed discount semantics.
+
+### M3 — Comparable Customer LTV And Richer Simulation
+
+Extend the current period snapshot and fixed-assumption simulator into an engine
+that can compare pricing configurations across customer segments, usage
+forecasts, risk classes, and contract conditions. This is the economics core
+needed by any seller-safe adaptive system.
+
+### M4 — Customer-Tuning Solver Prototype
+
+Expose a customer/seller configuration interface where selected parameters are
+tunable and the solver adjusts the rest while preserving seller economics. This
+milestone is the first actual realization of the adaptive-pricing thesis in
+`INTENT.md`.
+
+### M5 — Provider Abstraction And Stripe Publication
+
+Add an outbound execution layer that maps internal pricing definitions to Stripe
+artifacts. This is where the repo moves from observatory-only to operational
+pricing infrastructure.
+
+### M6 — Governance And Recommendation Workflows
+
+Operationalize the engine with approval policies, publish/change workflows,
+auditable recommendations, experiment guardrails, and customer-facing safe
+tuning contracts.
+
+## Workplan Set
+
+- `ADAPTIVE-WP-0003` — Canonical pricing core and schema extraction
+- `ADAPTIVE-WP-0004` — Boundary engine and explainable validation
+- `ADAPTIVE-WP-0005` — Comparable customer LTV and simulation upgrade
+- `ADAPTIVE-WP-0006` — Customer-tuning solver prototype
+- `ADAPTIVE-WP-0007` — Provider abstraction and Stripe publication
+- `ADAPTIVE-WP-0008` — Governance and recommendation workflows
+
+## Near-Term Recommendation
+
+Start with `ADAPTIVE-WP-0003`.
+
+The current implementation bottleneck is not UI or provider execution. It is
+the absence of a sufficiently expressive internal pricing model. Until that
+schema exists, later milestones would hard-code MVP assumptions into layers that
+should remain generic.