adaptive-pricing/SCOPE.md

# 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, governance models, and typed customer assurance claims backed by
  tenancy-posture minimums.
- 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.
- Treating a tier's assurance wording as authorization, placement state, or a
  substitute for current service/provider posture evidence. The tier records
  the commercial minimum; operational owners declare and enforce what exists.
- Plan-derived tenant guardrail ceilings until `ADAPTIVE-WP-0010` establishes a
  jointly accepted contract with `tenant-engine`. No ceiling schema or feed is
  implemented yet.
- 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-0009`
  are finished. The repo now has canonical pricing models, explainable boundary
  validation, comparable-customer LTV simulation, customer-tuning, provider
  shadow publication, governance workflows, and typed tier assurance claims.
- **Generic runtime surface:** reusable implementation lives under
  `adaptive_pricing_core/`. Assurance claims are optional and default empty;
  when present, the schema validates typed `{I,A,E,P,R,V}` minima, the boundary
  engine checks wording and coupled floors, and governance requires one-time
  approval when a tier definition adds, changes, or removes a claim.
- **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.
- **Current commercial posture:** all current Coulomb pricing models remain
  silent on isolation, availability, retention, and performance assurances.
  The claim machinery is a preparatory guardrail; it does not invent a live
  customer promise.
- **Tenancy posture:** root `tenancy.yaml` declares the observatory as a local,
  unauthenticated, single-user design-time tool (`I0/A0/E0`, `P/R: n/a`,
  `V0`). Exposing it as a shared service is a new scope decision requiring a
  fresh posture assessment before deployment.
- **Execution boundary:** Stripe support is currently a provider abstraction and
  local shadow-state publisher, not live Stripe API management.
- **Next proposed seam:** `ADAPTIVE-WP-0010` explores plan-derived tenant
  guardrail ceilings, but its interface and ownership contract with
  `tenant-engine` are not yet agreed and no implementation has started.
- **Coordination:** State Hub integration (`ADAPTIVE-WP-0001`) remains the repo
  workflow backbone for orientation, workplan tracking, generated
  `WORK-RECORDS.md`, 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`
- Tenancy posture declaration: `tenancy.yaml`
- 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`