From 9c7576e8de4e7ef98fa088982dbf1436560db9f6 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 3 Aug 2026 20:31:52 +0200 Subject: [PATCH] Accept PhaseProvenanceSpecAddendum, file TREV-WP-0015 implementation specs/PhaseProvenanceSpecAddendum.md accepted 2026-08-03. Implementation filed as its own workplan (TREV-WP-0015), seven tasks mapping 1:1 to the addendum's sections rather than repeating field shapes/rationale: schema change, specs/policies/ + specs/profiles/ extraction, Control Plane reference-rendering routes, ledger UI change, forgejo_hubs migration, backfilling the three example manifests, and tests/closeout. Co-Authored-By: Claude Sonnet 5 --- README.md | 3 +- specs/PhaseProvenanceSpecAddendum.md | 10 +- ...WP-0015-phase-provenance-implementation.md | 132 ++++++++++++++++++ 3 files changed, 139 insertions(+), 6 deletions(-) create mode 100644 workplans/TREV-WP-0015-phase-provenance-implementation.md diff --git a/README.md b/README.md index 56ac0a2..7fef07b 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Extracted and stabilized from the concept draft under `workplans/TREV-WP-0003-no | [`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) | -| [`specs/PhaseProvenanceSpecAddendum.md`](specs/PhaseProvenanceSpecAddendum.md) | Proposed schema/spec-file/UI changes from WP-0012-T02–T04's accepted decisions — repo provenance fields, `specs/policies/`/`specs/profiles/` extraction, ledger UI treatment. **Not yet accepted for implementation** (WP-0012-T05) | +| [`specs/PhaseProvenanceSpecAddendum.md`](specs/PhaseProvenanceSpecAddendum.md) | Schema/spec-file/UI changes from WP-0012-T02–T04's accepted decisions — repo provenance fields, `specs/policies/`/`specs/profiles/` extraction, ledger UI treatment. **Accepted 2026-08-03**, implementation tracked in WP-0015 | **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). @@ -89,6 +89,7 @@ The concept's §13 now defines a **Global Contingency Share Determination Rule** | [TREV-WP-0012](workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md) | Phase provenance, ledger reference, and degeneration-policy modeling — **finished**, all 5 tasks done. Decisions (T02–T04) synthesized into [`specs/PhaseProvenanceSpecAddendum.md`](specs/PhaseProvenanceSpecAddendum.md) (T05) — **not yet accepted for implementation**; that's the document to discuss before any schema/UI work is filed as its own workplan | | [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 | +| [TREV-WP-0015](workplans/TREV-WP-0015-phase-provenance-implementation.md) | Implement `specs/PhaseProvenanceSpecAddendum.md` — active; T01 (schema change) next. Seven tasks map 1:1 to the addendum's §1–§6 | Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md) diff --git a/specs/PhaseProvenanceSpecAddendum.md b/specs/PhaseProvenanceSpecAddendum.md index d535e61..414f7d4 100644 --- a/specs/PhaseProvenanceSpecAddendum.md +++ b/specs/PhaseProvenanceSpecAddendum.md @@ -6,11 +6,11 @@ workplan's Result sections for the full reasoning behind each) into one reviewable document, covering the concrete schema, spec-file, and Control Plane UI changes they imply. -**This document proposes changes. It does not make them.** Per the -maintainer's own established sequencing for this workplan, nothing here -is implemented until this addendum itself is reviewed and accepted — at -which point the implementation work is filed as its own workplan(s), -the same way WP-0009/WP-0010 were split out of an earlier combined plan. +**Accepted 2026-08-03.** Implementation is tracked in +`workplans/TREV-WP-0015-phase-provenance-implementation.md`, whose seven +tasks map 1:1 to this document's §1–§6 (this document remains the +authoritative source for field shapes and rationale; that workplan does +not repeat them). --- diff --git a/workplans/TREV-WP-0015-phase-provenance-implementation.md b/workplans/TREV-WP-0015-phase-provenance-implementation.md new file mode 100644 index 0000000..ebc98c2 --- /dev/null +++ b/workplans/TREV-WP-0015-phase-provenance-implementation.md @@ -0,0 +1,132 @@ +--- +id: TREV-WP-0015 +type: workplan +title: "Implement Phase provenance, spec-file, and ledger UI changes" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-08-03" +updated: "2026-08-03" +--- + +# Implement Phase provenance, spec-file, and ledger UI changes + +Implements `specs/PhaseProvenanceSpecAddendum.md`, accepted 2026-08-03, +which itself synthesizes the decisions from +`workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` T02–T04. +Task numbering below matches the addendum's §6 suggested breakdown +1:1 — each task cites its addendum section as the authoritative source of +what to build, rather than re-deriving field shapes or rationale here. + +```task +id: TREV-WP-0015-T01 +status: todo +priority: high +``` + +**Schema change** (addendum §1): add `repo_hub`, `repo_hub_uri`, +`repo_id`, `repo_name` as required properties of +`phase.milestone_release`, and `phase.base_phase_id` as an optional +property of `phase`, to `schemas/phase_manifest.schema.json`. Update +`validation.py` if the new pattern/format constraints need anything +beyond what JSON Schema's own `pattern`/`format` keywords already +enforce (they shouldn't). Add offline tests: a manifest missing any of +the four new required fields is rejected; one with `base_phase_id` +absent validates (first Phase); one with it present and correctly +patterned validates (successive Phase). + +```task +id: TREV-WP-0015-T02 +status: todo +priority: high +``` + +**Spec-file extraction** (addendum §2): create `specs/policies/ +linear-longstop-v0.md` (extracted from `specs/ +OpenQuestions-WorkingDefaults.md` Q7's prose, with `policy_id`/`title` +frontmatter); create the six `specs/profiles/*.md` files (extracted from +`specs/CanonicalMonetizationProfiles.md` §1–§6, with `extension_id`/ +`title` frontmatter), leaving §7 (cross-profile summary) and §8 +(non-goals) in place as the overview document. Add `calculator_id`/ +`revision`/`title` frontmatter to `specs/ +DevelopmentEffortCalculatorConcept.md` (no move). Update +`OpenQuestions-WorkingDefaults.md` Q7 to point at the new file rather +than contain the policy's content directly. + +```task +id: TREV-WP-0015-T03 +status: todo +priority: medium +``` + +**Control Plane reference-rendering routes** (addendum §2): add +`GET /reference/policies/{slug}` and `GET /reference/profiles/{slug}` to +`service/control_plane_app.py`, rendering the corresponding +`specs/policies/`/`specs/profiles/` markdown file to HTML server-side at +request time (a small Python markdown library — confirm one is already +an acceptable addition to the `service` extras in `pyproject.toml`, or +add it). Read-only, no edit capability. Link to these routes from +wherever a policy id or extension id already appears in +`phase_detail.html`/`phase_new.html`. + +```task +id: TREV-WP-0015-T04 +status: todo +priority: medium +``` + +**Ledger UI change** (addendum §3): drop the `ledger` input from +`phase_new.html`; have the registration route auto-compute +`phase.ledger` as the canonical `/phases/{phase_id}/ledger` reference +before validation/persistence. Add a small "ledger reference" +link/disclosure to `phase_detail.html` showing the raw reference plus a +live-data link when it resolves to this same instance. The existing +Ledger entries table is untouched. + +```task +id: TREV-WP-0015-T05 +status: todo +priority: high +``` + +**`forgejo_hubs` migration** (addendum §4): new migration +`migrations/0007_forgejo_hubs.sql`, table `forgejo_hubs (hub_slug +PRIMARY KEY, service_uri, first_seen_at, updated_at)`, auto-populated on +first sight of a `repo_hub` during Phase registration (mirroring +`ensure_licensor_identity`'s auto-create-on-first-INSERT trigger +pattern in `migrations/0005_licensor_credentials.sql`). Decide during +implementation (not a T02-style human gate, per the addendum) whether +correcting a hub's URI after the fact is a `SECURITY DEFINER` governance +action or a plain `UPDATE`, and document whichever is chosen. + +```task +id: TREV-WP-0015-T06 +status: todo +priority: medium +``` + +**Backfill the three example manifests** (addendum §5): +`examples/pilot-candidates/{net-kingdom-local-identity, +railiance-vergabe-teilnahme, info-tech-canon-service-surface}/manifest.json` +each get `repo_hub`/`repo_hub_uri`/`repo_id`/`repo_name` from their real +Forgejo data (`GET /api/v1/repos/{owner}/{repo}`, same call already +confirmed working for `target-revenue` itself during WP-0012-T02), no +`base_phase_id` (all three are first Phases), and `ledger` set to match +what the Control Plane would now auto-compute. + +```task +id: TREV-WP-0015-T07 +status: todo +priority: high +``` + +**Tests, docs, and closeout**: offline schema/validation tests (T01), +Docker-gated `TestClient` tests for T03's new routes and T04/T05's +changes (extending `tests/test_control_plane_app.py`), a rendering smoke +test that each `specs/policies/`/`specs/profiles/` file actually renders +without error. Update `README.md`'s WP-0015 row and this workplan's +Result sections; run the full offline + Docker-gated suite; fence-count +check before committing any workplan edit, per this project's standing +practice.