​
The lifecycle

Every transition is an RPC (transition_rfc) that re-checks the caller’s role and writes an audit row with actor, action and hash. Saving a new revision on a reviewed RFC invalidates the review. Changing an RFC’s number/domain after creation resets it to needing domain-owner approval again.

​
Documents and revisions

  • The editor document is Markdown with a YAML frontmatter block (rfc, title, domain, status, owners, created). Live lint covers both RFC 2119 keyword case (lowercase must/should/may are flagged; synonyms like SHALL/REQUIRED are normalized to the five canonical keywords at extraction time) and frontmatter validity.
  • Save stores the whole document into rfc_versions.body_md — frontmatter block included — and the parsed frontmatter into the JSONB column. A version row whose body_md lacks the --- block will fail every subsequent save with “fix frontmatter before saving”; the fix is a new, complete revision.
  • Versions are immutable rows; the revision number only ever grows.
The RFC editor flagging a lowercase RFC 2119 keyword as you type

​
Statement extraction

On approval (and re-approval of new revisions), the SPA invokes the extract-statements Edge Function:
  1. Input: RFC body + frontmatter + the RFC’s existing statements (slug + text).
  2. One LLM call returns statements with slug, level, section, text, sdlc_stage (design/implementation/review/ci/operations).
  3. The prompt requires slug reuse for materially unchanged statements; removed statements become status='retired', never deleted.
  4. Output is validated against a Zod schema after normalizing RFC 2119 synonyms (REQUIRED/SHALL/RECOMMENDED/OPTIONAL/FORBIDDEN/PROHIBITED → the five canonical levels) — one off-enum value must not discard the whole batch.
  5. Approval survives extraction failure (most commonly a free-plan org hitting the llm_extraction entitlement gate, HTTP 402) — the RFC is approved, the toast says extraction failed, and re-approving later re-runs it.
Statements extracted from an approved RFC, with stable slugs and RFC 2119 levels

​
Audit trail

Actions recorded per RFC include rfc.revision_saved, rfc.proposed, rfc.reviewer_assigned, rfc.reviewed, rfc.approved, rfc.enforced, plus member, API-key, GitHub, scan and violation events at org level. Settings → Audit shows the full chain with per-row hashes and offers JSON/CSV export; the export can be verified independently:
The export comes from a canonicalizing view (stable JSON form), so a verifier that recomputes sha256(prev_hash || canonical_json(entry)) needs no database access.
Settings → Audit: the append-only, hash-chained audit trail with export buttons