target-revenue/specs/PhaseManifestSpecification.md

# 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`).