RFC authoring structure audit
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Observed and migrated on 2026-10-01. RFC-0000 §5 requires an accompanying
QA.md for each RFC. The owner chose per-RFC files. All 57 flat authored
narrative/rfc-NNNN.md files now have a companion
narrative/rfc-NNNN/QA.md, and the former central decision log is a generated
index at narrative/QA.md.
The 18 original RFC sections were moved without changing their question and answer text. They contain 91 questions: 90 answered and one explicitly open multi-host write-sharding question in RFC-0007. Six draft questions from the authored RFC-0055 and RFC-0056 prose were moved into their companions, preserving the numbered question sections as links. RFC-0000 and RFC-0019 through RFC-0054 have since received focused authoring reviews. The owner-approved RFC-0019 and RFC-0020 decisions are reflected in their authored text, Lean catalogs, and RDF projections. No companion retains an authoring-review-pending notice. A missing historical entry was not evidence that its RFC had no open design questions.
python3 tools/check_qa.py checks file coverage, IDs, question status, and
index drift; --write regenerates only the central index. The corpus link
checker includes the companions and index. tools/check_release.py blocks a
normative release while any file remains review-pending or any question is
open. The contributor workflow now names the companion files and commands.
Owner: spec. Remaining acceptance: resolve or explicitly defer the 195
open questions with an owner and trigger, then pass the strict release gate.
Seven-part RFC layout audit
RFC-0000 §5 separately requires seven content areas in every RFC: scope, invariants, data contract, resolution/evaluation rules, failure modes and diagnostics, security/authorization, and compatibility/migration. The current 57 authored RFCs retain topic-specific H2 layouts. A source scan on 2026-10-02 found the following literal H2 heading-token coverage:
| Token | RFCs with a matching H2 |
|---|---|
scope | 23 |
invariant | 45 |
data contract | 0 |
evaluation | 1 |
failure | 13 |
security | 22 |
compatibility | 32 |
Thirty-three RFCs have fewer than three of those seven tokens in their H2
headings. These counts do not show that the content is absent: for example,
RFC-0026 uses Call Mode Semantics, gRPC Status Code Taxonomy, Auth, and
TLS Configuration instead of the prescribed labels. They do show that a
literal seven-heading gate would fail most of the existing corpus and cannot
be introduced as a formatting-only change. tools/check_rfc_structure.py
checks generated RDF structure, not this authored Markdown obligation.
The owner must choose whether §5 requires seven named authoring sections or seven reviewed semantic obligations that may appear under topic-specific headings. For the latter, record each RFC’s source section or explicit not-applicable rationale for all seven areas in a drift-gated inventory, with no automatic inference from heading words. For the former, migrate authored RFCs and their links/anchors deliberately, then gate the required headings. In either case, do not mark an RFC structurally complete solely because it has front matter, a companion Q&A, or emitted RDF.