Add grandfathered pricing migration guard

grandfathered-pricing-migration-guard/README.md

@@ -0,0 +1,36 @@
+# Grandfathered Pricing Migration Guard
+
+This self-contained Revenue Infrastructure slice validates whether a legacy-price customer can be migrated to a new price book before an invoice is released.
+
+The guard focuses on a gap that is separate from existing billing ledgers, usage metering, quota rollover, coupon checks, committed-usage true-ups, grant billing, FX settlement, tax handling, invoice delivery, and analytics-seat licensing work.
+
+## What it checks
+
+- active price locks and grandfathered contract windows
+- required customer notice periods before a price increase
+- explicit consent for material increases
+- annual and volume discount compatibility
+- included seat and compute regressions
+- add-on parity during plan migration
+- currency changes that need finance approval
+- dispute, delinquency, and strategic-account review holds
+- reviewer evidence such as order forms, runbooks, legal approval, and sales owner signoff
+
+## Run locally
+
+```sh
+npm test
+npm run demo
+```
+
+The demo writes reviewer artifacts under `artifacts/`:
+
+- `pricing-migration-results.json`
+- `pricing-migration-report.md`
+- `pricing-migration-summary.svg`
+- `pricing-migration-demo.mp4` when `swift scripts/make-demo-video.swift artifacts/pricing-migration-demo.mp4` is run on macOS
+- `demo-transcript.md`
+
+## Boundaries
+
+All data is synthetic. The module does not call payment processors, customer systems, pricing APIs, bank rails, external services, or private billing records.

grandfathered-pricing-migration-guard/REQUIREMENT_MAP.md

@@ -0,0 +1,17 @@
+# Requirement Map
+
+| Issue requirement | Implementation |
+| --- | --- |
+| Tiered subscription billing | Evaluates current and target plans, price books, billing cycles, included seats, and included compute. |
+| Volume discounts and annual cycles | Blocks or reviews incompatible annual commitments, volume discounts, seat caps, and billing-cycle regressions. |
+| Free trials, coupons, consortium pricing coexistence | Keeps this slice distinct by checking plan migration release readiness rather than coupon eligibility itself. |
+| Institutional invoicing | Produces deterministic RELEASE, REVIEW, or HOLD decisions before legacy-price invoices can be released. |
+| Usage-based pricing for AI compute | Detects target plan compute regressions against recent average compute usage. |
+| Transparent quotas and usage meters | Includes included-seat and compute-hour deltas in every reviewer result. |
+| High-margin, predictable recurring revenue | Prevents surprise migrations, missing consent, active price-lock violations, and add-on parity regressions before invoices ship. |
+| Reviewer-ready evidence | Demo script generates JSON, Markdown, SVG, and transcript artifacts from synthetic account packets. |
+| Safe contribution boundary | No payment processor calls, no live customers, no credentials, no external APIs, and no private billing records. |
+
+## Distinct slice statement
+
+This contribution is focused only on grandfathered-price and price-book migration release decisions. It intentionally does not implement generic subscriptions, payment collection, quota rollover, tax/VAT, dunning, FX settlement, grant compute budgets, committed-usage true-ups, analytics-seat licensing, invoice delivery, or coupon eligibility.

grandfathered-pricing-migration-guard/artifacts/demo-transcript.md

@@ -0,0 +1,14 @@
+# Demo Transcript
+
+1. Load five synthetic legacy-price account packets.
+2. Evaluate notice windows, price locks, consent thresholds, add-on parity, usage regressions, and reviewer evidence.
+3. Emit deterministic invoice-release decisions: RELEASE_INVOICE, REVIEW_BEFORE_RELEASE, or HOLD_INVOICE.
+4. Write JSON, Markdown, and SVG artifacts for reviewer replay.
+
+## Demo Output
+
+- Release: 1
+- Review: 1
+- Hold: 3
+- Held accounts: acct-lab-price-lock, acct-notice-gap, acct-currency-mismatch
+- Review accounts: acct-grace-review

grandfathered-pricing-migration-guard/artifacts/pricing-migration-report.md

@@ -0,0 +1,51 @@
+# Grandfathered Pricing Migration Report
+
+As of: 2026-06-18
+
+## Summary
+
+- Total accounts: 5
+- Release: 1
+- Review: 1
+- Hold: 3
+- Monthly revenue delta: USD 1,510.00 before currency-specific settlement review
+
+## Account Decisions
+
+| Account | Decision | Monthly delta | Primary reason |
+| --- | --- | ---: | --- |
+| Northbridge University Research Office | RELEASE_INVOICE | USD 390.00 | All release checks passed |
+| Meridian Lab Collaborative | HOLD_INVOICE | USD 160.00 | ACTIVE_PRICE_LOCK: Price lock remains active until 2026-12-31. |
+| Civic Methods Consortium | HOLD_INVOICE | USD 520.00 | ADD_ON_PARITY_GAP: Target plan is missing legacy add-ons: sso. |
+| Helix Bioinformatics Studio | REVIEW_BEFORE_RELEASE | EUR 180.00 | INSIDE_LEGACY_GRACE_PERIOD: Grandfathering ended 29 days ago, inside the 45-day review grace period. |
+| Pacific Applied Science Center | HOLD_INVOICE | HKD 260.00 | CURRENCY_CHANGE_WITHOUT_FINANCE_APPROVAL: Currency changes from USD to HKD. |
+
+## Release Actions
+
+### Northbridge University Research Office
+- Release invoice under the target price book.
+
+### Meridian Lab Collaborative
+- Keep the account on the legacy price book until the price lock expires or a new order form is signed.
+- Request explicit customer approval before creating a new-price invoice.
+- Hold invoice release until the notice window is satisfied.
+- Collect explicit consent or signed renewal before migration.
+- Attach legal approval before release.
+
+### Civic Methods Consortium
+- Route through renewals review before release.
+- Hold invoice release until the notice window is satisfied.
+- Collect explicit consent or signed renewal before migration.
+- Attach legal approval before release.
+- Increase target seat allowance or collect admin confirmation for seat reduction.
+- Confirm customer-facing compute entitlement changes before billing.
+- Add equivalent add-ons or document an accepted replacement.
+- Confirm volume discount recalculation with revenue operations.
+- Attach named sales owner or renewal owner signoff.
+
+### Helix Bioinformatics Studio
+- Route through renewals review before release.
+- Attach legal approval before release.
+
+### Pacific Applied Science Center
+- Add finance approval and settlement notes for the currency migration.