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

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