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.
This commit is contained in:
tegwick 2026-07-28 18:34:10 +02:00
parent 7286b52f07
commit 4496244bb8
16 changed files with 1252 additions and 227 deletions

View file

@ -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` (Q1Q3, 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` Q1Q2; 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 T01T05, 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.

View file

@ -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, 67). 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).

View file

@ -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).

View file

@ -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 workplans 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 17) 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 T01T05 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.