tegwick
58a4dd1db2
T01: specs/TargetDegenerationPolicyResearch.md. Survey finds no precedent (BSL/FSL/Elastic) implements progress-sensitive degeneration - TRSL's model is original design. Proposes a candidate v1 formula (90-day rolling "quiet period" pause on Remission Credit accrual during active Development Credit periods), resolves the contributor-diversity input as explicitly not-adopted (no gaming-resistant signal exists yet), and resolves the longstop/progress-sensitivity relationship as a hard, unconditional backstop. Does not recommend v0 vs v1 for T02 - that's the human gate. T02: recommendation added (confirm v0 for the first pilot cohort, name v1 as the next iteration) - left todo per the human-accept policy. T03: specs/CanonicalMonetizationProfiles.md with worked narratives for all six catalog profiles, plus two new fixtures (product-ideation, general-consulting), both schema-validated and added to the parametrized conformance test. T04: specs/CanonicalizationReviewChecklist.md, an 8-item checklist layered on the already-implemented promote_extension_canonical() mechanism (WP-0006-T03) - defines what a reviewer must verify, not a new promotion mechanism.
108 lines
6 KiB
Markdown
108 lines
6 KiB
Markdown
# 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.
|