Add implementation roadmap and milestone workplans

2026-07-02 20:40:08 +02:00
parent d11e7a0742
commit 75c94bbfe5
9 changed files with 616 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ pricing to payment-provider execution.
 |-----|---------|
 | [INTENT.md](INTENT.md) | Project purpose, problem space, lifecycle model |
 | [docs/ProductRequirementsDocument.md](docs/ProductRequirementsDocument.md) | Generic product requirements |
+| [docs/ImplementationRoadmap.md](docs/ImplementationRoadmap.md) | Milestone-based implementation path from observatory MVP to adaptive engine |
 | [AGENTS.md](AGENTS.md) | Agent instructions, dev workflow, State Hub integration |
 | [workplans/](workplans/) | Active workstreams and tasks |
 | [projects/coulomb-pricing/](projects/coulomb-pricing/) | Coulomb Social MVP deployment material |
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -37,6 +37,7 @@ adapting, and implementing pricing models across the product lifecycle. See

 - Start with: `INTENT.md`
 - Product requirements (generic): `docs/ProductRequirementsDocument.md`
+- Implementation roadmap: `docs/ImplementationRoadmap.md`
 - Agent instructions: `AGENTS.md`
 - Workplans: `workplans/`
 - Coulomb MVP artifacts: `projects/coulomb-pricing/`
--- a/docs/ImplementationRoadmap.md
+++ b/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.
--- a/workplans/ADAPTIVE-WP-0003-canonical-pricing-core-and-schema.md
+++ b/workplans/ADAPTIVE-WP-0003-canonical-pricing-core-and-schema.md
@@ -0,0 +1,86 @@
+---
+id: ADAPTIVE-WP-0003
+type: workplan
+title: "Canonical pricing core and schema extraction"
+domain: financials
+repo: adaptive-pricing
+status: ready
+owner: codex
+topic_slug: helix-forge
+created: "2026-07-02"
+updated: "2026-07-02"
+state_hub_workstream_id: "7a4a23fc-c424-471b-9abb-b48b101799d5"
+---
+
+# Canonical pricing core and schema extraction
+
+Extract a reusable adaptive-pricing core from the Coulomb observatory MVP and
+define the canonical pricing-model schema needed by the later milestones.
+
+## Define Canonical Pricing Schema
+
+```task
+id: ADAPTIVE-WP-0003-T01
+status: todo
+priority: high
+state_hub_task_id: "c79647e3-f760-4a2f-ae45-a3532692a3d3"
+```
+
+Define the repository's canonical pricing-model schema and parameter taxonomy.
+Cover charge components, commitments, tunable parameters, calculated fields,
+eligibility, lifecycle metadata, and provider-mapping hooks.
+
+## Extract Generic Pricing Core
+
+```task
+id: ADAPTIVE-WP-0003-T02
+status: todo
+priority: high
+state_hub_task_id: "2d27616b-ea0c-4600-b7a2-eb5a22932b58"
+```
+
+Refactor the current Coulomb-specific observatory modules so generic pricing
+logic can live outside project-specific deployment code. Preserve Coulomb as the
+first adopter of the extracted core rather than leaving the core trapped inside
+`projects/coulomb-pricing/observatory/`.
+
+## Implement Schema Loader And Validator
+
+```task
+id: ADAPTIVE-WP-0003-T03
+status: todo
+priority: high
+state_hub_task_id: "6fa1ee8f-27ae-45b3-bd98-ea2a4873c0c8"
+```
+
+Implement loading and validation for the canonical schema, including structural
+checks, required-field rules, and scenario tests for flat, hybrid, and
+commitment-backed models.
+
+## Migrate Coulomb Pricing Registries
+
+```task
+id: ADAPTIVE-WP-0003-T04
+status: todo
+priority: medium
+state_hub_task_id: "fed8cb44-4219-4b7f-b641-90d872ebc285"
+```
+
+Migrate `projects/coulomb-pricing/data/pricing-models.json` and related loading
+paths so the Coulomb observatory uses the canonical schema without losing
+existing dashboard behavior.
+
+## Exit Criteria
+
+```task
+id: ADAPTIVE-WP-0003-T05
+status: todo
+priority: medium
+state_hub_task_id: "77305962-6f56-44aa-a8e4-32cfc5de262b"
+```
+
+Exit when the repo has a documented canonical schema, a validator with tests,
+and a working Coulomb observatory instance backed by the new internal model.
+
+Dependencies: `ADAPTIVE-WP-0002` completed baseline.
+
--- a/workplans/ADAPTIVE-WP-0004-boundary-engine-and-explainable-validation.md
+++ b/workplans/ADAPTIVE-WP-0004-boundary-engine-and-explainable-validation.md
@@ -0,0 +1,84 @@
+---
+id: ADAPTIVE-WP-0004
+type: workplan
+title: "Boundary engine and explainable validation"
+domain: financials
+repo: adaptive-pricing
+status: backlog
+owner: codex
+topic_slug: helix-forge
+created: "2026-07-02"
+updated: "2026-07-02"
+state_hub_workstream_id: "3ab759a2-97b6-4cf0-8c14-80dae637c23a"
+---
+
+# Boundary engine and explainable validation
+
+Turn strategic pricing constraints from `INTENT.md` into an explicit validation
+engine with inspectable outcomes.
+
+## Formalize Constraint Model
+
+```task
+id: ADAPTIVE-WP-0004-T01
+status: todo
+priority: high
+state_hub_task_id: "180ea896-4e89-4256-b1ba-0d72e4d49dcd"
+```
+
+Define the internal representation for hard and soft constraints, including
+minimum margin, cost floor, payment fees, commitment requirements, segment
+eligibility, and approval thresholds.
+
+## Implement Validation Engine
+
+```task
+id: ADAPTIVE-WP-0004-T02
+status: todo
+priority: high
+state_hub_task_id: "16c96dc5-45fc-4cca-9f71-d3b8d797f28f"
+```
+
+Implement evaluation logic that accepts a pricing configuration and returns
+pass/fail results, violated constraints, and structured reasons.
+
+## Model Commitment-Backed Discounts
+
+```task
+id: ADAPTIVE-WP-0004-T03
+status: todo
+priority: high
+state_hub_task_id: "adaa7751-b1b9-4d9e-a708-4caaf6a4801d"
+```
+
+Encode rules for discounts, concessions, and improved unit economics so they
+require enforceable or economically meaningful commitments instead of optimistic
+usage assumptions.
+
+## Add Scenario And Abuse Tests
+
+```task
+id: ADAPTIVE-WP-0004-T04
+status: todo
+priority: medium
+state_hub_task_id: "96a1f2d4-518f-4e4f-8227-43bac08ff615"
+```
+
+Add scenario tests that cover valid configurations, invalid discounting,
+rejected commitment trades, and edge cases such as zero-usage, high-fee, or
+unprofitable configurations.
+
+## Exit Criteria
+
+```task
+id: ADAPTIVE-WP-0004-T05
+status: todo
+priority: medium
+state_hub_task_id: "0a771125-cc2b-4339-b210-ac834562516f"
+```
+
+Exit when pricing configurations can be validated against explicit constraints
+with machine-readable and human-readable explanations.
+
+Dependencies: `ADAPTIVE-WP-0003`.
+
--- a/workplans/ADAPTIVE-WP-0005-comparable-customer-ltv-and-simulation-upgrade.md
+++ b/workplans/ADAPTIVE-WP-0005-comparable-customer-ltv-and-simulation-upgrade.md
@@ -0,0 +1,86 @@
+---
+id: ADAPTIVE-WP-0005
+type: workplan
+title: "Comparable customer LTV and simulation upgrade"
+domain: financials
+repo: adaptive-pricing
+status: backlog
+owner: codex
+topic_slug: helix-forge
+created: "2026-07-02"
+updated: "2026-07-02"
+state_hub_workstream_id: "7fb6c58e-fabb-4e52-87d1-4a02984191ea"
+---
+
+# Comparable customer LTV and simulation upgrade
+
+Upgrade the current observatory economics layer so pricing models can be
+compared using segment-aware, risk-aware seller economics rather than only the
+current-period Coulomb snapshot.
+
+## Define Comparable-Customer LTV Model
+
+```task
+id: ADAPTIVE-WP-0005-T01
+status: todo
+priority: high
+state_hub_task_id: "2c6ff5b9-de47-46c1-aaa8-5e6e226f96d0"
+```
+
+Specify `average_comparable_customer_lifetime_value`, the reference-model
+selection logic, required-improvement semantics, and the data assumptions
+required for reliable estimates.
+
+## Extend Simulation Inputs
+
+```task
+id: ADAPTIVE-WP-0005-T02
+status: todo
+priority: high
+state_hub_task_id: "fbf4e274-70ec-468f-988c-cbebeef304d2"
+```
+
+Extend the simulator beyond fixed member counts and hard-coded token assumptions
+to use segments, usage forecasts, churn/default risk, contract conditions, and
+commitment offsets.
+
+## Rework Pricing Comparison Outputs
+
+```task
+id: ADAPTIVE-WP-0005-T03
+status: todo
+priority: medium
+state_hub_task_id: "084bf0bb-5892-429e-bd8a-1f9edc273eb3"
+```
+
+Produce comparison outputs that can explain why one model is better for seller
+economics, what assumptions drive the outcome, and how sensitive the outcome is
+to forecast changes.
+
+## Calibrate With Coulomb Pilot Data
+
+```task
+id: ADAPTIVE-WP-0005-T04
+status: todo
+priority: medium
+state_hub_task_id: "9c60c8d2-7cd0-4035-92dc-cae8c4cd85d7"
+```
+
+Use the Coulomb observatory data and scenario fixtures to calibrate the first
+version of the comparison engine, while preserving its generic interface for
+other products.
+
+## Exit Criteria
+
+```task
+id: ADAPTIVE-WP-0005-T05
+status: todo
+priority: medium
+state_hub_task_id: "fabd1f1b-d3b7-4bfb-a2fc-212ec31c5f31"
+```
+
+Exit when simulations can compare pricing models using an explicit LTV-oriented
+economic model with documented assumptions and test coverage.
+
+Dependencies: `ADAPTIVE-WP-0003`, `ADAPTIVE-WP-0004`.
+
--- a/workplans/ADAPTIVE-WP-0006-customer-tuning-solver-prototype.md
+++ b/workplans/ADAPTIVE-WP-0006-customer-tuning-solver-prototype.md
@@ -0,0 +1,82 @@
+---
+id: ADAPTIVE-WP-0006
+type: workplan
+title: "Customer-tuning solver prototype"
+domain: financials
+repo: adaptive-pricing
+status: backlog
+owner: codex
+topic_slug: helix-forge
+created: "2026-07-02"
+updated: "2026-07-02"
+state_hub_workstream_id: "4083f345-1bd3-462f-aa70-50f299729d7c"
+---
+
+# Customer-tuning solver prototype
+
+Implement the first seller-safe customer-tuning flow described in `INTENT.md`.
+
+## Define Tuning Interface
+
+```task
+id: ADAPTIVE-WP-0006-T01
+status: todo
+priority: high
+state_hub_task_id: "ad2df753-ae93-4813-bd35-fb8ee78149cc"
+```
+
+Define which pricing parameters may be customer-tunable, how preferences are
+expressed, and which parts remain seller-controlled or calculated.
+
+## Implement Solver Core
+
+```task
+id: ADAPTIVE-WP-0006-T02
+status: todo
+priority: high
+state_hub_task_id: "9146f1dc-2e86-4617-8e3e-0b5e4799daa3"
+```
+
+Implement a solver that accepts selected tunable inputs and computes a valid
+configuration or rejection based on constraints and comparable-customer LTV
+requirements.
+
+## Explain Solver Outcomes
+
+```task
+id: ADAPTIVE-WP-0006-T03
+status: todo
+priority: high
+state_hub_task_id: "57d6066d-088b-413c-817b-9e374f60f83a"
+```
+
+Return structured explanations for accepted and rejected tuned configurations,
+including which constraints bound the result and which trade-offs were chosen.
+
+## Pilot Against Coulomb Hybrid Models
+
+```task
+id: ADAPTIVE-WP-0006-T04
+status: todo
+priority: medium
+state_hub_task_id: "86423454-71e4-4f8e-afe0-61ceb70314c2"
+```
+
+Use the Coulomb candidate hybrid models as the first pilot surface for solver
+behavior, without exposing customer-visible billing changes before validation is
+trusted.
+
+## Exit Criteria
+
+```task
+id: ADAPTIVE-WP-0006-T05
+status: todo
+priority: medium
+state_hub_task_id: "72f7d7b4-6ad2-4b63-b9de-acb7a7b81832"
+```
+
+Exit when the repo can produce and explain seller-safe tuned configurations for
+at least one hybrid pricing model family.
+
+Dependencies: `ADAPTIVE-WP-0004`, `ADAPTIVE-WP-0005`.
+
--- a/workplans/ADAPTIVE-WP-0007-provider-abstraction-and-stripe-publication.md
+++ b/workplans/ADAPTIVE-WP-0007-provider-abstraction-and-stripe-publication.md
@@ -0,0 +1,82 @@
+---
+id: ADAPTIVE-WP-0007
+type: workplan
+title: "Provider abstraction and Stripe publication"
+domain: financials
+repo: adaptive-pricing
+status: backlog
+owner: codex
+topic_slug: helix-forge
+created: "2026-07-02"
+updated: "2026-07-02"
+state_hub_workstream_id: "3e348457-0ef7-4b5c-b4c5-9668e03b63ac"
+---
+
+# Provider abstraction and Stripe publication
+
+Add the first outbound execution layer so internal pricing definitions can be
+published to Stripe without making Stripe the source of truth.
+
+## Define Provider-Neutral Artifact Model
+
+```task
+id: ADAPTIVE-WP-0007-T01
+status: todo
+priority: high
+state_hub_task_id: "b4eb157d-54a8-4518-b99c-16355c3e22cf"
+```
+
+Define the internal publishable artifacts for products, charge components,
+meters, recurring prices, discounts, commitments, and customer-specific
+configurations.
+
+## Implement Stripe Mapping
+
+```task
+id: ADAPTIVE-WP-0007-T02
+status: todo
+priority: high
+state_hub_task_id: "73fd1384-0b9e-48ea-851b-4045928e9c58"
+```
+
+Map the canonical internal primitives to Stripe Billing objects and document
+where the mapping is exact, approximate, or unsupported.
+
+## Add Publish / Update / Drift Logic
+
+```task
+id: ADAPTIVE-WP-0007-T03
+status: todo
+priority: high
+state_hub_task_id: "da137f4b-0b2a-49fb-adf2-7133cb908af0"
+```
+
+Implement idempotent publish, update, and drift-detection behavior so generated
+provider state remains auditable and synchronized with internal definitions.
+
+## Preserve Reconciliation And Rollback
+
+```task
+id: ADAPTIVE-WP-0007-T04
+status: todo
+priority: medium
+state_hub_task_id: "3e3e2fc3-f38f-4869-890a-94bffac97439"
+```
+
+Add metadata, logs, and rollback mechanics needed to reconcile internal pricing
+state with Stripe artifacts and to unwind failed publish attempts safely.
+
+## Exit Criteria
+
+```task
+id: ADAPTIVE-WP-0007-T05
+status: todo
+priority: medium
+state_hub_task_id: "1dd8f49a-87fb-43ea-9c65-b6aa909e4a56"
+```
+
+Exit when the repo can publish a validated pricing model to Stripe in a
+repeatable, explainable, and reversible way.
+
+Dependencies: `ADAPTIVE-WP-0003`, `ADAPTIVE-WP-0004`, `ADAPTIVE-WP-0005`.
+
--- a/workplans/ADAPTIVE-WP-0008-governance-and-recommendation-workflows.md
+++ b/workplans/ADAPTIVE-WP-0008-governance-and-recommendation-workflows.md
@@ -0,0 +1,81 @@
+---
+id: ADAPTIVE-WP-0008
+type: workplan
+title: "Governance and recommendation workflows"
+domain: financials
+repo: adaptive-pricing
+status: backlog
+owner: codex
+topic_slug: helix-forge
+created: "2026-07-02"
+updated: "2026-07-02"
+state_hub_workstream_id: "d83543cc-f93f-47cc-9650-f985463f6f43"
+---
+
+# Governance and recommendation workflows
+
+Operationalize adaptive pricing with approval policies, recommendation
+interfaces, experiment guardrails, and auditable lifecycle workflows.
+
+## Define Governance Policy Model
+
+```task
+id: ADAPTIVE-WP-0008-T01
+status: todo
+priority: high
+state_hub_task_id: "66f36062-b16b-426b-b216-e5263d532b2a"
+```
+
+Define publish, change, rollback, grandfathering, approval, and exposure-limit
+policies for adaptive pricing operations.
+
+## Implement Seller Recommendation Workflow
+
+```task
+id: ADAPTIVE-WP-0008-T02
+status: todo
+priority: high
+state_hub_task_id: "1b402c31-1afd-4b71-a8a9-23dadbaae6ac"
+```
+
+Evolve the current rules-based recommendation layer into a workflow that can
+cite assumptions, constraints, simulations, and approval requirements.
+
+## Define Customer-Facing Safe-Tuning Contract
+
+```task
+id: ADAPTIVE-WP-0008-T03
+status: todo
+priority: medium
+state_hub_task_id: "3f4a8e6e-4333-48d8-9af7-fae53fe85c7b"
+```
+
+Define the API and UX contract for customer-visible tuning so buyers can
+understand price trade-offs without exposing unsafe or opaque pricing behavior.
+
+## Add Experiment And Health-Check Surfaces
+
+```task
+id: ADAPTIVE-WP-0008-T04
+status: todo
+priority: medium
+state_hub_task_id: "e1fd3a11-eb6c-4747-ae32-7d18fa6c9446"
+```
+
+Add pricing health checks, experiment guardrails, version history, and audit
+surfaces needed for ongoing operations after solver and provider publication
+exist.
+
+## Exit Criteria
+
+```task
+id: ADAPTIVE-WP-0008-T05
+status: todo
+priority: medium
+state_hub_task_id: "75778f37-e77a-4a70-865a-52042729fe42"
+```
+
+Exit when adaptive pricing changes are explainable, policy-governed, auditable,
+and operable by both humans and agents.
+
+Dependencies: `ADAPTIVE-WP-0006`, `ADAPTIVE-WP-0007`.