# Governance Workflows

Status: MVP for `ADAPTIVE-WP-0008` and `ADAPTIVE-WP-0009`.

## Purpose

This milestone turns pricing outputs into governed workflows instead of
standalone metrics.

The repository now exposes:

- a governance policy model
- governed seller recommendations
- a customer-facing safe-tuning contract surface
- pricing health checks
- provider-publication audit and revision surfaces
- one-time approval for new or changed tier assurance definitions

## Core And Adapter Layers

Generic core:

- `adaptive_pricing_core/governance.py`

Coulomb adapter:

- `projects/coulomb-pricing/observatory/governance.py`
- `projects/coulomb-pricing/data/governance_policy.json`

## Governance Policy

The policy model covers:

- approval thresholds
- customer-visible price-change rules
- experiment capacity
- candidate rollout limits
- provider execution limits
- customer communication ownership
- grandfathering and notice expectations
- customer-visible tuning enablement

For Coulomb, the current policy keeps customer-visible tuning disabled and
requires approval for candidate rollouts and approximate Stripe mappings.

## Tier Assurance Definition Gate

`assess_tier_definition_assurance()` compares a proposed pricing model with
its previously approved definition. Adding, changing, or removing an
`assurance_claims` entry returns `approval_required`, with the claim's evidence
reference attached to the blocking requirement. An unchanged definition
returns `proceed`.

This gate runs when a tier definition changes. It is deliberately not a
campaign, publication, or per-customer approval: the approved tier records the
commercial wording and typed tenancy-posture minimum once, while service and
provider owners remain authoritative for current operational posture.

## Recommendation Workflow

Recommendations now include:

- recommendation type: research, simulation, model change, or execution
- rationale
- confidence
- risks
- supporting observations
- governance decision
- approval requirements

This satisfies the PRD requirement that recommendations be explainable and
distinguish between evidence gathering, simulation, model design, and execution.

## Safe-Tuning Contract

The governance surface exposes a structured contract for customer-tunable
pricing:

- allowed tunable parameters
- a trade-off lexicon
- pilot examples
- whether a model is customer-visible or still pilot-only

For the current Coulomb MVP, the contract exists only as a pilot surface for
`membership-plus-overage`; accepted examples are still seller-assisted rather
than self-serve.

## Health And Audit

The dashboard payload now includes:

- pricing health checks
- provider execution readiness checks
- tuning pilot health
- experiment capacity checks
- provider revision history and active revision metadata

These surfaces are intended to help both humans and agents decide whether the
next safe step is research, simulation, approval, execution, or rollback.