Skip to content

EP-0009: The EP Process

Status: active Type: process

The PEP-1 analogue: this active process EP defines what EPs are, when one is warranted, the type and status vocabulary, and the durability rules. docs/EP/README.md is the index; this EP is the process rule.

Normative home: this active EP, specifically its §Specification.

Ruling recorded 2026-06-11. The corpus already follows this process de facto, and the first coherence remediation made the process dependency explicit by marking this EP active. This note records that activation in the EP itself so the process document follows its own recorded-ruling rule.

Abstract

re-frame2 EPs follow the Python Enhancement Proposal model: durable, numbered design records that carry a decision from proposal through ruling into a normative home, and then remain forever as the record of why — including when the answer was no. The authority rule is per type: a standards-track EP graduates into spec/, which is then the authoritative contract — the EP is the design document behind it, never a second normative home. A process EP graduates into its named normative home, which MAY be the active EP itself (the PEP-8 precedent: the style guide is the PEP). Every active process EP names its normative home explicitly so there is exactly one.

Relationships

  • README is the index and summary page only. It mirrors statuses and points readers at this EP for process rules; it is not a second normative home.
  • scripts/check_ep_status_sync.py enforces the mechanical part of this process: README/header status sync, status grammar, and the post-EP-0005 Type: header rule.
  • EP-0005 and EP-0006 are the pattern for final EPs that outlive their implementation waves through a closed errata ledger. This EP generalizes that pattern for future standards-track EPs.
  • EP-0007 (one name per fact) is the sibling process EP that graduates into spec/Conventions.md. This EP remains active as its own process rulebook.

Specification

When an EP is warranted

An EP is for:

  • feature-level or public-contract decisions with unresolved alternatives (new artefacts, breaking contract changes, cross-cutting invariants — EP-0001..0006, EP-0008); or
  • process and convention rules worth a durable rationale record (the PEP-8 analogue — EP-0007, this EP).

Settled, mechanical material — a rename with no alternatives, a doc fix, a bug — goes straight to beads and spec/ edits. The test: if the design conversation fits in a bead description, it is a bead. When in doubt, the operator (Mike) decides; EPs are cheap to reject and rejection is itself a valuable record.

Types

Type Meaning Terminal success status
standards-track changes the framework's public contracts or runtime behavior; graduates into spec/ + implementation beads final
process rules about how the project itself works (conventions, lifecycle, review posture); on acceptance it names its normative home — either an existing spec doc (EP-0007 names Conventions.md §Namespacing) or the active EP itself (this EP's home is this EP) — and that one home governs active

EP-0001 through EP-0005 may omit the Type: header and are treated as standards-track. EPs numbered EP-0006 and later carry an explicit Type: header.

Statuses

proposal ──► accepted ──► final            (standards-track)
    │             └─────► active           (process)
    ├──► rejected     (ruled no — kept as the record of why not)
    ├──► withdrawn    (author retracted — kept)
    └──► deferred     (parked with a stated revisit trigger)

any non-terminal EP may become: superseded-by EP-NNNN (kept)

The Status: line is machine-readable. Its value MUST be one of: proposal, accepted, final, active, rejected, withdrawn, deferred, or superseded-by EP-NNNN.

  • proposal — under discussion. Normative-voiced text is permitted (it makes graduation a move, not a rewrite) but binds nothing; the proposal itself is not implementation authority. Independently settled work may still land by bead/spec/operator ruling and be recorded in the proposal as evidence or an already-resolved dependency, but any decision that relies on the EP waits for acceptance.
  • accepted — ruled by the operator; graduation into the normative home + beads begins. EP-authorized implementation may start.
  • final / active — graduated. The named normative home is now authoritative: for standards-track that is spec/, and where the EP body and the spec differ, the spec governs (the EP-0002 precedent); for process EPs it is the home the EP named — possibly the EP itself, in which case the EP's §Specification is the rule and the rest of the document remains rationale. A final EP MAY carry an implementation-errata ledger (the EP-0005 pattern): final means the decisions are settled; it does not assert the build is gap-free. Ledger rows cite live bead ids and are struck as they close.
  • rejected / withdrawn / deferred / superseded — terminal or parked, and always kept: recording why something was not done is half an EP corpus's value.

Durability rules

  1. EPs are never deleted. Numbers are stable and never reused.
  2. Resolved Decisions live in the EP. Operator rulings on an EP's open issues are recorded in a Resolved Decisions section (the EP-0001/0002 pattern); an EP must not go final/active with open issues silently unresolved (the EP-0004 lesson — dispositions are recorded even when the answer emerged from the implementation).
  3. Amendment is allowed only before implementation. Once an EP is accepted and beads are in flight, substantive changes go through a new EP or a recorded ruling — not silent edits. (Mechanical corrections and errata-ledger updates are always fine.) Mechanical means the edit cannot change a reasonable reader's understanding of the proposal, alternatives, rationale, ruling, or scope; anything past that line is recorded as a dated erratum/addendum beside the affected passage, preserving the original text — freeze meaning, not bytes (rf2-r7ahi). Relationship history is bidirectional: when a later EP changes an accepted/final predecessor, the successor cites the predecessor and the predecessor gains a dated follow-up note linking back to the successor. If a successor absorbs a non-terminal EP, that EP and the README index move to superseded-by EP-NNNN; a terminal predecessor keeps its historical status and records the later relationship in an addendum instead.
  4. One EP, one decision surface. Bundling independent decisions invites all-or-nothing rulings; prefer narrow EPs and cross-references.
  5. Graduation includes a guide-impact assessment: the graduating EP names which docs/core chapters change and which payoffs become newly teachable; the docs bead of the EP's wave carries those edits (e.g. EP-0010 upgrades guide ch.07's clock section from the cofx idiom to the envelope stamp; EP-0011 rewrites ch.10's no-await box around the reply envelope; EP-0008 extends ch.16's production section with the always-on error axis; EP-0013 eventually warrants a realms chapter). An EP may conclude "no human-facing guide change yet" and record why.

Document conventions

  • Filename EP-NNNN-slug.md; preamble lines Status: and Type:, plus Created: and — from acceptance onward — Resolution: for new EPs. New and materially revised EPs follow one forward-looking top-level structure: Abstract → Motivation → Specification → Rationale → Backwards Compatibility → Resolved Decisions → Open Issues → References, keeping the sections that apply. This is the compact PEP shape the EP-0030..EP-0035 corpus adopted, and it is the authoring default. Older EPs (this one included) keep their existing sections — their bodies are a historical record, not a migration backlog.
  • EP-0030 and later carry an ISO Created: YYYY-MM-DD line. Once such an EP is no longer proposal, it also carries a non-empty Resolution: line recording the ruling chronology. check_ep_status_sync.py enforces this transition boundary; older omissions remain historical rather than a retrofit project.
  • Where the older house sections now live: scope (goals/non-goals) opens the Specification, and the ownership half of the old Relationships section joins it there; relationships/provenance — dependencies, cross-references, and supporting spikes/findings — live in References; implementation tracking lives in the beads issue tracker (referenced from References), and the graduation guide-impact assessment closes the Specification (rule 5); resolved rulings live in Resolved Decisions (rule 2); and the author's recommendation is argued in the body and dispositioned under Resolved Decisions once the operator rules.
  • New EPs carry Type: standards-track or Type: process. EPs predating this process may omit Type: and are treated as standards-track.
  • This is a PEP-shaped house process, not Python's repository wire format. The H1 owns number/title; Git history, the Resolution: chronology, and linked programme records supply provenance; dated errata/addenda are the local Post-History equivalent. Do not mint empty Python-governance fields such as Sponsor or Discussions-To merely to resemble an RFC preamble.
  • State the positive principle first; subtractive framing is migration mechanics, not the rule (the EP-0002 lesson).
  • Dependencies live in References; material successor relationships are linked in both directions per durability rule 3. The index row in docs/EP/README.md carries status + one-line summary. check_ep_status_sync.py enforces README status sync, status/type grammar, the EP-0030 metadata boundary, supersession-target existence, and index-link numbering.

Backwards Compatibility

This codifies the process the EP corpus is already converging on. Existing EP-0001..EP-0005 files may continue without Type: headers; they are treated as standards-track. The README remains an index, not a second normative home.

Bead Plan

  1. Done. README bead: docs/EP/README.md is the per-type authority summary, lifecycle vocabulary, and index, pointing here for the full process.
  2. Done. Tooling bead: check_ep_status_sync.py enforces README/header status sync, status grammar, the post-EP-0005 Type: header rule, the EP-0030+ transition metadata, supersession targets, and index numbering.
  3. Done. EP-template.md encodes the controlled status/type vocabulary, per-type graduation, created/resolution metadata, and bidirectional successor-record rule. Implementor guidance points to this process rather than maintaining a second lifecycle.

Recommendation

Keep this EP active. It codifies the model the corpus already de-facto follows (stable numbers, graduation into spec, resolved-decision records, the errata ledger) and adds the missing pieces: the worthiness bar, the type split, the terminal statuses, and the never-delete rule.

References