Add TREV-WP-0012/0013/0014: modeling pass + spun-out implementation gaps
TREV-WP-0012 is the modeling-only workplan requested after using the Control Plane UI surfaced real gaps: Phase registration has no structured repo/provenance fields, the ledger URI is hand-typed, and degeneration policies are opaque ids with no reviewable spec behind them. It produces a use-cases document and a discussable spec addendum before any schema/UI implementation. Two of the use cases uncovered while scoping this turned out to be bigger than documentation gaps and are tracked as their own workplans per that direction: TREV-WP-0013 (nothing currently computes or writes Remission Credit ledger entries at all) and TREV-WP-0014 (Extension Registry, Breach Record, and Conversion Attestation backends already exist from WP-0006 but have no Control Plane UI). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
e103937e21
commit
ca53a9f820
4 changed files with 331 additions and 0 deletions
177
workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md
Normal file
177
workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
---
|
||||
id: TREV-WP-0012
|
||||
type: workplan
|
||||
title: "Phase provenance, ledger reference, and degeneration-policy modeling"
|
||||
domain: infotech
|
||||
repo: target-revenue
|
||||
status: active
|
||||
owner: claude
|
||||
topic_slug: infotech
|
||||
created: "2026-07-30"
|
||||
updated: "2026-07-30"
|
||||
---
|
||||
|
||||
# Phase provenance, ledger reference, and degeneration-policy modeling
|
||||
|
||||
Triggered by using the Control Plane UI for the first time (WP-0009-T04):
|
||||
the Phase registration form asked for a bare `source_revision` with no
|
||||
repo attribution, a hand-typed `ledger` URI, and an opaque
|
||||
`degeneration_policy` id with no way to see what it actually specifies.
|
||||
These aren't UI bugs — the Phase Manifest schema
|
||||
(`schemas/phase_manifest.schema.json`) itself doesn't yet carry the
|
||||
structure the UI would need to show any of this properly, and FR-11
|
||||
(Successive Phases, `specs/ProductRequirementsDocument.md`) already commits
|
||||
the framework to base-release/prior-Phase provenance that the schema has
|
||||
never modeled either.
|
||||
|
||||
This is a **modeling-only** workplan: it produces documents (a use-cases
|
||||
spec and a discussable spec addendum) and decisions, not schema or UI
|
||||
changes. Implementation follows in later workplans once the addendum is
|
||||
reviewed (T05).
|
||||
|
||||
```task
|
||||
id: TREV-WP-0012-T01
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
**Write the use-cases document**, as its own spec file (not folded into
|
||||
`specs/PhaseManifestSpecification.md`) — working title
|
||||
`specs/PhaseLifecycleUseCases.md`. Cover, systematically, at minimum:
|
||||
|
||||
1. First Phase ever declared for a repo (the three real pilot candidates:
|
||||
`net-kingdom`, `railiance-vergabe-teilnahme`, `info-tech-canon`).
|
||||
2. A successive Phase on a repo that already had an earlier, converted
|
||||
Phase (FR-11) — including what "base release" means when the prior
|
||||
Phase's Milestone Release is itself the base.
|
||||
3. Operator registers a Phase; Contributor proposes a Development Credit;
|
||||
Operator/Admin reviews (already built, WP-0009 — include for
|
||||
completeness/cross-reference, not to redesign it).
|
||||
4. Remission Credit accrual over time under the active degeneration
|
||||
policy — note as an open gap for WP-0013, not solved here.
|
||||
5. Conversion Event fires, Attestation published — note as a UI gap for
|
||||
WP-0014.
|
||||
6. Monetization Extension registration and canonical-status review — note
|
||||
as a UI gap for WP-0014.
|
||||
7. Breach/Compliance Record publication — note as a UI gap for WP-0014.
|
||||
8. A second Licensor tenant besides `binky` onboards.
|
||||
9. An external auditor verifies a Phase's evidence package offline,
|
||||
without needing to trust or even reach the Control Plane UI (FR-8/FR-9
|
||||
— call out explicitly that this use case has *no* UI surface by
|
||||
design, so it doesn't get silently forgotten as "not yet built").
|
||||
|
||||
```task
|
||||
id: TREV-WP-0012-T02
|
||||
status: todo
|
||||
priority: high
|
||||
human_accept_required: true
|
||||
```
|
||||
|
||||
**Decide repo identification and Phase-provenance fields (human gate).**
|
||||
Per direction already given: identity rests on the Forgejo instance
|
||||
("home hub") plus the repo's own stable id within that instance, *and*
|
||||
the Forgejo service URI and repo name are also retained (not derived) —
|
||||
so a rename or instance move stays repairable rather than silently
|
||||
breaking a Phase's provenance link. Concretely decide and record:
|
||||
|
||||
- Field names/shape for `milestone_release`: a hub identifier, a
|
||||
Forgejo-internal repo id, the Forgejo service URI, and the repo name
|
||||
(owner/repo slug) — four values, not one string.
|
||||
- Whether this is required or recommended for Stage 0 (precedent:
|
||||
`longstop_at` moved from recommended to required under a working
|
||||
default, `specs/OpenQuestions-WorkingDefaults.md` Q8).
|
||||
- How a successive Phase (use case 2 above) references its base — a
|
||||
`trsl:phase:...` id, and what a first-ever Phase puts there instead
|
||||
(null, or an explicit "no prior Phase" marker — decide which is
|
||||
cleaner for fold/validation logic downstream).
|
||||
- Whether any of this is retroactively backfillable for the three
|
||||
existing pilot-candidate example manifests, or only required going
|
||||
forward.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0012-T03
|
||||
status: todo
|
||||
priority: high
|
||||
human_accept_required: true
|
||||
```
|
||||
|
||||
**Decide the degeneration-policy / calculation-model spec-file
|
||||
convention (human gate).** Per direction already given: every policy or
|
||||
calculation model (this includes the Development Effort Calculator's own
|
||||
Candidate A formula, `specs/DevelopmentEffortCalculatorConcept.md`, not
|
||||
just degeneration policies) corresponds to a markdown specification file
|
||||
with a simple, distinct name, an id, and a revision — built on git's own
|
||||
mechanisms (commit hash and/or file path, no new versioning
|
||||
infrastructure). Concretely decide:
|
||||
|
||||
- Where these spec files live (likely already `specs/*.md` — decide
|
||||
whether a dedicated subdirectory or naming convention is needed so a
|
||||
policy id like `trsl:policy:linear-longstop-v0` maps unambiguously to
|
||||
one file).
|
||||
- What "id and revision, built on git internals" means precisely — e.g.
|
||||
the policy id embeds the file path and a pinned commit hash, or the
|
||||
file's own frontmatter carries an id/revision pair that a human commits
|
||||
to alongside code changes (check how `the-custodian`/state-hub already
|
||||
present read-only reference-documentation views linked by id, per the
|
||||
user's explicit steer to reuse that pattern rather than invent a new
|
||||
one, and follow whichever mechanism is actually in use there).
|
||||
- How the Control Plane UI links a policy id shown next to a Phase to a
|
||||
**read-only** rendered view of that spec file — no in-UI editing,
|
||||
consistent with every other governance-action pattern in this project.
|
||||
- Whether this same convention should also cover the six canonical
|
||||
monetization profiles (`specs/CanonicalMonetizationProfiles.md`) for
|
||||
consistency, or is scoped to degeneration policies and calculators only
|
||||
for now.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0012-T04
|
||||
status: todo
|
||||
priority: medium
|
||||
human_accept_required: true
|
||||
```
|
||||
|
||||
**Decide the ledger's UI treatment (human gate).** Per direction already
|
||||
given: keep the `ledger` field in the schema — not as something the
|
||||
standard Phase view surfaces, but as an internal reference reachable only
|
||||
via an explicit drill-down/details action. This is intentional groundwork
|
||||
for eventually supporting more than one ledger per Phase (federation,
|
||||
`specs/ProductRequirementsDocument.md` NFR-3), not just a display
|
||||
preference. Decide:
|
||||
|
||||
- What the drill-down actually shows (the raw ledger URI/reference plus a
|
||||
link to `GET /phases/{id}/ledger`'s live data, or something more), and
|
||||
where it lives in the Control Plane's navigation (a "details" link on
|
||||
`phase_detail.html` rather than a top-level field).
|
||||
- Whether the Phase registration form still needs a `ledger` input at
|
||||
all going forward, or whether the Trust Service should compute/assign
|
||||
it automatically now that it is always the ledger's host in Stage 0 —
|
||||
distinct from the schema question of whether the field stays.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0012-T05
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
**Draft the spec addendum** reflecting T01–T04's accepted decisions, for
|
||||
review before any implementation — schema changes (`schemas/
|
||||
phase_manifest.schema.json`), the policy-spec-file convention, and the
|
||||
Control Plane UI changes it implies. Do not implement anything from this
|
||||
task; it produces a reviewable document only. Once accepted, file the
|
||||
implementation work as its own workplan(s), consistent with how WP-0009
|
||||
and WP-0010 were split from a single combined plan.
|
||||
|
||||
## Related gaps spun out as their own workplans
|
||||
|
||||
Use cases 4, 6, and 7 above are bigger than a modeling exercise — they
|
||||
are missing implementation, not missing documentation — and are tracked
|
||||
separately rather than folded in here:
|
||||
|
||||
- `workplans/TREV-WP-0013-remission-credit-automation.md` — use case 4.
|
||||
- `workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md`
|
||||
— use cases 5, 6, 7.
|
||||
|
||||
Use case 8 (second Licensor tenant onboarding) is judged small enough to
|
||||
stay under `workplans/TREV-WP-0008-governance-and-pilot-rollout.md`
|
||||
rather than warrant its own workplan — revisit that call if it turns out
|
||||
to need real design work once a second tenant is actually on the table.
|
||||
Loading…
Add table
Add a link
Reference in a new issue