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.