--- id: TREV-WP-0003 type: workplan title: "Normative core extraction (PRD Phase 1)" domain: infotech repo: target-revenue status: finished owner: claude topic_slug: infotech created: "2026-07-28" updated: "2026-07-29" 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:** `specs/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: done priority: high state_hub_task_id: "e3e5fa79-2412-45b6-8e55-1cfad01c7136" ``` Result 2026-07-29: `specs/TargetRevenueFrameworkCore.md` (TRF-Core-0.1) produced, extracting concept §7–§10, §18 (points 1–7), §22 without paraphrase drift; §8 lists which open questions remain unresolved by this extract rather than answering them by omission. 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: done priority: high state_hub_task_id: "c0b4462a-599b-46e0-87bb-53d50129e3cb" ``` Result 2026-07-29: `specs/PhaseManifestSpecification.md` (TRF-PhaseManifest-0.1) produced, aligned field-for-field with `schemas/phase_manifest.schema.json`. `longstop_at` explicitly marked "Required for Stage 0" with a dedicated §4 flagging it as a working default pending promotion, not silently folded into permanent Rule 1 scope. 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: done priority: high state_hub_task_id: "ab11ec85-9c4c-4ca1-bc58-a0a044241c01" ``` Result 2026-07-29: `specs/TargetLedgerSpecification.md` (TRF-Ledger-0.1) produced, aligned with `schemas/ledger_entry.schema.json` and `src/target_revenue/fold.py`/`hashing.py`. Flagged the `administrative-correction` fold-side effect as a Stage 0 simplification (concept §17 names the entry type but does not specify which side of the target it corrects) for T06 review. Result 2026-07-29 (same day, human decision): **Resolved** — maintainer chose to split the ambiguous type into `administrative-correction-development` and `administrative-correction-remission` (option (a) of three offered). Updated `schemas/ledger_entry.schema.json`, `src/target_revenue/fold.py`, `specs/TargetLedgerSpecification.md` §2/§6, `specs/TechnicalSpecificationDocument.md` §3.2, and `specs/ProductRequirementsDocument.md` FR-5. Added dedicated test coverage (`tests/test_ledger_fold.py`) for both new types plus a regression test confirming the old unsplit type name is now rejected. `specs/TargetRevenueLicenseConcept.md` §17 was left unedited — its entry-type list is explicitly non-exhaustive ("may include"), so the split specializes rather than contradicts it. 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: done priority: medium state_hub_task_id: "5129e0a2-8e7c-4279-8b3a-3570778bd749" ``` Result 2026-07-29: Produced the full `specs/MonetizationExtensionSpecification.md` (TRF-Extension-0.1), not just a stub — freezes the six-field contract, registered/canonical distinction, and the Stage 0 Q11 catalog table (with `product-ideation`/`general-consulting` correctly marked as not yet fixture-backed). Deep profile narratives deferred to the planned `CanonicalMonetizationProfiles.md`, as the task allowed. 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: done priority: medium state_hub_task_id: "ae77d3ac-81ea-4bf9-8e19-21b8d758e9b0" ``` Result 2026-07-29: Added "Normative documents" section to README with a table pointing at all four extracts plus forbidden-synonym guidance. Updated PRD §6.1/§6.2 and TSD §0/§1.1 to cite the extracts as the day-to-day reference alongside the concept document as ultimate authority. Updated CONTRIBUTING.md terminology and human-gate sections. Confirmed via `grep -rn "^xxx$" spec/ specs/` — no placeholder tails remain. - 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: done priority: high human_accept_required: true human_accepted_by: Bernd human_accepted_at: "2026-07-29" 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. **Review checklist prepared 2026-07-29** (task remains `todo` pending human accept): - [x] `specs/TargetRevenueFrameworkCore.md` — terms in §1 match concept §7 wording; formula in §2 matches concept §8; five verbs (§3) and nine rules (§4) copied without paraphrase drift; §7 invariants match concept §22 twelve items exactly. **Reviewed and accepted 2026-07-29, one fix applied:** §1.11 had paraphrased concept §7.11's closed extension- redefinition list ("Phase, Initial Target, Development Credit, Remission Credit, Outstanding Target, Conversion Event, or Future License") as "any term in this section" — silently broadening the constitutional boundary to also cover Milestone Release, Target Multiple, Trust Service, and Monetization Profile/Extension itself, and creating an inconsistency with `MonetizationExtensionSpecification.md` §3, which already carried the concept's narrower list correctly. Corrected §1.11 to quote the closed list verbatim; confirmed no other document (TSD §5, PRD FR-4) carries the broadened version. - [x] `specs/PhaseManifestSpecification.md` — field tiers match `schemas/phase_manifest.schema.json` (already implemented, WP-0002-T02); `phase.longstop_at` is explicitly labeled a Stage 0 working default (Q8), not silently presented as permanent Rule 1 scope. **Reviewed and accepted 2026-07-29, no fix needed** — three minor notes recorded: (1) §3 Rule 1 says "any Required field" in the bare sense, while `longstop_at` is tiered "Required for Stage 0"; §4's provisional- pending-promotion language and the schema together make the Stage 0 binding unambiguous, so this reads correctly despite the differently- worded tier label. (2) `degeneration_policy` is correctly plain Required (the concept always required *a* policy); Q7 is about *which* pilot policy is designated, and appears only in the schema field's description (`schemas/phase_manifest.schema.json`), not as a tier qualifier — consistent, not a drift. (3) `target_basis` as a whole is optional in the schema, with its four subfields Recommended individually when the object is present — matches this spec exactly. - [x] `specs/TargetLedgerSpecification.md` — entry-type table matches `schemas/ledger_entry.schema.json`. **Resolved 2026-07-29:** the `administrative-correction` ambiguity was reviewed and split into `administrative-correction-development` / `-remission` (maintainer's choice of option (a)); this was the one place the extraction added interpretation beyond a direct concept citation, and it is now closed. - [x] `specs/MonetizationExtensionSpecification.md` — six-field contract matches concept §12; registered/canonical distinction matches concept §12.1–§12.2; Stage 0 catalog table (Q11) correctly shows `product-ideation` and `general-consulting` as not yet fixture-backed. **Reviewed and accepted 2026-07-29, no fix needed** — six fields (value/pricing/allocation/recognition/reversal/evidence) match concept §12's YAML verbatim; the redefinition list matches (fixed alongside item 1); registered/canonical wording matches §12.1/§12.2; the six canonical candidates match concept §12.2's list in the same order, with the two unfixtured profiles honestly labeled rather than implied complete. - [x] Cross-links (T05) — confirm PRD §6.1/§6.2, TSD §0/§1.1, README, and CONTRIBUTING.md all point at the new extracts without contradicting `specs/TargetRevenueLicenseConcept.md` as ultimate authority. **Reviewed and accepted 2026-07-29 as polish-only, two fixes applied:** added the same "ultimate source / day-to-day reference" dual-citation to the PRD header's Terminology alignment line (previously only in README/TSD/CONTRIBUTING); named all three other extracts (`PhaseManifestSpecification.md`, `TargetLedgerSpecification.md`, `MonetizationExtensionSpecification.md`) in CONTRIBUTING.md's Terminology section, which previously named only `TargetRevenueFrameworkCore.md` — now symmetric with README's full four-document table. - [x] No open question (concept §24) is answered by omission — each extract either cites a working default explicitly or states the item remains open. **Reviewed and accepted 2026-07-29, no fix needed.** Once accepted, update this task's `status` to `done` and record `human_accepted_by` / `human_accepted_at`, following the ADR-0001 / WP-0002-T01 pattern.