From 75c94bbfe5c726e065301636fb69cbc10706dc0e Mon Sep 17 00:00:00 2001 From: codex Date: Thu, 2 Jul 2026 20:40:08 +0200 Subject: [PATCH] Add implementation roadmap and milestone workplans --- README.md | 1 + SCOPE.md | 1 + docs/ImplementationRoadmap.md | 113 ++++++++++++++++++ ...-0003-canonical-pricing-core-and-schema.md | 86 +++++++++++++ ...ndary-engine-and-explainable-validation.md | 84 +++++++++++++ ...ble-customer-ltv-and-simulation-upgrade.md | 86 +++++++++++++ ...P-0006-customer-tuning-solver-prototype.md | 82 +++++++++++++ ...ider-abstraction-and-stripe-publication.md | 82 +++++++++++++ ...governance-and-recommendation-workflows.md | 81 +++++++++++++ 9 files changed, 616 insertions(+) create mode 100644 docs/ImplementationRoadmap.md create mode 100644 workplans/ADAPTIVE-WP-0003-canonical-pricing-core-and-schema.md create mode 100644 workplans/ADAPTIVE-WP-0004-boundary-engine-and-explainable-validation.md create mode 100644 workplans/ADAPTIVE-WP-0005-comparable-customer-ltv-and-simulation-upgrade.md create mode 100644 workplans/ADAPTIVE-WP-0006-customer-tuning-solver-prototype.md create mode 100644 workplans/ADAPTIVE-WP-0007-provider-abstraction-and-stripe-publication.md create mode 100644 workplans/ADAPTIVE-WP-0008-governance-and-recommendation-workflows.md diff --git a/README.md b/README.md index e93dd84..ce99c49 100644 --- 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 | diff --git a/SCOPE.md b/SCOPE.md index ef1cae5..9da38a6 100644 --- 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/` diff --git a/docs/ImplementationRoadmap.md b/docs/ImplementationRoadmap.md new file mode 100644 index 0000000..0ddce79 --- /dev/null +++ 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. diff --git a/workplans/ADAPTIVE-WP-0003-canonical-pricing-core-and-schema.md b/workplans/ADAPTIVE-WP-0003-canonical-pricing-core-and-schema.md new file mode 100644 index 0000000..ba882cb --- /dev/null +++ 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. + diff --git a/workplans/ADAPTIVE-WP-0004-boundary-engine-and-explainable-validation.md b/workplans/ADAPTIVE-WP-0004-boundary-engine-and-explainable-validation.md new file mode 100644 index 0000000..e28a2af --- /dev/null +++ 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`. + diff --git a/workplans/ADAPTIVE-WP-0005-comparable-customer-ltv-and-simulation-upgrade.md b/workplans/ADAPTIVE-WP-0005-comparable-customer-ltv-and-simulation-upgrade.md new file mode 100644 index 0000000..112d357 --- /dev/null +++ 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`. + diff --git a/workplans/ADAPTIVE-WP-0006-customer-tuning-solver-prototype.md b/workplans/ADAPTIVE-WP-0006-customer-tuning-solver-prototype.md new file mode 100644 index 0000000..42b402e --- /dev/null +++ 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`. + diff --git a/workplans/ADAPTIVE-WP-0007-provider-abstraction-and-stripe-publication.md b/workplans/ADAPTIVE-WP-0007-provider-abstraction-and-stripe-publication.md new file mode 100644 index 0000000..5006c3c --- /dev/null +++ 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`. + diff --git a/workplans/ADAPTIVE-WP-0008-governance-and-recommendation-workflows.md b/workplans/ADAPTIVE-WP-0008-governance-and-recommendation-workflows.md new file mode 100644 index 0000000..d0715cd --- /dev/null +++ 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`.