target-revenue/workplans/TREV-WP-0003-normative-core-extraction.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
TREV-WP-0003	workplan	Normative core extraction (PRD Phase 1)	infotech	target-revenue	finished	claude	infotech	2026-07-28	2026-07-29	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

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

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

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

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

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)

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):

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.