# How to read the specs

> Status headers, RFC 2119 keywords, living files versus immutable RFCs, independent 26.x lines, and what Draft seeking input still leaves open.

- Repository: g2tf-org/g2tf-standards
- GitHub: https://github.com/g2tf-org/g2tf-standards
- Human docs: https://grok-wiki.com/public/docs/g2tf-org-g2tf-standards-436ba3f3e0ff
- Complete Markdown: https://grok-wiki.com/public/docs/g2tf-org-g2tf-standards-436ba3f3e0ff/llms-full.txt

## Source Files

- `README.md`
- `CONTRIBUTING.md`
- `GOVERNANCE.md`
- `rfcs/README.md`
- `specs/g2p/spec.md`
- `architecture/overview.md`

---

---
title: "How to read the specs"
description: "Status headers, RFC 2119 keywords, living files versus immutable RFCs, independent 26.x lines, and what Draft seeking input still leaves open."
---

Every file under `specs/`, `members/`, and `architecture/` is a living document except `architecture/design-principles.md`, which is marked `Status: Informative`. The only published RFC is `rfcs/grid-2-rfc-1.pdf` (RFC #1, August 2026). That PDF is archival and is never edited. Normative evolution happens in the Markdown files. Protocol files currently carry `Version: 26.0-draft` and `Status: Draft — seeking input`. Member and architecture files carry the same status string (or `Informative`) and do not yet carry a `Version:` line.

## Document surfaces

```text
rfcs/grid-2-rfc-1.pdf          immutable narrative snapshot (Published)
architecture/*.md              system model (Draft, one Informative file)
specs/{g2p,gcap,desp}/spec.md  G2P / GCAP / DESP (26.0-draft)
members/{use,buffer,source,allocator}.md
                               per-element behavior (Draft — seeking input)
CONTRIBUTING.md                keyword and status-header rules
GOVERNANCE.md                  Draft → Proposed → Stable → RFC
```

| Path | What it is | Header status now | RFC 2119 boilerplate |
|---|---|---|---|
| `rfcs/grid-2-rfc-1.pdf` | Immutable RFC #1 | Published (table in `rfcs/README.md`) | N/A — do not edit |
| `specs/g2p/spec.md` | Transport and messages | `26.0-draft` · Draft — seeking input | Present |
| `specs/gcap/spec.md` | Clearing | `26.0-draft` · Draft — seeking input | Present |
| `specs/desp/spec.md` | Service classes | `26.0-draft` · Draft — seeking input | Present |
| `members/*.md` | Use, Buffer, Source, Allocator | Draft — seeking input | Present |
| `architecture/*.md` except design-principles | System model | Draft — seeking input | Present except `overview.md` |
| `architecture/design-principles.md` | Design rationale | `Status: Informative` | Absent (by rule) |

`README.md` summarizes `architecture/` as **Draft** and `specs/` plus `members/` as **Draft — seeking input**. File headers are the authority when those labels differ.

<Note>
`architecture/overview.md` is `Status: Draft — seeking input` but does not include the RFC 2119 / RFC 8174 sentence. Treat its prose as the system model, not as a keyword-normative member or protocol spec.
</Note>

## Status headers

Normative files open with a one-line header. Protocol specs add `Version:` and a stack role.

```markdown
**Version:** 26.0-draft · **Status:** Draft — seeking input · **Editors:** TBD
**Role in stack:** Addressing, service configuration, and response — …
```

```markdown
**Status:** Draft — seeking input · **Editors:** TBD · **Source:** [RFC #1](../rfcs/grid-2-rfc-1.pdf), §…
```

```markdown
**Status:** Informative · **Source:** [RFC #1](../rfcs/grid-2-rfc-1.pdf), §Key Design Principles; …
```

<ParamField body="Status" type="enum" required>
Allowed values on living files: `Draft — seeking input`, `Proposed`, `Stable (vXX.Y)`, or `Informative`. Current normative files all use `Draft — seeking input`.
</ParamField>

<ParamField body="Version" type="YY.N-draft" required>
Present only on `specs/g2p/spec.md`, `specs/gcap/spec.md`, and `specs/desp/spec.md`. Current value is `26.0-draft` on each line independently.
</ParamField>

<ParamField body="Editors" type="string" required>
Each normative document lists its editors here. All current headers say `TBD`.
</ParamField>

<ParamField body="Source" type="RFC #1 section" required>
Architecture and member files point at the RFC #1 section they decompose. Protocol files do not use this field; they declare `Role in stack` instead.
</ParamField>

<ParamField body="Role in stack" type="string">
Protocol-only. G2P is addressing, service configuration, and response. GCAP is fair allocation and scheduling. DESP is service classification and prioritization.
</ParamField>

### Lifecycle states

```mermaid
stateDiagram-v2
    [*] --> Draft: new living file
    Draft --> Proposed: rough consensus on scope and approach
    Proposed --> Stable: implementable YY.N
    Stable --> RFC: Task Force publishes snapshot to rfcs/
    RFC --> [*]: immutable; errata only
    note right of Draft
        Status: Draft — seeking input
        current state of specs/, members/,
        and most of architecture/
    end note
    note right of Stable
        Status: Stable (vXX.Y)
        changes require a compatibility statement
    end note
    note right of RFC
        rfcs/*.pdf never modified
        living files keep evolving
    end note
```

| Status | Meaning | What you may treat as frozen |
|---|---|---|
| `Draft — seeking input` | Scope and approach are open. Open items and `*(Open: …)*` markers are first-class. | Nothing. Normative `MUST`s still bind a reader of that file, but they can change without a compatibility statement. |
| `Proposed` | Rough consensus on scope and approach. Not yet an implementable `YY.N`. | Scope and approach, unless the responsible editor records otherwise. |
| `Stable (vXX.Y)` | Implementable. Further changes require a compatibility statement on the PR. | The `vXX.Y` contract until a new version is published. |
| `Informative` | Rationale only. Must not use RFC 2119 keywords. | No conformance claim. |
| RFC in `rfcs/` | Immutable snapshot. | The PDF text. Fixes land as `errata` Issues, then in living files. |

<Warning>
`GOVERNANCE.md` says the README carries a compatibility matrix. `README.md` only promises that matrix “as the specs diverge in maturity.” No matrix exists yet. Do not infer cross-protocol compatibility from the shared `26.0-draft` string.
</Warning>

## RFC 2119 keywords

Normative documents (`specs/`, `members/`, and any `architecture/` file **not** marked `Status: Informative`) interpret uppercase keywords per [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174):

| Keyword | Spec meaning in this repo |
|---|---|
| `MUST` / `MUST NOT` | Absolute requirement or prohibition for a conformant Member, Allocator, or protocol implementation. |
| `SHOULD` / `SHOULD NOT` | Recommended default. A deviation needs a recorded reason. |
| `MAY` | Optional. Absence of the behavior is still conformant. |

Protocol files restate this immediately under the header:

```text
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be
interpreted as described in RFC 2119 / RFC 8174.
```

<Info>
RFC 8174 restricts special meaning to **uppercase** keywords. Lowercase “must” in narrative is not a requirement. Informative documents, including `architecture/design-principles.md` and the DESP §3 workload-mapping section, must avoid the keywords entirely.
</Info>

A single file can mix layers. `specs/desp/spec.md` is normative overall; **§3 Mapping workloads to classes (informative)** is not a class-assignment requirement. Flex 0–3 and ERCOT CLR/PCLR mappings there do not bind the Allocator.

Pull requests against normative files must use these keywords and must state compatibility impact. Two spec editors review those PRs. Merged decisions go into the `GOVERNANCE.md` decision log.

## Living files versus immutable RFCs

RFC #1 is the August 2026 launch narrative. The repo then decomposes that narrative into commentable surfaces. The 2026-08 decision-log entry is explicit: keep the immutable story in `rfcs/`, put evolving requirements in living Markdown.

```text
                    never rewrite
  rfcs/grid-2-rfc-1.pdf ─────────────► archival citation
           │
           │  decompose / errata Issues labeled `errata`
           ▼
  architecture/  specs/  members/     living text, PRs allowed
           │
           │  Task Force snapshot when a line is Stable
           ▼
  rfcs/grid-2-rfc-N.pdf               next immutable RFC
```

<Steps>
  <Step title="Cite RFC #1 for intent">
    Use the PDF for the proposal, membership story, protocol-interaction table, figures, and phased-adoption framing. Do not patch the PDF.
  </Step>
  <Step title="Implement from living files">
    Implement G2P, GCAP, DESP, and member behavior from `specs/` and `members/`. Architecture files define domains, the one-minute clock, federation, and failsafe.
  </Step>
  <Step title="File RFC mistakes as errata">
    Defects in RFC #1 are GitHub Issues labeled `errata`. The fix is written into the living spec, not into the PDF.
  </Step>
  <Step title="Treat a new RFC as a snapshot, not a branch">
    Publication to `rfcs/` freezes that snapshot. The Markdown files keep their own `Status` and `Version` lines.
  </Step>
</Steps>

New or substantially revised normative text prefers **one sentence per line** so diffs stay reviewable.

## Independent 26.x version lines

Protocol versions use **YY.N** (year of the line, then increment). `26.0` is the first 2026 release. G2P, GCAP, and DESP version **independently**. Sharing `26.0-draft` today is coincidence of launch year, not a lockstep contract.

| Line | Current identifier | 26.0 scope already written into the file |
|---|---|---|
| G2P | `26.0-draft` | Positions are units of energy in the interval. Wire format, state machines, version negotiation, and conformance vectors are unspecified. |
| GCAP | `26.0-draft` | Headroom → Buffers → C-then-B-then-A curtailment. Exact proportionality formula is open. |
| DESP | `26.0-draft` | Classes A / B / C above Grid 1 Firm. Supply class structure may stay single-class in 26.0. |
| Architecture / members | no `Version:` field | Overview states 26.0 is energy in the one-minute window on the bulk power system only. |

Out of 26.0 unless a later `YY.N` says otherwise: voltage-support goal-seeks, distribution-scale devices (IEEE 2030.5), and routing through SSTs / HVDC.

When a line reaches `Stable (vXX.Y)`, a breaking change on that line needs a compatibility statement on the PR. Cross-protocol impact is supposed to land in the README matrix once the three lines diverge. Until that table exists, do not assume G2P `26.n` works with GCAP `26.m`.

## What Draft seeking input still leaves open

`Draft — seeking input` means implementers can code against written `MUST`s, but several surfaces are explicitly unfinished. Treat `*(Open: …)*`, `## Open items`, and `## To be specified` as non-requirements.

<AccordionGroup>
  <Accordion title="G2P — unspecified mechanism">
    Identifier format; forward-vector length, resolution, and revision; verification granularity, metering source of truth, and attestation; intra-interval timing budget and clock sync; PKI / key management, NERC CIP mapping, replay protection; wire format and encoding; per-element state machines; version negotiation; conformance test vectors.
  </Accordion>
  <Accordion title="GCAP — unspecified clearing details">
    Exact proportionality weights (connection size vs. request size); indivisible loads; multi-constraint (nodal) vs. single-zone headroom; whether deferred Class C accrues priority across intervals; mid-interval interaction with market dispatch instructions.
  </Accordion>
  <Accordion title="DESP — naming, extensibility, SLAs">
    Assured/Preferred/Best-Efforts vs. Firm/Semi-Firm/Flex names; whether class count is fixed at three; per-class unmet-frequency envelopes; per-class ramp and snap-back limits; enforcement of declared class behavior.
  </Accordion>
  <Accordion title="Members">
    Use: facility-type class mapping, minimum telemetry, unused-allocation return. Buffer: SoC visibility, multi-Buffer priority, investment framing. Source: forecast-error vs. headroom, same-interval redirect to co-located Buffers, single-class vs. mirrored A/B/C supply. Allocator: active/standby redundancy, input-digest publication, utility vs. third-party hosting.
  </Accordion>
  <Accordion title="Architecture">
    Allocation domains: conformance tests, machine-readable domain descriptors, overlapping-domain membership. Temporal position: federated clock epoch, late-arrival / skew, 15-minute settlement interaction. Failsafe: numeric staleness thresholds, re-entry hysteresis, coincidental-fallback stability, fallback audit. Federation: announcement payload, loop prevention, import policy, Phase 2 milestone criteria.
  </Accordion>
</AccordionGroup>

RFC #1 also parks three Discussion categories that living files point back to rather than close: **Commercial terms**, **Reliability assurance**, and **Engineering**. Those are not protocol knobs. Domain class-mix limits, for example, are commercial-terms matters in the domain agreement, not DESP wire fields.

<Check>
A written `MUST` in a Draft file is still a requirement of that file. An `Open` marker is not. If a behavior you need sits only in an Open item, it is not implementable from the spec yet — raise a Discussion or a PR.
</Check>

## How to apply a Draft requirement

<Steps>
  <Step title="Read the file header first">
    Confirm `Status`, `Version` if present, and whether the file is `Informative`. Skip keyword semantics on Informative files.
  </Step>
  <Step title="Separate MUST from Open">
    Implement uppercase `MUST` / `MUST NOT`. Leave `*(Open: …)*` and `## Open items` unimplemented unless your deployment documents a local choice.
  </Step>
  <Step title="Prefer living text over the PDF on conflict">
    RFC #1 is the source narrative. If living text has already decomposed or tightened a rule, the Markdown wins for implementers. File `errata` if the PDF is wrong.
  </Step>
  <Step title="Do not invent a wire or a compatibility matrix">
    G2P has no specified encoding. G2P, GCAP, and DESP are not version-locked. Interop claims need identical-input GCAP determinism plus whatever local encoding the domain agrees — not a repo-defined packet.
  </Step>
  <Step title="Report Phase 0 experience in Discussions">
    Shadow-mode implementations execute only the Grid 1 baseline. Running-code reports feed the next revision; they do not promote a file out of Draft by themselves.
  </Step>
</Steps>

## Related pages

<CardGroup>
  <Card title="Document lifecycle" href="/document-lifecycle">
    Draft → Proposed → Stable → RFC, YY.N versions, compatibility statements, and the GOVERNANCE.md decision log.
  </Card>
  <Card title="Comment, review, and file errata" href="/comment-and-errata">
    Discussions vs Issues vs PRs, the `errata` label, two-editor review, and RFC 2119 on normative changes.
  </Card>
  <Card title="Contributing" href="/contributing">
    Open participation, comment-cycle steps, one-sentence-per-line, and Phase 0 implementation reports.
  </Card>
  <Card title="Overview" href="/overview">
    Overlay plane, three-protocol stack, and first routes after RFC #1.
  </Card>
  <Card title="G2P reference" href="/g2p-reference">
    Current 26.0-draft message families and the still-unspecified wire format.
  </Card>
  <Card title="Governance and licenses" href="/governance">
    Editors, rough consensus, CC BY 4.0 spec text, Apache-2.0 code, trademarks.
  </Card>
</CardGroup>