From 9886742fa8b5d62bee3816d74f923c39e3814272 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 29 Jul 2026 22:52:52 +0200 Subject: [PATCH] Advance WP-0008: governance, candidate survey, pilot manifests, CLA draft MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit T01: specs/TRSL-Governance.md. Resolves the Licensor-identity question (maintainer decision, 2026-07-29): a single shared Licensor, Binky Hedgehog GmbH, operating as the binky tenant, across all four product lines - not per-product-line. Unblocks (does not itself resolve) the License/CUA arbitral-institution selection now that the Licensor's own jurisdiction is known. Tables versioning/extension-governance/operator- governance status per concept §20, naming open items (compatibility rules, deprecation criteria, conflict-of-interest rule, key-rotation history) rather than silently assuming them solved. T02: specs/PilotPhaseCandidateSurvey.md. Direct repo inspection (hub had no goal data for three of four product lines) plus an Explore-agent survey of all ten railiance-* repos. Two defensible candidates found: NK-WP-0002 Local Identity (net-kingdom, Incremental 10x) and vergabe-teilnahme (railiance-apps, Product-defining 100x, the only genuinely product-shaped deliverable across ten railiance-* repos). coulomb-loop and helix-forge have no candidate, for stated principled reasons (internal tooling; pre-implementation-stage, respectively). T03: examples/pilot-candidates/ - draft, non-binding Phase Manifests for both real candidates, trsl:phase:draft-* ids, empty ledgers, schema-validated, explicit README stating nothing here is authorized to go live. T04: specs/TRSL-ContributorLicenseAgreement-Draft.md, implementing the CLA-not-assignment recommendation from history/260729-TRSL-ContributorRights-Research.md - narrowly scoped to the current Phase's TRSL terms plus its already-declared Future License at Conversion, same preliminary-candidate treatment as the License/CUA V1C1 documents. CONTRIBUTING.md updated to point at it while keeping the external-contribution block in effect until accepted. T05's precondition list updated to reflect what's now resolved, still left todo by design pending the maintainer's own go-live decision. --- CONTRIBUTING.md | 2 +- README.md | 2 +- examples/pilot-candidates/README.md | 31 ++++ .../net-kingdom-local-identity/ledger.json | 1 + .../net-kingdom-local-identity/manifest.json | 28 +++ .../railiance-vergabe-teilnahme/ledger.json | 1 + .../railiance-vergabe-teilnahme/manifest.json | 29 ++++ specs/PilotPhaseCandidateSurvey.md | 158 +++++++++++++++++ .../TRSL-ContributorLicenseAgreement-Draft.md | 159 ++++++++++++++++++ specs/TRSL-Governance.md | 143 ++++++++++++++++ tests/test_pilot_candidate_manifests.py | 35 ++++ ...EV-WP-0008-governance-and-pilot-rollout.md | 96 ++++++++++- 12 files changed, 677 insertions(+), 8 deletions(-) create mode 100644 examples/pilot-candidates/README.md create mode 100644 examples/pilot-candidates/net-kingdom-local-identity/ledger.json create mode 100644 examples/pilot-candidates/net-kingdom-local-identity/manifest.json create mode 100644 examples/pilot-candidates/railiance-vergabe-teilnahme/ledger.json create mode 100644 examples/pilot-candidates/railiance-vergabe-teilnahme/manifest.json create mode 100644 specs/PilotPhaseCandidateSurvey.md create mode 100644 specs/TRSL-ContributorLicenseAgreement-Draft.md create mode 100644 specs/TRSL-Governance.md create mode 100644 tests/test_pilot_candidate_manifests.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ebd195c..7422c42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,7 @@ Pre-conversion software is **source-available**, not OSI Open Source. ## External contributions and governed code -**External contributions are not accepted into any governed Milestone Release** until a contributor-rights instrument (CLA, assignment, or equivalent inbound grant covering both TRSL phase and Future License) is adopted. +**External contributions are not accepted into any governed Milestone Release** until a contributor-rights instrument (CLA, assignment, or equivalent inbound grant covering both TRSL phase and Future License) is adopted. A candidate draft exists at `specs/TRSL-ContributorLicenseAgreement-Draft.md` (`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T04) — it is not yet adopted, and this block remains in effect until a human maintainer explicitly accepts it per that document's own status banner. Documentation-only and schema-only contributions to *this* framework repository may be accepted under the repository LICENSE without that instrument, at maintainer discretion. diff --git a/README.md b/README.md index ff18853..428f845 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ The concept's §13 now defines a **Global Contingency Share Determination Rule** | [TREV-WP-0005](workplans/TREV-WP-0005-enforcement-network-research.md) | Enforcement Network legal feasibility research — **finished**, T10 synthesis accepted 2026-07-29 on the same alpha/beta basis (Japan's Article 12 risk remains explicitly unresolved) | | [TREV-WP-0006](workplans/TREV-WP-0006-trust-service-implementation.md) | Hosted Trust Service reference implementation (PRD Phase 4b) — **finished**, all 9 tasks done (Postgres-backed registries/ledger/metrics/attestation/breach-record, ADR-0002 accepted, onboarding CLI, hosted conformance suite) | | [TREV-WP-0007](workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md) | Degeneration policy + canonical monetization profile catalog — **finished**, all 4 tasks done. `trsl:policy:linear-longstop-v0` confirmed 2026-07-29 as the v1 norm for the first pilot cohort; `progress-paused-longstop-v1` named as the next iteration, not yet adopted | -| [TREV-WP-0008](workplans/TREV-WP-0008-governance-and-pilot-rollout.md) | Governance formalization + pilot rollout across `coulomb-loop`/`net-kingdom`/`helix-forge`/`railiance-*` — active, not yet started; real Phase declarations gated behind T05 | +| [TREV-WP-0008](workplans/TREV-WP-0008-governance-and-pilot-rollout.md) | Governance formalization + pilot rollout across `coulomb-loop`/`net-kingdom`/`helix-forge`/`railiance-*` — active; T01 (Licensor: Binky Hedgehog GmbH), T02 (candidate survey), T03 (draft pilot manifests), T04 (CLA draft) done; T05 (go-live gate, human decision) remains `todo` by design | Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md) diff --git a/examples/pilot-candidates/README.md b/examples/pilot-candidates/README.md new file mode 100644 index 0000000..99f4b7a --- /dev/null +++ b/examples/pilot-candidates/README.md @@ -0,0 +1,31 @@ +# Pilot candidate Phase Manifests — DRAFT, NOT DECLARED + +These manifests are **draft, non-binding worked examples** +(`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T03), following +the pattern established by `examples/phase-001/`. They are structurally +valid and conformance-tested exactly like `examples/phase-001/`, but: + +- **No Commercial Entitlement is for sale under either manifest.** +- **No Development Credit is being tracked for either candidate.** +- **Neither repo's actual License header has been changed to TRSL.** +- `phase.id` uses a `draft-` prefix specifically so it cannot be confused + with a real, declared Phase. + +Built from the two candidates identified with a defensible rationale in +`specs/PilotPhaseCandidateSurvey.md` (T02) — `coulomb-loop` and +`helix-forge` produced no defensible candidate at survey time and are +not represented here. + +**Nothing here is authorized to go live.** That remains gated behind +`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T05, regardless +of how complete or plausible these examples look. + +| Directory | Product line | Candidate deliverable | Indicative Target Multiple | +|---|---|---|---| +| `net-kingdom-local-identity/` | `net-kingdom` | `NK-WP-0002` Local Identity | Incremental (10x) | +| `railiance-vergabe-teilnahme/` | `railiance-*` (`railiance-apps`) | `vergabe-teilnahme` (`RAILIANCE-WP-0002`/`-0014`) | Product-defining (100x) | + +All figures (`initial_target`, `target_basis`) are illustrative +placeholders for this worked-example exercise, not a real costing or +pricing proposal — see `specs/PilotPhaseCandidateSurvey.md` for the +underlying candidate rationale. diff --git a/examples/pilot-candidates/net-kingdom-local-identity/ledger.json b/examples/pilot-candidates/net-kingdom-local-identity/ledger.json new file mode 100644 index 0000000..fe51488 --- /dev/null +++ b/examples/pilot-candidates/net-kingdom-local-identity/ledger.json @@ -0,0 +1 @@ +[] diff --git a/examples/pilot-candidates/net-kingdom-local-identity/manifest.json b/examples/pilot-candidates/net-kingdom-local-identity/manifest.json new file mode 100644 index 0000000..6afd2f4 --- /dev/null +++ b/examples/pilot-candidates/net-kingdom-local-identity/manifest.json @@ -0,0 +1,28 @@ +{ + "framework": "TRF-0.1", + "license": "TRSL-0.1", + "phase": { + "id": "trsl:phase:draft-net-kingdom-local-identity", + "milestone_release": { + "name": "net-kingdom-local-identity-v1 (NK-WP-0002)", + "source_revision": "3890dca" + }, + "initial_target": { + "amount": 200000, + "currency": "EUR" + }, + "target_basis": { + "estimated_effort_days": 20, + "daily_rate": 1000, + "approved_direct_costs": 0, + "target_multiple": 10 + }, + "future_license": "MIT", + "degeneration_policy": "trsl:policy:linear-longstop-v0@1.0", + "longstop_at": "2028-01-01T00:00:00Z", + "ledger": "examples/pilot-candidates/net-kingdom-local-identity/ledger.json" + }, + "extensions": [ + "trsl:extension:development-license@1.0" + ] +} diff --git a/examples/pilot-candidates/railiance-vergabe-teilnahme/ledger.json b/examples/pilot-candidates/railiance-vergabe-teilnahme/ledger.json new file mode 100644 index 0000000..fe51488 --- /dev/null +++ b/examples/pilot-candidates/railiance-vergabe-teilnahme/ledger.json @@ -0,0 +1 @@ +[] diff --git a/examples/pilot-candidates/railiance-vergabe-teilnahme/manifest.json b/examples/pilot-candidates/railiance-vergabe-teilnahme/manifest.json new file mode 100644 index 0000000..bd6dd72 --- /dev/null +++ b/examples/pilot-candidates/railiance-vergabe-teilnahme/manifest.json @@ -0,0 +1,29 @@ +{ + "framework": "TRF-0.1", + "license": "TRSL-0.1", + "phase": { + "id": "trsl:phase:draft-railiance-vergabe-teilnahme", + "milestone_release": { + "name": "vergabe-teilnahme-v1 (RAILIANCE-WP-0002/RAILIANCE-WP-0014)", + "source_revision": "398b0fe" + }, + "initial_target": { + "amount": 3500000, + "currency": "EUR" + }, + "target_basis": { + "estimated_effort_days": 30, + "daily_rate": 1000, + "approved_direct_costs": 5000, + "target_multiple": 100 + }, + "future_license": "Apache-2.0", + "degeneration_policy": "trsl:policy:linear-longstop-v0@1.0", + "longstop_at": "2029-01-01T00:00:00Z", + "ledger": "examples/pilot-candidates/railiance-vergabe-teilnahme/ledger.json" + }, + "extensions": [ + "trsl:extension:development-license@1.0", + "trsl:extension:cost-plus-operations@1.0" + ] +} diff --git a/specs/PilotPhaseCandidateSurvey.md b/specs/PilotPhaseCandidateSurvey.md new file mode 100644 index 0000000..bbdfb4e --- /dev/null +++ b/specs/PilotPhaseCandidateSurvey.md @@ -0,0 +1,158 @@ +# Pilot Phase Candidate Survey + +Status: Draft v0.1 +Date: 2026-07-29 +Workplan: `workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T02 +Feeds: `workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T03 (draft pilot Phase Manifests) +Primary artifacts: `specs/TargetRevenueFrameworkCore.md` §1.4 (Target Multiple) + +Surveys `coulomb-loop`, `net-kingdom`, `helix-forge`, and the +`railiance-*` family for one plausible first Milestone Release candidate +per product line — a bounded, recently- or soon-to-be-completed piece of +work with a defensible Target Multiple classification, not an arbitrary +pick. The state hub's `get_repo_goals` returned no data for +`coulomb-loop`, `net-kingdom`, or `helix-forge` at survey time, so this +relied on direct repo inspection (README/SCOPE.md, `git log`, `workplans/`) +instead, per the task's own fallback instruction. + +**This is a candidate survey, not a Phase declaration.** Nothing here +authorizes any real Phase — that remains gated behind T05. + +--- + +## 1. `coulomb-loop` — no defensible candidate found + +**One-liner:** "Customer engagement repository for Coulomb fleet +self-improvement loops — contracts, rosters, and activity definitions; +not agent runtime" (SCOPE.md). Its own scope explicitly excludes +"application code for Coulomb products" — this repo organizes *how* other +repos get worked on, it does not itself contain a product. + +**Recent activity:** workplan-first agent guidance, instruction +regeneration from state-hub templates, `.repo-classification.yaml` setup — +all internal coordination tooling, not customer-facing capability. + +**Recommendation:** no candidate. Forcing a pick here would violate the +task's own "not an arbitrary pick" instruction — this repo is +infrastructure for *how work happens*, not a governed software capability +a Customer would pay for. Revisit if `coulomb-loop`'s scope changes, or +treat product Phases for Coulomb-managed products as living in those +products' own repos rather than here. + +## 2. `net-kingdom` — candidate: Local Identity (`NK-WP-0002`) + +**One-liner:** "Platform domain for NetKingdom identity and security +services" (SCOPE.md) — a real product domain, unlike `coulomb-loop`. + +**Candidate:** `NK-WP-0002` — "Local Identity: Bootstrap User Store & +Minimal OIDC" (finished 2026-03-05). A zero-dependency, file-based user +management capability deriving the primary user from the Linux identity, +auto-generating test users, and (Stage 3) providing a minimal native OIDC +provider for dev/test use — a standalone, bounded capability a Kubernetes +deployment without a running Keycloak/full IAM stack yet could adopt +independently. + +**Passed over:** +- `NK-WP-0001` (Keycloak SSO/MFA Platform) — status `DEFERRED`, superseded + by `NK-WP-0003` (KeyCape + Authelia + LLDAP). Not a clean "finished" + candidate; the stack it targeted is no longer the deployed one. +- `NET-WP-0020` (OpenBao unseal custody models), `NK-WP-0021` + (activity-core ops/Temporal UI least-privilege SSO) — both finished and + real, but both are *operational hardening of NetKingdom's own + infrastructure* (secrets custody, internal operator access control), not + a bounded capability an external Customer would license. These are + exactly the kind of "internal-infra, necessary but not product-shaped" + work the task's Target Multiple guidance is meant to screen out. +- `NK-WP-0022`/`NK-WP-0023` (railiance01 identity cutover, user-engine + portal integration) — currently `active`, not yet a "finished" candidate. + +**Indicative Target Multiple classification:** **Incremental (10x)** — +NK-WP-0002 is a material, standalone enhancement (bootstrap identity +without a full IAM stack dependency) rather than a net-new platform +(1000x) or mere cost recovery (1x); it is a real, reusable capability, not +a from-scratch new market (100x-class "product-defining" would overstate +a bootstrap utility component). + +## 3. `helix-forge` — no candidate; explicitly pre-product + +**One-liner:** "HelixForge defines a capability-first development +ecosystem for turning human intent into governed, reusable software +capabilities" — but its own SCOPE.md states plainly: **"It is not yet an +application implementation."** + +**Recommendation:** no candidate, and this is not a survey gap — the repo +itself says it is not yet at the implementation stage a Milestone Release +requires. Revisit once HelixForge produces an actual implemented +capability, not its current intent/architecture/vocabulary artifacts. + +## 4. `railiance-*` family — candidate: `vergabe-teilnahme` (`railiance-apps` / `RAILIANCE-WP-0002`) + +Surveyed all ten repos (`railiance-apps`, `-bootstrap` [not found under +this exact name at survey time], `-cluster`, `-enablement`, `-fabric`, +`-forge`, `-hosts`, `-infra`, `-master`, `-platform`). + +**Candidate:** `RAILIANCE-WP-0002` (`railiance-apps`, finished 2026-05-19, +refreshed by `RAILIANCE-WP-0014` finished 2026-07-11) — deployed +`vergabe-teilnahme`, a Django application supporting participation in +German public-sector procurement ("Vergabe") processes, to production at +`https://vergabe-teilnahme.whywhynot.de`, with its own PostgreSQL +database, container registry image, HTTPS/cert-manager TLS, and an +operator runbook. + +**Why this is the strongest candidate across the whole family:** it is +the *only* deliverable found across all ten repos that is genuinely +product-shaped — a discrete, customer-facing application a business that +participates in public tenders could plausibly license or subscribe to. +Everything else surveyed is internal infrastructure necessary to keep the +Railiance stack itself running: + +| Repo | What was found | Why passed over | +|---|---|---| +| `railiance-cluster` | Kubernetes substrate (k3s, Helm, ingress, CNI), most recently a Knative serving install | Infra plumbing, not customer-facing | +| `railiance-enablement` | CI/CD templates, SDKs, buildpacks | Internal developer tooling | +| `railiance-fabric` | Ecosystem graph/registry modeling repo-family relations | Internal ontology/graph plumbing | +| `railiance-forge` | Forgejo/Gitea, registries, Actions runners | Internal build/artifact infra | +| `railiance-hosts` | Legacy Terraform/Ansible server provisioning, being retired in favor of `railiance-infra` | Superseded internal infra | +| `railiance-infra` | Canonical infra substrate (successor to `-hosts`); recent finished work is a Forgejo production migration | Internal ops | +| `railiance-master` | Repo taxonomy, cross-repo ADRs — architecture home, not even code-shaped | Organizational restructuring, not software | +| `railiance-platform` | Shared platform services (Postgres HA, cache, secrets, identity, object storage); recent finished work is a secrets-management extraction boundary | Internal platform plumbing | + +**Indicative Target Multiple classification:** **Product-defining (100x)** +— `vergabe-teilnahme` is a real, market-facing application serving a +specific commercial use case (public-tender participation management), +not merely cost recovery or an incremental internal enhancement; whether +it in fact represents a *new platform* (1000x) depends on ambitions beyond +this survey's scope (e.g., whether it becomes a multi-tenant SaaS offering +vs. a single-deployment tool) — 100x is the defensible default absent +that broader roadmap information. + +--- + +## 5. Summary table for T03 + +| Product line | Candidate | Status | Indicative Target Multiple | +|---|---|---|---| +| `coulomb-loop` | None | — | — | +| `net-kingdom` | `NK-WP-0002` Local Identity | Finished 2026-03-05 | Incremental (10x) | +| `helix-forge` | None (pre-product) | — | — | +| `railiance-*` | `vergabe-teilnahme` (`RAILIANCE-WP-0002`/`-0014`) | Finished 2026-05-19 / refreshed 2026-07-11 | Product-defining (100x) | + +Two of four product lines (`net-kingdom`, `railiance-*`) have a +defensible candidate; two (`coulomb-loop`, `helix-forge`) do not, for +principled reasons stated above, not because the survey was shallow. +T03's draft, non-binding worked Phase Manifest examples should be built +from the two real candidates — inventing manifests for the other two +would misrepresent repos that are not yet at a stage this framework +applies to. + +## 6. Non-goals + +- Declaring any real Phase — gated behind T05 regardless of what this + survey finds. +- Selecting a Target Multiple value with legal or financial finality — the + classifications above are indicative, per `specs/TargetRevenueFrameworkCore.md` + §1.4's own framing ("a product and commercial hypothesis, not an + objectively measurable claim"). +- Re-surveying `coulomb-loop`/`helix-forge` on a schedule — revisit + opportunistically when either repo's own scope changes, not on a fixed + cadence this document sets. diff --git a/specs/TRSL-ContributorLicenseAgreement-Draft.md b/specs/TRSL-ContributorLicenseAgreement-Draft.md new file mode 100644 index 0000000..7b435e1 --- /dev/null +++ b/specs/TRSL-ContributorLicenseAgreement-Draft.md @@ -0,0 +1,159 @@ +# Target Revenue Framework Contributor License Agreement + +**Version 1, Candidate 1 (V1C1)** + +--- + +> **PRELIMINARY CANDIDATE — SUBJECT TO CHANGE — NOT FINAL — DO NOT USE TO ACCEPT REAL CONTRIBUTIONS TO A GOVERNED MILESTONE RELEASE** +> +> This is the first working candidate of the Target Revenue Framework Contributor License Agreement ("**Agreement**" or "**CLA**"), the instrument `CONTRIBUTING.md` and `history/260729-TRSL-ContributorRights-Research.md` §5–§6 both identify as a precondition before any external contribution may be accepted into a governed Milestone Release. It is written as operative agreement text so it can be read and tested against real scenarios — **not** as a final, legally binding, or production-ready document. +> +> This CLA implements `history/260729-TRSL-ContributorRights-Research.md`'s recommendation: a CLA, not copyright assignment, scoped narrowly to (a) the Contribution's use under the Phase's current TRSL terms, and (b) the Contribution's automatic, irrevocable relicensing under that Phase's **already-declared** Future License at its Conversion Event — not an open-ended "any future license" grant, since the Future License is fixed at Phase declaration (working default Q3), not invented later. +> +> Before any candidate of this Agreement can become an official **Version 1.0** template: +> +> 1. it must pass specialist legal review in every jurisdiction where it will be used; **not yet done — see `SCOPE.md` §1's alpha/beta legal-review deferral**, which applies equally to this new document, not only the License/CUA; +> 2. every item listed in **Appendix A — Candidate Notes** below must be resolved or explicitly and knowingly accepted by the Licensor; +> 3. a human maintainer must explicitly accept it, per `CONTRIBUTING.md`'s human-decision-gate policy. +> +> Bracketed placeholders (e.g. `[Project/Licensor Legal Name]`) are normal template blanks to be filled in per deployment; they are distinct from the substantive open items tracked in Appendix A. + +--- + +## 1. Definitions + +Terms defined in `specs/TargetRevenueFrameworkCore.md` §1 (**Phase**, +**Milestone Release**, **Initial Target**, **Development Credit**, +**Remission Credit**, **Outstanding Target**, **Conversion Event**, +**Future License**) carry the same meaning here and are not redefined by +this Agreement. + +**"Contribution"** means any original work of authorship, including +modifications or additions to existing work, intentionally submitted by +You to the Project for inclusion in, or documentation of, a governed +Milestone Release. + +**"Project"** means `[Project/Licensor Legal Name]`, the Licensor for the +Phase(s) the Contribution may be incorporated into. + +**"You" (or "Your")** means the individual or legal entity submitting a +Contribution, and, if an entity, includes all other entities that control, +are controlled by, or are under common control with that entity. + +## 2. Grant of Copyright License (current Phase terms) + +Subject to the terms of this Agreement, You grant to the Project and to +recipients of software distributed under the current Phase's TRSL terms a +perpetual, worldwide, non-exclusive, royalty-free, irrevocable copyright +license to reproduce, prepare derivative works of, publicly display, +publicly perform, sublicense, and distribute Your Contributions as part of +the governed Milestone Release, under the terms of the applicable Phase's +`specs/TargetRevenueSourceLicense-V1C1.md`-governed license text. + +## 3. Grant of Future License Rights (Conversion Event) + +This is the clause `history/260729-TRSL-ContributorRights-Research.md` §2 +identifies as the gap an ordinary DCO does not cover. In addition to +Section 2, You grant to the Project a perpetual, worldwide, non-exclusive, +royalty-free, irrevocable license to relicense Your Contribution, as part +of the governed Milestone Release, under the **Future License already +declared in the applicable Phase Manifest at the time You submit Your +Contribution** (`MIT` or `Apache-2.0`, per working default Q3), effective +automatically upon that Phase's Conversion Event, with no further action +or consent required from You at that time. + +**This grant is intentionally narrow, not open-ended:** it covers only the +specific Future License already fixed in the Phase Manifest governing +Your Contribution at submission time — not "any future license the +Project might later choose." If a later Phase declares a different Future +License, a new Contribution submitted under that later Phase is covered by +this Agreement's grant with respect to *that* Phase's declared Future +License, not retroactively for earlier Contributions. + +## 4. Grant of Patent License + +Subject to the terms of this Agreement, You grant to the Project and to +recipients of software distributed under the applicable Phase's license +terms (both the current TRSL terms and, upon Conversion Event, the +declared Future License) a perpetual, worldwide, non-exclusive, +royalty-free, irrevocable (except as stated in this Section) patent +license to make, have made, use, offer to sell, sell, import, and +otherwise transfer the Contribution, where such license applies only to +patent claims licensable by You that are necessarily infringed by Your +Contribution alone or by combination of Your Contribution with the +Milestone Release to which it was submitted. [Candidate note: modeled on +Apache CLA §5 pattern; termination-on-litigation clause intentionally +omitted from this draft pending legal review — flagged in Appendix A.] + +## 5. Representations + +You represent that: + +- each Contribution is Your original creation, or You have sufficient + rights to submit it under the terms of this Agreement (per Section 6 if + submitted on behalf of an employer or other third party); +- You are legally entitled to grant the licenses in Sections 2–4; +- to Your knowledge, Your Contribution does not violate any third party's + copyrights, patents, or other intellectual property rights, except as + You have disclosed in writing to the Project at the time of submission. + +## 6. Submissions on behalf of a third party + +If Your employer(s) has rights to intellectual property You create, +including Contributions, You represent that You have received permission +to make Contributions on behalf of that employer, that Your employer has +waived such rights for Your Contributions, or that Your employer has +executed a separate corporate CLA with the Project. [Candidate note: a +separate corporate/entity CLA variant is not drafted here — flagged in +Appendix A as a possible future deliverable if entity-scale contribution +becomes relevant.] + +## 7. No obligation + +The Project is under no obligation to accept or incorporate any +Contribution into any Milestone Release. + +## 8. Disclaimer of Warranty + +UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING, YOU PROVIDE +YOUR CONTRIBUTIONS ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS +OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY +WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR +FITNESS FOR A PARTICULAR PURPOSE. + +## 9. Governing law and venue + +[Adopted for alpha/beta 2026-07-29, consistent with License §11.1 and CUA +§18: disputes arising under this Agreement shall be resolved by binding +arbitration, seated at a neutral, arbitration-mature venue (Singapore or +London candidates). The specific arbitral institution and substantive +governing law remain a per-deployment blank pending final selection, now +that the Licensor entity (Binky Hedgehog GmbH, `specs/TRSL-Governance.md` +§1) is known — see `history/260729-TRSL-Jurisdiction-Synthesis.md` §2.] + +## 10. Miscellaneous + +This Agreement is the entire agreement between You and the Project +concerning the Contributions You submit, and supersedes any prior +agreements or understandings regarding the subject matter of this +Agreement, except that this Agreement does not modify or supersede the +terms of any separate Commercial Use Agreement You may have with the +Project in a different capacity (e.g., as a Customer rather than a +contributor). + +--- + +## Appendix A — Candidate Notes (Non-Normative) + +| # | Section | Item | Status | Research basis | +|---|---|---|---|---| +| 1 | §4 | Patent litigation termination clause (Apache CLA §5's usual companion clause) intentionally omitted from this draft | **[LEGAL, OPEN]** | Deliberately deferred rather than guessed at; add only after specialist review confirms the right scope for this framework | +| 2 | §6 | Entity/corporate CLA variant not drafted | **[OPEN]**, separate deliverable if needed | This document covers individual contributors submitting under Section 6's employer-permission model only | +| 3 | §9 | Governing law and venue — institution/substantive law still blank | **[LEGAL, OPEN]** | Same status as License Appendix A item 6 / CUA Appendix A item 1, now unblocked by known Licensor jurisdiction (`specs/TRSL-Governance.md` §1) but not yet selected | +| 4 | (all) | Full specialist legal review in every jurisdiction of intended use | **[LEGAL]** | Deferred per `SCOPE.md` §1's alpha/beta risk-acceptance decision | +| 5 | (all) | No dedicated CLA-specific jurisdiction research performed | **[OPEN]** | `history/260729-TRSL-ContributorRights-Research.md` covered the CLA-vs-assignment structural question, not per-jurisdiction CLA enforceability — a narrower research pass than the License/CUA received | + +**Promotion path:** requires explicit human acceptance before being +treated as adequate for accepting any real external contribution to a +governed Milestone Release, per `CONTRIBUTING.md`'s human-decision-gate +policy — same standard already applied to the License/CUA V1C1 documents. diff --git a/specs/TRSL-Governance.md b/specs/TRSL-Governance.md new file mode 100644 index 0000000..8a0ea61 --- /dev/null +++ b/specs/TRSL-Governance.md @@ -0,0 +1,143 @@ +# TRSL/TRF Governance + +Status: Draft v0.1 +Date: 2026-07-29 +Workplan: `workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T01 +Primary artifacts: `specs/TargetRevenueLicenseConcept.md` §20, `specs/MonetizationExtensionSpecification.md` §4, `specs/CanonicalizationReviewChecklist.md`, `docs/adr/ADR-0002-hosted-trust-service-stack.md` + +Implements concept §20's four governance principles (complexity budget, +versioning, extension governance, operator governance) as concrete, +operative rules for this framework's actual current state — a single +hosted Trust Service instance, one resolved Licensor, and four candidate +product lines — rather than restating §20 in the abstract. + +--- + +## 1. Licensor identity — resolved + +**Decision (maintainer, 2026-07-29):** there is a single Licensor across +all Phases declared under this framework for the foreseeable future: +**Binky Hedgehog GmbH**, operating as the **`binky` tenant** in the +`licensors` table (`migrations/0001_registries.sql`) and across the +`coulomb` Forgejo org's product lines (`coulomb-loop`, `net-kingdom`, +`helix-forge`, the `railiance-*` family). + +**Consequences of this choice, made explicit rather than left implicit:** + +- One Licensor API token (or a small, rotatable set under the same + `licensor_id`) covers all four product lines' Phase registrations and + Ledger appends — there is no per-product-line Licensor isolation at the + Trust Service level; isolation between *Phases* (`TS-FR-8`) still holds, + but not between *product lines*, since they share one Licensor identity. +- Commercial and legal exposure across all four product lines' Phases + nominally attaches to the same legal entity. A dispute, breach + determination (`specs/TargetRevenueSourceLicense-V1C1.md` §7.4), or + Enforcement Action (`specs/EnforcementNetworkConcept.md`) on one + product line's Phase does not legally implicate the others, but it is + the same counterparty's record across all of them — a reputational and + administrative fact worth naming, not a legal one this document + resolves. +- **Now unblocked, not yet decided:** knowing the Licensor entity's own + jurisdiction (Germany, GmbH) is exactly the missing input + `history/260729-TRSL-Jurisdiction-Synthesis.md` §2 flagged before the + arbitral institution and substantive governing law in License §11.1 / + CUA §18 could be filled in from a template blank to an actual value. + This document does not make that selection — it is a distinct, focused + decision for whoever owns the License/CUA templates next, now that the + blocking unknown (Licensor identity) is resolved. +- If this decision changes later (e.g., a product line spins out under + its own entity), each Phase already declared under `binky` remains + governed by `binky` as its Licensor of record — Phase Manifests are + immutable (TSD §3.1), so a Licensor change is prospective only, never + retroactive. + +## 2. Complexity budget (concept §20.1) + +Applied as-is: a proposed addition to the normative core +(`specs/TargetRevenueFrameworkCore.md`, `specs/PhaseManifestSpecification.md`, +`specs/TargetLedgerSpecification.md`, `specs/MonetizationExtensionSpecification.md`) +must pass all three tests — universal, interoperable, trust-critical — or +it belongs in a canonical profile +(`specs/CanonicalMonetizationProfiles.md`), a degeneration policy +(`specs/TargetDegenerationPolicyResearch.md`), an implementation detail +(`docs/adr/`), or a project-specific policy (a single Phase's own Manifest +fields), never the shared core. This is not new policy — WP-0003's own +review process already applied it (e.g., the §1.11 fix rejecting a +broadened core-term-redefinition list) — this section names it as a +standing rule rather than an ad hoc practice. + +## 3. Versioning (concept §20.2) + +Already implemented, not merely planned, across every layer §20.2 names: + +| Layer | Versioning mechanism | Where | +|---|---|---| +| TRSL legal text | `Version 1, Candidate ` in the document header | `specs/TargetRevenueSourceLicense-V1C1.md` | +| Framework core | Dated normative extracts, sourced from the concept doc | `specs/TargetRevenueFrameworkCore.md` et al. | +| Phase Manifest schema | `framework`/`license` semver-like tags in the manifest itself | `schemas/phase_manifest.schema.json` | +| Degeneration policies | `trsl:policy:@` URN | e.g. `trsl:policy:linear-longstop-v0@1.0` | +| Monetization extensions | `trsl:extension:@` URN | `schemas/extension_contract.schema.json` | +| Trust Service protocol | This repository's own commit history + `docs/adr/` decisions | `docs/adr/ADR-0001`, `ADR-0002` | + +**Rule, stated explicitly for the first time here:** a Phase remains +governed by the exact versions it declared at registration +(`phase.framework`, `phase.license`, `phase.degeneration_policy`, +`phase.extensions[]`) unless an explicit, recorded migration is accepted +for that specific Phase — never a silent, framework-wide reinterpretation +that changes an already-registered Phase's terms out from under it. + +## 4. Extension governance (concept §20.3) + +| §20.3 item | Status | +|---|---| +| Registration criteria | `specs/MonetizationExtensionSpecification.md` §3 (conformance rule) + `src/target_revenue/validation.py` — implemented and tested | +| Canonicalization criteria | `specs/CanonicalizationReviewChecklist.md` (WP-0007-T04) — implemented as a checklist, not yet exercised against any real profile | +| Conformance tests | `tests/test_extension_conformance.py`, `tests/test_hosted_conformance.py` — implemented | +| Compatibility rules | **Not yet defined.** No document yet states what happens when a `canonical` extension's own contract needs a breaking change (new major version vs. deprecate-and-replace). Flagged as an open item, §6 below. | +| Deprecation rules | **Partially defined.** `status: deprecated` exists in the schema and is described in §4 of the extension spec ("no longer recommended; existing registrations remain valid evidence") but no document describes *who* may deprecate an extension or under what criteria — same gap pattern as canonicalization had before WP-0007-T04. Flagged, §6. | +| Conflict-of-interest rules | **Not yet defined.** With a single Licensor (§1) reviewing its own extensions for canonicalization, the reviewer and the reviewed party's interests are not separated by default. Flagged, §6. | +| Dispute procedures | Partially covered by `specs/TargetRevenueSourceLicense-V1C1.md` §7 (breach/cure/termination) and `specs/TargetRevenueCommercialUseAgreement-V1C1.md` §9 (breach disclosure), but no procedure exists yet for a dispute *about an extension's canonicalization or deprecation* specifically, as distinct from a dispute about a Phase's own Commercial Use. Flagged, §6. | + +## 5. Operator governance (concept §20.4) + +For the single hosted Trust Service instance +(`workplans/TREV-WP-0006-trust-service-implementation.md`, deployed per +`docs/adr/ADR-0002-hosted-trust-service-stack.md` on `railiance-cluster`): + +| §20.4 disclosure | Current answer | +|---|---| +| Operator identity | Binky Hedgehog GmbH (`binky` tenant) — same entity as the Licensor (§1); this framework does not currently distinguish "who operates the Trust Service" from "who is the Licensor," since both are the same party at this stage | +| Applicable terms | This repository's specs (`specs/TargetRevenueLicenseConcept.md` and its extracts) govern the framework; no separate Trust-Service-specific terms of service exist yet — flagged, §6 | +| Signing keys | `TRF_SIGNING_KEY_HEX` env var, Ed25519, exposed publicly and unauthenticated via `GET /public-key` (`service/app.py`) so any party can verify a signature independent of trusting the operator's access control (`docs/adr/ADR-0002-hosted-trust-service-stack.md`) | +| Key-rotation history | **Not yet tracked.** No mechanism exists yet to publish a history of past signing keys if the current one is ever rotated — a verifier who only has the current public key cannot verify historical entries signed under a prior key. Flagged, §6. | +| Service continuity policy | Single-instance, single-server (ADR-0002's explicitly named risk: "single HostEurope server is a single point of failure... acceptable for alpha/beta pilot scale... must be revisited before any external or higher-availability commitment") | +| Archival and export policy | Every Phase's full evidence package (Manifest, Ledger, Attestation) is exportable via public `GET` endpoints at any time (`specs/TrustServiceProductRequirementsDocument.md` §6) — no separate scheduled-archival process exists beyond "export is always available," which is adequate for offline verifiability (TSD §5) but not a substitute for an operator-side backup/disaster-recovery policy, which is an infrastructure concern for `railiance-cluster`, not this repository | +| Correction and dispute processes | Ledger corrections: `credit-reversal`/`remission-correction`/`administrative-correction-*` entry types (append-only, TSD §3.2). Broader disputes: License §7 / CUA §9. No Trust-Service-specific "I think this record is wrong" process beyond those ledger-level correction types exists yet | +| Framework change process | This repository's own workplan/ADR/human-accept-gate process (`CONTRIBUTING.md`), which is itself the framework change process — there is no separate, more formal process distinct from how this repository already operates | + +## 6. Explicitly open items (not resolved by this document) + +Naming these here — rather than letting them stay implicit — is this +document's actual contribution beyond restating what already exists: + +1. **Extension compatibility/deprecation criteria** (§4): who may deprecate + a canonical extension, and what counts as a breaking vs. non-breaking + change to one. +2. **Conflict-of-interest rule for canonicalization** (§4): with one + Licensor currently reviewing its own extensions, some explicit + acknowledgment or safeguard is warranted before canonicalization + becomes routine — even if the safeguard is initially as simple as + "canonicalization decisions are recorded publicly with named + attribution" (already true per `CanonicalizationReviewChecklist.md` + item 8) rather than a heavier external-review requirement. +3. **Extension/canonicalization-specific dispute procedure**, distinct + from the License/CUA's Commercial-Use-focused dispute provisions. +4. **Signing-key rotation history publication** (§5): no mechanism yet for + a verifier to check a signature made under a since-rotated key. +5. **A Trust-Service-specific terms-of-service document**, separate from + the framework specs themselves. + +None of these block `workplans/TREV-WP-0008-governance-and-pilot-rollout.md` +T02–T04 (repo survey, draft pilot manifests, CLA draft) — they are named +so that T05's go-live gate can weigh them explicitly rather than discover +them as an afterthought once real Phases are already running. diff --git a/tests/test_pilot_candidate_manifests.py b/tests/test_pilot_candidate_manifests.py new file mode 100644 index 0000000..1bc6e5f --- /dev/null +++ b/tests/test_pilot_candidate_manifests.py @@ -0,0 +1,35 @@ +"""Conformance test for the draft pilot-candidate Phase Manifests +(WP-0008-T03, examples/pilot-candidates/). These are non-binding worked +examples, not real Phases, but they must stay schema-conformant like +examples/phase-001/ does. +""" + +from __future__ import annotations + +import json + +import pytest +from conftest import REPO_ROOT + +from target_revenue import validation + +PILOT_CANDIDATES_DIR = REPO_ROOT / "examples" / "pilot-candidates" + + +@pytest.mark.parametrize( + "name", + ["net-kingdom-local-identity", "railiance-vergabe-teilnahme"], +) +def test_pilot_candidate_manifest_is_conformant(name): + manifest = json.loads((PILOT_CANDIDATES_DIR / name / "manifest.json").read_text()) + validation.validate_phase_manifest(manifest) + assert manifest["phase"]["id"].startswith("trsl:phase:draft-") + + +@pytest.mark.parametrize( + "name", + ["net-kingdom-local-identity", "railiance-vergabe-teilnahme"], +) +def test_pilot_candidate_ledger_is_empty_draft_state(name): + ledger = json.loads((PILOT_CANDIDATES_DIR / name / "ledger.json").read_text()) + assert ledger == [], "draft candidates must not carry any real ledger entries" diff --git a/workplans/TREV-WP-0008-governance-and-pilot-rollout.md b/workplans/TREV-WP-0008-governance-and-pilot-rollout.md index 5fe1cf3..d0cad24 100644 --- a/workplans/TREV-WP-0008-governance-and-pilot-rollout.md +++ b/workplans/TREV-WP-0008-governance-and-pilot-rollout.md @@ -40,7 +40,7 @@ T01–T04 must not create pressure to skip T05. ```task id: TREV-WP-0008-T01 -status: todo +status: done priority: high state_hub_task_id: "bae630d7-907b-4eb4-bad4-d72803ccbd33" ``` @@ -61,11 +61,30 @@ multiple product lines depend on them, extension canonicalization review T04's narrower checklist), and dispute/conflict-of-interest handling per concept §20.3–§20.4. +**Result:** `specs/TRSL-Governance.md` produced. **Licensor identity +resolved (maintainer decision, 2026-07-29): a single shared Licensor, +Binky Hedgehog GmbH, operating as the `binky` tenant**, across all four +product lines — not per-product-line. This unblocks (but does not itself +resolve) the License §11.1/CUA §18 arbitral-institution/governing-law +template blank, now that the Licensor's own jurisdiction (Germany) is +known. Documents versioning (already implemented across every layer +§20.2 names — URN `@version` suffixes, document headers, ADRs) and +extension governance status (registration/conformance implemented; +canonicalization checklist implemented via WP-0007-T04; compatibility, +deprecation, and conflict-of-interest rules **not yet defined** — named as +open items, not silently assumed). Operator governance (§20.4) tabulated +against the actual hosted Trust Service instance: signing-key disclosure +and public verification already implemented (WP-0006); key-rotation +history publication, a Trust-Service-specific terms-of-service document, +and an extension-specific dispute procedure are flagged as open, not +blocking T02–T04 but named so T05's go-live gate can weigh them +explicitly. + ## Repo inventory and Phase-candidate survey ```task id: TREV-WP-0008-T02 -status: todo +status: done priority: high state_hub_task_id: "4f4f4922-4bc6-4ff9-a408-b836287186db" ``` @@ -80,11 +99,30 @@ classification (`specs/TargetRevenueFrameworkCore.md` §1.4), not an arbitrary pick. Document why each candidate was chosen and what was passed over. +**Result:** `specs/PilotPhaseCandidateSurvey.md` produced. State hub +`get_repo_goals` returned no data for `coulomb-loop`/`net-kingdom`/ +`helix-forge`, so this used direct repo inspection instead (per the +task's own fallback), including an Explore-agent survey of all ten +`railiance-*` repos. Findings: **`coulomb-loop`** — no candidate; +SCOPE.md explicitly excludes product application code. **`net-kingdom`** +— `NK-WP-0002` Local Identity (finished 2026-03-05), Incremental (10x); +passed over the deferred/superseded `NK-WP-0001` Keycloak plan and two +real-but-internal-ops-hardening finished workplans (`NET-WP-0020`, +`NK-WP-0021`). **`helix-forge`** — no candidate; its own SCOPE.md states +"it is not yet an application implementation." **`railiance-*`** — +`vergabe-teilnahme` (`RAILIANCE-WP-0002`/`-0014`, finished 2026-05-19 / +2026-07-11), a production Django app for German public-tender +participation, Product-defining (100x); the only genuinely product-shaped +deliverable across all ten repos, passing over nine repos' worth of +internal infrastructure (cluster substrate, CI/CD, secrets platform, +architecture taxonomy, etc.). Two of four product lines have a defensible +candidate; two do not, for stated principled reasons, feeding T03. + ## Draft pilot Phase Manifests (non-binding worked examples) ```task id: TREV-WP-0008-T03 -status: todo +status: done priority: high state_hub_task_id: "942943ae-14a2-4f23-888e-6084aa9c6024" ``` @@ -98,11 +136,29 @@ takes effect from these). Choose an applicable Monetization Extension per Phase from `workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md` T03's catalog. +**Result:** `examples/pilot-candidates/` produced, for T02's two real +candidates only (`coulomb-loop`/`helix-forge` had none). Each manifest +uses a `trsl:phase:draft-*` id specifically so it cannot be confused with +a declared Phase, an empty `ledger.json`, and validates cleanly against +`schemas/phase_manifest.schema.json` +(`tests/test_pilot_candidate_manifests.py`, 4 tests). **NetKingdom Local +Identity** (`NK-WP-0002`): 200,000 EUR Initial Target (Incremental 10x), +`development-license` extension, `future_license: MIT`. **Railiance +vergabe-teilnahme**: 3,500,000 EUR Initial Target (Product-defining +100x), `development-license` + `cost-plus-operations` extensions +(reflecting its actual hosted-application delivery model), `future_license: +Apache-2.0`. Both reference the real commit each Milestone Release +finished at (`3890dca`, `398b0fe`) for traceability. A top-level +`examples/pilot-candidates/README.md` states plainly that no Commercial +Entitlement is for sale, no Development Credit is tracked, and neither +repo's actual License header has changed — nothing here is authorized to +go live regardless of how complete it looks (T05 still gates that). + ## Contributor rights instrument (CLA) ```task id: TREV-WP-0008-T04 -status: todo +status: done priority: medium state_hub_task_id: "666a800b-96a7-4664-9448-24af989b57c5" ``` @@ -119,6 +175,23 @@ candidate treatment as the License/CUA V1C1 documents (status banner, Appendix A-style candidate notes) — this is a new legal document, not exempt from that pattern. +**Result:** `specs/TRSL-ContributorLicenseAgreement-Draft.md` produced, +implementing the research's CLA-not-assignment recommendation. §2 grants +rights under the current Phase's TRSL terms; §3 is the clause the +research flagged as the actual gap a plain DCO leaves open — an +irrevocable grant to relicense the Contribution under the Phase's +**already-declared** Future License at Conversion, deliberately narrow +(scoped to the one Future License fixed at the time of submission, not +"any future license"). §4 patent grant modeled on the Apache CLA pattern +with the litigation-termination clause deliberately omitted, flagged +Appendix A item 1 rather than guessed at. Same preliminary-candidate +status banner and Appendix A pattern as the License/CUA V1C1 documents; +governing law (§9) matches their alpha/beta arbitration default, now +citing the resolved Licensor jurisdiction from `specs/TRSL-Governance.md` +§1. `CONTRIBUTING.md` updated to point at this draft while keeping the +external-contribution block in effect until it is actually accepted, not +merely drafted. + ## Go-live gate (human decision) ```task @@ -150,10 +223,21 @@ infrastructure exists. Before acceptance, confirm: Network fee mechanics) are acceptable for that scope — this is not automatically satisfied by the waiver existing in the abstract; - T01's Licensor-identity question is resolved for whichever product - line goes first; + line goes first — **done** (Binky Hedgehog GmbH / `binky` tenant, single + shared Licensor across all product lines, `specs/TRSL-Governance.md` §1); - `workplans/TREV-WP-0006-trust-service-implementation.md` has a working hosted Trust Service, or an explicit interim manual/git-based ledger - process is accepted for the pilot instead. + process is accepted for the pilot instead — **done** (WP-0006 finished, + all 9 tasks, Postgres-backed hosted service per ADR-0002); +- T02's candidate survey and T03's draft manifests exist for the chosen + product line — **done** (`specs/PilotPhaseCandidateSurvey.md`, + `examples/pilot-candidates/`), though drafting a non-binding example + is not the same event as this gate's own acceptance; +- if the chosen Phase expects external contributions before its + Conversion Event, T04's CLA (`specs/TRSL-ContributorLicenseAgreement-Draft.md`) + has been reviewed and, if needed for that Phase, accepted — **drafted, + not yet accepted**; `CONTRIBUTING.md`'s external-contribution block + remains in effect until it is. Once accepted, this task's Result should name which specific repo and Phase go live first — "governance and rollout infrastructure exists" is