Implement governance workflows and close WP-0008

docs/GovernanceWorkflows.md

@@ -0,0 +1,85 @@
+# Governance Workflows
+
+Status: MVP for `ADAPTIVE-WP-0008`.
+
+## 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
+
+## 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.
+
+## 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.