From 7c2e33bc31d94f17d5356107edd15171a7741b5e Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 30 Jul 2026 11:02:45 +0200 Subject: [PATCH] Split TREV-WP-0009 into Control Plane (WP-0009) and Effort Calculator (WP-0010) The two deliverables have independent formula/rights decisions and implementation arcs; keeping them in one workplan blurred that they can be reviewed and sequenced separately, even though the Control Plane's Phase-registration flow is expected to consume the Calculator's output once both exist. WP-0009 (Target Revenue Control Plane): keeps the original workstream ID, retitled and re-tasked to 3 focused tasks - rights-model decision (human gate), backend auth/audit layer, interactive UI flows. WP-0010 (Development Effort Calculator, new): 3 tasks - formula decision (human gate), implementation, application to the real candidate repos already identified in WP-0008. No real Phase declaration in either workplan's scope. Updated both concept documents' workplan cross-references and README.md's summary table accordingly. --- README.md | 3 +- specs/DevelopmentEffortCalculatorConcept.md | 2 +- specs/TargetRevenueControlPlaneConcept.md | 2 +- ...009-control-plane-and-effort-calculator.md | 138 ------------------ ...EV-WP-0009-target-revenue-control-plane.md | 99 +++++++++++++ ...V-WP-0010-development-effort-calculator.md | 111 ++++++++++++++ 6 files changed, 214 insertions(+), 141 deletions(-) delete mode 100644 workplans/TREV-WP-0009-control-plane-and-effort-calculator.md create mode 100644 workplans/TREV-WP-0009-target-revenue-control-plane.md create mode 100644 workplans/TREV-WP-0010-development-effort-calculator.md diff --git a/README.md b/README.md index c51ba2e..73b32be 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,8 @@ The concept's §13 now defines a **Global Contingency Share Determination Rule** | [TREV-WP-0006](workplans/TREV-WP-0006-trust-service-implementation.md) | Hosted Trust Service reference implementation (PRD Phase 4b) — **finished**, all 9 tasks done (Postgres-backed registries/ledger/metrics/attestation/breach-record, ADR-0002 accepted, onboarding CLI, hosted conformance suite) | | [TREV-WP-0007](workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md) | Degeneration policy + canonical monetization profile catalog — **finished**, all 4 tasks done. `trsl:policy:linear-longstop-v0` confirmed 2026-07-29 as the v1 norm for the first pilot cohort; `progress-paused-longstop-v1` named as the next iteration, not yet adopted | | [TREV-WP-0008](workplans/TREV-WP-0008-governance-and-pilot-rollout.md) | Governance formalization + pilot rollout — active; T01–T04 done. `info-tech-canon` dry-run onboarding routine exercised end-to-end 2026-07-29. **Org-wide TRSL license adoption executed 2026-07-30** across ~90 `coulomb`-org repos (`history/260730-TRSL-OrgWideLicenseRollout.md`) — a license-text adoption, not a Phase declaration. T05 (real Phase go-live gate) remains `todo` by design; no Phase exists yet for any repo | -| [TREV-WP-0009](workplans/TREV-WP-0009-control-plane-and-effort-calculator.md) | Target Revenue Control Plane (interactive UI for the `binky` tenant, incl. interactive Development Credit entry creation) + Development Effort Calculator (turns human time/workplan-task volume/repo size/AI token cost into `target_basis` values) — active, concepts only so far (`specs/TargetRevenueControlPlaneConcept.md`, `specs/DevelopmentEffortCalculatorConcept.md`); T01/T02 human-gated formula/rights decisions not yet made | +| [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`) — active, concept only so far; T01 (rights-model human gate) not yet decided | +| [TREV-WP-0010](workplans/TREV-WP-0010-development-effort-calculator.md) | Development Effort Calculator — turns human time/workplan-task volume/repo size/AI token cost into `target_basis` values feeding the framework's existing Initial Target formula (`specs/DevelopmentEffortCalculatorConcept.md`) — active, concept only so far; T01 (formula human gate) not yet decided. Split from TREV-WP-0009 2026-07-30 | Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md) diff --git a/specs/DevelopmentEffortCalculatorConcept.md b/specs/DevelopmentEffortCalculatorConcept.md index 0a419d0..4e5e2b4 100644 --- a/specs/DevelopmentEffortCalculatorConcept.md +++ b/specs/DevelopmentEffortCalculatorConcept.md @@ -2,7 +2,7 @@ Status: Concept v0.1 Date: 2026-07-30 -Workplan: `workplans/TREV-WP-0009-control-plane-and-effort-calculator.md` +Workplan: `workplans/TREV-WP-0010-development-effort-calculator.md` Primary artifacts: `specs/TargetRevenueFrameworkCore.md` §1.4 (Target Multiple, Initial Target formula), `specs/PhaseManifestSpecification.md` (`target_basis` fields), state hub `get_token_summary`/`get_recent_progress`/`list_tasks` tools **Scope note:** this is a concept for a **working, explicitly refinable v0 diff --git a/specs/TargetRevenueControlPlaneConcept.md b/specs/TargetRevenueControlPlaneConcept.md index 1c6c054..d67851d 100644 --- a/specs/TargetRevenueControlPlaneConcept.md +++ b/specs/TargetRevenueControlPlaneConcept.md @@ -2,7 +2,7 @@ Status: Concept v0.1 Date: 2026-07-30 -Workplan: `workplans/TREV-WP-0009-control-plane-and-effort-calculator.md` +Workplan: `workplans/TREV-WP-0009-target-revenue-control-plane.md` Primary artifacts: `specs/TrustServiceProductRequirementsDocument.md`, `src/target_revenue/service/app.py`, `specs/TRSL-Governance.md` §1 (Licensor identity), `scripts/trf_onboard.py` **Scope note:** this is a concept, not an implementation. It defines what diff --git a/workplans/TREV-WP-0009-control-plane-and-effort-calculator.md b/workplans/TREV-WP-0009-control-plane-and-effort-calculator.md deleted file mode 100644 index b0f3fb8..0000000 --- a/workplans/TREV-WP-0009-control-plane-and-effort-calculator.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -id: TREV-WP-0009 -type: workplan -title: "Target Revenue Control Plane and Development Effort Calculator" -domain: infotech -repo: target-revenue -status: active -owner: claude -topic_slug: infotech -created: "2026-07-30" -updated: "2026-07-30" -state_hub_workstream_id: "0e8dfd43-a742-4458-9e9b-514a9284821b" ---- - -# Target Revenue Control Plane and Development Effort Calculator - -Builds the two pieces the maintainer identified as needed to move from -"license text adopted org-wide" (`history/260730-TRSL-OrgWideLicenseRollout.md`) -toward actually declaring real Phases with defensible Initial Targets: - -1. A **Control Plane** — an interactive UI over the hosted Trust Service - (`workplans/TREV-WP-0006-trust-service-implementation.md`, finished), - usable by a human user with appropriate rights acting as the `binky` - tenant, to interactively register Phases and — the specific, - named requirement — create Development Credit ledger entries - interactively rather than via raw API calls or the CLI. -2. A **Development Effort Calculator** — turns measurable repo activity - (human interaction time, workplan/task volume, file/line complexity, - AI token cost) into `target_basis` values - (`specs/PhaseManifestSpecification.md`), which combined with a human - Target Multiple classification (10x/100x/1000x) produces a proposed - Initial Target via the framework's own existing formula - (`specs/TargetRevenueFrameworkCore.md` §1.4) — not a new formula. - -**Does not include:** declaring any real Phase for any repo. Both -deliverables here are inputs to that decision -(`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T05), not a way -to bypass it. - -## Development Effort Calculator — formula decision (human gate) - -```task -id: TREV-WP-0009-T01 -status: todo -priority: high -human_accept_required: true -state_hub_task_id: "96ea1067-22f5-490b-8c42-5236a2193b1a" -``` - -`specs/DevelopmentEffortCalculatorConcept.md` §3 presents two combination -strategies without choosing between them: Candidate A (labor-cost- -anchored — human time drives `estimated_effort_days`/`daily_rate`, token -cost becomes `approved_direct_costs`, workplan/file metrics are a sanity -check) or Candidate B (composite-index-anchored — all four metric -families scored into one complexity index, converted via a $-per-unit -rate). Confirm one as the adopted v0 approach (or propose a refinement), -per the same human-gate pattern already used for the degeneration policy -formula (`workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md` T02). -Agents may prepare a recommendation and leave this `todo`. - -## Control Plane user rights model — decision (human gate) - -```task -id: TREV-WP-0009-T02 -status: todo -priority: high -human_accept_required: true -state_hub_task_id: "9d3b2d3d-1a3c-4b63-8cd1-8e6c949ad8b8" -``` - -`specs/TargetRevenueControlPlaneConcept.md` §2 proposes a four-tier rights -model (Viewer/Contributor/Operator/Admin) and recommends option (b) for -the auth-attribution question (Control Plane holds the one Licensor -token server-side, layers its own human-user auth/audit log in front of -it, rather than requiring a WP-0006 schema change for per-human -sub-credentials). Confirm the rights tiers and the (a)-vs-(b) choice, or -propose a refinement. Agents may prepare a recommendation and leave this -`todo`. - -## Implement Development Effort Calculator - -```task -id: TREV-WP-0009-T03 -status: todo -priority: high -state_hub_task_id: "fadaef32-0d6a-443f-8dde-9a85952c6d76" -``` - -Using T01's confirmed formula, implement the calculator: data collection -(commit-timestamp clustering for human time; workplan/task counts via -state hub `list_tasks`/`list_workplans` or direct `workplans/` directory -inspection; file/line counts with generated/vendored-path exclusion per -`specs/DevelopmentEffortCalculatorConcept.md` §2c's flagged distortion; -token cost via `get_token_summary(scope="repo", id=...)`), and the -combination formula itself, producing `target_basis` field values ready -to drop into a Phase Manifest. Output must show its work (which inputs -produced which numbers) — a black-box dollar figure with no visible -derivation would undermine the "transparent, non-gameable" goal -(`specs/TargetRevenueLicenseConcept.md` §4.6) this whole framework is -built around. - -## Implement Control Plane (backend + interactive UI) - -```task -id: TREV-WP-0009-T04 -status: todo -priority: high -state_hub_task_id: "77b91435-780b-4360-8fe0-922d6483d549" -``` - -Using T02's confirmed rights model, implement the Control Plane: human -user authentication, the rights-tiered action set from -`specs/TargetRevenueControlPlaneConcept.md` §3–§4 (interactive Development -Credit entry creation as the priority flow), and the Control Plane's own -audit log distinct from the Trust Service's signed records (§5). Reuses -the existing hosted Trust Service API (`service/app.py`) as its backend -without modification unless T02 specifically selects the -per-human-sub-credential option, in which case that WP-0006 auth -extension is this task's prerequisite, not an assumed given. - -## Apply calculator to real candidate repos - -```task -id: TREV-WP-0009-T05 -status: todo -priority: medium -state_hub_task_id: "3ee25a56-3cbb-4284-b240-d58e12622bf9" -``` - -Once T03 is implemented, run it against the real candidates already -identified (`specs/PilotPhaseCandidateSurvey.md`: `net-kingdom`'s -`NK-WP-0002`, `railiance-apps`'s `vergabe-teilnahme`, and -`info-tech-canon`'s service surface) to produce **proposed**, calculator- -derived `target_basis` values, replacing the hand-picked illustrative -figures currently in `examples/pilot-candidates/*/manifest.json`. This -remains draft/non-binding — updating a draft manifest's numbers is not a -Phase declaration, and does not touch -`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T05's own gate. diff --git a/workplans/TREV-WP-0009-target-revenue-control-plane.md b/workplans/TREV-WP-0009-target-revenue-control-plane.md new file mode 100644 index 0000000..2731931 --- /dev/null +++ b/workplans/TREV-WP-0009-target-revenue-control-plane.md @@ -0,0 +1,99 @@ +--- +id: TREV-WP-0009 +type: workplan +title: "Target Revenue Control Plane" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-07-30" +updated: "2026-07-30" +state_hub_workstream_id: "0e8dfd43-a742-4458-9e9b-514a9284821b" +--- + +# Target Revenue Control Plane + +An interactive UI over the hosted Trust Service +(`workplans/TREV-WP-0006-trust-service-implementation.md`, finished), +usable by a human user with appropriate rights acting as the `binky` +tenant. The specific, named requirement driving this workplan: make it +possible to interactively register Phases and create Development Credit +ledger entries, rather than requiring raw API calls or the +`scripts/trf_onboard.py` CLI. + +**Split from the former combined `TREV-WP-0009-control-plane-and-effort-calculator.md` +(2026-07-30)** — the Development Effort Calculator is a separate concern +with its own formula decision and implementation arc; it now lives in +`workplans/TREV-WP-0010-development-effort-calculator.md`. The two remain +related (the Control Plane's Phase-registration flow is expected to use +the Calculator's output, per T03 below) but are sequenced and reviewed +independently. + +**Does not include:** declaring any real Phase for any repo, or changing +the Trust Service's core guarantees (determinism, append-only, no +discretionary conversion authority) — the Control Plane is a client of +the existing hosted service, bound by the same rules any other client is. + +Concept: `specs/TargetRevenueControlPlaneConcept.md`. + +## User rights model — decision (human gate) + +```task +id: TREV-WP-0009-T01 +status: todo +priority: high +human_accept_required: true +``` + +`specs/TargetRevenueControlPlaneConcept.md` §2 proposes a four-tier rights +model (Viewer/Contributor/Operator/Admin) and recommends option (b) for +the auth-attribution question: the Control Plane holds the one `binky` +Licensor token server-side and layers its own human-user auth/audit log +in front of it, rather than requiring a WP-0006 schema change for +per-human sub-credentials (option (a)). Confirm the rights tiers and the +(a)-vs-(b) choice, or propose a refinement. Agents may prepare a +recommendation and leave this `todo`. + +## Control Plane backend: auth layer and audit log + +```task +id: TREV-WP-0009-T02 +status: todo +priority: high +``` + +Using T01's confirmed rights model, implement the human-user +authentication/authorization layer and the Control Plane's own audit log +(concept §5) — which human user took which action, timestamped, alongside +the Trust Service's own signed record id for that action. This is the +piece that must exist before any write-capable UI flow (T03) can be built +responsibly, since the Trust Service's own signature only ever attests +"the `binky` Licensor did this," never which individual human initiated +it (concept §2's design tension). + +## Control Plane interactive UI: Phase registration and Development Credit entry + +```task +id: TREV-WP-0009-T03 +status: todo +priority: high +``` + +Implement the interactive flows themselves, using T02's auth/audit layer +and the existing hosted Trust Service API (`service/app.py`) as the +backend, unmodified unless T01 specifically selected the +per-human-sub-credential option: + +- Phase registration, informed by + `workplans/TREV-WP-0010-development-effort-calculator.md`'s output + once available (not blocking — a manual `target_basis` entry path must + work standalone too, since the Calculator may not be ready first); +- the priority flow: interactively creating a `development-credit` ledger + entry against a selected, already-registered Phase (concept §3's + step-by-step description) — select Phase, fill amount/currency/ + recognized-date/evidence-reference/Monetization-Extension, submit, + immediately show the updated `GET /phases/{id}/metrics` result; +- read-only views (Phase status, Ledger, Attestation, Breach/Compliance + Record history) — already public/unauthenticated at the Trust Service + layer, so these need no new backend work, only UI. diff --git a/workplans/TREV-WP-0010-development-effort-calculator.md b/workplans/TREV-WP-0010-development-effort-calculator.md new file mode 100644 index 0000000..41404b8 --- /dev/null +++ b/workplans/TREV-WP-0010-development-effort-calculator.md @@ -0,0 +1,111 @@ +--- +id: TREV-WP-0010 +type: workplan +title: "Development Effort Calculator" +domain: infotech +repo: target-revenue +status: active +owner: claude +topic_slug: infotech +created: "2026-07-30" +updated: "2026-07-30" +--- + +# Development Effort Calculator + +Turns measurable repo activity (human interaction time, workplan/task +volume, file/line complexity, AI token cost) into `target_basis` values +(`specs/PhaseManifestSpecification.md`), which combined with a human +Target Multiple classification (10x/100x/1000x) produces a proposed +Initial Target via the framework's own existing formula +(`specs/TargetRevenueFrameworkCore.md` §1.4) — **not a new formula**. This +calculator is a value-input tool feeding that existing formula, not a +competing valuation methodology. + +**Split from the former combined `TREV-WP-0009-control-plane-and-effort-calculator.md` +(2026-07-30)** — this deliverable has its own formula decision and +implementation arc, independent of the Target Revenue Control Plane +(`workplans/TREV-WP-0009-target-revenue-control-plane.md`), even though +the Control Plane's Phase-registration flow is expected to consume this +calculator's output once both exist. + +**Does not include:** declaring any real Phase for any repo, or choosing +a repo's Target Multiple classification unilaterally — per +`specs/DevelopmentEffortCalculatorConcept.md` §4, that classification +remains a human judgment call the calculator can inform but not make. + +Concept: `specs/DevelopmentEffortCalculatorConcept.md`. + +## Formula decision (human gate) + +```task +id: TREV-WP-0010-T01 +status: todo +priority: high +human_accept_required: true +``` + +`specs/DevelopmentEffortCalculatorConcept.md` §3 presents two combination +strategies without choosing between them: + +- **Candidate A (labor-cost-anchored, recommended v0 default)** — human + time drives `estimated_effort_days`/`daily_rate` directly; AI token + cost becomes `approved_direct_costs` (a real, metered direct cost); + workplan/task-volume and repo-size metrics are a sanity check/adjustment + on the human-time estimate, not a separate dollar figure. +- **Candidate B (composite-index-anchored)** — all four metric families + scored into one weighted complexity index, converted to dollars via a + declared $-per-unit rate. + +Confirm one as the adopted v0 approach (or propose a refinement), per the +same human-gate pattern already used for the degeneration policy formula +(`workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md` T02). +Agents may prepare a recommendation and leave this `todo`. + +## Implement the calculator + +```task +id: TREV-WP-0010-T02 +status: todo +priority: high +``` + +Using T01's confirmed formula, implement data collection for each metric +family and the combination formula itself, producing `target_basis` +field values ready to drop into a Phase Manifest: + +- **Human interaction time** — v0 default: commit-timestamp clustering + (session-gap grouping over git history), explicitly a floor estimate, + not a true count (concept §2a). +- **Workplan/task volume** — counts via state hub `list_tasks`/ + `list_workplans` scoped to the repo, or direct `workplans/` directory + inspection where hub coverage is thin (concept §2b). +- **File/line complexity** — raw counts with generated/vendored-path + exclusion (concept §2c's flagged distortion: dependency trees, + lockfiles, and generated files must not inflate this signal). +- **AI token cost** — `get_token_summary(scope="repo", id=...)`, the + strongest, least speculative input since it is a real metered cost, not + a proxy (concept §2d). + +Output must show its work (which inputs produced which numbers) — a +black-box dollar figure with no visible derivation would undermine the +"transparent, non-gameable" goal (`specs/TargetRevenueLicenseConcept.md` +§4.6) this whole framework is built around. + +## Apply calculator to real candidate repos + +```task +id: TREV-WP-0010-T03 +status: todo +priority: medium +``` + +Once T02 is implemented, run it against the real candidates already +identified (`specs/PilotPhaseCandidateSurvey.md`: `net-kingdom`'s +`NK-WP-0002`, `railiance-apps`'s `vergabe-teilnahme`, and +`info-tech-canon`'s service surface) to produce **proposed**, +calculator-derived `target_basis` values, replacing the hand-picked +illustrative figures currently in `examples/pilot-candidates/*/manifest.json`. +This remains draft/non-binding — updating a draft manifest's numbers is +not a Phase declaration, and does not touch +`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T05's own gate.