Advance WP-0007: degeneration research, profile catalog, canonicalization checklist
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.
This commit is contained in:
parent
8894acc584
commit
58a4dd1db2
8 changed files with 658 additions and 4 deletions
108
specs/CanonicalizationReviewChecklist.md
Normal file
108
specs/CanonicalizationReviewChecklist.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue