diff --git a/README.md b/README.md index b554e15..7429c64 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ Extracted and stabilized from the concept draft under `workplans/TREV-WP-0003-no | [`specs/PhaseManifestSpecification.md`](specs/PhaseManifestSpecification.md) | Phase Manifest field tiers and validation rules | | [`specs/TargetLedgerSpecification.md`](specs/TargetLedgerSpecification.md) | Ledger entry types, hash chain, Outstanding Target fold | | [`specs/MonetizationExtensionSpecification.md`](specs/MonetizationExtensionSpecification.md) | Six-field extension contract, registered vs. canonical | +| [`specs/PhaseLifecycleUseCases.md`](specs/PhaseLifecycleUseCases.md) | Nine Phase-lifecycle use cases mapped to what's built, what's a real gap, and what has no UI by design (WP-0012-T01) | **Forbidden synonyms:** do not treat undifferentiated "revenue captured" as equivalent to Development Credit (see `CONTRIBUTING.md` § Terminology); do not call pre-conversion software "Open Source" (see the guardrail table above). @@ -84,7 +85,7 @@ The concept's §13 now defines a **Global Contingency Share Determination Rule** | [TREV-WP-0009](workplans/TREV-WP-0009-target-revenue-control-plane.md) | Target Revenue Control Plane — interactive UI for the `binky` tenant, incl. interactive Development Credit entry creation (`specs/TargetRevenueControlPlaneConcept.md`) — **finished**, all 4 tasks done. **T04 (interactive UI, `src/target_revenue/service/control_plane_app.py`) built on vendored `whynot-design` web components** rather than from scratch, per an explicit feasibility check | | [TREV-WP-0010](workplans/TREV-WP-0010-development-effort-calculator.md) | Development Effort Calculator — **finished**, all 3 tasks done. Applied to the three real pilot candidates (`history/260730-EffortCalculator-CandidateApplication.md`) — every calculator-derived Initial Target came out materially lower than the earlier hand-picked placeholders, two of three carrying explicit warnings recommending manual review | | [TREV-WP-0011](workplans/TREV-WP-0011-railiance-reef-deployment.md) | Deploy Trust Service + Control Plane to the Railiance reef, fronted by `revenue.coulomb.social` — active; T01 (deployment-pattern decision, human gate) next. Deployment alone does not authorize a real Phase go-live — that remains WP-0008-T05 | -| [TREV-WP-0012](workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md) | Phase provenance, ledger reference, and degeneration-policy modeling — active; T01 (use-cases document) next. Modeling-only: produces a use-cases spec + a discussable spec addendum, no schema/UI changes yet | +| [TREV-WP-0012](workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md) | Phase provenance, ledger reference, and degeneration-policy modeling — active; T01 done (`specs/PhaseLifecycleUseCases.md`), T02 (repo/provenance fields, human gate) next. Modeling-only: produces a use-cases spec + a discussable spec addendum, no schema/UI changes yet | | [TREV-WP-0013](workplans/TREV-WP-0013-remission-credit-automation.md) | Remission Credit automation (degeneration policy execution) — active; T01–T03 `wait` on WP-0012-T03's policy-spec-file decision. Nothing currently computes or writes `remission-credit` ledger entries | | [TREV-WP-0014](workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md) | Control Plane UI: Extension Registry, Breach Records, Conversion Attestation — active; T01 next. Backend for all three already exists (WP-0006); UI-only work, not blocked on WP-0012 | diff --git a/specs/PhaseLifecycleUseCases.md b/specs/PhaseLifecycleUseCases.md new file mode 100644 index 0000000..3e7c787 --- /dev/null +++ b/specs/PhaseLifecycleUseCases.md @@ -0,0 +1,245 @@ +# Phase Lifecycle Use Cases + +`workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` T01. +Written after using the Control Plane UI (WP-0009-T04) for the first time +surfaced that the Phase Manifest schema and the UI built on top of it +don't yet cover several use cases the framework's own normative documents +already commit to. This document enumerates those use cases systematically +— **as a map of what exists, what's missing, and what's out of scope by +design** — before T02–T05 turn any of the gaps into schema or UI +decisions. + +This is a documentation-only artifact. It does not itself change any +schema, code, or UI. + +--- + +## 1. First Phase ever declared for a repo + +The common case today: a repo has never had a Phase before, and one is +declared for its first governed Milestone Release. + +**Real examples** (`examples/pilot-candidates/*/manifest.json`, +`specs/PilotPhaseCandidateSurvey.md`): `net-kingdom-local-identity`, +`railiance-vergabe-teilnahme`, `info-tech-canon-service-surface`. All +three currently use a `trsl:phase:draft-...` id — none has actually been +registered against the hosted Trust Service. That's intentional: no real +Phase go-live is authorized yet +(`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T05). + +**What the manifest captures today**: `milestone_release.name` (a free-text +label, e.g. `"vergabe-teilnahme-v1 (RAILIANCE-WP-0002/RAILIANCE-WP-0014)"`) +and `milestone_release.source_revision` (a bare short SHA, e.g. +`"398b0fe"`). **What it does not capture**: which repo, or which Forgejo +instance, that revision belongs to. The workplan references embedded in +the `name` string are the only thing tying a Phase back to its source +today, and they're prose, not structured data — a human convention, not +something the schema or the UI can rely on. + +**Gap → WP-0012-T02** (repo identification fields). + +--- + +## 2. A successive Phase on a repo that already had an earlier Phase + +FR-11 (`specs/ProductRequirementsDocument.md`) requires the framework to +"support multiple independently governed, sequential Phases over a +software's lifetime, each identifying its base release, included change +set, Milestone Release, Initial Target, Future License, degeneration +policy, and ledger." Rule 7 (`specs/TargetRevenueFrameworkCore.md` §4) +then requires that rights already granted by an earlier converted +Milestone Release can never be withdrawn or restricted by a later Phase. + +**None of this is modeled in the schema today.** There is no field +anywhere in `phase_manifest.schema.json` for "the Phase this one +succeeds" or "the base release this Phase's change set is measured +against." A second Phase for the same repo today would look, structurally, +identical to a completely unrelated repo's first Phase — the only +difference would be human-readable text in `milestone_release.name`. + +This matters concretely: `railiance-vergabe-teilnahme`'s candidate manifest +already names two workplans (`RAILIANCE-WP-0002/RAILIANCE-WP-0014`) +inside a single Milestone Release's `name` — a preview of exactly this +use case arriving before the schema was ready for it. + +**Open question this use case raises, not yet answered**: what does a +first-ever Phase put in a "base Phase" field that a successive Phase +would use? A null/absent value works structurally, but the Trust +Service's fold and validation logic downstream should treat "no prior +Phase" and "prior Phase exists" as two branches it explicitly recognizes, +not an accidentally-empty string. + +**Gap → WP-0012-T02** (repo identification fields, same task — the two +questions are tightly coupled: "which repo" and "which prior Phase for +that repo" are really one provenance model, not two). + +--- + +## 3. Operator registers a Phase; Contributor proposes; Operator/Admin reviews + +**Already built** (`workplans/TREV-WP-0009-target-revenue-control-plane.md`, +all four tasks done). Included here for completeness and cross-reference, +not to redesign it: + +- Rights model: Viewer / Contributor / Operator / Admin, ordinal via + `registry.RIGHTS_TIERS`/`has_right()` + (`specs/TargetRevenueControlPlaneConcept.md` §2's table). +- Operator+ registers a Phase (`control_plane.register_phase`) and + appends Development Credit directly + (`control_plane.append_development_credit`). +- Contributor submits a proposed entry instead + (`control_plane.propose_ledger_entry`); Operator+ approves (appending + under the *reviewer's own* credential, + `control_plane.approve_proposed_entry`) or rejects + (`control_plane.reject_proposed_entry`). +- Every action is recorded in the Control Plane's own audit log + (`control_plane.record_audit_event`/`get_audit_log`), independent of + the Trust Service's own signed records, which only ever attest "the + `binky` tenant acted," never which individual human. +- UI: `service/control_plane_app.py` + `service/control_plane_templates/` + (WP-0009-T04). + +No gap here, no follow-up workplan. + +--- + +## 4. Remission Credit accrual over time under the active degeneration policy + +`trsl:policy:linear-longstop-v0` (the accepted v1 norm, +`specs/OpenQuestions-WorkingDefaults.md` Q7) defines +`R(t) = T0 × clamp((t − t0)/(tL − t0), 0, 1)`, with discrete +`remission-credit` ledger entries computed on a published schedule. FR-6 +(`specs/ProductRequirementsDocument.md`) requires this to actually happen. + +**Nothing in this codebase computes or writes these entries.** +`fold.py` can *consume* a `remission-credit` entry if one exists in the +ledger; nothing produces one. This is not a Control Plane UI gap — it +predates the UI entirely, and was never in scope for WP-0006 (Trust +Service) either. It surfaced now only because working through this +use-case list prompted a fuller look at what a Phase's lifecycle actually +requires end to end, not because anything about the recent UI work +introduced it. + +**Gap → `workplans/TREV-WP-0013-remission-credit-automation.md`** +(its own workplan, not folded into this modeling pass, since it's a +missing *implementation*, not a missing *decision*). + +--- + +## 5. Conversion Event fires; Attestation published + +FR-7 defines the Conversion Event as the objective moment Outstanding +Target reaches zero, computable from the Manifest + Ledger alone, with no +Trust Service declaration required (`attestation.py`'s module docstring: +"a Conversion Event is true the instant the ledger fold first reaches +Outstanding Target = 0, independent of whether anything ever publishes an +attestation about it"). `attestation.publish_attestation` is implemented, +tested, and exposed at `GET /phases/{id}/attestation` — idempotent, +publish-on-first-observation, never regenerated. + +**What's missing is purely presentational**: the Control Plane UI has no +view of a Phase's Attestation once one exists. A caller has to know to +hit the Trust Service endpoint directly. + +**Gap → `workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md` +T03.** + +--- + +## 6. Monetization Extension registration and canonical-status review + +FR-4 defines the six-field extension contract; `registry.register_extension` +and `registry.promote_extension_canonical` are implemented and tested. +Canonicalization is a governance action (`set_extension_status`, +SECURITY DEFINER, never a plain `UPDATE`) — the same pattern already used +for credential revocation and proposed-entry review elsewhere in this +project. + +**Two things are missing, one of them a real open question, not just +UI**: + +- No Control Plane UI to register an extension or review/promote one. +- **Unresolved**: `specs/TargetRevenueControlPlaneConcept.md` §2's rights + table (cited in use case 3 above) does not mention extension + registration or canonicalization at all — unlike breach records (use + case 7), which the table explicitly assigns to Operator+. Whether + registering a new extension should require any rights tier at all + (the Trust Service's own `registry.register_extension` doesn't gate it + today — any authenticated tenant can call it directly), and who should + be able to canonicalize one, needs an explicit answer before UI work + starts, not an assumption made while building the form. + +**Gap → `workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md` +T01.** + +--- + +## 7. Breach/Compliance Record publication + +FR-10 and License V1C1 §7.4: a Licensor's own breach/termination +determination, anonymized (Phase + category only) by default, named only +with an explicit Commercial Use Agreement opt-in. +`breach_record.publish_breach_event`/`get_breach_records` are implemented +and tested. **Unlike extension registration, this one's rights tier is +already decided**: `specs/TargetRevenueControlPlaneConcept.md` §2 assigns +"publish breach/compliance records" to Operator+ explicitly, alongside +Phase registration and direct ledger append. No open rights question here +— purely a missing UI. + +**Gap → `workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md` +T02.** + +--- + +## 8. A second Licensor tenant besides `binky` onboards + +Today, `binky` is the only Licensor identity in every environment (test +fixtures, the local dev instance, presumably any eventual deployment). +`registry.create_licensor_identity`/`issue_sub_credential` support a +second tenant structurally and are exercised in tests, but never in any +real onboarding flow — there is no "onboard a new Licensor" use case +documented anywhere, only "issue another credential for the Licensor that +already exists." + +**Judged not to need its own workplan** (per the decision recorded in +`workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md`'s +closing section) — this is squarely a governance matter and belongs under +`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` if and when a +second real tenant is actually on the table. Revisit that call if it +turns out to need real design work once that happens, rather than +speculatively designing it now. + +--- + +## 9. An external auditor verifies a Phase's evidence package offline + +FR-8/FR-9: a complete Phase evidence package (manifest, ledger, +extensions, attestation) can be exported in an open format and +independently verified — recomputing the fold, checking the Ed25519 +signature chain — **without trusting, or even being able to reach, the +Trust Service or the Control Plane at all** (NFR-1 determinism/ +reproducibility; `attestation.py`'s own docstring makes the same point +about conversion status specifically). + +**This use case has, by design, no Control Plane UI surface.** Recording +it here explicitly so it doesn't get silently miscounted as "not yet +built" alongside cases 4–7 above, which *are* real gaps. `fold.py` and +`hashing.py` are the offline-verifiable surface this use case depends on; +both are already implemented, tested, and covered by the hosted +conformance suite (`tests/test_hosted_conformance.py`). + +--- + +## Summary table + +| # | Use case | Status | +|---|---|---| +| 1 | First Phase for a repo | Partially modeled — no repo/provenance fields (→ T02) | +| 2 | Successive Phase, same repo | Not modeled at all (→ T02) | +| 3 | Register / propose / review (rights model) | Done (WP-0009) | +| 4 | Remission Credit accrual | Not implemented (→ WP-0013) | +| 5 | Conversion Attestation view | Backend done, no UI (→ WP-0014-T03) | +| 6 | Extension registration/canonicalization | Backend done, no UI, rights tier undecided (→ WP-0014-T01) | +| 7 | Breach/Compliance Record | Backend done, no UI, rights tier already decided (→ WP-0014-T02) | +| 8 | Second Licensor tenant onboarding | Structurally supported, no onboarding flow — deferred to WP-0008 | +| 9 | Offline evidence verification | Done by design, no UI needed | diff --git a/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md b/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md index c5a82bd..306c36e 100644 --- a/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md +++ b/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md @@ -32,7 +32,7 @@ reviewed (T05). ```task id: TREV-WP-0012-T01 -status: todo +status: done priority: high state_hub_task_id: "2871b8ff-b845-4ed4-aaa1-8fdfd1f601b7" ``` @@ -62,6 +62,17 @@ state_hub_task_id: "2871b8ff-b845-4ed4-aaa1-8fdfd1f601b7" — call out explicitly that this use case has *no* UI surface by design, so it doesn't get silently forgotten as "not yet built"). +**Result:** `specs/PhaseLifecycleUseCases.md` written, covering all nine +use cases. Two findings worth flagging beyond the original scope: (a) use +case 2 (successive Phases) and use case 1 (first Phase) turned out to +share one underlying provenance model rather than being separate +concerns, so T02 below covers both together; (b) cross-checking +`specs/TargetRevenueControlPlaneConcept.md` §2's rights table while +writing use cases 6–7 found that breach-record publication already has a +decided rights tier (Operator+) but extension registration/canonicalization +does not — that's now recorded as an explicit open question for +WP-0014-T01 rather than something to assume while building that UI. + ```task id: TREV-WP-0012-T02 status: todo