Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(rfc): address Codex review — fence-aware format gate, exact corpus counts

Browse Source 
Two findings from the pre-ready review, both verified:

- verify-rfc-format scanned raw lines, so an RFC quoting a Status line,
  a banned heading, or the grandfather comment inside a fenced example
  would false-positive. The content scans (duplicate Status, H2 headings,
  banned headings, grandfather, legacy marker) now ignore fenced blocks;
  the positional header-block checks stay raw. Verified: a fenced
  'Status: implemented' + '## Plan' + grandfather quote inside a walked
  RFC no longer trips the gate.

- The companion RFC's pre-format corpus counts were imprecise: 27
  distinct Status spellings (reasons collapsed), not 'some fifteen';
  nineteen implemented files carrying thirty proposal-era heading
  occurrences, not 'over twenty files'; three English files (plus one zh
  counterpart) with no status, not four.
This commit is contained in:
Tianyi Cui
2026-07-05 23:45:34 +08:00
parent e6fad266a6
commit 0e29de459e
2 changed files with 20 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/rfc/implemented/process/2026-07-05-uniform-rfc-format.md
View File

@@ -4,7 +4,7 @@ Status: implemented
## Problem
The tree's layout is uniform — [the classification scheme](2026-06-20-rfc-classification.md) path-encodes lifecycle and class and gates both — but the file insides never were. The corpus the format decision faced had two H1 spellings; some fifteen `Status:` line spellings, from bare enums through dated parentheticals duplicating what the filename and git already carry, to four files with no status at all; two body genres side by side (ADR-style `Context`/`Decision`/`Consequences` beside proposal-style `Problem`/`Proposal`/`Risks`), so every new RFC guessed its shape from whichever neighbor its author opened; thirty-nine files carrying a debt comment that flagged them as "legacy ADR/RFC body format" awaiting a unified template that was never actually defined; and over twenty implemented RFCs still carrying the proposal-era headings (`Acceptance criteria`, `Plan`, `Migration plan`) that the [documentation standard's slop checklist](../../../AGENTS.md) outlaws for `implemented/` — outlawed, but enforced by nothing, so the `proposed/` → `implemented/` move could silently skip the rewrite [implemented/AGENTS.md](../AGENTS.md) requires.
The tree's layout is uniform — [the classification scheme](2026-06-20-rfc-classification.md) path-encodes lifecycle and class and gates both — but the file insides never were. The corpus the format decision faced had two H1 spellings; some twenty-seven `Status:` line spellings once free-text rejection reasons are collapsed — bare enums, dated parentheticals duplicating what the filename and git already carry — plus three English files (and the zh counterpart of one of them) with no status at all; two body genres side by side (ADR-style `Context`/`Decision`/`Consequences` beside proposal-style `Problem`/`Proposal`/`Risks`), so every new RFC guessed its shape from whichever neighbor its author opened; thirty-nine files carrying a debt comment that flagged them as "legacy ADR/RFC body format" awaiting a unified template that was never actually defined; and nineteen implemented RFCs still carrying thirty occurrences of the proposal-era headings (`Acceptance criteria`, `Plan`, `Migration plan`, `Proposal`) that the [documentation standard's slop checklist](../../../AGENTS.md) outlaws for `implemented/` — outlawed, but enforced by nothing, so the `proposed/` → `implemented/` move could silently skip the rewrite [implemented/AGENTS.md](../AGENTS.md) requires.
## Decision
@@ -20,7 +20,7 @@ The whole corpus was normalized in the same change that defined the format — t
- **Dated status** (`Status: implemented (accepted YYYY-MM-DD)`) — rejected: the acceptance date is narrated history the writing rules keep out of docs; the filename carries first-proposed, git carries the rest, and the gate could check a date's format but never its truth.
- **A bare `# <title>` H1** — rejected: the `RFC: ` prefix is the corpus-majority form and self-describes the genre when a file is read outside its tree; the index generator strips it, so index rows are identical either way.
- **`## What we give up` as the implemented closer** (the README's own phrase for what an RFC records) — rejected: it names only costs, and an honest consequences section records what the trade-off bought as well.
- **Convention without a gate** (write the contract down, enforce by review) — rejected: the slop checklist already outlawed spec-speak in `implemented/` by convention, and over twenty files show what convention alone achieves here.
- **Convention without a gate** (write the contract down, enforce by review) — rejected: the slop checklist already outlawed spec-speak in `implemented/` by convention, and nineteen files show what convention alone achieves here.
- **A standalone `FORMAT.md` contract file** — the first landed home; folded into README.md once the generated index moved out to [INDEX.md](../../INDEX.md): with the tables gone the README regained the room, and one front door carrying layout, classification, and format beats splitting the contract across two files.
## Consequences