target-revenue/specs/CanonicalizationReviewChecklist.md

Canonicalization Review Checklist

Status: Draft v0.1 Date: 2026-07-29 Workplan: workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md T04 Primary artifacts: specs/MonetizationExtensionSpecification.md §4, specs/CanonicalMonetizationProfiles.md, src/target_revenue/registry.py (promote_extension_canonical)

Scope note: this is the short, profile-level checklist specs/MonetizationExtensionSpecification.md §4 says must exist before any of the six catalog profiles can be promoted from registered to canonical. It is not a general governance framework — that's workplans/TREV-WP-0008-governance-and-pilot-rollout.md T01 (specs/TRSL-Governance.md, extension canonicalization review process, dispute/conflict-of-interest handling at the organization level). This document answers one narrower question: what does a reviewer actually check before canonicalizing one of these six profiles?

---

1. Mechanism (already built, not new here)

Canonicalization is performed by target_revenue.registry.promote_extension_canonical(conn, extension_id, version, approved_by) (WP-0006-T03), which calls the database's set_extension_status() function — the only way to change an extension's status, since the application role has no UPDATE grant on extensions at all (migrations/0001_registries.sql). This checklist exists so that whoever calls that function (the approved_by recorded) has actually verified the items below first — the system enforces who performed the promotion and that it's attributable; it does not and cannot enforce that the reviewer actually checked anything. That's what this document is for.

2. Checklist

A profile is ready for promote_extension_canonical once all of the following are true:

1. Already registered and passing conformance. Schema-valid (validation.validate_extension_contract) and the core-term non-redefinition check passes — a prerequisite, not sufficient alone, since that check is a pattern-based heuristic (validation.check_extension_core_term_redefinition's own docstring), not an exhaustive semantic review.
2. A human has read the allocation.rule text itself, not just confirmed the heuristic check passed, and confirms it does not redefine Phase, Milestone Release, Initial Target, Development Credit, Remission Credit, Outstanding Target, Conversion Event, or Future License in substance, even if it happens not to trip the pattern-based check's specific wording triggers.
3. Internal consistency: value.description, pricing.method, and allocation.rule tell the same story about what's being sold and what counts toward the target. A profile whose narrative description implies one thing and whose allocation rule computes another is not ready, regardless of schema validity.
4. reversal.rule covers the realistic refund/chargeback path for this profile's actual pricing model (e.g., a cost-plus profile's reversal rule should address partial refunds proportional to the cost basis, not only full reversal).
5. evidence.requirement is proportionate to the profile's typical transaction size and the allocation it can produce — per specs/OpenQuestions-WorkingDefaults.md Q10's evidence tiers (E0/E1/E2): a profile capable of generating a large Development Credit per transaction should not have only an E0-level evidence requirement.
6. At least one full worked narrative exists, not only the bare JSON fixture — specs/CanonicalMonetizationProfiles.md §1–§6 satisfies this for all six catalog profiles as of this document.
7. No known open legal/compliance flag specific to this profile's structure. This is a sanity check, not a legal opinion: does the pricing/allocation shape resemble a regulated financial instrument (e.g., a sponsorship structured with an implied return expectation could resemble a security) closely enough to warrant specialist input before recommending it broadly? If yes, canonicalization should wait for that input; if no obvious resemblance exists, this item is satisfied by the reviewer's own note that they considered it.
8. Sign-off is recorded. promote_extension_canonical's approved_by parameter, plus a one-line note (in this document, a workplan Result, or a dated history/ entry) of who reviewed against this checklist and when — the mechanism records that an approval happened; a human record should say why it passed.

3. Applying the checklist to the six catalog profiles now

This document does not itself canonicalize anything — recording the checklist is T04's job; running it against a real profile and deciding to promote is a separate governance action (item 8 above), appropriately left to whoever owns that decision (plausibly folded into workplans/TREV-WP-0008-governance-and-pilot-rollout.md T01's broader governance work, or done independently once a first real pilot Phase actually wants to declare canonical status for one). A quick read against the six profiles in specs/CanonicalMonetizationProfiles.md suggests development-license and general-consulting are the two simplest, lowest-ambiguity candidates (fixed 100%/0% allocation, no per-transaction declaration required) if a first canonicalization pass is wanted before a full governance review cadence exists — but that recommendation is exactly the kind of judgment call item 7/8 above require a named human to actually make, not something this checklist resolves on its own.

4. Non-goals

• Performing any canonicalization — a separate, attributable governance action per §1–§2 above.
• Organization-wide governance (Licensor identity, dispute process, conflict-of-interest handling) — workplans/TREV-WP-0008-governance-and-pilot-rollout.md T01.
• Changing promote_extension_canonical's implementation — already built and tested in WP-0006-T03; this document is a human-process checklist layered on top of it, not a code change.