From ca53a9f8204fec87d9d17b36f8e69f884d179be0 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 30 Jul 2026 19:35:18 +0200 Subject: [PATCH] Add TREV-WP-0012/0013/0014: modeling pass + spun-out implementation gaps TREV-WP-0012 is the modeling-only workplan requested after using the Control Plane UI surfaced real gaps: Phase registration has no structured repo/provenance fields, the ledger URI is hand-typed, and degeneration policies are opaque ids with no reviewable spec behind them. It produces a use-cases document and a discussable spec addendum before any schema/UI implementation. Two of the use cases uncovered while scoping this turned out to be bigger than documentation gaps and are tracked as their own workplans per that direction: TREV-WP-0013 (nothing currently computes or writes Remission Credit ledger entries at all) and TREV-WP-0014 (Extension Registry, Breach Record, and Conversion Attestation backends already exist from WP-0006 but have no Control Plane UI). Co-Authored-By: Claude Sonnet 5 --- README.md | 3 + ...12-phase-provenance-and-policy-modeling.md | 177 ++++++++++++++++++ ...REV-WP-0013-remission-credit-automation.md | 77 ++++++++ ...-plane-extensions-breach-attestation-ui.md | 74 ++++++++ 4 files changed, 331 insertions(+) create mode 100644 workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md create mode 100644 workplans/TREV-WP-0013-remission-credit-automation.md create mode 100644 workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md diff --git a/README.md b/README.md index e99c5e5..b554e15 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,9 @@ 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-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 | Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md) diff --git a/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md b/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md new file mode 100644 index 0000000..b9e517c --- /dev/null +++ b/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md @@ -0,0 +1,177 @@ +--- +id: TREV-WP-0012 +type: workplan +title: "Phase provenance, ledger reference, and degeneration-policy modeling" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-07-30" +updated: "2026-07-30" +--- + +# Phase provenance, ledger reference, and degeneration-policy modeling + +Triggered by using the Control Plane UI for the first time (WP-0009-T04): +the Phase registration form asked for a bare `source_revision` with no +repo attribution, a hand-typed `ledger` URI, and an opaque +`degeneration_policy` id with no way to see what it actually specifies. +These aren't UI bugs — the Phase Manifest schema +(`schemas/phase_manifest.schema.json`) itself doesn't yet carry the +structure the UI would need to show any of this properly, and FR-11 +(Successive Phases, `specs/ProductRequirementsDocument.md`) already commits +the framework to base-release/prior-Phase provenance that the schema has +never modeled either. + +This is a **modeling-only** workplan: it produces documents (a use-cases +spec and a discussable spec addendum) and decisions, not schema or UI +changes. Implementation follows in later workplans once the addendum is +reviewed (T05). + +```task +id: TREV-WP-0012-T01 +status: todo +priority: high +``` + +**Write the use-cases document**, as its own spec file (not folded into +`specs/PhaseManifestSpecification.md`) — working title +`specs/PhaseLifecycleUseCases.md`. Cover, systematically, at minimum: + +1. First Phase ever declared for a repo (the three real pilot candidates: + `net-kingdom`, `railiance-vergabe-teilnahme`, `info-tech-canon`). +2. A successive Phase on a repo that already had an earlier, converted + Phase (FR-11) — including what "base release" means when the prior + Phase's Milestone Release is itself the base. +3. Operator registers a Phase; Contributor proposes a Development Credit; + Operator/Admin reviews (already built, WP-0009 — include for + completeness/cross-reference, not to redesign it). +4. Remission Credit accrual over time under the active degeneration + policy — note as an open gap for WP-0013, not solved here. +5. Conversion Event fires, Attestation published — note as a UI gap for + WP-0014. +6. Monetization Extension registration and canonical-status review — note + as a UI gap for WP-0014. +7. Breach/Compliance Record publication — note as a UI gap for WP-0014. +8. A second Licensor tenant besides `binky` onboards. +9. An external auditor verifies a Phase's evidence package offline, + without needing to trust or even reach the Control Plane UI (FR-8/FR-9 + — call out explicitly that this use case has *no* UI surface by + design, so it doesn't get silently forgotten as "not yet built"). + +```task +id: TREV-WP-0012-T02 +status: todo +priority: high +human_accept_required: true +``` + +**Decide repo identification and Phase-provenance fields (human gate).** +Per direction already given: identity rests on the Forgejo instance +("home hub") plus the repo's own stable id within that instance, *and* +the Forgejo service URI and repo name are also retained (not derived) — +so a rename or instance move stays repairable rather than silently +breaking a Phase's provenance link. Concretely decide and record: + +- Field names/shape for `milestone_release`: a hub identifier, a + Forgejo-internal repo id, the Forgejo service URI, and the repo name + (owner/repo slug) — four values, not one string. +- Whether this is required or recommended for Stage 0 (precedent: + `longstop_at` moved from recommended to required under a working + default, `specs/OpenQuestions-WorkingDefaults.md` Q8). +- How a successive Phase (use case 2 above) references its base — a + `trsl:phase:...` id, and what a first-ever Phase puts there instead + (null, or an explicit "no prior Phase" marker — decide which is + cleaner for fold/validation logic downstream). +- Whether any of this is retroactively backfillable for the three + existing pilot-candidate example manifests, or only required going + forward. + +```task +id: TREV-WP-0012-T03 +status: todo +priority: high +human_accept_required: true +``` + +**Decide the degeneration-policy / calculation-model spec-file +convention (human gate).** Per direction already given: every policy or +calculation model (this includes the Development Effort Calculator's own +Candidate A formula, `specs/DevelopmentEffortCalculatorConcept.md`, not +just degeneration policies) corresponds to a markdown specification file +with a simple, distinct name, an id, and a revision — built on git's own +mechanisms (commit hash and/or file path, no new versioning +infrastructure). Concretely decide: + +- Where these spec files live (likely already `specs/*.md` — decide + whether a dedicated subdirectory or naming convention is needed so a + policy id like `trsl:policy:linear-longstop-v0` maps unambiguously to + one file). +- What "id and revision, built on git internals" means precisely — e.g. + the policy id embeds the file path and a pinned commit hash, or the + file's own frontmatter carries an id/revision pair that a human commits + to alongside code changes (check how `the-custodian`/state-hub already + present read-only reference-documentation views linked by id, per the + user's explicit steer to reuse that pattern rather than invent a new + one, and follow whichever mechanism is actually in use there). +- How the Control Plane UI links a policy id shown next to a Phase to a + **read-only** rendered view of that spec file — no in-UI editing, + consistent with every other governance-action pattern in this project. +- Whether this same convention should also cover the six canonical + monetization profiles (`specs/CanonicalMonetizationProfiles.md`) for + consistency, or is scoped to degeneration policies and calculators only + for now. + +```task +id: TREV-WP-0012-T04 +status: todo +priority: medium +human_accept_required: true +``` + +**Decide the ledger's UI treatment (human gate).** Per direction already +given: keep the `ledger` field in the schema — not as something the +standard Phase view surfaces, but as an internal reference reachable only +via an explicit drill-down/details action. This is intentional groundwork +for eventually supporting more than one ledger per Phase (federation, +`specs/ProductRequirementsDocument.md` NFR-3), not just a display +preference. Decide: + +- What the drill-down actually shows (the raw ledger URI/reference plus a + link to `GET /phases/{id}/ledger`'s live data, or something more), and + where it lives in the Control Plane's navigation (a "details" link on + `phase_detail.html` rather than a top-level field). +- Whether the Phase registration form still needs a `ledger` input at + all going forward, or whether the Trust Service should compute/assign + it automatically now that it is always the ledger's host in Stage 0 — + distinct from the schema question of whether the field stays. + +```task +id: TREV-WP-0012-T05 +status: todo +priority: high +``` + +**Draft the spec addendum** reflecting T01–T04's accepted decisions, for +review before any implementation — schema changes (`schemas/ +phase_manifest.schema.json`), the policy-spec-file convention, and the +Control Plane UI changes it implies. Do not implement anything from this +task; it produces a reviewable document only. Once accepted, file the +implementation work as its own workplan(s), consistent with how WP-0009 +and WP-0010 were split from a single combined plan. + +## Related gaps spun out as their own workplans + +Use cases 4, 6, and 7 above are bigger than a modeling exercise — they +are missing implementation, not missing documentation — and are tracked +separately rather than folded in here: + +- `workplans/TREV-WP-0013-remission-credit-automation.md` — use case 4. +- `workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md` + — use cases 5, 6, 7. + +Use case 8 (second Licensor tenant onboarding) is judged small enough to +stay under `workplans/TREV-WP-0008-governance-and-pilot-rollout.md` +rather than warrant its own workplan — revisit that call if it turns out +to need real design work once a second tenant is actually on the table. diff --git a/workplans/TREV-WP-0013-remission-credit-automation.md b/workplans/TREV-WP-0013-remission-credit-automation.md new file mode 100644 index 0000000..c9e2bd8 --- /dev/null +++ b/workplans/TREV-WP-0013-remission-credit-automation.md @@ -0,0 +1,77 @@ +--- +id: TREV-WP-0013 +type: workplan +title: "Remission Credit automation (degeneration policy execution)" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-07-30" +updated: "2026-07-30" +--- + +# Remission Credit automation (degeneration policy execution) + +Spun out of `workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` +(use case 4). Every Phase declares a `degeneration_policy` +(`trsl:policy:linear-longstop-v0` is the accepted v1 norm, +`specs/OpenQuestions-WorkingDefaults.md` Q7), which is supposed to +generate `remission-credit` Target Ledger entries over time when +Development Credit progress is insufficient (FR-6, +`specs/ProductRequirementsDocument.md`). **Nothing in this codebase +currently computes or writes these entries.** `fold.py` can consume them +if they exist; nothing produces them. This gap predates the Control Plane +UI work — it was never in scope for WP-0006 (Trust Service) or WP-0009 +(Control Plane), and surfaced now only because reviewing the UI's +Phase-registration flow prompted a fuller look at what a Phase's lifecycle +actually requires end to end. + +Blocked on `workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` +T03's decision (how a policy id maps to its spec file) — the +implementation here should be checkable against that spec file, per the +user's explicit requirement that policy code and policy specification stay +verifiably in sync. + +```task +id: TREV-WP-0013-T01 +status: wait +priority: high +``` + +**Design the remission calculation and scheduling model.** `R(t) = T0 × +clamp((t - t0)/(tL - t0), 0, 1)` (Q7) needs: a chosen recognition cadence +(daily/monthly UTC per Q7's own text), an idempotent +"has this period's remission already been recorded" check (ledger entries +are append-only — a re-run must not double-remit), and a decision on +where `t0` (Phase activation) comes from if it isn't already a manifest +field (registration time? an explicit `activated_at`?). Cross-check +against whatever `trsl:policy:linear-longstop-v0`'s spec file (once +WP-0012-T03 lands) says, rather than re-deriving the formula from Q7 +prose alone. + +```task +id: TREV-WP-0013-T02 +status: wait +priority: high +``` + +**Implement and test** the calculation as a pure function (mirroring +`fold.py`'s determinism discipline) plus whatever writes the resulting +`remission-credit` entries into the hosted Target Ledger — a scheduled +job, an on-demand Control Plane action, or both. Decide which actor +"submits" these entries for attribution purposes (no human credential +naturally owns a policy-driven entry) and record that decision explicitly +rather than leaving `submitted_by_token` implicitly null. + +```task +id: TREV-WP-0013-T03 +status: wait +priority: medium +``` + +**Surface it in the Control Plane UI**: `phase_detail.html`'s Ledger +table already renders `remission-credit` rows generically once they +exist; verify that holds, and add a metrics-level explanation (e.g. next +scheduled remission date/amount) if `metrics.py` doesn't already forecast +one. diff --git a/workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md b/workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md new file mode 100644 index 0000000..423d077 --- /dev/null +++ b/workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md @@ -0,0 +1,74 @@ +--- +id: TREV-WP-0014 +type: workplan +title: "Control Plane UI: Extension Registry, Breach Records, Conversion Attestation" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-07-30" +updated: "2026-07-30" +--- + +# Control Plane UI: Extension Registry, Breach Records, Conversion Attestation + +Spun out of `workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` +(use cases 5, 6, 7). Unlike `workplans/TREV-WP-0013-remission-credit-automation.md`, +the backend for all three already exists and is tested +(`registry.register_extension`/`promote_extension_canonical`, +`breach_record.publish_breach_event`/`get_breach_records`, +`attestation.publish_attestation`) — this is UI-only work, extending +`service/control_plane_app.py` and its templates the same way WP-0009-T04 +did for Phases and the Ledger. Not blocked on WP-0012; can start any time. + +```task +id: TREV-WP-0014-T01 +status: todo +priority: medium +``` + +**Extension Registry UI**: a page listing registered extensions with +their `registered`/`canonical` status, a form to register a new extension +(any authenticated tenant, per `registry.register_extension` — confirm +whether Control Plane rights-gating applies here or whether extension +registration is intentionally open, since `control_plane.py` today has no +wrapper for it at all), and a canonical-promotion action restricted to +whatever rights tier canonicalization review actually requires (check +`specs/TargetRevenueControlPlaneConcept.md` §2's rights table — this may +need its own entry there if it's missing). + +```task +id: TREV-WP-0014-T02 +status: todo +priority: medium +``` + +**Breach/Compliance Record UI**: a form to publish a breach/compliance +determination against a Phase (`breach_record.publish_breach_event`), +respecting the anonymized-by-default / named-only-with-opt-in rule +(FR-10, License V1C1 §7.4), and a read view on `phase_detail.html` +listing a Phase's published records. + +```task +id: TREV-WP-0014-T03 +status: todo +priority: low +``` + +**Conversion Attestation UI**: read-only — a Phase that has converted +should show its Attestation (`attestation.publish_attestation` is +idempotent/publish-on-first-observation) on `phase_detail.html`, including +Future License and the supporting ledger checkpoint, rather than requiring +a caller to hit the Trust Service's `GET /phases/{id}/attestation` +directly to see it. + +```task +id: TREV-WP-0014-T04 +status: todo +priority: low +``` + +**Tests and docs**: Docker-gated `TestClient` tests for all three (same +pattern as `tests/test_control_plane_app.py`), workplan Result sections, +`README.md` row update.