# SCOPE

## One-liner

Auto-regulating market value exploring price engine.

## Core Idea

`adaptive-pricing` provides a practical framework for defining, evaluating,
adapting, and implementing pricing models across the product lifecycle. See
`INTENT.md` for the full problem space, lifecycle model, and strategic direction.

## In Scope

- Generic pricing core under `adaptive_pricing_core/`, including:
  canonical pricing schema and validation, boundary evaluation, comparable
  customer LTV, customer-tuning solver, provider-publication primitives, Stripe
  mapping, and governance models.
- Generic framework documentation and research (`INTENT.md`, `docs/`,
  `research/`, `registry/`).
- Project-specific proving grounds under `projects/<slug>/`, with Coulomb
  Social as the first full adopter of the generic core.
- Local execution surfaces that keep internal pricing definitions as the source
  of truth, including provider shadow publication, governed recommendations,
  tuning contracts, health checks, and audit history.
- State Hub workplans under `workplans/` (ADR-001).

## Out of Scope

- Owning unrelated adjacent systems as the source of truth, including Bubble,
  Stripe, and OpenRouter runtimes.
- Live payment-provider mutation as the default repo behavior. Current provider
  execution stops at mapping, shadow-state publication, drift detection, and
  rollback planning.
- Treating approximate provider mappings as fully enforced billing behavior when
  they still require supplemental operational or contract logic.
- Autonomous customer-visible pricing rollouts or irreversible pricing changes
  without human approval.
- Project-specific deployment material in generic doc paths (use
  `projects/<slug>/`).

## Current State

- **Phase:** framework plus executable core. The repo is no longer just docs and
  research around a single MVP; it now contains reusable pricing-core modules
  and one concrete deployment.
- **Implemented milestones:** `ADAPTIVE-WP-0003` through `ADAPTIVE-WP-0008`
  are finished. The repo now has canonical pricing models, explainable boundary
  validation, comparable-customer LTV simulation, customer-tuning, provider
  shadow publication, and governance workflows.
- **Generic runtime surface:** reusable implementation lives under
  `adaptive_pricing_core/`.
- **Deployment surface:** Coulomb Social remains the first proving ground under
  `projects/coulomb-pricing/observatory/`, including the dashboard/API, data
  loaders, tuning pilot, Stripe shadow-publication flow, and governed
  recommendation surfaces.
- **Execution boundary:** Stripe support is currently a provider abstraction and
  local shadow-state publisher, not live Stripe API management.
- **Coordination:** State Hub integration (`ADAPTIVE-WP-0001`) remains the repo
  workflow backbone for orientation, workplan tracking, and brief sync.

## Getting Oriented

- Start with: `INTENT.md`
- Product requirements (generic): `docs/ProductRequirementsDocument.md`
- Canonical pricing schema: `docs/PricingModelSchema.md`
- Customer tuning: `docs/CustomerTuningSolver.md`
- Provider publication: `docs/StripePublication.md`
- Governance workflow: `docs/GovernanceWorkflows.md`
- Implementation roadmap: `docs/ImplementationRoadmap.md`
- Agent instructions: `AGENTS.md`
- Workplans: `workplans/`
- Generic code: `adaptive_pricing_core/`
- Coulomb deployment artifacts: `projects/coulomb-pricing/`
- Offline hub brief: `.custodian-brief.md`