From 4496244bb8331748ea2a1d4b80fb2a14bcbe8243 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 28 Jul 2026 18:34:10 +0200 Subject: [PATCH] Adapt specs and workplans to SWOT Stage 0 sequencing Introduce SCOPE, expanded README, CONTRIBUTING, and provisional open-question defaults. Rescope Trust Service work to offline schemas/fold/fixtures, add normative core extraction workplan, and split PRD roadmap Phase 4 into foundation vs hosted service. Sync workplans with State Hub. --- .repo-classification.yaml | 8 +- CONTRIBUTING.md | 46 +++ INTENT.md | 2 +- README.md | 66 ++++- SCOPE.md | 95 ++++++ WORK-RECORDS.md | 21 +- history/260728-SWOT-Assessment.md | 280 ++++++++++++++++++ ...SWOT-Followup-Spec-Workplan-Adaptations.md | 39 +++ spec/TargetRevenueLicenseConcept.md | 4 +- specs/OpenQuestions-WorkingDefaults.md | 221 ++++++++++++++ specs/ProductRequirementsDocument.md | 135 +++++---- specs/TechnicalSpecificationDocument.md | 90 ++++-- ...TREV-WP-0001-license-prior-art-research.md | 31 ++ .../TREV-WP-0002-trust-service-foundation.md | 169 +++++++++++ ...-trust-service-implementation-bootstrap.md | 133 --------- .../TREV-WP-0003-normative-core-extraction.md | 139 +++++++++ 16 files changed, 1252 insertions(+), 227 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 SCOPE.md create mode 100644 history/260728-SWOT-Assessment.md create mode 100644 history/260728-SWOT-Followup-Spec-Workplan-Adaptations.md create mode 100644 specs/OpenQuestions-WorkingDefaults.md create mode 100644 workplans/TREV-WP-0002-trust-service-foundation.md delete mode 100644 workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md create mode 100644 workplans/TREV-WP-0003-normative-core-extraction.md diff --git a/.repo-classification.yaml b/.repo-classification.yaml index 8ca5748..e17af14 100644 --- a/.repo-classification.yaml +++ b/.repo-classification.yaml @@ -7,7 +7,13 @@ repo_classification: domain: infotech secondary_domains: - financials - capability_tags: [] + capability_tags: + - licensing + - monetization-framework + - delayed-open-source + - source-available + - trust-ledger + - development-credits business_stake: - technology - product diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fe86216 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing to target-revenue + +## Repository status + +This repository defines a **framework concept and specifications**. It does not yet provide a production-ready Target Revenue Source License (TRSL) or a production Trust Service. + +**Do not** use draft TRSL language to govern production software or accept customer commercial entitlements under TRF until specialist legal review is complete and SCOPE says otherwise. + +## What contributions are welcome now + +| Kind | Guidance | +| --- | --- | +| Spec and doc improvements | Preferred: clarity, consistency with core terms, open-question research, examples | +| Schemas, pure fold, validators, golden fixtures | Preferred once workplans WP-0002 / WP-0003 are active | +| Prior-art research notes | Prefer updating or linking from WP-0001 deliverables | +| Implementation of a full hosted Trust Service | Out of scope until SCOPE sequencing rules are met | + +## Terminology + +Use the normative terms from `spec/TargetRevenueLicenseConcept.md` §7. Do **not** reintroduce ambiguous synonyms for conversion metrics (e.g. treating total project “revenue captured” as equivalent to Development Credit). + +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. + +Documentation-only and schema-only contributions to *this* framework repository may be accepted under the repository LICENSE without that instrument, at maintainer discretion. + +A Developer Certificate of Origin (DCO) alone is **not** assumed sufficient for dual-phase relicensing of product code; see open questions and WP-0001-T04. + +## Human decision gates + +The following must not be marked complete by agents alone without explicit human accept (comment, decision record, or maintainer message): + +- Non-binding TRSL draft skeleton (WP-0001-T06) +- Library/stack ADR that locks implementation technology (WP-0002-T01) +- Promotion of working defaults into normative core wording + +## Workplans + +Prefer small, hub-linked workplan tasks. Do not register workplans only in the State Hub; write the workplan file under `workplans/` and run consistency sync so local files remain source of truth. + +## Questions + +Start from `README.md` reading order and `SCOPE.md`. Unresolved product questions live in the PRD §14 and `specs/OpenQuestions-WorkingDefaults.md`. diff --git a/INTENT.md b/INTENT.md index d5d7433..f8cbaaf 100755 --- a/INTENT.md +++ b/INTENT.md @@ -125,6 +125,6 @@ The mature framework should be understandable enough for small projects, rigorou This document defines the durable purpose and intended direction of the Target Revenue Framework repository. -**INTENT is stable and aspirational.** `SCOPE.md`, specifications, workplans, and implementation documents should describe what is actually being designed or built at a particular time. A gap between INTENT and current SCOPE is expected while the framework matures and should be treated as a visible maturity signal rather than resolved by weakening this document. +**INTENT is stable and aspirational.** [`SCOPE.md`](SCOPE.md), specifications, workplans, and implementation documents should describe what is actually being designed or built at a particular time. A gap between INTENT and current SCOPE is expected while the framework matures and should be treated as a visible maturity signal rather than resolved by weakening this document. Stage 0 scope, sequencing, and “done enough” criteria are maintained in `SCOPE.md` (as of 2026-07-28: concept + orientation specs + offline foundation; not production legal text or hosted Trust Service). Changes to this file should represent a deliberate shift in what the Target Revenue Framework is meant to become, not ordinary scope evolution, implementation learning, or release planning. diff --git a/README.md b/README.md index 712c76e..bf4ea4c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,67 @@ # target-revenue -The TargetRevenueLicense Framework is a canonical and extensible system for monetizing product exploration, software development, operation, services, consulting, sponsorship and other value-producing activities to drive open source and knowledge creation and evolution. \ No newline at end of file +**Status:** Concept and specification only (Stage 0). Not production legal text. Do not attach TRSL to production software yet. + +The **Target Revenue Framework (TRF)** is a phased software monetization system: a defined development **Phase** accumulates **Development Credit** and **Remission Credit** against an immutable **Initial Target** until the **Milestone Release** automatically converts to a permissive **Future License** (MIT or Apache-2.0). A **Trust Service** publishes manifests, ledgers, extensions, and attestations as factual evidence — it does not decide conversion. + +> Commercial beneficiaries fund the creation and early availability of a software improvement; once the declared target is satisfied, the governed release becomes permissively open source. + +## Terminology guardrail + +Before conversion, software under TRSL is **source-available** with commercial-use restrictions. It is **not** Open Source under the [OSI Open Source Definition](https://opensource.org/osd) (field-of-endeavour non-discrimination). After the Conversion Event, the Milestone Release is available under the declared OSI-style Future License. + +| State | Accurate label | +| --- | --- | +| Pre-conversion, noncommercial | Source-available (permitted uses) | +| Pre-conversion, commercial | Commercially licensed / entitlement required | +| Post-conversion | Open source under Future License | + +## Reading order + +1. [`INTENT.md`](INTENT.md) — durable purpose and design principles +2. [`SCOPE.md`](SCOPE.md) — what is in scope *now* vs later maturity +3. [`spec/TargetRevenueLicenseConcept.md`](spec/TargetRevenueLicenseConcept.md) — normative concept (§1–10 for the kernel) +4. [`specs/ProductRequirementsDocument.md`](specs/ProductRequirementsDocument.md) — goals, FRs, roadmap +5. [`specs/TechnicalSpecificationDocument.md`](specs/TechnicalSpecificationDocument.md) — schema field tables and boundaries +6. [`specs/OpenQuestions-WorkingDefaults.md`](specs/OpenQuestions-WorkingDefaults.md) — provisional Stage 0 defaults + +Exploration transcript (non-normative): [`history/260728-InitialExploration.md`](history/260728-InitialExploration.md) +Program assessment: [`history/260728-SWOT-Assessment.md`](history/260728-SWOT-Assessment.md) + +## Repository layout + +| Path | Role | +| --- | --- | +| `INTENT.md` | Stable purpose (change rarely) | +| `SCOPE.md` | Living Stage 0 scope | +| `spec/` | Normative **concept** source (`TargetRevenueLicenseConcept.md`) | +| `specs/` | Product/tech specs, working defaults, future normative extracts | +| `workplans/` | Active delivery plans | +| `history/` | Dated non-normative exploration and assessments | +| `examples/` | Golden Phase packages (planned; WP-0002) | +| `schemas/` | Machine-readable schemas (planned; WP-0002) | + +**`spec/` vs `specs/`:** The concept document predates the plural `specs/` directory and remains under `spec/` so history and cross-references stay stable. New product/tech artifacts go under `specs/`. Do not move the concept file without a deliberate migration note. + +## Active work + +| Workplan | Focus | +| --- | --- | +| [TREV-WP-0001](workplans/TREV-WP-0001-license-prior-art-research.md) | Prior-art research → non-binding TRSL draft skeleton | +| [TREV-WP-0002](workplans/TREV-WP-0002-trust-service-foundation.md) | Schemas, pure Outstanding Target fold, golden fixture (not full service) | +| [TREV-WP-0003](workplans/TREV-WP-0003-normative-core-extraction.md) | Extract stable normative core docs (PRD Phase 1) | + +Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md) + +## What this repo does not claim yet + +- Final legal license text or enforceable TRSL +- A running production Trust Service +- A finalized degeneration formula (research + working defaults only) +- That any real product Phase is governed by TRF today + +See [`SCOPE.md`](SCOPE.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md). + +## License + +Repository contents are under [MIT No Attribution](LICENSE) unless a file states otherwise. That is the license of *this repository*, not the Target Revenue Source License for third-party software. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..287f8e5 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,95 @@ +# Target Revenue Framework — SCOPE + +**Status:** Living document for Stage 0 +**Authority:** Describes what is actually in design or delivery *now*. +**Counterpart:** [`INTENT.md`](INTENT.md) is stable and aspirational. A gap between INTENT and this file is expected and is a maturity signal, not a defect. + +**Last updated:** 2026-07-28 +**Basis:** SWOT recommendations in `history/260728-SWOT-Assessment.md` + +--- + +## 1. Current maturity + +| Label | Meaning | +| --- | --- | +| **Stage 0** | Concept consolidated; product/tech orientation specs exist; no production legal text; no production Trust Service | +| Trust Service federation | Stages 1–6 from concept §15 are **out of current delivery scope** (design readiness only) | +| Legal TRSL | Research and non-binding draft skeleton only; specialist review required before any real Phase | + +--- + +## 2. In scope now + +### Documentation and specification + +- Maintain INTENT, this SCOPE, concept, PRD, TSD, and working defaults. +- Extract normative core artifacts (PRD Roadmap Phase 1): + - `specs/TargetRevenueFrameworkCore.md` + - `specs/PhaseManifestSpecification.md` + - `specs/TargetLedgerSpecification.md` +- Prior-art research and non-binding `TargetRevenueSourceLicense-Draft.md` skeleton (WP-0001). +- Provisional answers to conversion-critical open questions (`specs/OpenQuestions-WorkingDefaults.md`). +- Degeneration policy research artifact (recommended default for Stage 0 pilots). +- Canonical monetization profiles as documentation (defaults + examples). +- Lightweight contributor policy (`CONTRIBUTING.md`). + +### Runnable specification foundation (not a hosted service) + +- Machine-readable schemas for Phase Manifest, Ledger Entry, Extension Contract, Conversion Attestation. +- Pure, deterministic Outstanding Target fold and offline conformance validators. +- Golden Phase package under `examples/` (concept §23 numbers). +- Optional thin library/CLI for `validate` / `fold` — **no** requirement for multi-tenant hosting, auth productization, or federation protocol. + +### Work system + +- Hub-linked workplans, progress events, and consistency sync for this repo. + +--- + +## 3. Explicitly out of scope now + +| Item | Deferred to | +| --- | --- | +| Production Trust Service (registries, hosted ledger API, metrics product) | After Phase 1 normative docs + schema foundation; dedicated Trust Service PRD | +| Finalized legal license text and commercial agreements | Specialist legal review post draft skeleton | +| Final degeneration formula as irreversible norm | Research + pilot learning | +| Federation Stage 2+ (replication, multi-operator, multi-authority) | PRD Roadmap Phase 6 | +| Multi-stakeholder governance institutions | PRD Roadmap Phase 7 (lightweight draft only if needed) | +| Tax / statutory revenue recognition | Permanently out of framework core (INTENT boundaries) | +| Governing third-party product Phases in production | After legal + Stage 0 package ready | +| Accepting external code into a governed Milestone Release | Until contributor-rights instrument exists | + +--- + +## 4. Sequencing rules (binding for workplans) + +These rules implement SWOT I-05 / I-06 and the PRD roadmap order: + +1. **Normative extraction (WP-0003) and prior-art research (WP-0001)** proceed in parallel with **schema + pure fold + golden fixture (WP-0002)**. +2. **Full Trust Service implementation** (Phase Registry service, hosted append API, Metrics product, multi-user operation) **must not** start until: + - WP-0003 core extract deliverables exist (or are explicitly waived by human decision), and + - Working defaults for Longstop, currency, recognition, and minimum evidence are published. +3. **Human accept gates** (recorded in the workplan or a decision note) are required before treating as done: + - WP-0001-T06 TRSL draft skeleton (legal-sensitive), + - WP-0002 stack/library ADR (if technology is locked), + - Any promotion of working defaults into normative core language. +4. New monetization ideas land as **profiles/extensions**, not core terms, unless they pass the complexity budget (universal / interoperable / trust-critical). + +--- + +## 5. Stage 0 “done enough” signal + +Stage 0 package is acceptable when: + +1. A newcomer can explain the five-verb lifecycle from README + core doc alone. +2. Offline tools validate a golden Phase and recompute Outstanding Target to zero with no network service. +3. Open questions have provisional defaults or explicit “blocked on legal/research” labels. +4. WP-0001 research artifact exists; legal draft is marked non-binding and not used in production. +5. This SCOPE honestly states what is not yet claimed. + +--- + +## 6. Change policy + +Update this file when Stage 0 boundaries change (e.g. first hosted Trust Service pilot authorized, first legal review complete). Do **not** weaken INTENT to match short-term delivery; expand SCOPE when INTENT milestones become active work. diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 148c887..99d5556 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -9,16 +9,23 @@ | Kind | ID | Status | Lane | Source | | --- | --- | --- | --- | --- | | workplan | TREV-WP-0001 | active | — | workplans/TREV-WP-0001-license-prior-art-research.md | -| workplan | TREV-WP-0002 | active | — | workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md | +| workplan | TREV-WP-0002 | active | — | workplans/TREV-WP-0002-trust-service-foundation.md | +| workplan | TREV-WP-0003 | active | — | workplans/TREV-WP-0003-normative-core-extraction.md | | task | TREV-WP-0001-T01 | todo | — | workplans/TREV-WP-0001-license-prior-art-research.md | | task | TREV-WP-0001-T02 | todo | — | workplans/TREV-WP-0001-license-prior-art-research.md | | task | TREV-WP-0001-T03 | todo | — | workplans/TREV-WP-0001-license-prior-art-research.md | | task | TREV-WP-0001-T04 | todo | — | workplans/TREV-WP-0001-license-prior-art-research.md | | task | TREV-WP-0001-T05 | todo | — | workplans/TREV-WP-0001-license-prior-art-research.md | | task | TREV-WP-0001-T06 | todo | — | workplans/TREV-WP-0001-license-prior-art-research.md | -| task | TREV-WP-0002-T01 | todo | — | workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md | -| task | TREV-WP-0002-T02 | todo | — | workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md | -| task | TREV-WP-0002-T03 | todo | — | workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md | -| task | TREV-WP-0002-T04 | todo | — | workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md | -| task | TREV-WP-0002-T05 | todo | — | workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md | -| task | TREV-WP-0002-T06 | todo | — | workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md | +| task | TREV-WP-0002-T01 | todo | — | workplans/TREV-WP-0002-trust-service-foundation.md | +| task | TREV-WP-0002-T02 | todo | — | workplans/TREV-WP-0002-trust-service-foundation.md | +| task | TREV-WP-0002-T03 | todo | — | workplans/TREV-WP-0002-trust-service-foundation.md | +| task | TREV-WP-0002-T04 | todo | — | workplans/TREV-WP-0002-trust-service-foundation.md | +| task | TREV-WP-0002-T05 | todo | — | workplans/TREV-WP-0002-trust-service-foundation.md | +| task | TREV-WP-0002-T06 | todo | — | workplans/TREV-WP-0002-trust-service-foundation.md | +| task | TREV-WP-0003-T01 | todo | — | workplans/TREV-WP-0003-normative-core-extraction.md | +| task | TREV-WP-0003-T02 | todo | — | workplans/TREV-WP-0003-normative-core-extraction.md | +| task | TREV-WP-0003-T03 | todo | — | workplans/TREV-WP-0003-normative-core-extraction.md | +| task | TREV-WP-0003-T04 | todo | — | workplans/TREV-WP-0003-normative-core-extraction.md | +| task | TREV-WP-0003-T05 | todo | — | workplans/TREV-WP-0003-normative-core-extraction.md | +| task | TREV-WP-0003-T06 | todo | — | workplans/TREV-WP-0003-normative-core-extraction.md | diff --git a/history/260728-SWOT-Assessment.md b/history/260728-SWOT-Assessment.md new file mode 100644 index 0000000..2ba6ad2 --- /dev/null +++ b/history/260728-SWOT-Assessment.md @@ -0,0 +1,280 @@ +# SWOT Assessment — target-revenue + +**Date:** 2026-07-28 +**Scope:** Full repository review (concept, specs, workplans, governance metadata, history) +**Repository state:** Documentation-and-specification only; no application source code +**Assessor:** Grok (session review) + +--- + +## 1. Executive summary + +`target-revenue` is a **high-quality concept repository** for the Target Revenue Framework (TRF): a revenue-triggered, delayed-open-source model that pairs a Target Revenue Source License (TRSL) with a Trust Service for phase manifests, ledgers, extensions, and conversion attestations. + +The conceptual kernel is unusually clear for a day-zero effort: small vocabulary, explicit allocation rules, automatic/irrevocable conversion, remission distinct from revenue, and federation-ready data discipline. Product and technical orientation documents (PRD, TSD) already translate that concept into goals, FRs/NFRs, schema field tables, and component boundaries. Two active workplans cover license prior-art research and Trust Service bootstrap; neither has started execution (0/12 tasks done). + +The principal risks are **maturity gap vs. ambition**, **sequencing pressure** (implementation workplan running ahead of normative core extraction), **unresolved design questions** that block a credible MVP, and **structural doc debt** that will slow every subsequent agent and human contributor. + +This assessment is a SWOT of the *repository and program as currently expressed*, not a legal opinion on TRSL enforceability. + +--- + +## 2. Inventory snapshot + +| Path | Role | Lines (approx.) | Maturity | +| --- | --- | --- | --- | +| `INTENT.md` | Durable purpose, users, principles, boundaries | 130 | Strong, stable by design | +| `README.md` | Public entry point | 2 | Minimal | +| `LICENSE` | Repo license (MIT No Attribution) | short | Present | +| `spec/TargetRevenueLicenseConcept.md` | Normative concept (terms, rules, lifecycle) | ~1188 | Concept-complete; trailing artifact (`xxx`) | +| `specs/ProductRequirementsDocument.md` | Product goals, FR/NFR, MVP, roadmap | ~441 | Draft v0.1, strong | +| `specs/TechnicalSpecificationDocument.md` | Schema tables, component boundaries | ~301 | Pre-implementation orientation | +| `history/260728-InitialExploration.md` | Dialogue / ideation transcript | ~1959 | Non-normative foundation | +| `workplans/TREV-WP-0001-…` | Prior-art research for TRSL draft | 6 tasks, all `todo` | Active, well-scoped | +| `workplans/TREV-WP-0002-…` | Trust Service implementation bootstrap | 6 tasks, all `todo` | Active; sequencing concern | +| `WORK-RECORDS.md` / `.custodian-brief.md` | Hub-synced work index | generated | Healthy integration | +| `.repo-classification.yaml` | Domain: infotech (+ financials) | short | Present; empty capability tags | + +**What is not present (and expected for later maturity):** + +- Machine-readable schemas (JSON Schema / OpenAPI / protobuf) +- Any of the 10 MVP deliverables listed in concept §25 / PRD §11.1 +- `SCOPE.md` (referenced by INTENT as the living counterpart to stable INTENT) +- Implementation code, tests, CI, ADRs, CONTRIBUTING +- Legal draft text, degeneration formula, worked example package +- Diagram assets or short “elevator” one-pager beyond INTENT’s one-sentence bargain + +--- + +## 3. SWOT + +### Strengths + +1. **Coherent constitutional core** + Seven-term vocabulary, five-verb lifecycle, nine core rules, and twelve invariants form a teachable kernel (“define → allocate → credit/remit → convert”). That is a genuine product asset, not just prose. + +2. **Correct architectural separations** + License rights vs. Trust Service facts; Development Credit vs. Remission Credit; development monetization vs. operations/services; attestation as evidence not cause. These separations directly attack the usual failure modes of delayed-open and open-core models (discretion, double-counting, fake “revenue captured”). + +3. **Honest non-goals and risk surface** + PRD non-goals, concept §5, and PRD risk table already name the hard problems (discretionary operators, indefinite restriction, extension fragmentation, contributor rights). That reduces strategic self-deception. + +4. **Specification ladder is in place** + Exploration → concept → INTENT → PRD → TSD is a sound stack. TSD field tables with required/recommended/optional tiers and pure-fold Outstanding Target rules are implementation-ready *as orientation*, not as vaporware. + +5. **Extensibility without core explosion** + Six-field monetization extension contract plus “complexity budget” (universal / interoperable / trust-critical) is the right governance reflex for a framework that wants a catalog of profiles. + +6. **Federation readiness is designed in early** + Global URNs, append-only hash chains, signable records, export packages, and staged federation maturity (0–6) avoid a later data-model rewrite—if discipline is kept during the first implementation. + +7. **Operational work system** + Custodian/State Hub workplans with IDs, WORK-RECORDS, and domain classification mean the repo is already legible to multi-agent and multi-session workflows. + +8. **Differentiation narrative** + Relative to BSL/FSL (time-triggered) and simple noncommercial licenses, TRF’s **progress + remission against an immutable development target**, with explicit non-target allocation for ops/services, is a distinctive economic story if it can be made simple enough to adopt. + +--- + +### Weaknesses + +1. **Zero execution progress on stated work** + All 12 tasks across two workplans are `todo`. Concept density is high; delivery evidence is nil. Credibility currently rests entirely on document quality. + +2. **Sequencing mismatch: implementation before normative core** + PRD roadmap places normative extraction (Phase 1), legal draft basis (Phase 2), and profiles/extensions (Phase 3) *before* Trust Service implementation (Phase 4). TREV-WP-0002 bootstraps implementation now, while MVP docs (`TargetRevenueFrameworkCore.md`, ledger/manifest specs, etc.) do not exist. Risk: code freezes provisional field names and forces rework when degeneration, FX, and evidence rules resolve. + +3. **Critical open questions remain open** + Fifteen design questions (concept §24 / PRD §14) include conversion-adjacent items: commercial-use definition, degeneration formula, Longstop relationship, minimum evidence, currency/FX, contributor rights. Without answers (even provisional defaults), neither legal draft nor ledger semantics can be “done enough” for a pilot Phase. + +4. **No machine-checkable contract** + Schemas live as markdown tables and YAML sketches. There is no validator a third party can run offline (despite TSD §5 requiring pure deterministic conformance functions). Drift between concept, PRD, TSD, and future code is currently unguarded. + +5. **Public entry point is inadequate** + `README.md` is a single long sentence. New readers cannot find status, “what to read first,” non-OSI terminology guardrails, or links to PRD/concept. Adoption friction starts at the root file. + +6. **Document topology friction** + - Normative concept under `spec/` (singular) vs. product/tech under `specs/` (plural)—called out in TSD but still a perpetual footgun. + - INTENT references `SCOPE.md`, which does not exist. + - Concept file ends with a stray `xxx` marker (integrity/polish issue). + - TSD §7 tree omits `workplans/`, `spec/`, and hub metadata files. + +7. **MVP is documentation-heavy without a thin “worked package”** + Ten large MVP docs are listed before any runnable example. Missing is a minimal *example phase package* (manifest + sample ledger + fold result + attestation stub) that agents and humans can use as a golden fixture—independent of a full Trust Service. + +8. **Legal and contributor path is acknowledged but empty** + Concept §21 and WP-0001 correctly gate final legal text, but there is no interim CLA/DCO policy sketch, no SPDX `LicenseRef-` stub, and no “do not use in production” banner strength proportional to the risk of premature use. + +9. **Ambition surface vs. single-operator bootstrap** + INTENT’s maturity target (9 items) reaches multi-provider federation and multi-stakeholder governance. Without a ruthless SCOPE for “Stage 0 only,” every session risks working on Stage 6 problems (crypto federation model, multi-authority phases) while Stage 0 definitions remain unfinished. + +10. **Classification / discoverability incomplete** + `.repo-classification.yaml` has empty `capability_tags`. Secondary domain `financials` is correct but not reflected in README or capability language for hub/search tooling. + +11. **No quality automation** + No link checks, markdown lint, schema CI, spell/consistency checks on core terms, or “forbidden synonym” guards (e.g., silently reintroducing “Target Revenue Captured” as the conversion metric). + +12. **Workplan ownership / review model is agent-centric** + Both workplans list `owner: claude`. Fine for bootstrap, but legal research (WP-0001) and stack ADR (WP-0002-T01) need explicit human checkpoint gates that are not yet encoded as workplan milestones or decision records. + +--- + +### Opportunities + +1. **Occupy a clear niche** + Publish TRF as the first well-specified *development-target-triggered* delayed-commons model with a public, verifiable ledger and default zero allocation for operations revenue—directly answering “what payments unlock the code?” + +2. **Ship a reference pilot on a real internal product** + A single Phase on a controlled product (e.g. an ecosystem tool the founder controls) would force degeneration, evidence, and commercial-use definitions to become concrete faster than pure research. + +3. **JSON Schema + golden fixtures as the “spec that runs”** + Extract TSD §3 into schemas and a pure fold library *before* a full service. That delivers NFR-1/NFR-3 value with less surface area than WP-0002’s full bootstrap. + +4. **Canonical profiles as product UX** + Six default profiles with worked numbers (already sketched in concept §11 and §23) can become the marketing and onboarding surface—many users will never read the license kernel. + +5. **Prior-art research as public positioning** + Completing WP-0001 (BSL, FSL, Fair Source, PolyForm, ELv2, SSPL-adjacent, OSI boundaries) yields both legal grounding and a comparison matrix usable for external communication. + +6. **Hub-native multi-agent delivery** + With workplans already hub-linked, the repo can become a showcase for disciplined agent execution (ralph-workplan, fix-consistency) if sequencing is fixed and tasks are sliced to token-budget size. + +7. **Cross-domain framing** + Secondary `financials` classification and ledger/attestation design open doors to auditor, sponsor, and finance-adjacent tooling without changing the core license story. + +8. **Contributor and patent profiles as family productization** + `TRSL-MIT` / `TRSL-ALv2` (already suggested in exploration and concept) can productize Future License choice once patent research (WP-0001-T03) lands. + +--- + +### Threats + +1. **Legal and standard-terms risk** + Automatic conversion, ambiguous “commercial use,” AGB-style clarity duties (e.g. German §307 BGB as flagged in exploration), and cross-border enforceability can invalidate the bargain or scare commercial counsel. Specialist review is mandatory before any real Phase. + +2. **Trust-service capture (perception or fact)** + If operators appear able to delay ledgers, withhold attestations, or soft-edit history, the automatic-conversion promise fails socially even if legal text is pure. Centralized Stage 0 amplifies this perception. + +3. **Complexity / adoption barrier** + Phase manifests, extensions, dual credit types, and evidence tiers may lose independent developers who would accept a simpler BSL-style Change Date. If the kernel is not explainable in one breath *and* operable with defaults, the framework remains theoretical. + +4. **Community and terminology backlash** + Mislabeling pre-conversion software as “Open Source” invites OSI and community rejection. Guardrails exist in docs but not yet in README or contributor templates. + +5. **Premature implementation lock-in** + Building storage and APIs before degeneration, FX, and evidence rules settle creates expensive rewrites or, worse, non-deterministic Outstanding Target implementations in the wild. + +6. **Abandoned-phase reputation risk** + Without a fixed Longstop or reliable remission, unsuccessful Phases look like permanent proprietary licensing with open-source marketing. That is both a fairness threat and a PR threat. + +7. **Operator discontinuity** + If the only Trust Service disappears, users must still recompute conversion from exported packages. Without export tooling and offline fold, discontinuity becomes a license-confidence crisis (open question 13). + +8. **Competitive simplicity** + BSL/FSL/Fair Source already ship usable legal text. TRF’s economic sophistication is an advantage only if accompanied by usable instruments; otherwise adopters will choose “good enough” time triggers. + +9. **Internal scope creep across the founder’s portfolio** + Monetization classes (ideation, consulting, ops) invite encoding company-wide pricing policy into the framework. Complexity-budget violations would bloat the core and slow convergence. + +10. **Agent-driven inconsistency** + Multiple agents editing concept/PRD/TSD/workplans without a term glossary freeze and schema CI can reintroduce synonym drift (“Revenue Credit” vs “Development Credit”) that the framework was designed to eliminate. + +--- + +## 4. Improvements addressing the most relevant weaknesses + +Improvements are ordered by **leverage on trust, correctness, and near-term delivery**. Each item maps to one or more weaknesses above. + +### P0 — Unblock clarity and stop self-inflicted friction (days) + +| # | Improvement | Weaknesses addressed | Concrete action | +| --- | ---: | --- | --- | +| I-01 | **Expand README into an orientation map** | W5, W8, T4 | Status (concept/spec only; not production legal text); one-sentence bargain; terminology guardrail (source-available ≠ OSI Open Source pre-conversion); reading order (INTENT → concept §1–10 → PRD → TSD); links to workplans and open questions; “do not attach TRSL to production code yet.” | +| I-02 | **Add `SCOPE.md` as living counterpart to INTENT** | W6, W9 | Declare current maturity: Stage 0 concept + orientation specs; in-scope now (normative extraction, prior art, golden example package); out-of-scope now (production Trust Service, federation Stage 2+, multi-stakeholder governance). Close the INTENT→SCOPE gap intentionally. | +| I-03 | **Doc hygiene pass** | W6 | Remove trailing `xxx` from concept doc; decide and document `spec/` vs `specs/` policy (keep concept in `spec/` with a root pointer, or migrate with redirects in README); update TSD §7 tree to match reality. | +| I-04 | **Encode human gates on legal/stack decisions** | W12, T1 | In WP-0001 and WP-0002, mark T06 (license skeleton) and T01 (stack ADR) as requiring explicit human accept before downstream tasks claim completion. Prefer decision records under `decisions/` or hub `resolve_decision` when available. | + +### P1 — Fix sequencing and create runnable specification (1–2 weeks) + +| # | Improvement | Weaknesses addressed | Concrete action | +| --- | ---: | --- | --- | +| I-05 | **Resequence or split WP-0002** | W2, W3, T5 | Prefer: (a) pause implementation tasks T02–T06 until Phase 1 normative docs exist; or (b) rewrite WP-0002 as “schema + pure fold library + golden fixture” without service hosting; keep T01 ADR only if needed for that thin library. Align workplan status narrative with PRD Phases 1→4. | +| I-06 | **Extract normative core docs (PRD Phase 1)** | W2, W7 | Produce at minimum: `TargetRevenueFrameworkCore.md`, `PhaseManifestSpecification.md`, `TargetLedgerSpecification.md` by *extracting* concept §7–10, §16–18 and TSD §3—not rewriting. Freeze term glossary and formulas there. | +| I-07 | **Machine-readable schemas + offline validators** | W4, W11, T10 | JSON Schema (or equivalent) for Phase Manifest, Ledger Entry, Extension Contract, Conversion Attestation; pure Outstanding Target fold; CLI or library `validate` / `fold` commands. Makes TSD §5 real. | +| I-08 | **Golden Phase package (concept §23)** | W7, T7 | Directory e.g. `examples/phase-001/` with manifest, ledger entries, expected outstanding series, conversion attestation stub. Wire to automated tests. This is the cheapest credibility boost for NFR-1. | +| I-09 | **Provisional defaults for blocking open questions** | W3, T6 | Publish `specs/OpenQuestions-WorkingDefaults.md` (or PRD appendix) with *non-final* choices: Longstop required yes/no; currency = phase-native only for v0; recognition = payment-settled only; minimum evidence levels; commercial-use pointer to a working definition. Mark each as provisional pending research. Unblocks schema enums and legal skeleton. | + +### P2 — Legal grounding and economic completeness (parallel track) + +| # | Improvement | Weaknesses addressed | Concrete action | +| --- | ---: | --- | --- | +| I-10 | **Execute WP-0001 fully** | W3, W8, O5 | Complete prior-art matrix (T01), terminology guardrails (T02), patent/Future License rec (T03), CLA vs DCO (T04), jurisdiction clarity flags (T05), non-binding `TargetRevenueSourceLicense-Draft.md` skeleton (T06). | +| I-11 | **Degeneration policy research as first-class artifact** | W3, T6 | `TargetDegenerationPolicyResearch.md` with 2–3 candidate formulas (fixed longstop only; linear time remission; progress-sensitive + longstop floor), worked numbers, and a recommended default for Stage 0 pilots. | +| I-12 | **Canonical monetization profiles doc** | W7, O4 | Six profiles with YAML examples, default allocation, and one “gotcha” each (e.g. ops surcharge must not silently count). Becomes onboarding surface. | +| I-13 | **Contributor rights interim policy** | W8, T1 | Even before final CLA: `CONTRIBUTING.md` stating that external contributions are not accepted into governed Milestone Releases until rights instrument exists; DCO optional for docs-only. Prevents accidental unconvertible code. | + +### P3 — Trust, governance, and growth hygiene (after Stage 0 core) + +| # | Improvement | Weaknesses addressed | Concrete action | +| --- | ---: | --- | --- | +| I-14 | **Trust Service PRD before full service code** | W2, T2 | Per original MVP list: `TrustServiceProductRequirementsDocument.md` focused on Stage 0–1 (centralized + public verification/export). Implementation follows schemas + pure fold, not the reverse. | +| I-15 | **Export / discontinuity story** | T7, open Q13 | Specify offline phase evidence package format and operator continuity policy *as docs* even while service is toy-grade. | +| I-16 | **Lightweight CI** | W11, T10 | Link check; glossary consistency (forbidden synonyms); schema validate on `examples/`; markdown structure checks. | +| I-17 | **Capability tags and discovery** | W10 | Fill `.repo-classification.yaml` tags (e.g. licensing, monetization-framework, delayed-open-source, trust-ledger). Reflect in README. | +| I-18 | **Governance sketch (lightweight)** | W9, O6 | Short `TRSL-Governance-Draft.md`: who can change core terms, how extensions get `canonical`, conflict-of-interest when operator is also licensor—enough for Stage 0 honesty, not multi-stakeholder final form. | + +--- + +## 5. Recommended near-term sequence + +```text +1. I-01…I-04 Doc entry + SCOPE + hygiene + human gates +2. I-05 Re-scope WP-0002 so implementation does not outrun norms +3. I-06…I-08 Core extract + JSON Schema + golden example +4. I-09 Working defaults for open questions +5. I-10…I-12 Prior art, degeneration research, canonical profiles (// parallel with 3–4) +6. I-13 CONTRIBUTING / no premature external Phase code +7. I-14…I-18 Trust Service PRD, export story, CI, tags, light governance +8. Only then Full registry/ledger service implementation (original WP-0002 T02–T06 or successor) +``` + +**Success signal for the next milestone (suggested “Stage 0 package”):** + +- A newcomer can explain the five-verb lifecycle from README + core doc alone. +- Offline tools validate a golden Phase and recompute Outstanding Target to zero without any network service. +- Open questions have provisional defaults or explicit “blocked on legal” labels. +- WP-0001 research artifact exists; legal draft is marked non-binding and not used in production. +- SCOPE.md honestly states what is *not* yet claimed. + +--- + +## 6. Overall judgment + +| Dimension | Rating (1–5) | Note | +| --- | ---: | --- | +| Conceptual clarity | 5 | Rarely this clean at concept stage | +| Specification completeness | 3.5 | Strong orientation; missing normative extract + schemas | +| Legal readiness | 1.5 | Correctly deferred; research workplan exists, not executed | +| Implementation readiness | 2 | TSD is enough to start a *library*; not enough for a stable *service* | +| Governance / process | 3 | Hub-integrated workplans; human gates and SCOPE incomplete | +| Adoption readiness | 1.5 | README and example package insufficient for external use | +| Strategic differentiation | 4 | Credible niche if simplicity and trust are preserved | + +**Bottom line:** The repository’s strength is intellectual architecture; its weakness is unfinished operationalization and a slight rush toward Trust Service code before the normative and legal floor is nailed down. The highest-ROI improvements are **orientation (README/SCOPE), resequencing implementation behind extractable schemas and a golden fold example, executing prior-art research, and publishing provisional defaults for conversion-critical open questions.** Do those before expanding federation, multi-provider, or catalog breadth. + +--- + +## 7. Sources reviewed + +- `README.md`, `INTENT.md`, `LICENSE` +- `spec/TargetRevenueLicenseConcept.md` (full) +- `specs/ProductRequirementsDocument.md`, `specs/TechnicalSpecificationDocument.md` +- `history/260728-InitialExploration.md` (structure and conclusions) +- `workplans/TREV-WP-0001-license-prior-art-research.md` +- `workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md` +- `WORK-RECORDS.md`, `.custodian-brief.md`, `.repo-classification.yaml` +- Git history (initial concept → PRD/TSD/workplans → classification/consistency sync) + +--- + +*This document is an assessment artifact under `history/`. It is non-normative and does not amend INTENT, concept, PRD, or TSD.* diff --git a/history/260728-SWOT-Followup-Spec-Workplan-Adaptations.md b/history/260728-SWOT-Followup-Spec-Workplan-Adaptations.md new file mode 100644 index 0000000..42f6b05 --- /dev/null +++ b/history/260728-SWOT-Followup-Spec-Workplan-Adaptations.md @@ -0,0 +1,39 @@ +# SWOT follow-up — specification and workplan adaptations + +**Date:** 2026-07-28 +**Basis:** `history/260728-SWOT-Assessment.md` recommendations I-01…I-18 (doc/scope/sequencing subset) +**Non-normative:** Change log of adaptations; authority remains INTENT / SCOPE / concept / PRD / TSD. + +--- + +## Applied + +| ID | Recommendation | Adaptation | +| --- | --- | --- | +| I-01 | Expand README | Root `README.md` orientation map, terminology guardrail, reading order, layout | +| I-02 | Add SCOPE.md | Stage 0 in/out scope, sequencing rules, done-enough signal | +| I-03 | Doc hygiene | Removed concept trailing `xxx`; documented `spec/` vs `specs/`; TSD §7 tree updated | +| I-04 | Human gates | WP-0001-T06, WP-0002-T01, WP-0003-T06; CONTRIBUTING.md | +| I-05 | Resequence WP-0002 | Renamed/rescoped to schemas + pure fold + golden fixture; hosted service deferred | +| I-06 | Normative core extract | **TREV-WP-0003** created (PRD Phase 1) | +| I-09 | Working defaults | `specs/OpenQuestions-WorkingDefaults.md` | +| I-13 | Contributor interim policy | `CONTRIBUTING.md` | +| I-17 | Capability tags | `.repo-classification.yaml` tags filled (hub advisory warns on non-family tags) | + +## Spec document updates + +- PRD → Draft v0.2: Tier A/B MVP, Phase 4a/4b split, open questions table with working defaults, workplan mapping +- TSD: Stage 0 sequencing, `longstop_at` required, currency reject rule, open technical Q defaults, repo tree +- INTENT: pointer to current SCOPE Stage 0 meaning +- Concept: related-documents header; artifact cleanup + +## Not yet delivered (still workplan tasks) + +- I-07 / I-08 machine schemas + golden package (WP-0002 tasks) +- I-06 extract files themselves (WP-0003 tasks) +- I-10 prior-art execution (WP-0001 tasks) +- I-11 degeneration research doc, I-12 full profiles catalog, I-14–I-16 Trust Service PRD / CI (later) + +## Hub sync + +`make fix-consistency REPO=target-revenue` applied 2026-07-28: WP-0002 title synced, WP-0003 registered with task IDs, WORK-RECORDS and custodian brief regenerated. diff --git a/spec/TargetRevenueLicenseConcept.md b/spec/TargetRevenueLicenseConcept.md index 6c174ea..924a368 100644 --- a/spec/TargetRevenueLicenseConcept.md +++ b/spec/TargetRevenueLicenseConcept.md @@ -5,6 +5,8 @@ **Document status:** Concept draft **Purpose:** Define the conceptual foundation for a revenue-triggered software licensing and monetization framework. +**Related documents:** Living scope in `SCOPE.md`; product requirements in `specs/ProductRequirementsDocument.md`; schema orientation in `specs/TechnicalSpecificationDocument.md`; provisional open-question defaults in `specs/OpenQuestions-WorkingDefaults.md`. Normative extracts under `specs/` (WP-0003) will freeze day-to-day terminology without relocating this file (`spec/` vs `specs/` policy: README / TSD §7). + > The Target Revenue Framework combines a source license and trust service to monetize software development transparently until a defined target is satisfied and the governed release automatically becomes permissively open source. --- @@ -1184,5 +1186,3 @@ The Target Revenue Framework is built around a deliberately small kernel: - one constrained extension interface. This minimal structure allows the framework to remain understandable while supporting a broad and evolving monetization canon. Development licensing funds the protected improvement. Operations monetization pays for operating the capability. Other forms of value creation may be integrated through explicit profiles and extensions. Target degeneration provides an eventual path into the commons when commercial validation is weak. The Trust Service enables consistent learning and adoption through centralization first, while open records and deterministic calculations prepare the framework for later federation. - -xxx diff --git a/specs/OpenQuestions-WorkingDefaults.md b/specs/OpenQuestions-WorkingDefaults.md new file mode 100644 index 0000000..cf49cd9 --- /dev/null +++ b/specs/OpenQuestions-WorkingDefaults.md @@ -0,0 +1,221 @@ +# Open Questions — Stage 0 Working Defaults + +**Status:** Provisional (non-normative until promoted into core specs) +**Date:** 2026-07-28 +**Authority:** Unblocks schema enums, golden fixtures, and draft legal skeleton. Does **not** finalize legal policy. +**Sources:** PRD §14, concept §24, SWOT I-09 +**Promotion rule:** Moving a default into `TargetRevenueFrameworkCore.md` or TRSL draft requires human accept (SCOPE §4). + +--- + +## How to read this document + +| Label | Meaning | +| --- | --- | +| **Working default** | Use this in Stage 0 schemas, examples, and validators | +| **Blocked on research** | No default yet; do not invent in code as if normative | +| **Blocked on legal** | Needs specialist input; skeleton may mark `[LEGAL]` only | + +Each item maps to PRD open question numbers in parentheses. + +--- + +## Q1 — Noncommercial rights during protected Phase (1) + +**Working default (documentation only):** +During a protected Phase, noncommercial users may view source, evaluate, test, and use for personal, research, and educational purposes consistent with a PolyForm-Noncommercial-style scope — exact clause text is **blocked on legal**. + +**Schema impact:** No mandatory machine field beyond Future License and Phase status. +**Not decided:** Contractor-on-behalf-of-enterprise edge cases (see Q2). + +--- + +## Q2 — Definition of commercial use (2) + +**Working default:** +Treat as **commercial use** any use by or for an organization that is not purely personal, academic research, or recognized non-profit educational classroom use — **provisional**, for examples and risk callouts only. + +**Blocked on legal:** Affiliates, contractors, mixed-purpose, public-sector, and internal-tools-only definitions must appear in TRSL draft with objective wording (AGB/clarity risk). + +**Stage 0 practice:** Golden examples assume a paying “commercial entitlement” for any company production use; do not encode a full classifier in the fold library. + +--- + +## Q3 — Future License options (3) + +**Working default:** +Both **MIT** and **Apache-2.0** are allowed `phase.future_license` enum values. Phase authors choose one at publication; default in examples is **MIT**. + +**Patent treatment of pre-conversion phase:** Express patent license for permitted uses is **blocked on legal** (WP-0001-T03). Schemas allow Future License enum only; no separate patent field required in Stage 0. + +--- + +## Q4 — Target Multiple classes (4) + +**Working default:** +`target_multiple` is an **open decimal** ≥ 0. The 0x / 1x / 10x / 100x / 1000x labels are **guidance classes** (concept §7.4), not a closed enum. + +**Stage 0 practice:** Examples use 100. Validators accept any non-negative decimal; may **warn** (not fail) if value is not in `{0,1,10,100,1000}`. + +--- + +## Q5 — Development-cost components in target basis (5) + +**Working default:** +Target basis transparency fields: `estimated_effort_days`, `daily_rate` (or equivalent published rate), `approved_direct_costs`. +`Initial Target = (effort × rate + direct costs) × target_multiple` when basis is fully supplied. + +**Excluded from Stage 0 basis by default:** Marketing, general overhead, unrelated R&D, opportunity cost, and speculative “market value” uplifts not expressed via Target Multiple. + +**Blocked on research/legal:** Employee vs contractor rate disclosure norms; mandatory audit of direct costs. + +--- + +## Q6 — Currency and FX (6) + +**Working default:** +A Phase has **one native currency** (`phase.initial_target.currency`). All ledger entries for that Phase **must** use the same currency in Stage 0. + +**Schema rule:** Reject entry currency mismatches. No FX conversion in the pure fold. + +**Later:** Optional FX extension may be registered; until then multi-currency Phases are out of scope. + +--- + +## Q7 — Progress-sensitive degeneration formula (7) + +**Working default (pilot formula, not final norm):** +Publish a versioned policy id `trsl:policy:linear-longstop-v0` defined as: + +- Remission accrues **only** by time toward a declared **Longstop Date** (see Q8). +- Between Phase activation `t0` and Longstop `tL`, + \( R(t) = T_0 \times \mathrm{clamp}((t - t_0)/(t_L - t_0), 0, 1) \) + with discrete ledger `remission-credit` entries computed on a published schedule (e.g. daily or monthly UTC), **or** a single full remission at longstop for minimal implementations. +- Development Credit does not change the remission schedule in v0 (no progress-sensitive boost/pause yet). + +**Blocked on research:** Progress-sensitive pause when material Development Credit arrives; diversity-of-payers factors. Track in `TargetDegenerationPolicyResearch.md` (planned). + +--- + +## Q8 — Fixed Longstop Date (8) + +**Working default:** +**Every Phase MUST declare a Longstop Date** (or equivalent full-remission instant) in the Phase Manifest for Stage 0 conformance. + +**Schema:** Treat `phase.longstop_at` (ISO 8601) as **Required** for Stage 0 validators (extension of TSD §3.1 recommended fields → required under working defaults). + +**Rationale:** Prevents indefinite restriction if the product hypothesis fails (PRD risk table; concept §13.3). + +--- + +## Q9 — Public metrics mandatory set (9) + +**Working default — mandatory public facts:** + +- Initial Target, currency +- Cumulative Development Credit +- Cumulative Remission Credit +- Outstanding Target +- Conversion status +- Last ledger entry id / checkpoint hash +- Longstop timestamp + +**Recommended:** Development Credit velocity; time since last material Development Credit; forecast conversion date **labeled as forecast only**. + +**Optional:** Contributor diversity counts; confidence ranges. + +--- + +## Q10 — Minimum evidence for Development Credit (10) + +**Working default — tiered evidence references:** + +| Tier | `evidence_reference` | When | +| --- | --- | --- | +| E0 | Opaque internal id (`confidential:…`) | Allowed in Stage 0 fixtures; insufficient for external audit claims | +| E1 | Settled payment reference (processor/id) | Minimum for any public claim of Development Credit in a pilot | +| E2 | Contract + invoice + settlement set | Recommended for disputed or high-value credits | + +**Recognition event (see extension contract):** Working default **`payment-settled`** only. Invoice/order without settlement do not create Development Credit in Stage 0 fold inputs. + +**Blocked on legal:** Audit rights wording and confidential evidence disclosure process. + +--- + +## Q11 — First canonical extensions (11) + +**Working default — Stage 0 catalog targets:** + +1. `development-license` — default development_allocation 100% of settled development fee (net of tax/refunds per extension) +2. `cost-plus-operations` — default development_allocation 0% +3. `phase-sponsorship` — development_allocation **explicitly declared** per transaction +4. `service-with-development-allocation` — default 0%; explicit split when reusable work enters Milestone +5. `product-ideation` — default 0% or declared +6. `general-consulting` — default 0% + +Status `canonical` requires documented review; Stage 0 may ship them as `registered` examples first. + +--- + +## Q12 — Disputes, audits, operator conflicts (12) + +**Working default (process stub):** + +1. Ledger is append-only; disputes create compensating entries, not silent edits. +2. Conversion already triggered remains irrevocable (Rule 9) even if a later dispute reduces Development Credit — shortfall is a commercial/audit matter, not re-restriction. +3. When the Trust Service operator is also a Phase licensor, attestations must be independently re-computable offline; public metrics must not depend on private operator judgment. + +**Blocked on governance:** Full dispute SLA and third-party auditor program (PRD Phase 7). + +--- + +## Q13 — Trust Service discontinuity (13) + +**Working default:** + +- Conversion is a pure function of Manifest + Ledger; offline recompute must remain possible. +- Every Phase SHOULD be exportable as a **phase evidence package** (manifest, ledger chain, extension snapshots, optional attestation). +- Operator failure must not be interpretable as “not converted” if Outstanding Target is already zero. + +**Stage 0 delivery:** Specify package layout in WP-0002 golden example; full archival SLA later. + +--- + +## Q14 — Cryptography / federation protocol (14) + +**Working default for Stage 0 library:** + +- Hash chain: SHA-256 over a canonical serialization of the previous entry (canonicalization algorithm fixed in schema ADR). +- Signatures: **Ed25519** over the same canonical bytes; public keys in a simple key registry file for examples. +- Key rotation: append-only key history document; not a multi-party federation protocol. + +**Blocked on research:** Full federation discovery, threshold attestation, multi-operator conflict resolution. + +--- + +## Q15 — Governance path (15) + +**Working default:** +Founder/maintainer-controlled experimentation under this SCOPE until `TRSL-Governance.md` exists. Core term changes require human accept; extensions may be registered as conformant without being canonical. + +--- + +## Schema checklist derived from defaults + +Stage 0 validators SHOULD enforce: + +1. Phase native currency consistency on all entries. +2. `longstop_at` present on every Phase Manifest. +3. Development Credit entries only with `recognition` consistent with payment-settled inputs (when extension data present). +4. `future_license` ∈ {`MIT`, `Apache-2.0`}. +5. Closed ledger entry type enum from TSD §3.2. +6. Outstanding Target = `max(0, T0 - C - R)` pure fold. +7. Conversion Attestation never required to compute conversion status. + +--- + +## Revision history + +| Date | Change | +| --- | --- | +| 2026-07-28 | Initial working defaults from SWOT I-09 / Stage 0 unblocking | diff --git a/specs/ProductRequirementsDocument.md b/specs/ProductRequirementsDocument.md index 5714376..0272777 100644 --- a/specs/ProductRequirementsDocument.md +++ b/specs/ProductRequirementsDocument.md @@ -1,9 +1,11 @@ # target-revenue — Product Requirements Document -Status: Draft v0.1 +Status: Draft v0.2 Date: 2026-07-28 Owner: target-revenue initiative -Primary artifacts: `INTENT.md`, `spec/TargetRevenueLicenseConcept.md`, `history/260728-InitialExploration.md` +Primary artifacts: `INTENT.md`, `SCOPE.md`, `spec/TargetRevenueLicenseConcept.md`, `history/260728-InitialExploration.md` +Living scope: `SCOPE.md` states Stage 0 in/out boundaries and workplan sequencing (normative extract + schemas/fold before hosted Trust Service). +Working defaults: `specs/OpenQuestions-WorkingDefaults.md` holds provisional answers to §14 items for Stage 0 unblocking; promotion into core requires human accept. Terminology alignment: This document does not redefine terms already normatively defined in `spec/TargetRevenueLicenseConcept.md`. Where a definitive formula, rule, or schema already exists there, this PRD references it rather than restating it with variation. --- @@ -153,11 +155,11 @@ The Trust Service's five core responsibilities — Phase Registry, Extension Reg ### 7.2 Out of scope -- Final legal license text (requires specialist review, §21.5). -- A final degeneration formula (currently an open design question, §24.6–§24.8). +- Final legal license text (requires specialist review, concept §21.5). +- A final degeneration formula (open design question; Stage 0 pilot formula only in `OpenQuestions-WorkingDefaults.md` Q7–Q8). - Tax and statutory accounting treatment. - Any specific product's or repository's actual TRSL Phase declarations — this repository is the framework, not a consumer of it. -- A production implementation of the Trust Service (this document specifies requirements; implementation is a separate workplan). +- A production hosted Trust Service (requirements live here; Stage 0 delivers offline schemas/fold/examples only — see §12 Phase 4 and `SCOPE.md`). --- @@ -327,74 +329,103 @@ The architectural invariant governing every layer: **the license establishes leg ### 11.1 MVP scope -The MVP corresponds to the "Proposed Initial Deliverables" already identified in `spec/TargetRevenueLicenseConcept.md` §25, sequenced as a conceptual and documentation MVP (no production Trust Service implementation required yet): +The MVP corresponds to the "Proposed Initial Deliverables" already identified in `spec/TargetRevenueLicenseConcept.md` §25, sequenced so that **runnable offline specification** lands before a hosted Trust Service: -1. `TargetRevenueFrameworkCore.md` — normative terminology, formulas, invariants, lifecycle (extracting and stabilizing §7–§10 and §22 of the concept doc). -2. `TargetRevenueSourceLicense-Draft.md` — initial legal drafting basis for specialist review. -3. `PhaseManifestSpecification.md` — required vs. recommended vs. optional manifest fields. -4. `TargetLedgerSpecification.md` — entry types, recognition, corrections, signatures, calculations. -5. `TargetDegenerationPolicyResearch.md` — comparative models and candidate formulas. -6. `MonetizationExtensionSpecification.md` — extension contract, registration, conformance, versioning. -7. `CanonicalMonetizationProfiles.md` — the six canonical profiles with worked examples. -8. `TrustServiceProductRequirementsDocument.md` — a dedicated PRD for the registry/ledger/metrics/evidence/attestation service (this document specifies the framework; the Trust Service PRD specifies its implementation). -9. `TrustServiceFederationArchitecture.md` — signed records, replication, discovery, federation. -10. `TRSL-Governance.md` — change process, extension review, disputes, conflicts of interest. +**Tier A — Stage 0 package (current delivery focus; `SCOPE.md` §5):** + +1. `TargetRevenueFrameworkCore.md` — normative terminology, formulas, invariants, lifecycle (extract concept §7–§10, §22) — **WP-0003**. +2. `PhaseManifestSpecification.md` / `TargetLedgerSpecification.md` — field tiers and fold rules — **WP-0003**. +3. Machine-readable schemas + pure Outstanding Target fold + golden Phase package under `examples/` — **WP-0002**. +4. `OpenQuestions-WorkingDefaults.md` — provisional defaults for conversion-critical open questions — **done (provisional)**. +5. `TargetRevenueSourceLicense-Draft.md` — non-binding legal drafting basis — **WP-0001** (human accept gate). +6. `MonetizationExtensionSpecification.md` (or Stage 0 stub) + path to `CanonicalMonetizationProfiles.md`. + +**Tier B — After Stage 0 package:** + +7. `TargetDegenerationPolicyResearch.md` — comparative models; promote beyond linear-longstop-v0 working default. +8. `TrustServiceProductRequirementsDocument.md` — dedicated PRD for hosted registry/ledger/metrics/attestation. +9. Hosted reference Trust Service (FR-8–FR-10) — **successor workplan only** after Tier A and Trust Service PRD. +10. `TrustServiceFederationArchitecture.md` / `TRSL-Governance.md` — federation and multi-stakeholder governance. ### 11.2 MVP non-scope -- A running Trust Service implementation. +- A production hosted Trust Service (Stage 0 offline validators/fold only). - Finalized legal license text. -- A finalized degeneration formula. -- Any concrete product's actual Phase declaration using the framework. +- A finalized degeneration formula (pilot policy id allowed). +- Any concrete third-party product's production Phase declaration. +- External contributions into governed Milestone Releases (`CONTRIBUTING.md`). ### 11.3 MVP acceptance criteria -The MVP is acceptable when a reader (human or agent) can: +**Stage 0 package** is acceptable when a reader (human or agent) can: -- Understand and explain the five-verb lifecycle and seven-term core vocabulary without consulting external sources. -- Construct a valid example Phase Manifest, ledger, and Conversion Attestation using only the published schemas. -- Classify a novel monetization idea as fitting an existing canonical profile or requiring a new conformant extension. -- Identify, for any given payment, whether and how much Development Credit it would generate under the canonical defaults. -- Trace why a specific conversion decision (or non-decision) is correct using only the Phase Manifest and ledger, without needing Trust Service discretion. +- Understand and explain the five-verb lifecycle and seven-term core vocabulary from README + core extract without external sources. +- Construct and **offline-validate** a Phase Manifest, ledger, and optional Conversion Attestation using published schemas and the golden example. +- Recompute Outstanding Target to zero for the golden Phase with no network service and without requiring an attestation file. +- Classify a novel monetization idea as fitting an existing canonical profile or requiring a new conformant extension (once profiles doc or stub exists). +- Identify, for any given payment, whether and how much Development Credit it would generate under the canonical/working defaults. +- Trace why a specific conversion decision (or non-decision) is correct using only the Phase Manifest and ledger, without Trust Service discretion. --- ## 12. Roadmap -### Phase 0 — Concept consolidation (this repository, current state) +Workplan mapping (see `workplans/`, `SCOPE.md` §4): -- `INTENT.md` and `spec/TargetRevenueLicenseConcept.md` established. -- This PRD translates the concept into product goals, scope, and requirements. +| Roadmap phase | Workplan / artifact | +| --- | --- | +| Phase 0 | Concept + this PRD + TSD + SCOPE + working defaults | +| Phase 1 | **TREV-WP-0003** normative core extraction | +| Phase 2 | **TREV-WP-0001** prior art + TRSL draft skeleton (human gate) | +| Phase 3 | Extension/profile docs (WP-0003-T04 stub; full catalog follow-on) | +| Phase 4a | **TREV-WP-0002** schemas, pure fold, golden fixture (not hosted service) | +| Phase 4b | Trust Service PRD + hosted reference implementation (future workplan) | +| Phase 5+ | Degeneration research promotion, federation, governance | -### Phase 1 — Normative core extraction +### Phase 0 — Concept consolidation (largely complete) + +- `INTENT.md`, `SCOPE.md`, and `spec/TargetRevenueLicenseConcept.md` established. +- This PRD and TSD translate the concept into product goals, requirements, and schema orientation. +- Stage 0 working defaults published; SWOT assessment under `history/260728-SWOT-Assessment.md`. + +### Phase 1 — Normative core extraction (active — WP-0003) - Produce `TargetRevenueFrameworkCore.md`, `PhaseManifestSpecification.md`, `TargetLedgerSpecification.md` as stable, versioned normative documents distinct from the exploratory concept draft. -### Phase 2 — Legal drafting basis +### Phase 2 — Legal drafting basis (active — WP-0001) -- Produce `TargetRevenueSourceLicense-Draft.md` for specialist legal review (automatic conditional grants, standard-terms law, contributor rights, cross-border enforceability — §21.5). +- Produce `TargetRevenueSourceLicense-Draft.md` for specialist legal review (automatic conditional grants, standard-terms law, contributor rights, cross-border enforceability — concept §21.5). +- Human accept required before marking draft skeleton complete. ### Phase 3 — Extension and profile catalog - Produce `MonetizationExtensionSpecification.md` and `CanonicalMonetizationProfiles.md`. -- Resolve open questions on multiplier-class definitions and minimum evidence requirements (§24.4–§24.10). +- Working defaults already list Stage 0 extension catalog targets and evidence tiers; research may refine (§14 items 4, 10, 11). -### Phase 4 — Trust Service specification and reference implementation +### Phase 4a — Runnable specification foundation (active — WP-0002) + +- Machine-readable schemas, pure Outstanding Target fold, offline validators, golden Phase package. +- Conversion always recomputable without attestation or network service. + +### Phase 4b — Hosted Trust Service (blocked until Phase 1 + 4a Stage 0 signal) - Produce `TrustServiceProductRequirementsDocument.md`. - Implement a centralized reference Trust Service satisfying FR-8–FR-10. +- Must not start under WP-0002; use a successor workplan after SCOPE Stage 0 “done enough” signal. ### Phase 5 — Degeneration policy resolution - Produce `TargetDegenerationPolicyResearch.md`; resolve the Longstop-vs-progress-decay relationship (§13.3, §24.7–24.8). +- Stage 0 pilot: `trsl:policy:linear-longstop-v0` + mandatory Longstop (`OpenQuestions-WorkingDefaults.md` Q7–Q8). ### Phase 6 — Federation path -- Produce `TrustServiceFederationArchitecture.md`; advance through Stage 1 (public verification) toward Stage 2+ (§15). +- Produce `TrustServiceFederationArchitecture.md`; advance through Stage 1 (public verification) toward Stage 2+ (concept §15). +- Out of current SCOPE for delivery; design readiness only. ### Phase 7 — Governance formalization -- Produce `TRSL-Governance.md` covering change process, dispute handling, and conflict-of-interest rules (§20.3–§20.4). +- Produce `TRSL-Governance.md` covering change process, dispute handling, and conflict-of-interest rules (concept §20.3–§20.4). --- @@ -414,23 +445,25 @@ The MVP is acceptable when a reader (human or agent) can: ## 14. Open questions -Carried forward from `spec/TargetRevenueLicenseConcept.md` §24, unresolved by this PRD: +Carried forward from `spec/TargetRevenueLicenseConcept.md` §24. **Provisional Stage 0 answers** live in `specs/OpenQuestions-WorkingDefaults.md` and do not close these questions permanently. -1. What precise rights should noncommercial users receive during a protected Phase? -2. How should "commercial use" be defined across enterprises, contractors, affiliates, research organizations, and mixed-purpose use? -3. Should MIT, Apache-2.0, or both be canonical Future License options for a given Phase? -4. How should the 0x/1x/10x/100x/1000x Target Multiple classes be defined and justified in practice? -5. Which development-cost components may enter the target basis? -6. How should currency and foreign-exchange conversion be handled in the ledger? -7. What is the simplest progress-sensitive degeneration formula? -8. Should every Phase have a fixed Longstop Date in addition to progress-based degeneration? -9. Which public metrics are mandatory, recommended, or optional? -10. What minimum evidence is required to recognize a Development Credit? -11. Which extensions should be canonical in the first release? -12. How are disputes, audits, corrections, and operator conflicts of interest handled procedurally? -13. How can Trust Service discontinuity be handled without impairing already-triggered license conversions? -14. What cryptographic and protocol model best supports later federation? -15. What governance path moves the framework from founder-controlled experimentation to a credible multi-stakeholder standard? +| # | Question | Stage 0 working default (summary) | +| --- | --- | --- | +| 1 | Noncommercial rights during protected Phase? | Doc-level PolyForm-like scope; clause text blocked on legal | +| 2 | Definition of commercial use? | Provisional org-production heuristic; legal definition blocked | +| 3 | MIT, Apache-2.0, or both? | **Both** allowed; examples default MIT | +| 4 | Target Multiple classes? | Open decimal; 0/1/10/100/1000 as guidance | +| 5 | Cost components in target basis? | Effort × rate + direct costs; exclude marketing/overhead by default | +| 6 | Currency / FX? | **Single native currency per Phase**; reject mismatches | +| 7 | Progress-sensitive degeneration? | Pilot **linear-longstop-v0** only; progress-sensitive blocked on research | +| 8 | Fixed Longstop? | **Required** on every Phase Manifest for Stage 0 | +| 9 | Public metrics? | Mandatory target/credit/outstanding/status/longstop set | +| 10 | Minimum Development Credit evidence? | payment-settled; tiers E0–E2 | +| 11 | First canonical extensions? | Six named catalog targets; may start as registered | +| 12 | Disputes / operator conflict? | Append-only + irrevocable conversion; full SLA later | +| 13 | Trust Service discontinuity? | Offline recompute + exportable phase evidence package | +| 14 | Crypto / federation protocol? | SHA-256 chain + Ed25519 for Stage 0; federation later | +| 15 | Governance path? | Maintainer-controlled until TRSL-Governance.md | --- diff --git a/specs/TechnicalSpecificationDocument.md b/specs/TechnicalSpecificationDocument.md index 6f4a1c2..42aabde 100644 --- a/specs/TechnicalSpecificationDocument.md +++ b/specs/TechnicalSpecificationDocument.md @@ -20,7 +20,9 @@ It: * makes explicit what is **normative now**, what is **deferred to later specification work**, and what is **intentionally left open**; * avoids encoding legal text, pricing decisions, or a fixed technology stack — those belong to the Legal Layer, canonical profiles, and future ADRs respectively. -Where a term, formula, or rule is already normatively defined in `spec/TargetRevenueLicenseConcept.md`, this document references it rather than restating it with variation. Where the PRD leaves a question open (PRD §14), this TSD does not resolve it by implication. +Where a term, formula, or rule is already normatively defined in `spec/TargetRevenueLicenseConcept.md`, this document references it rather than restating it with variation. Where the PRD leaves a question open (PRD §14), this TSD does not resolve it by implication unless `specs/OpenQuestions-WorkingDefaults.md` states a **Stage 0 working default** for schema unblocking (those defaults remain provisional until human promotion into core specs). + +**Sequencing (SCOPE.md):** Stage 0 technical delivery is offline schemas, pure fold, and golden fixtures (**WP-0002**), not a hosted Trust Service. Hosted registries and multi-user ledger APIs are deferred to PRD Phase 4b. --- @@ -28,17 +30,25 @@ Where a term, formula, or rule is already normatively defined in `spec/TargetRev The Target Revenue Framework, as it exists in this repository, is **currently a specification and schema artifact set**, not a running system. Two composition states apply: -### 1.1 Current state — documentation and schema repository +### 1.1 Current state — documentation and Stage 0 foundation * `INTENT.md` — durable purpose and strategic boundaries. +* `SCOPE.md` — living Stage 0 in/out scope and sequencing rules. * `spec/TargetRevenueLicenseConcept.md` — normative concept: terminology, formulas, rules, lifecycle. * `specs/ProductRequirementsDocument.md` — product goals, scope, functional/non-functional requirements. * `specs/TechnicalSpecificationDocument.md` (this document) — schema and component-boundary orientation. -* `history/` — dated exploration transcripts, non-normative. +* `specs/OpenQuestions-WorkingDefaults.md` — provisional Stage 0 defaults for open questions. +* `workplans/` — TREV-WP-0001 (legal research), TREV-WP-0002 (schemas/fold), TREV-WP-0003 (core extract). +* `history/` — dated exploration and assessments, non-normative. +* Planned by WP-0002: `schemas/`, `examples/` (machine-readable contracts + golden Phase). -### 1.2 Target future state — reference Trust Service +### 1.2 Near-term target — offline runnable specification (PRD Phase 4a) -A centralized reference implementation (PRD §11.1 item 8, Roadmap Phase 4) providing the Phase Registry, Extension Registry, Target Ledger, Metrics, and Conversion Attestation responsibilities defined in `spec/TargetRevenueLicenseConcept.md` §14. This TSD specifies the **data model and component boundaries** that implementation must satisfy; it does not select a language, storage engine, or hosting model. +JSON Schema (or equivalent), pure Outstanding Target fold, offline validators, and golden fixtures. No requirement for multi-tenant hosting. Conversion status must be computable without network services or attestation files. + +### 1.3 Later target — reference Trust Service (PRD Phase 4b) + +A centralized reference implementation providing the Phase Registry, Extension Registry, Target Ledger, Metrics, and Conversion Attestation responsibilities defined in `spec/TargetRevenueLicenseConcept.md` §14. This TSD specifies the **data model and component boundaries** that implementation must satisfy; it does not select a language, storage engine, or hosting model. Hosted implementation is **out of scope for WP-0002**. --- @@ -86,15 +96,17 @@ The following schemas formalize the YAML sketches already present in `spec/Targe | `phase.target_basis.daily_rate` | decimal | Recommended | | | `phase.target_basis.approved_direct_costs` | decimal | Recommended | | | `phase.target_basis.target_multiple` | decimal | Recommended | One of the indicative classes (PRD §6.1) or a declared custom value. | -| `phase.future_license` | enum (`MIT`, `Apache-2.0`, ...) | Required | | -| `phase.degeneration_policy` | string (URN, `trsl:policy:@`) | Required | | -| `phase.ledger` | URL | Required | Location of the authoritative Target Ledger for this Phase. | +| `phase.future_license` | enum (`MIT`, `Apache-2.0`) | Required | Stage 0 closed set per working default Q3; additional Future Licenses require core revision. | +| `phase.degeneration_policy` | string (URN, `trsl:policy:@`) | Required | Stage 0 pilot: `trsl:policy:linear-longstop-v0` (working default Q7). | +| `phase.longstop_at` | ISO 8601 timestamp | Required (Stage 0) | Working default Q8: every Phase must declare a full-remission / maximum-protection instant. Promote to permanent core via WP-0003 extract + human accept. | +| `phase.ledger` | URL or path URI | Required | Location of the authoritative Target Ledger for this Phase (may be relative path in offline packages). | | `extensions[]` | list of `trsl:extension:@` | Optional | Applicable monetization profiles/extensions for this Phase. | **Validation rules:** -- A manifest missing any Required field MUST be rejected at registration (not merely flagged). +- A manifest missing any Required field MUST be rejected at registration or offline validation (not merely flagged). - `phase.initial_target.amount` MUST NOT decrease or increase after first publication except through a versioned, historically-visible correction record distinct from ordinary Remission Credit. - `phase.id` MUST be immutable and MUST NOT be reused across Phases, including a superseded or abandoned Phase. +- `entry.currency` for all ledger entries MUST match `phase.initial_target.currency` in Stage 0 (working default Q6); FX is out of scope for the pure fold. ### 3.2 Target Ledger Entry @@ -228,27 +240,39 @@ No schema field may be optional if its absence would make the Conversion Event's ```text target-revenue/ ├── INTENT.md +├── SCOPE.md ├── README.md +├── CONTRIBUTING.md ├── LICENSE ├── history/ -│ └── 260728-InitialExploration.md -└── specs/ - ├── ProductRequirementsDocument.md - ├── TechnicalSpecificationDocument.md (this document) - └── (near-term, per PRD §11.1 MVP list:) - ├── TargetRevenueFrameworkCore.md - ├── TargetRevenueSourceLicense-Draft.md - ├── PhaseManifestSpecification.md - ├── TargetLedgerSpecification.md - ├── TargetDegenerationPolicyResearch.md - ├── MonetizationExtensionSpecification.md - ├── CanonicalMonetizationProfiles.md - ├── TrustServiceProductRequirementsDocument.md - ├── TrustServiceFederationArchitecture.md - └── TRSL-Governance.md +│ ├── 260728-InitialExploration.md +│ └── 260728-SWOT-Assessment.md +├── spec/ +│ └── TargetRevenueLicenseConcept.md # normative concept (singular path, stable) +├── specs/ +│ ├── ProductRequirementsDocument.md +│ ├── TechnicalSpecificationDocument.md # this document +│ ├── OpenQuestions-WorkingDefaults.md +│ └── (near-term extracts / drafts:) +│ ├── TargetRevenueFrameworkCore.md # WP-0003 +│ ├── PhaseManifestSpecification.md # WP-0003 +│ ├── TargetLedgerSpecification.md # WP-0003 +│ ├── MonetizationExtensionSpecification.md +│ ├── TargetRevenueSourceLicense-Draft.md # WP-0001 +│ ├── CanonicalMonetizationProfiles.md +│ ├── TargetDegenerationPolicyResearch.md +│ ├── TrustServiceProductRequirementsDocument.md # before hosted service +│ ├── TrustServiceFederationArchitecture.md +│ └── TRSL-Governance.md +├── workplans/ +│ ├── TREV-WP-0001-license-prior-art-research.md +│ ├── TREV-WP-0002-trust-service-foundation.md +│ └── TREV-WP-0003-normative-core-extraction.md +├── schemas/ # planned — WP-0002 +└── examples/ # planned — WP-0002 golden Phase package ``` -Note that `spec/TargetRevenueLicenseConcept.md` (singular `spec/`) predates the `specs/` directory established by the PRD and this TSD; it remains the normative concept source and is referenced, not moved, to preserve its history. +**`spec/` vs `specs/` policy:** The concept document remains under singular `spec/` so git history and existing citations stay valid. New product, technical, research, and extracted normative artifacts go under plural `specs/`. Do not relocate the concept file without an explicit migration note in README and this section. --- @@ -268,13 +292,17 @@ Any future inclusion of these concerns requires a PRD revision or an explicit AD ## 9. Open Technical Questions -Carried forward from `specs/ProductRequirementsDocument.md` §14 and narrowed to schema-level impact: +Carried forward from `specs/ProductRequirementsDocument.md` §14 and narrowed to schema-level impact. Stage 0 working defaults (provisional) from `OpenQuestions-WorkingDefaults.md`: -1. Should `entry.currency` mismatches across a Phase's entries be rejected outright, or resolved via a declared FX-rate extension field? -2. Should `phase.target_basis.target_multiple` be a closed enum (the five indicative classes) or an open decimal with the classes as guidance only? -3. What is the minimum `evidence.requirement` string grammar — free text, a controlled vocabulary, or a reference to an external evidence schema? -4. Should `extension.status` transitions (`registered` → `canonical`) be recorded as their own ledger-like append-only history, or as mutable registry metadata outside the Target Ledger's append-only guarantee? -5. What signature scheme (and key-rotation record format) should `entry.signature` and `attestation.signature` assume, given the federation-readiness requirement in §6.3? +| # | Question | Stage 0 working default | +| --- | --- | --- | +| 1 | Currency mismatches vs FX extension? | **Reject** mismatches; single native currency; no FX in fold | +| 2 | `target_multiple` closed enum or open decimal? | **Open decimal**; classes are guidance; optional warn | +| 3 | `evidence.requirement` grammar? | Free text or short tier tag (E0–E2) until controlled vocab | +| 4 | `extension.status` history? | Mutable registry metadata outside Target Ledger for Stage 0 | +| 5 | Signature scheme / key rotation? | **SHA-256** chain + **Ed25519** example signatures; append-only key history file | + +Unresolved beyond Stage 0: progress-sensitive degeneration parameters, federation discovery, multi-authority attestation. --- diff --git a/workplans/TREV-WP-0001-license-prior-art-research.md b/workplans/TREV-WP-0001-license-prior-art-research.md index 5b95cec..c282195 100644 --- a/workplans/TREV-WP-0001-license-prior-art-research.md +++ b/workplans/TREV-WP-0001-license-prior-art-research.md @@ -29,6 +29,16 @@ This workplan does **not** produce final legal text. It produces the research basis and an initial non-binding draft skeleton for specialist review, per `specs/TechnicalSpecificationDocument.md` §8 (out-of-scope reinforcement). +**Sequencing:** Runs in parallel with WP-0003 (normative core extract) and +WP-0002 (schemas / pure fold). Does not depend on a hosted Trust Service. +Stage 0 terminology and Future License enum defaults are in +`specs/OpenQuestions-WorkingDefaults.md` (Q1–Q3, Q15); refine or challenge +them with research evidence rather than silently inventing alternatives. + +**Human gate:** Task T06 (TRSL draft skeleton) MUST NOT be marked `done` +without explicit human accept (SCOPE §4, CONTRIBUTING.md). Agents may +prepare the draft and leave status `todo` or note “ready for human accept.” + ## Survey delayed-open-source and source-available license models ```task @@ -48,6 +58,8 @@ wording, and known criticisms or disputes. Record findings so they can be diffed directly against TRSL's Phase/Target/Conversion model in `spec/TargetRevenueLicenseConcept.md` §7, §10, §18. +**Deliverable path (suggested):** `history/` or `specs/research/TRSL-PriorArt-Survey.md`. + ## Survey OSI Open Source Definition and Fair Source boundary framing ```task @@ -65,6 +77,10 @@ OSI-approved license" framing applies or should be adapted. Produce recommended terminology guardrails (source-available vs. open source vs. commercially licensed) for use consistently across all TRF documents. +Align with README terminology guardrail and +`specs/OpenQuestions-WorkingDefaults.md` Q1–Q2; update those if research +improves the wording (human accept if changing published working defaults). + ## Survey patent-grant and Future License precedent (MIT vs Apache-2.0) ```task @@ -83,6 +99,9 @@ parallel canonical options (per PRD open question 3 / whether the TRSL pre-conversion phase itself needs an express patent license independent of the eventual Future License choice. +Working default already allows both Future Licenses in schemas +(`OpenQuestions-WorkingDefaults.md` Q3); this task confirms or revises that. + ## Survey contributor-rights instruments for dual-future licensing ```task @@ -101,6 +120,10 @@ whether a DCO alone is sufficient or whether TRSL requires a broader inbound grant (per `history/260728-InitialExploration.md` §8 and `spec/TargetRevenueLicenseConcept.md` §21.4). +Update `CONTRIBUTING.md` if the recommendation changes interim policy +(external contributions still blocked for governed Milestone Releases until +instrument exists). + ## Survey jurisdiction-specific standard-terms constraints ```task @@ -119,6 +142,9 @@ constraints in other jurisdictions relevant to likely early commercial users "commercial use," "captured," "Development Credit," and "Conversion Event." Flag terms that most urgently need objective, litigation-safe definitions. +Feed clarity-critical terms into T06 skeleton as `[LEGAL]` markers and into +working defaults Q2 if definitions improve. + ## Synthesize findings into an initial TRSL draft skeleton ```task @@ -126,6 +152,7 @@ id: TREV-WP-0001-T06 status: todo priority: high state_hub_task_id: "9e29b76f-37c0-4204-8cdc-e8d75e8412b4" +human_accept_required: true ``` Using T01–T05, produce `specs/TargetRevenueSourceLicense-Draft.md`: a @@ -136,3 +163,7 @@ commercial-use restriction, automatic Future License conversion, patent treatment, termination and cure, warranty/liability exclusions). Explicitly mark every clause requiring specialist legal review before use, per `spec/TargetRevenueLicenseConcept.md` §21.5. + +**Human accept gate:** Do not set this task to `done` until a human maintainer +explicitly accepts the skeleton as adequate briefing material for counsel. +Agent completion of the file is “ready for review,” not done. diff --git a/workplans/TREV-WP-0002-trust-service-foundation.md b/workplans/TREV-WP-0002-trust-service-foundation.md new file mode 100644 index 0000000..689521f --- /dev/null +++ b/workplans/TREV-WP-0002-trust-service-foundation.md @@ -0,0 +1,169 @@ +--- +id: TREV-WP-0002 +type: workplan +title: "Trust Service foundation — schemas, pure fold, golden fixture" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-07-28" +updated: "2026-07-28" +state_hub_workstream_id: "2b31c2c6-7c68-4c66-ae26-5f25e91a9af0" +supersedes_title: "Trust Service implementation bootstrap" +--- + +# Trust Service foundation — schemas, pure fold, golden fixture + +**Rescoped (2026-07-28)** from “Trust Service implementation bootstrap” per +`history/260728-SWOT-Assessment.md` I-05 and `SCOPE.md` sequencing rules. + +This workplan delivers the **runnable specification foundation** for the +Trust Layer (PRD NFR-1, NFR-3; TSD §3, §5, §6) **without** a hosted multi-user +Trust Service: + +- machine-readable schemas; +- pure Outstanding Target fold and offline validators; +- golden Phase package (`examples/`) from concept §23; +- conversion status as a pure function of Manifest + Ledger (attestation + optional evidence only). + +It does **not** implement Phase Registry hosting, multi-tenant ledger APIs, +metrics productization, production key management, or federation (PRD +Roadmap Phases 4 service, 6–7). Those require a later workplan after WP-0003 +normative extract and a Trust Service PRD (`SCOPE.md` §3–§4). + +**Depends on / parallels:** Working defaults in +`specs/OpenQuestions-WorkingDefaults.md` (currency, longstop, Future License +enum, hash/signature Stage 0 choices). Normative prose extract is WP-0003; +keep schema field names aligned with TSD §3 and that extract. + +**Human gate:** Task T01 (library stack ADR) MUST NOT be marked `done` +without explicit human accept if it locks language/runtime for the repo. + +## Record library stack ADR (schemas + fold only) + +```task +id: TREV-WP-0002-T01 +status: todo +priority: high +state_hub_task_id: "bdaa3e6a-e13d-4d4f-a6b0-9c56c18850a9" +human_accept_required: true +``` + +`specs/TechnicalSpecificationDocument.md` is non-binding on language and +storage (§10). Record an ADR for the **Stage 0 library only**: language for +JSON Schema (or equivalent) validators and the pure fold, canonical +serialization for hashing, and signature approach consistent with +`OpenQuestions-WorkingDefaults.md` Q14 (SHA-256 chain, Ed25519 for examples). + +**Do not** select production database hosting, multi-tenant ops, or federation +protocols in this ADR. Full service storage ADRs wait for a later Trust +Service implementation workplan. + +**Human accept gate:** Required before treating the ADR as locking repo +technology choices. Agents may draft the ADR for review. + +## Phase Manifest schema and pure conformance validator + +```task +id: TREV-WP-0002-T02 +status: todo +priority: high +state_hub_task_id: "92568684-2dff-497c-9593-7a0e91cb95a3" +``` + +Implement machine-readable schema + pure validator for Phase Manifest +(TSD §3.1), applying Stage 0 working defaults: + +- Required fields per TSD §3.1; +- `phase.longstop_at` required (working default Q8); +- `future_license` ∈ {MIT, Apache-2.0} (Q3); +- immutability rules documented for `phase.id` and initial target after + credits (enforced in validator docs; registry service not required). + +Reject non-conformant manifests offline. **No hosted Phase Registry** in +this workplan. + +## Target Ledger schema, hash chain, and pure Outstanding Target fold + +```task +id: TREV-WP-0002-T03 +status: todo +priority: high +state_hub_task_id: "df4133ee-9776-438d-901a-78a906356cfb" +``` + +Implement ledger entry schema (TSD §3.2): six entry types, currency match to +Phase native currency (Q6), `previous_entry_hash` chain, signature field +shape. Implement Outstanding Target as a pure fold: + +`max(0, T0 − Σ development-credit effective − Σ remission-credit effective)` + +with reversals/corrections as compensating entries (Rule 8). No update/delete +API. Folder layout under `schemas/` + library/CLI `fold` is sufficient; +hosted append service is out of scope. + +## Extension contract schema and conformance validator + +```task +id: TREV-WP-0002-T04 +status: todo +priority: medium +state_hub_task_id: "8454269e-fb3d-4751-b564-ef0cc33f9c97" +``` + +Implement Monetization Extension Contract schema (TSD §3.3) and conformance +check: required fields; `allocation.rule` must not redefine core terms. +Support status values `registered` / `canonical` / `deprecated` as data; +canonical promotion remains a documented human/governance action (not +automated). Include at least one conforming and one deliberately +non-conforming extension fixture (align names with working default Q11 where +practical). + +## Conversion detection and attestation schema (evidence only) + +```task +id: TREV-WP-0002-T05 +status: todo +priority: high +state_hub_task_id: "e60c8ccf-cd98-4b15-8ad2-e7718b08acc4" +``` + +Implement Conversion Event detection as pure read over Manifest + fold +(Outstanding Target reaches zero) and Conversion Attestation **document +schema** / optional generator (TSD §3.5). Enforce: attestation is never a +precondition for conversion status; tooling must recompute conversion without +an attestation file (PRD FR-7 / G6; working default Q13). + +## Golden Phase package and conformance suite + +```task +id: TREV-WP-0002-T06 +status: todo +priority: medium +state_hub_task_id: "90711ebf-3d89-4b45-8300-489f39cfa3cc" +``` + +Build `examples/phase-001/` (or equivalent) exercising concept §23: + +- Initial Target $100,000; +- mixed Development/Remission credits through Outstanding Target zero; +- expected fold series and optional attestation matching final totals. + +Automated suite: valid/invalid manifests, hash-chain integrity, extension +conformance, full lifecycle fold. Prefer tests runnable without network +services. + +## Deferred (not tasks of this workplan) + +Do **not** implement under WP-0002: + +- Hosted Phase / Extension Registry services +- Multi-user ledger append API and auth +- Metrics product and forecasts UI +- Federation replication protocol +- Production operator continuity SLA + +Track those only after WP-0003 Stage 0 normative extract and an explicit +Trust Service PRD / successor workplan (`SCOPE.md` §4). diff --git a/workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md b/workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md deleted file mode 100644 index 94788eb..0000000 --- a/workplans/TREV-WP-0002-trust-service-implementation-bootstrap.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -id: TREV-WP-0002 -type: workplan -title: "Trust Service implementation bootstrap" -domain: infotech -repo: target-revenue -status: active -owner: claude -topic_slug: infotech -created: "2026-07-28" -updated: "2026-07-28" -state_hub_workstream_id: "2b31c2c6-7c68-4c66-ae26-5f25e91a9af0" ---- - -# Trust Service implementation bootstrap - -Start the reference implementation of the Trust Service (PRD Roadmap Phase 4, -`specs/ProductRequirementsDocument.md` §11.1 item 8). The data model and -component boundaries are already specified in -`specs/TechnicalSpecificationDocument.md` §3 (Phase Manifest, Target Ledger -Entry, Extension Contract, Transaction Allocation, Conversion Attestation) -and §4 (component architecture: Phase Registry, Extension Registry, Target -Ledger, Metrics, Attestation — observe/record/validate/calculate/publish/ -attest only, never discretionary over conversion). - -This workplan bootstraps the implementation; it does not attempt full -production hardening, federation (PRD Roadmap Phase 6), or governance -process design (PRD Roadmap Phase 7). - -## Record stack and storage ADR - -```task -id: TREV-WP-0002-T01 -status: todo -priority: high -state_hub_task_id: "bdaa3e6a-e13d-4d4f-a6b0-9c56c18850a9" -``` - -`specs/TechnicalSpecificationDocument.md` is explicitly non-binding on -language, runtime, and storage engine (§10 Traceability Note). Before writing -code, record an ADR choosing an initial implementation stack and storage -model (relational, document, or event-sourced/append-log-native), justified -against the append-only, hash-chained, deterministic-fold requirements in -TSD §3.2 and §6.1. Resolve TSD open question 5 (signature scheme and -key-rotation record format) as part of the same ADR. - -## Implement Phase Manifest validation and Phase Registry - -```task -id: TREV-WP-0002-T02 -status: todo -priority: high -state_hub_task_id: "92568684-2dff-497c-9593-7a0e91cb95a3" -``` - -Implement the Phase Manifest schema from TSD §3.1 with a pure, deterministic -conformance validator (required-field checks, immutability enforcement on -`phase.initial_target.amount` and `phase.id`) per TSD §5. Implement the Phase -Registry component (TSD §4.1) storing and serving published, immutable -Manifests. Reject non-conformant manifests at registration, not at query -time. - -## Implement the Target Ledger as an append-only, hash-chained store - -```task -id: TREV-WP-0002-T03 -status: todo -priority: high -state_hub_task_id: "df4133ee-9776-438d-901a-78a906356cfb" -``` - -Implement the Target Ledger Entry schema from TSD §3.2: the six entry types -(`development-credit`, `remission-credit`, `credit-reversal`, -`remission-correction`, `administrative-correction`, `conversion-checkpoint`), -`previous_entry_hash` chaining, and signature fields. Enforce append-only -semantics at the storage layer (no update/delete path exists, not merely -disallowed by convention). Implement the Outstanding Target calculation as a -pure fold over a Phase's ordered entries plus its Manifest's -`initial_target.amount`, independently re-runnable by any conformant -external tool (TSD §3.2 validation rules, §6.1). - -## Implement the Extension Registry and conformance validator - -```task -id: TREV-WP-0002-T04 -status: todo -priority: medium -state_hub_task_id: "8454269e-fb3d-4751-b564-ef0cc33f9c97" -``` - -Implement the Monetization Extension Contract schema from TSD §3.3 and its -conformance check: required-field validation plus the rule that -`allocation.rule` may only consume transaction-level fields and must not -reference or redefine core terms (Phase, Initial Target, Development Credit, -Remission Credit, Outstanding Target, Conversion Event, Future License). -Support the `registered` / `canonical` / `deprecated` status field, with -`canonical` promotion left as a manual, documented action (governance process -itself is out of scope here — PRD Roadmap Phase 7). - -## Implement Conversion detection and Attestation publication - -```task -id: TREV-WP-0002-T05 -status: todo -priority: high -state_hub_task_id: "e60c8ccf-cd98-4b15-8ad2-e7718b08acc4" -``` - -Implement Conversion Event detection as a pure read over the Target Ledger -fold (Outstanding Target reaches zero) and Conversion Attestation generation -per TSD §3.5. Enforce the legal-technical rule that attestation publication -is evidence of conversion, never a precondition for it — any conformant -external tool must be able to independently recompute conversion status from -the raw Manifest and Ledger without waiting for or requiring an attestation -(TSD §3.5, PRD FR-7/G6). - -## Stand up conformance test suite and a worked end-to-end example - -```task -id: TREV-WP-0002-T06 -status: todo -priority: medium -state_hub_task_id: "90711ebf-3d89-4b45-8300-489f39cfa3cc" -``` - -Build an automated conformance suite exercising: manifest validation (valid -and deliberately invalid manifests), ledger append-only enforcement and hash -chain integrity, extension conformance (a conforming and a non-conforming -extension example), and a full worked Phase lifecycle from the illustrative -example in `spec/TargetRevenueLicenseConcept.md` §23 (Initial Target -$100,000, mixed Development/Remission Credit entries, reaching Outstanding -Target zero, and a generated Conversion Attestation matching that example's -numbers). diff --git a/workplans/TREV-WP-0003-normative-core-extraction.md b/workplans/TREV-WP-0003-normative-core-extraction.md new file mode 100644 index 0000000..18b9ecc --- /dev/null +++ b/workplans/TREV-WP-0003-normative-core-extraction.md @@ -0,0 +1,139 @@ +--- +id: TREV-WP-0003 +type: workplan +title: "Normative core extraction (PRD Phase 1)" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-07-28" +updated: "2026-07-28" +state_hub_workstream_id: "26d0f7ff-7e53-4729-a12e-5d526a843949" +--- + +# Normative core extraction (PRD Phase 1) + +Extract stable, versioned normative documents from the exploratory concept +draft so that schemas (WP-0002), legal skeleton (WP-0001), and later Trust +Service work share one frozen vocabulary. + +**Authority chain:** `spec/TargetRevenueLicenseConcept.md` remains the +concept source. Extracted docs under `specs/` become the day-to-day +normative references for implementers; they must not invent divergent +meanings for core terms (PRD §6.1). Working defaults that affect required +fields (`OpenQuestions-WorkingDefaults.md`) are cited explicitly and marked +provisional until human promotion. + +**Sequencing:** Parallel with WP-0001 and WP-0002. Full hosted Trust Service +implementation remains blocked until this workplan’s core extract tasks are +done or explicitly waived (`SCOPE.md` §4). + +**Method:** Prefer extract-and-stabilize over rewrite. Copy formulas, rules, +and invariants; add version headers and cross-links; avoid expanding scope +into profiles or federation. + +## Extract TargetRevenueFrameworkCore.md + +```task +id: TREV-WP-0003-T01 +status: todo +priority: high +state_hub_task_id: "e3e5fa79-2412-45b6-8e55-1cfad01c7136" +``` + +Produce `specs/TargetRevenueFrameworkCore.md` containing: + +- minimal core terminology (concept §7); +- target determination formulas (§8); +- five-verb lifecycle (§9); +- nine core rules (§10); +- foundational invariants (§22); +- conversion legal-technical requirements summary (§18 points 1–7) without + full license text. + +State document version (e.g. TRF-Core-0.1) and that concept §24 open +questions remain open except where working defaults apply provisionally. + +## Extract PhaseManifestSpecification.md + +```task +id: TREV-WP-0003-T02 +status: todo +priority: high +state_hub_task_id: "c0b4462a-599b-46e0-87bb-53d50129e3cb" +``` + +Produce `specs/PhaseManifestSpecification.md` from concept §16 and TSD §3.1: + +- required / recommended / optional field tiers; +- Stage 0 addition: `longstop_at` required per working default Q8 (mark as + Stage 0 working default pending promotion); +- immutability and identifier rules; +- validation rules aligned with WP-0002 schemas. + +## Extract TargetLedgerSpecification.md + +```task +id: TREV-WP-0003-T03 +status: todo +priority: high +state_hub_task_id: "ab11ec85-9c4c-4ca1-bc58-a0a044241c01" +``` + +Produce `specs/TargetLedgerSpecification.md` from concept §17 and TSD §3.2: + +- entry types (closed set); +- recognition (settled payment; working default Q10); +- corrections without erasure; +- hash chain and signature field requirements (algorithm details may + reference WP-0002 ADR / working default Q14); +- pure Outstanding Target fold definition; +- currency consistency rule (working default Q6). + +## Align Monetization Extension specification stub + +```task +id: TREV-WP-0003-T04 +status: todo +priority: medium +state_hub_task_id: "5129e0a2-8e7c-4279-8b3a-3570778bd749" +``` + +Produce either a full `specs/MonetizationExtensionSpecification.md` (PRD +Phase 3 item) or a clearly labeled Stage 0 stub that freezes the six-field +extension contract (concept §12, TSD §3.3) and the registered vs canonical +distinction, so WP-0002 validators have a prose normative home. Prefer a +complete short spec if it fits without cataloguing all six profiles (profiles +may remain a follow-on: `CanonicalMonetizationProfiles.md`). + +## Cross-link and freeze glossary + +```task +id: TREV-WP-0003-T05 +status: todo +priority: medium +state_hub_task_id: "ae77d3ac-81ea-4bf9-8e19-21b8d758e9b0" +``` + +- Add a short “Normative documents” section pointer from README and/or + concept header to the extracted files once they exist. +- Ensure PRD §6.1 and TSD §0 still point at the correct authority documents. +- List forbidden synonym guidance (e.g. do not use undifferentiated “revenue + captured” as Outstanding Target input) consistent with CONTRIBUTING.md. +- Confirm no remaining `xxx` or placeholder tails in normative paths. + +## Human promotion review (gate) + +```task +id: TREV-WP-0003-T06 +status: todo +priority: high +human_accept_required: true +state_hub_task_id: "b2ef367b-7c09-4bd7-b0e7-d9deee02000a" +``` + +Human maintainer reviews T01–T05 extracts for term consistency with concept +and for accidental elevation of working defaults to permanent norm without +labeling. Mark this task `done` only after human accept; agents prepare the +diff and a short review checklist.