diff --git a/README.md b/README.md index 129629a..56ac0a2 100644 --- a/README.md +++ b/README.md @@ -39,6 +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) | **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). @@ -85,7 +86,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–T04 done. **T02**: `milestone_release` gains required `repo_hub`/`repo_hub_uri`/`repo_id`/`repo_name`, `phase.base_phase_id` optional for successive Phases; hub↔URI mapping lives in the hosted Trust Service, not this repo. **T03**: `specs/policies/` + `specs/profiles/` subdirectories (one file per policy/profile, id+revision frontmatter), rendered read-only via a new lightweight server-side markdown route. **T04 accepted 2026-08-03**: registration form drops the `ledger` input (auto-computed), drill-down shows only the raw reference + live-data link. T05 (spec addendum draft) next | +| [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 | diff --git a/specs/PhaseProvenanceSpecAddendum.md b/specs/PhaseProvenanceSpecAddendum.md new file mode 100644 index 0000000..d535e61 --- /dev/null +++ b/specs/PhaseProvenanceSpecAddendum.md @@ -0,0 +1,264 @@ +# Phase Provenance, Ledger Reference, and Policy/Profile Spec-File Addendum + +`workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` T05. +Synthesizes T02–T04's accepted decisions (all accepted; see that +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. + +--- + +## 1. Phase Manifest schema changes (T02) + +`schemas/phase_manifest.schema.json`, `phase.milestone_release`: four new +**required** properties, alongside the two that already exist +(`name`, `source_revision`; `artifact_sha256` stays optional): + +```jsonc +"milestone_release": { + "type": "object", + "required": ["name", "source_revision", "repo_hub", "repo_hub_uri", "repo_id", "repo_name"], + "additionalProperties": false, + "properties": { + "name": { "type": "string" }, + "source_revision": { "type": "string" }, + "artifact_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, + "repo_hub": { + "type": "string", + "pattern": "^[a-z0-9-]+$", + "description": "Stable, human-assigned slug for the Forgejo instance hosting this repo, e.g. \"forgejo-coulomb\". Minted by this project, not read from Forgejo — Forgejo has no instance-level identity endpoint (confirmed live 2026-07-30, /api/v1/nodeinfo -> 404)." + }, + "repo_hub_uri": { + "type": "string", + "format": "uri", + "description": "The Forgejo service's current base URL, e.g. \"https://forgejo.coulomb.social\". Retained alongside repo_hub (not derived from it) so a domain change stays repairable without breaking every Phase's provenance link." + }, + "repo_id": { + "type": "integer", + "minimum": 1, + "description": "Forgejo's own internal numeric repo id (GET /api/v1/repos/{owner}/{repo} -> id). Stable across repo renames, unlike repo_name." + }, + "repo_name": { + "type": "string", + "pattern": "^[\\w.-]+/[\\w.-]+$", + "description": "\"owner/repo\" slug at time of Phase registration, e.g. \"coulomb/target-revenue\". Human-readable; repo_id is authoritative if this ever diverges after a rename." + } + } +} +``` + +`phase`: one new **optional** property, `base_phase_id` — present only +for a successive Phase, absent for a first-ever Phase (no sentinel +value): + +```jsonc +"base_phase_id": { + "type": "string", + "pattern": "^trsl:phase:[a-zA-Z0-9._-]+$", + "description": "The prior Phase this one succeeds (FR-11, Rule 7). Absent for a repo's first-ever Phase." +} +``` + +`phase.ledger` is **unchanged** by this addendum — see §4. + +### Not part of this schema + +The `repo_hub` → `repo_hub_uri` mapping is **not** schema-level or +file-level data in this repo. `target-revenue` is the generic framework, +not a specific deployment's list of repos it monetizes. The mapping is +hosted Trust Service data — see §5. + +--- + +## 2. Degeneration-policy and calculation-model spec files (T03) + +New `specs/policies/` subdirectory, one file per policy, replacing the +current situation where `linear-longstop-v0`'s actual definition is a +subsection (Q7) inside `specs/OpenQuestions-WorkingDefaults.md`, mixed +with many unrelated open questions: + +- `specs/policies/linear-longstop-v0.md` — extracted from Q7's prose + (`R(t) = T0 × clamp((t − t0)/(tL − t0), 0, 1)`, discrete + `remission-credit` entries on a published cadence). Frontmatter: + + ```yaml + --- + policy_id: trsl:policy:linear-longstop-v0@1.0 + title: Linear Longstop v0 + --- + ``` + + `OpenQuestions-WorkingDefaults.md` Q7 becomes a pointer to this file + (the *decision record* — "this is the accepted v1 norm" — stays there; + the policy's own *content* moves out). + +New `specs/profiles/` subdirectory, one file per canonical monetization +profile, splitting `specs/CanonicalMonetizationProfiles.md`'s six +sections into their own files — these already have stable ids used in +real Phase Manifests today (`extensions: ["trsl:extension:development-license@1.0", ...]`), +so the id→file mapping is immediate, not something newly invented: + +- `specs/profiles/development-license.md` +- `specs/profiles/cost-plus-operations.md` +- `specs/profiles/phase-sponsorship.md` +- `specs/profiles/service-with-development-allocation.md` +- `specs/profiles/product-ideation.md` +- `specs/profiles/general-consulting.md` + +Each with frontmatter in the same shape: + +```yaml +--- +extension_id: trsl:extension:development-license@1.0 +title: Development License +--- +``` + +`specs/CanonicalMonetizationProfiles.md` §7 (cross-profile summary) and +§8 (non-goals) stay as the comparison/overview document; the six +per-profile sections (§1–§6) move out. + +`specs/DevelopmentEffortCalculatorConcept.md` requires **no move** — one +file, one model, already a distinct name. Add matching frontmatter for +consistency: + +```yaml +--- +calculator_id: development-effort-calculator-candidate-a +revision: "1.0" +title: Development Effort Calculator — Candidate A +--- +``` + +(No `trsl:...` schema id exists for calculators — this is a +documentation-traceability convention only, since calculators aren't +referenced by id from inside a Phase Manifest the way +`degeneration_policy` is.) + +**Id and revision, built on git internals**: the id is the stable +identifier already in use (with its existing `@version` suffix where +applicable), mapped to exactly one file by naming convention; the +revision/audit trail is that file's own git history +(`git log -- specs/policies/linear-longstop-v0.md`). No new versioning +table, no pinned-commit scheme — nothing beyond what git already +provides. + +### Control Plane rendering + +One new read-only route family, server-side markdown → HTML at request +time (a small Python markdown library — e.g. `markdown` or `mistune` — +not a new build pipeline): + +``` +GET /reference/policies/{slug} +GET /reference/profiles/{slug} +``` + +A plain link next to wherever a policy id already appears +(`phase_detail.html`, `phase_new.html`) — never in-UI editable, matching +every governance-action pattern already established in this project +(credential revocation, extension canonicalization, proposed-entry +review — all view/act, never edit-in-place). + +This deliberately does **not** adopt state-hub's Observable-Framework +static-build + "?" overlay pattern (`~/state-hub/dashboard/src/docs/*.md`) +— confirmed live 2026-07-30 that it's a real static-site generator, a +materially heavier dependency than this repo's existing lightweight +FastAPI+Jinja2 stack needs for six profile pages and one policy page. + +--- + +## 3. Ledger UI treatment (T04) + +- `phase_new.html` drops the `ledger` input entirely. The registration + route (`control_plane.register_phase`, or its caller) sets + `phase.ledger` to the canonical `/phases/{phase_id}/ledger` reference + automatically, before the manifest is validated/persisted — no human + types it in v0. +- `phase_detail.html` gains a small "ledger reference" link/disclosure + (not a new prominent field) showing the raw `ledger` string from the + manifest, plus — only when it resolves to this same Trust Service + instance — a link to `GET /phases/{id}/ledger`'s live JSON. +- The existing Ledger entries table on `phase_detail.html` is + **unaffected** — this addendum only concerns the otherwise-invisible + raw reference string, not the ledger data itself. +- The schema field `phase.ledger` is unchanged (still required, still + federation-ready for a future Phase whose ledger genuinely lives + elsewhere) — this section is a Control Plane UI change only. + +--- + +## 4. Hosted Trust Service: `forgejo_hubs` table + +A new migration (numbered after `0006_control_plane.sql`, so `0007`), +analogous to `licensor_identities` +(`migrations/0005_licensor_credentials.sql`): + +```sql +CREATE TABLE IF NOT EXISTS forgejo_hubs ( + hub_slug text PRIMARY KEY, + service_uri text NOT NULL, + first_seen_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); +``` + +Auto-populated the first time a `repo_hub` is seen during Phase +registration (mirroring `ensure_licensor_identity`'s auto-create-on-first- +INSERT trigger pattern) — no separate onboarding step required. This +table is purely an admin/repair convenience for the hosting layer (e.g. +"this hub's URI changed, update it in one place") — a Phase Manifest +never needs it to be reachable for offline verification, since the +manifest itself always carries `repo_hub_uri`/`repo_name` directly at +registration time (use case 9, `specs/PhaseLifecycleUseCases.md`). + +Whether correcting a hub's URI after the fact should be a governance +action (a `SECURITY DEFINER` function, like `revoke_credential`) or a +plain `UPDATE` is left to the implementation workplan to decide — not +load-bearing enough to need a T02-style human gate here, but flagged so +it isn't silently decided by whichever pattern is fastest to type. + +--- + +## 5. Backfilling the three example manifests + +Once the schema change above lands, `examples/pilot-candidates/*/manifest.json` +(all three still `trsl:phase:draft-*`, never registered) get: + +- `repo_hub`/`repo_hub_uri`/`repo_id`/`repo_name` filled in from each + repo's real Forgejo data (the same `GET /api/v1/repos/{owner}/{repo}` + call already confirmed working for `target-revenue` itself applies + identically to `net-kingdom`, `railiance-apps`/`vergabe-teilnahme`, and + `info-tech-canon`). +- No `base_phase_id` — all three are first-ever Phases for their repos. +- `ledger` set to each candidate's own canonical reference, matching + whatever the Control Plane would auto-compute (§3), for consistency + between examples and real registered Phases. + +--- + +## 6. Suggested implementation task breakdown + +Once this addendum is accepted, file as its own workplan (working title +`TREV-WP-0015` or similar — not created yet, per this task's own charter +of producing a document, not a workplan): + +1. Schema change (§1) + `validation.py`/`tests/` updates. +2. `specs/policies/`, `specs/profiles/` extraction (§2) + + `DevelopmentEffortCalculatorConcept.md` frontmatter. +3. Control Plane reference-rendering route (§2) + linking from + `phase_detail.html`/`phase_new.html`. +4. Ledger UI change (§3) — drop the form field, add the drill-down link. +5. `forgejo_hubs` migration + auto-populate-on-first-registration logic + (§4). +6. Backfill the three example manifests (§5). +7. Tests (offline schema/validation tests for §1, Docker-gated tests for + §4/§5, a rendering smoke test for §2's new routes) and a `README.md`/ + workplan Result update, following this project's existing pattern for + every prior task in this session. 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 9bb52d2..44b1b5b 100644 --- a/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md +++ b/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md @@ -4,11 +4,11 @@ type: workplan title: "Phase provenance, ledger reference, and degeneration-policy modeling" domain: infotech repo: target-revenue -status: active +status: finished owner: claude topic_slug: infotech created: "2026-07-30" -updated: "2026-07-30" +updated: "2026-08-03" state_hub_workstream_id: "763a31ee-85fe-43d0-9040-1e6fd432601c" --- @@ -289,7 +289,7 @@ All four T02–T04 decisions now feed T05's spec addendum draft. ```task id: TREV-WP-0012-T05 -status: todo +status: done priority: high state_hub_task_id: "152b54a6-08a9-4ced-a5f6-d5638d102900" ``` @@ -302,7 +302,17 @@ 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 +**Result:** `specs/PhaseProvenanceSpecAddendum.md` written — six +sections covering the schema diff (§1), the `specs/policies/`/ +`specs/profiles/` extraction with concrete file lists and frontmatter +shapes (§2), the ledger UI change (§3), a new `forgejo_hubs` migration +sketch for the hub-registry decision from T02 (§4), the backfill plan +for the three example manifests (§5), and a suggested implementation +task breakdown (§6) for whatever workplan follows once this addendum is +reviewed. **Not yet accepted** — this is the document to discuss before +any implementation work is filed or started. All five WP-0012 tasks are +now done; this workplan is finished pending that discussion, which +happens outside this workplan's own task list. Use cases 4, 6, and 7 above are bigger than a modeling exercise — they are missing implementation, not missing documentation — and are tracked