tegwick
65568132d9
Bernd reviewed all four extracts (TargetRevenueFrameworkCore.md, PhaseManifestSpecification.md, TargetLedgerSpecification.md, MonetizationExtensionSpecification.md) plus cross-links and open-question coverage. Six-item checklist complete: one real fix (§1.11's extension- redefinition list had drifted broader than concept §7.11's closed list), one polish pass (PRD/CONTRIBUTING cross-link symmetry), four items confirmed with no changes needed. Marks WP-0003-T06 done and the WP-0003 workplan finished (all 6 tasks complete). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
254 lines
12 KiB
Markdown
254 lines
12 KiB
Markdown
---
|
||
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.
|