tegwick
55a1756f7c
Moves TargetRevenueLicenseConcept.md from the separate singular spec/ directory into specs/ (git mv, preserving history) and updates every live cross-reference (README, CONTRIBUTING, all specs/*.md, workplans, schema comments, source docstrings, test file) to the new path. This resolves the spec/ vs specs/ split that history/260728-SWOT-Assessment.md flagged as a "perpetual footgun" and recommended deciding on. The historical record of that split and the recommendation itself are left unedited in history/ (a dated assessment, not a living document) — only README and TSD now document the merge as resolved, with a pointer back to that history file for context. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
86 lines
5.3 KiB
Markdown
86 lines
5.3 KiB
Markdown
# Phase Manifest Specification (Normative Extract)
|
|
|
|
**Document version:** TRF-PhaseManifest-0.1
|
|
**Status:** Normative extract, Stage 0
|
|
**Extracted from:** `specs/TargetRevenueLicenseConcept.md` §16 and `specs/TechnicalSpecificationDocument.md` §3.1
|
|
**Machine-readable counterpart:** `schemas/phase_manifest.schema.json` — implemented and tested under `workplans/TREV-WP-0002-trust-service-foundation.md` T02 (`src/target_revenue/validation.py::validate_phase_manifest`). This document is the prose normative reference; the schema file is the authoritative machine-checkable definition. They must not drift — a change to one requires reviewing the other.
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
A Phase Manifest is the immutable, machine-readable declaration that establishes a Phase per `specs/TargetRevenueFrameworkCore.md` §1.1. No Development Credit may be accepted for a Phase before its Manifest is published (Rule 1).
|
|
|
|
## 2. Field tiers
|
|
|
|
| Field | Type | Tier | Notes |
|
|
|---|---|---|---|
|
|
| `framework` | string | Required | Framework version tag, e.g. `TRF-0.1`. |
|
|
| `license` | string | Required | TRSL version tag, e.g. `TRSL-0.1`. |
|
|
| `phase.id` | string (URN `trsl:phase:<slug>`) | Required | Globally unique; immutable once published. |
|
|
| `phase.milestone_release.name` | string | Required | Human-readable release name. |
|
|
| `phase.milestone_release.source_revision` | string | Required | Immutable VCS reference. |
|
|
| `phase.milestone_release.artifact_sha256` | string (hex-64) | Recommended | Required if a built artifact (not just source) is governed. |
|
|
| `phase.initial_target.amount` | decimal (> 0) | Required | Immutable once Development Credits are accepted (Rule 1). |
|
|
| `phase.initial_target.currency` | ISO 4217 code | Required | One native currency per Phase (working default Q6). |
|
|
| `phase.target_basis.estimated_effort_days` | decimal | Recommended | Transparency metadata (working default Q5), not legally required. |
|
|
| `phase.target_basis.daily_rate` | decimal | Recommended | |
|
|
| `phase.target_basis.approved_direct_costs` | decimal | Recommended | |
|
|
| `phase.target_basis.target_multiple` | decimal | Recommended | Open decimal (working default Q4); guidance classes are not a closed enum. |
|
|
| `phase.future_license` | enum `{MIT, Apache-2.0}` | Required | Closed set for Stage 0 (working default Q3). |
|
|
| `phase.degeneration_policy` | string (URN `trsl:policy:<slug>@<version>`) | Required | e.g. `trsl:policy:linear-longstop-v0@1.0`. |
|
|
| `phase.longstop_at` | ISO 8601 timestamp | **Required for Stage 0** | Stage 0 working default (Q8): elevates this from TSD's original "recommended" to required, so every Phase has a maximum-protection instant. **Marked provisional pending promotion** — see §4. |
|
|
| `phase.ledger` | URL or path URI | Required | Location of the authoritative Target Ledger for this Phase. |
|
|
| `extensions[]` | list of `trsl:extension:<id>@<version>` | Optional | Applicable monetization profiles/extensions. |
|
|
|
|
## 3. Validation rules
|
|
|
|
1. A manifest missing any Required field **must** be rejected at registration or offline validation, not merely flagged.
|
|
2. `phase.initial_target.amount` **must not** decrease or increase after first publication except through a versioned, historically-visible correction record distinct from ordinary Remission Credit (Rule 1). Stage 0 has no such correction-record type yet; any observed change is a violation (`src/target_revenue/validation.py::check_manifest_immutability`).
|
|
3. `phase.id` **must** be immutable and **must not** be reused across Phases, including a superseded or abandoned Phase.
|
|
4. `phase.initial_target.currency` fixes the Phase's native currency; every Target Ledger entry for this Phase must use the same currency (working default Q6, enforced in `specs/TargetLedgerSpecification.md`).
|
|
|
|
## 4. Stage 0 working default requiring promotion
|
|
|
|
`phase.longstop_at` is required by Stage 0 validators as a working default (Q8), not yet a permanent normative rule. Promoting this requirement into permanent status (i.e., removing the "working default" qualifier) requires human accept per `SCOPE.md` §4 and `workplans/TREV-WP-0003-normative-core-extraction.md` T06. Until then, treat it as: **binding for Stage 0 conformance, provisional as permanent norm.**
|
|
|
|
## 5. Minimal example
|
|
|
|
```yaml
|
|
framework: TRF-0.1
|
|
license: TRSL-0.1
|
|
|
|
phase:
|
|
id: trsl:phase:example-001
|
|
milestone_release:
|
|
name: release-1.0
|
|
source_revision: abc123
|
|
artifact_sha256: "44cd1493bd179c1207c7025c1372cdad89aac114e151db27aba2bdf3d55c688"
|
|
|
|
initial_target:
|
|
amount: 100000
|
|
currency: USD
|
|
|
|
target_basis:
|
|
estimated_effort_days: 1
|
|
daily_rate: 1000
|
|
approved_direct_costs: 0
|
|
target_multiple: 100
|
|
|
|
future_license: MIT
|
|
degeneration_policy: trsl:policy:linear-longstop-v0@1.0
|
|
longstop_at: "2031-08-01T00:00:00Z"
|
|
ledger: examples/phase-001/ledger.json
|
|
|
|
extensions:
|
|
- trsl:extension:development-license@1.0
|
|
- trsl:extension:cost-plus-operations@1.0
|
|
```
|
|
|
|
A working, schema-validated instance of this example lives at `examples/phase-001/manifest.json`.
|
|
|
|
## 6. Not covered here
|
|
|
|
- Ledger entry schema and the Outstanding Target fold: `specs/TargetLedgerSpecification.md`.
|
|
- Extension contract fields: `specs/MonetizationExtensionSpecification.md`.
|
|
- Final legal text for what a Phase Manifest legally binds: deferred to specialist legal review (`workplans/TREV-WP-0001-license-prior-art-research.md`).
|