Complete WP-0012-T05: Phase provenance spec addendum draft
specs/PhaseProvenanceSpecAddendum.md synthesizes T02-T04's accepted decisions into one reviewable document: the phase_manifest schema diff (repo_hub/repo_hub_uri/repo_id/repo_name, base_phase_id), the specs/policies/ + specs/profiles/ extraction with concrete file lists and frontmatter shapes, the ledger UI change, a forgejo_hubs migration sketch for the hosted hub registry, the three-example-manifest backfill plan, and a suggested implementation task breakdown. This is a proposal only, not yet accepted for implementation -- per the maintainer's own established sequencing, this is the document to discuss before any of it is filed as its own workplan. All five WP-0012 tasks are done; workplan marked finished. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
8aa04a1f05
commit
694b280a7e
3 changed files with 280 additions and 5 deletions
|
|
@ -39,6 +39,7 @@ Extracted and stabilized from the concept draft under `workplans/TREV-WP-0003-no
|
|||
| [`specs/TargetLedgerSpecification.md`](specs/TargetLedgerSpecification.md) | Ledger entry types, hash chain, Outstanding Target fold |
|
||||
| [`specs/MonetizationExtensionSpecification.md`](specs/MonetizationExtensionSpecification.md) | Six-field extension contract, registered vs. canonical |
|
||||
| [`specs/PhaseLifecycleUseCases.md`](specs/PhaseLifecycleUseCases.md) | Nine Phase-lifecycle use cases mapped to what's built, what's a real gap, and what has no UI by design (WP-0012-T01) |
|
||||
| [`specs/PhaseProvenanceSpecAddendum.md`](specs/PhaseProvenanceSpecAddendum.md) | Proposed schema/spec-file/UI changes from WP-0012-T02–T04's accepted decisions — repo provenance fields, `specs/policies/`/`specs/profiles/` extraction, ledger UI treatment. **Not yet accepted for implementation** (WP-0012-T05) |
|
||||
|
||||
**Forbidden synonyms:** do not treat undifferentiated "revenue captured" as equivalent to Development Credit (see `CONTRIBUTING.md` § Terminology); do not call pre-conversion software "Open Source" (see the guardrail table above).
|
||||
|
||||
|
|
@ -85,7 +86,7 @@ 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–T04 done. **T02**: `milestone_release` gains required `repo_hub`/`repo_hub_uri`/`repo_id`/`repo_name`, `phase.base_phase_id` optional for successive Phases; hub↔URI mapping lives in the hosted Trust Service, not this repo. **T03**: `specs/policies/` + `specs/profiles/` subdirectories (one file per policy/profile, id+revision frontmatter), rendered read-only via a new lightweight server-side markdown route. **T04 accepted 2026-08-03**: registration form drops the `ledger` input (auto-computed), drill-down shows only the raw reference + live-data link. T05 (spec addendum draft) next |
|
||||
| [TREV-WP-0012](workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md) | Phase provenance, ledger reference, and degeneration-policy modeling — **finished**, all 5 tasks done. Decisions (T02–T04) synthesized into [`specs/PhaseProvenanceSpecAddendum.md`](specs/PhaseProvenanceSpecAddendum.md) (T05) — **not yet accepted for implementation**; that's the document to discuss before any schema/UI work is filed as its own workplan |
|
||||
| [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 |
|
||||
|
||||
|
|
|
|||
264
specs/PhaseProvenanceSpecAddendum.md
Normal file
264
specs/PhaseProvenanceSpecAddendum.md
Normal file
|
|
@ -0,0 +1,264 @@
|
|||
# Phase Provenance, Ledger Reference, and Policy/Profile Spec-File Addendum
|
||||
|
||||
`workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` T05.
|
||||
Synthesizes T02–T04's accepted decisions (all accepted; see that
|
||||
workplan's Result sections for the full reasoning behind each) into one
|
||||
reviewable document, covering the concrete schema, spec-file, and Control
|
||||
Plane UI changes they imply.
|
||||
|
||||
**This document proposes changes. It does not make them.** Per the
|
||||
maintainer's own established sequencing for this workplan, nothing here
|
||||
is implemented until this addendum itself is reviewed and accepted — at
|
||||
which point the implementation work is filed as its own workplan(s),
|
||||
the same way WP-0009/WP-0010 were split out of an earlier combined plan.
|
||||
|
||||
---
|
||||
|
||||
## 1. Phase Manifest schema changes (T02)
|
||||
|
||||
`schemas/phase_manifest.schema.json`, `phase.milestone_release`: four new
|
||||
**required** properties, alongside the two that already exist
|
||||
(`name`, `source_revision`; `artifact_sha256` stays optional):
|
||||
|
||||
```jsonc
|
||||
"milestone_release": {
|
||||
"type": "object",
|
||||
"required": ["name", "source_revision", "repo_hub", "repo_hub_uri", "repo_id", "repo_name"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"source_revision": { "type": "string" },
|
||||
"artifact_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
|
||||
"repo_hub": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z0-9-]+$",
|
||||
"description": "Stable, human-assigned slug for the Forgejo instance hosting this repo, e.g. \"forgejo-coulomb\". Minted by this project, not read from Forgejo — Forgejo has no instance-level identity endpoint (confirmed live 2026-07-30, /api/v1/nodeinfo -> 404)."
|
||||
},
|
||||
"repo_hub_uri": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "The Forgejo service's current base URL, e.g. \"https://forgejo.coulomb.social\". Retained alongside repo_hub (not derived from it) so a domain change stays repairable without breaking every Phase's provenance link."
|
||||
},
|
||||
"repo_id": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"description": "Forgejo's own internal numeric repo id (GET /api/v1/repos/{owner}/{repo} -> id). Stable across repo renames, unlike repo_name."
|
||||
},
|
||||
"repo_name": {
|
||||
"type": "string",
|
||||
"pattern": "^[\\w.-]+/[\\w.-]+$",
|
||||
"description": "\"owner/repo\" slug at time of Phase registration, e.g. \"coulomb/target-revenue\". Human-readable; repo_id is authoritative if this ever diverges after a rename."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`phase`: one new **optional** property, `base_phase_id` — present only
|
||||
for a successive Phase, absent for a first-ever Phase (no sentinel
|
||||
value):
|
||||
|
||||
```jsonc
|
||||
"base_phase_id": {
|
||||
"type": "string",
|
||||
"pattern": "^trsl:phase:[a-zA-Z0-9._-]+$",
|
||||
"description": "The prior Phase this one succeeds (FR-11, Rule 7). Absent for a repo's first-ever Phase."
|
||||
}
|
||||
```
|
||||
|
||||
`phase.ledger` is **unchanged** by this addendum — see §4.
|
||||
|
||||
### Not part of this schema
|
||||
|
||||
The `repo_hub` → `repo_hub_uri` mapping is **not** schema-level or
|
||||
file-level data in this repo. `target-revenue` is the generic framework,
|
||||
not a specific deployment's list of repos it monetizes. The mapping is
|
||||
hosted Trust Service data — see §5.
|
||||
|
||||
---
|
||||
|
||||
## 2. Degeneration-policy and calculation-model spec files (T03)
|
||||
|
||||
New `specs/policies/` subdirectory, one file per policy, replacing the
|
||||
current situation where `linear-longstop-v0`'s actual definition is a
|
||||
subsection (Q7) inside `specs/OpenQuestions-WorkingDefaults.md`, mixed
|
||||
with many unrelated open questions:
|
||||
|
||||
- `specs/policies/linear-longstop-v0.md` — extracted from Q7's prose
|
||||
(`R(t) = T0 × clamp((t − t0)/(tL − t0), 0, 1)`, discrete
|
||||
`remission-credit` entries on a published cadence). Frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
policy_id: trsl:policy:linear-longstop-v0@1.0
|
||||
title: Linear Longstop v0
|
||||
---
|
||||
```
|
||||
|
||||
`OpenQuestions-WorkingDefaults.md` Q7 becomes a pointer to this file
|
||||
(the *decision record* — "this is the accepted v1 norm" — stays there;
|
||||
the policy's own *content* moves out).
|
||||
|
||||
New `specs/profiles/` subdirectory, one file per canonical monetization
|
||||
profile, splitting `specs/CanonicalMonetizationProfiles.md`'s six
|
||||
sections into their own files — these already have stable ids used in
|
||||
real Phase Manifests today (`extensions: ["trsl:extension:development-license@1.0", ...]`),
|
||||
so the id→file mapping is immediate, not something newly invented:
|
||||
|
||||
- `specs/profiles/development-license.md`
|
||||
- `specs/profiles/cost-plus-operations.md`
|
||||
- `specs/profiles/phase-sponsorship.md`
|
||||
- `specs/profiles/service-with-development-allocation.md`
|
||||
- `specs/profiles/product-ideation.md`
|
||||
- `specs/profiles/general-consulting.md`
|
||||
|
||||
Each with frontmatter in the same shape:
|
||||
|
||||
```yaml
|
||||
---
|
||||
extension_id: trsl:extension:development-license@1.0
|
||||
title: Development License
|
||||
---
|
||||
```
|
||||
|
||||
`specs/CanonicalMonetizationProfiles.md` §7 (cross-profile summary) and
|
||||
§8 (non-goals) stay as the comparison/overview document; the six
|
||||
per-profile sections (§1–§6) move out.
|
||||
|
||||
`specs/DevelopmentEffortCalculatorConcept.md` requires **no move** — one
|
||||
file, one model, already a distinct name. Add matching frontmatter for
|
||||
consistency:
|
||||
|
||||
```yaml
|
||||
---
|
||||
calculator_id: development-effort-calculator-candidate-a
|
||||
revision: "1.0"
|
||||
title: Development Effort Calculator — Candidate A
|
||||
---
|
||||
```
|
||||
|
||||
(No `trsl:...` schema id exists for calculators — this is a
|
||||
documentation-traceability convention only, since calculators aren't
|
||||
referenced by id from inside a Phase Manifest the way
|
||||
`degeneration_policy` is.)
|
||||
|
||||
**Id and revision, built on git internals**: the id is the stable
|
||||
identifier already in use (with its existing `@version` suffix where
|
||||
applicable), mapped to exactly one file by naming convention; the
|
||||
revision/audit trail is that file's own git history
|
||||
(`git log -- specs/policies/linear-longstop-v0.md`). No new versioning
|
||||
table, no pinned-commit scheme — nothing beyond what git already
|
||||
provides.
|
||||
|
||||
### Control Plane rendering
|
||||
|
||||
One new read-only route family, server-side markdown → HTML at request
|
||||
time (a small Python markdown library — e.g. `markdown` or `mistune` —
|
||||
not a new build pipeline):
|
||||
|
||||
```
|
||||
GET /reference/policies/{slug}
|
||||
GET /reference/profiles/{slug}
|
||||
```
|
||||
|
||||
A plain link next to wherever a policy id already appears
|
||||
(`phase_detail.html`, `phase_new.html`) — never in-UI editable, matching
|
||||
every governance-action pattern already established in this project
|
||||
(credential revocation, extension canonicalization, proposed-entry
|
||||
review — all view/act, never edit-in-place).
|
||||
|
||||
This deliberately does **not** adopt state-hub's Observable-Framework
|
||||
static-build + "?" overlay pattern (`~/state-hub/dashboard/src/docs/*.md`)
|
||||
— confirmed live 2026-07-30 that it's a real static-site generator, a
|
||||
materially heavier dependency than this repo's existing lightweight
|
||||
FastAPI+Jinja2 stack needs for six profile pages and one policy page.
|
||||
|
||||
---
|
||||
|
||||
## 3. Ledger UI treatment (T04)
|
||||
|
||||
- `phase_new.html` drops the `ledger` input entirely. The registration
|
||||
route (`control_plane.register_phase`, or its caller) sets
|
||||
`phase.ledger` to the canonical `/phases/{phase_id}/ledger` reference
|
||||
automatically, before the manifest is validated/persisted — no human
|
||||
types it in v0.
|
||||
- `phase_detail.html` gains a small "ledger reference" link/disclosure
|
||||
(not a new prominent field) showing the raw `ledger` string from the
|
||||
manifest, plus — only when it resolves to this same Trust Service
|
||||
instance — a link to `GET /phases/{id}/ledger`'s live JSON.
|
||||
- The existing Ledger entries table on `phase_detail.html` is
|
||||
**unaffected** — this addendum only concerns the otherwise-invisible
|
||||
raw reference string, not the ledger data itself.
|
||||
- The schema field `phase.ledger` is unchanged (still required, still
|
||||
federation-ready for a future Phase whose ledger genuinely lives
|
||||
elsewhere) — this section is a Control Plane UI change only.
|
||||
|
||||
---
|
||||
|
||||
## 4. Hosted Trust Service: `forgejo_hubs` table
|
||||
|
||||
A new migration (numbered after `0006_control_plane.sql`, so `0007`),
|
||||
analogous to `licensor_identities`
|
||||
(`migrations/0005_licensor_credentials.sql`):
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS forgejo_hubs (
|
||||
hub_slug text PRIMARY KEY,
|
||||
service_uri text NOT NULL,
|
||||
first_seen_at timestamptz NOT NULL DEFAULT now(),
|
||||
updated_at timestamptz NOT NULL DEFAULT now()
|
||||
);
|
||||
```
|
||||
|
||||
Auto-populated the first time a `repo_hub` is seen during Phase
|
||||
registration (mirroring `ensure_licensor_identity`'s auto-create-on-first-
|
||||
INSERT trigger pattern) — no separate onboarding step required. This
|
||||
table is purely an admin/repair convenience for the hosting layer (e.g.
|
||||
"this hub's URI changed, update it in one place") — a Phase Manifest
|
||||
never needs it to be reachable for offline verification, since the
|
||||
manifest itself always carries `repo_hub_uri`/`repo_name` directly at
|
||||
registration time (use case 9, `specs/PhaseLifecycleUseCases.md`).
|
||||
|
||||
Whether correcting a hub's URI after the fact should be a governance
|
||||
action (a `SECURITY DEFINER` function, like `revoke_credential`) or a
|
||||
plain `UPDATE` is left to the implementation workplan to decide — not
|
||||
load-bearing enough to need a T02-style human gate here, but flagged so
|
||||
it isn't silently decided by whichever pattern is fastest to type.
|
||||
|
||||
---
|
||||
|
||||
## 5. Backfilling the three example manifests
|
||||
|
||||
Once the schema change above lands, `examples/pilot-candidates/*/manifest.json`
|
||||
(all three still `trsl:phase:draft-*`, never registered) get:
|
||||
|
||||
- `repo_hub`/`repo_hub_uri`/`repo_id`/`repo_name` filled in from each
|
||||
repo's real Forgejo data (the same `GET /api/v1/repos/{owner}/{repo}`
|
||||
call already confirmed working for `target-revenue` itself applies
|
||||
identically to `net-kingdom`, `railiance-apps`/`vergabe-teilnahme`, and
|
||||
`info-tech-canon`).
|
||||
- No `base_phase_id` — all three are first-ever Phases for their repos.
|
||||
- `ledger` set to each candidate's own canonical reference, matching
|
||||
whatever the Control Plane would auto-compute (§3), for consistency
|
||||
between examples and real registered Phases.
|
||||
|
||||
---
|
||||
|
||||
## 6. Suggested implementation task breakdown
|
||||
|
||||
Once this addendum is accepted, file as its own workplan (working title
|
||||
`TREV-WP-0015` or similar — not created yet, per this task's own charter
|
||||
of producing a document, not a workplan):
|
||||
|
||||
1. Schema change (§1) + `validation.py`/`tests/` updates.
|
||||
2. `specs/policies/`, `specs/profiles/` extraction (§2) +
|
||||
`DevelopmentEffortCalculatorConcept.md` frontmatter.
|
||||
3. Control Plane reference-rendering route (§2) + linking from
|
||||
`phase_detail.html`/`phase_new.html`.
|
||||
4. Ledger UI change (§3) — drop the form field, add the drill-down link.
|
||||
5. `forgejo_hubs` migration + auto-populate-on-first-registration logic
|
||||
(§4).
|
||||
6. Backfill the three example manifests (§5).
|
||||
7. Tests (offline schema/validation tests for §1, Docker-gated tests for
|
||||
§4/§5, a rendering smoke test for §2's new routes) and a `README.md`/
|
||||
workplan Result update, following this project's existing pattern for
|
||||
every prior task in this session.
|
||||
|
|
@ -4,11 +4,11 @@ type: workplan
|
|||
title: "Phase provenance, ledger reference, and degeneration-policy modeling"
|
||||
domain: infotech
|
||||
repo: target-revenue
|
||||
status: active
|
||||
status: finished
|
||||
owner: claude
|
||||
topic_slug: infotech
|
||||
created: "2026-07-30"
|
||||
updated: "2026-07-30"
|
||||
updated: "2026-08-03"
|
||||
state_hub_workstream_id: "763a31ee-85fe-43d0-9040-1e6fd432601c"
|
||||
---
|
||||
|
||||
|
|
@ -289,7 +289,7 @@ All four T02–T04 decisions now feed T05's spec addendum draft.
|
|||
|
||||
```task
|
||||
id: TREV-WP-0012-T05
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "152b54a6-08a9-4ced-a5f6-d5638d102900"
|
||||
```
|
||||
|
|
@ -302,7 +302,17 @@ 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
|
||||
**Result:** `specs/PhaseProvenanceSpecAddendum.md` written — six
|
||||
sections covering the schema diff (§1), the `specs/policies/`/
|
||||
`specs/profiles/` extraction with concrete file lists and frontmatter
|
||||
shapes (§2), the ledger UI change (§3), a new `forgejo_hubs` migration
|
||||
sketch for the hub-registry decision from T02 (§4), the backfill plan
|
||||
for the three example manifests (§5), and a suggested implementation
|
||||
task breakdown (§6) for whatever workplan follows once this addendum is
|
||||
reviewed. **Not yet accepted** — this is the document to discuss before
|
||||
any implementation work is filed or started. All five WP-0012 tasks are
|
||||
now done; this workplan is finished pending that discussion, which
|
||||
happens outside this workplan's own task list.
|
||||
|
||||
Use cases 4, 6, and 7 above are bigger than a modeling exercise — they
|
||||
are missing implementation, not missing documentation — and are tracked
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue