gnomonlearn
Docs/RFC authoring structure audit

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:

TokenRFCs with a matching H2
scope23
invariant45
data contract0
evaluation1
failure13
security22
compatibility32

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.