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
|
|
@ -84,6 +84,9 @@ The concept's §13 now defines a **Global Contingency Share Determination Rule**
|
|||
| [TREV-WP-0009](workplans/TREV-WP-0009-target-revenue-control-plane.md) | Target Revenue Control Plane — interactive UI for the `binky` tenant, incl. interactive Development Credit entry creation (`specs/TargetRevenueControlPlaneConcept.md`) — **finished**, all 4 tasks done. **T04 (interactive UI, `src/target_revenue/service/control_plane_app.py`) built on vendored `whynot-design` web components** rather than from scratch, per an explicit feasibility check |
|
||||
| [TREV-WP-0010](workplans/TREV-WP-0010-development-effort-calculator.md) | Development Effort Calculator — **finished**, all 3 tasks done. Applied to the three real pilot candidates (`history/260730-EffortCalculator-CandidateApplication.md`) — every calculator-derived Initial Target came out materially lower than the earlier hand-picked placeholders, two of three carrying explicit warnings recommending manual review |
|
||||
| [TREV-WP-0011](workplans/TREV-WP-0011-railiance-reef-deployment.md) | Deploy Trust Service + Control Plane to the Railiance reef, fronted by `revenue.coulomb.social` — active; T01 (deployment-pattern decision, human gate) next. Deployment alone does not authorize a real Phase go-live — that remains WP-0008-T05 |
|
||||
| [TREV-WP-0012](workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md) | Phase provenance, ledger reference, and degeneration-policy modeling — active; T01 (use-cases document) next. Modeling-only: produces a use-cases spec + a discussable spec addendum, no schema/UI changes yet |
|
||||
| [TREV-WP-0013](workplans/TREV-WP-0013-remission-credit-automation.md) | Remission Credit automation (degeneration policy execution) — active; T01–T03 `wait` on WP-0012-T03's policy-spec-file decision. Nothing currently computes or writes `remission-credit` ledger entries |
|
||||
| [TREV-WP-0014](workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md) | Control Plane UI: Extension Registry, Breach Records, Conversion Attestation — active; T01 next. Backend for all three already exists (WP-0006); UI-only work, not blocked on WP-0012 |
|
||||
|
||||
Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md)
|
||||
|
||||
|
|
|
|||
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.
|
||||
77
workplans/TREV-WP-0013-remission-credit-automation.md
Normal file
77
workplans/TREV-WP-0013-remission-credit-automation.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
id: TREV-WP-0013
|
||||
type: workplan
|
||||
title: "Remission Credit automation (degeneration policy execution)"
|
||||
domain: infotech
|
||||
repo: target-revenue
|
||||
status: active
|
||||
owner: claude
|
||||
topic_slug: infotech
|
||||
created: "2026-07-30"
|
||||
updated: "2026-07-30"
|
||||
---
|
||||
|
||||
# Remission Credit automation (degeneration policy execution)
|
||||
|
||||
Spun out of `workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md`
|
||||
(use case 4). Every Phase declares a `degeneration_policy`
|
||||
(`trsl:policy:linear-longstop-v0` is the accepted v1 norm,
|
||||
`specs/OpenQuestions-WorkingDefaults.md` Q7), which is supposed to
|
||||
generate `remission-credit` Target Ledger entries over time when
|
||||
Development Credit progress is insufficient (FR-6,
|
||||
`specs/ProductRequirementsDocument.md`). **Nothing in this codebase
|
||||
currently computes or writes these entries.** `fold.py` can consume them
|
||||
if they exist; nothing produces them. This gap predates the Control Plane
|
||||
UI work — it was never in scope for WP-0006 (Trust Service) or WP-0009
|
||||
(Control Plane), and surfaced now only because reviewing the UI's
|
||||
Phase-registration flow prompted a fuller look at what a Phase's lifecycle
|
||||
actually requires end to end.
|
||||
|
||||
Blocked on `workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md`
|
||||
T03's decision (how a policy id maps to its spec file) — the
|
||||
implementation here should be checkable against that spec file, per the
|
||||
user's explicit requirement that policy code and policy specification stay
|
||||
verifiably in sync.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0013-T01
|
||||
status: wait
|
||||
priority: high
|
||||
```
|
||||
|
||||
**Design the remission calculation and scheduling model.** `R(t) = T0 ×
|
||||
clamp((t - t0)/(tL - t0), 0, 1)` (Q7) needs: a chosen recognition cadence
|
||||
(daily/monthly UTC per Q7's own text), an idempotent
|
||||
"has this period's remission already been recorded" check (ledger entries
|
||||
are append-only — a re-run must not double-remit), and a decision on
|
||||
where `t0` (Phase activation) comes from if it isn't already a manifest
|
||||
field (registration time? an explicit `activated_at`?). Cross-check
|
||||
against whatever `trsl:policy:linear-longstop-v0`'s spec file (once
|
||||
WP-0012-T03 lands) says, rather than re-deriving the formula from Q7
|
||||
prose alone.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0013-T02
|
||||
status: wait
|
||||
priority: high
|
||||
```
|
||||
|
||||
**Implement and test** the calculation as a pure function (mirroring
|
||||
`fold.py`'s determinism discipline) plus whatever writes the resulting
|
||||
`remission-credit` entries into the hosted Target Ledger — a scheduled
|
||||
job, an on-demand Control Plane action, or both. Decide which actor
|
||||
"submits" these entries for attribution purposes (no human credential
|
||||
naturally owns a policy-driven entry) and record that decision explicitly
|
||||
rather than leaving `submitted_by_token` implicitly null.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0013-T03
|
||||
status: wait
|
||||
priority: medium
|
||||
```
|
||||
|
||||
**Surface it in the Control Plane UI**: `phase_detail.html`'s Ledger
|
||||
table already renders `remission-credit` rows generically once they
|
||||
exist; verify that holds, and add a metrics-level explanation (e.g. next
|
||||
scheduled remission date/amount) if `metrics.py` doesn't already forecast
|
||||
one.
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
---
|
||||
id: TREV-WP-0014
|
||||
type: workplan
|
||||
title: "Control Plane UI: Extension Registry, Breach Records, Conversion Attestation"
|
||||
domain: infotech
|
||||
repo: target-revenue
|
||||
status: active
|
||||
owner: claude
|
||||
topic_slug: infotech
|
||||
created: "2026-07-30"
|
||||
updated: "2026-07-30"
|
||||
---
|
||||
|
||||
# Control Plane UI: Extension Registry, Breach Records, Conversion Attestation
|
||||
|
||||
Spun out of `workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md`
|
||||
(use cases 5, 6, 7). Unlike `workplans/TREV-WP-0013-remission-credit-automation.md`,
|
||||
the backend for all three already exists and is tested
|
||||
(`registry.register_extension`/`promote_extension_canonical`,
|
||||
`breach_record.publish_breach_event`/`get_breach_records`,
|
||||
`attestation.publish_attestation`) — this is UI-only work, extending
|
||||
`service/control_plane_app.py` and its templates the same way WP-0009-T04
|
||||
did for Phases and the Ledger. Not blocked on WP-0012; can start any time.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0014-T01
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
**Extension Registry UI**: a page listing registered extensions with
|
||||
their `registered`/`canonical` status, a form to register a new extension
|
||||
(any authenticated tenant, per `registry.register_extension` — confirm
|
||||
whether Control Plane rights-gating applies here or whether extension
|
||||
registration is intentionally open, since `control_plane.py` today has no
|
||||
wrapper for it at all), and a canonical-promotion action restricted to
|
||||
whatever rights tier canonicalization review actually requires (check
|
||||
`specs/TargetRevenueControlPlaneConcept.md` §2's rights table — this may
|
||||
need its own entry there if it's missing).
|
||||
|
||||
```task
|
||||
id: TREV-WP-0014-T02
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
**Breach/Compliance Record UI**: a form to publish a breach/compliance
|
||||
determination against a Phase (`breach_record.publish_breach_event`),
|
||||
respecting the anonymized-by-default / named-only-with-opt-in rule
|
||||
(FR-10, License V1C1 §7.4), and a read view on `phase_detail.html`
|
||||
listing a Phase's published records.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0014-T03
|
||||
status: todo
|
||||
priority: low
|
||||
```
|
||||
|
||||
**Conversion Attestation UI**: read-only — a Phase that has converted
|
||||
should show its Attestation (`attestation.publish_attestation` is
|
||||
idempotent/publish-on-first-observation) on `phase_detail.html`, including
|
||||
Future License and the supporting ledger checkpoint, rather than requiring
|
||||
a caller to hit the Trust Service's `GET /phases/{id}/attestation`
|
||||
directly to see it.
|
||||
|
||||
```task
|
||||
id: TREV-WP-0014-T04
|
||||
status: todo
|
||||
priority: low
|
||||
```
|
||||
|
||||
**Tests and docs**: Docker-gated `TestClient` tests for all three (same
|
||||
pattern as `tests/test_control_plane_app.py`), workplan Result sections,
|
||||
`README.md` row update.
|
||||
Loading…
Add table
Add a link
Reference in a new issue