Tianyi Cui
e6fad266a6
Define the in-file RFC contract in docs/rfc/README.md § The file format: the header block (`# RFC: <title>` plus a dateless Status enum cross-checked against the lifecycle folder), the per-lifecycle body skeleton (a Problem opener everywhere; Proposal/Alternatives considered/ Acceptance criteria/Risks in proposed/; present-tense Decision/ Consequences with proposal-era headings banned in implemented/; the frozen proposal shape in rejected/), and a mandatory Alternatives considered section with a date-fenced grandfather comment for pre-format RFCs whose alternatives are not reconstructible from the record. Enforce it with a new doc-sync gate, scripts/verify-rfc-format.ts, and normalize all 112 RFCs to it: ~15 Status-line spellings collapse to the enum, 29 Context openers become Problem, the 39 legacy-format XXX debt markers are resolved and banned from reappearing, proposal-era sections in implemented RFCs are rewritten to shipped reality (including the web/fs/subagent seam RFCs' migration plans and test checklists, closing the doc-tiers deferred-work item on the web seam), every RFC gains an Alternatives considered section or the grandfather comment, and the bilingual pair is re-mirrored and re-recorded. Move the generated index tables out of README.md into a fully generated docs/rfc/INDEX.md — gen-rfc-index now writes the whole file, and verify-rfc-classification checks its freshness and rejects index-shaped rows in the curated README — which makes room for the format contract to live in the README front door instead of a separate FORMAT.md. The decision record, and the first RFC written in the new format, is docs/rfc/implemented/process/2026-07-05-uniform-rfc-format.md.
63 lines
2.8 KiB
TypeScript
63 lines
2.8 KiB
TypeScript
/**
|
|
* Doc-sync gate: enforce the RFC classification scheme
|
|
* ([the classification RFC](../docs/rfc/implemented/process/2026-06-20-rfc-classification.md))
|
|
* and the freshness of the generated index
|
|
* ([the index-generation RFC](../docs/rfc/implemented/process/2026-07-04-generate-rfc-index-tables.md)).
|
|
* Every RFC is filed at `docs/rfc/{lifecycle}/{class}/yyyy-mm-dd-topic.md`; the
|
|
* folder IS the label. This gate is the machine source of truth for the closed
|
|
* class set and keeps the generated index honest.
|
|
*
|
|
* Three checks (all against [rfc-index.ts](./rfc-index.ts), the shared walker
|
|
* and renderer):
|
|
*
|
|
* 1. STRUCTURE — every `.md` under a lifecycle folder lives in a class folder
|
|
* from CLASSES, is named `yyyy-mm-dd-*.md`, and opens with a parseable H1.
|
|
* A loose `.md` directly under a lifecycle root (other than the
|
|
* README/AGENTS allowlist) fails; an unknown class folder fails; a stray
|
|
* file at an unexpected depth fails. This is what makes the set CLOSED: a
|
|
* new class folder can't appear without amending CLASSES (and the README's
|
|
* Classification section, per the RFC).
|
|
* 2. FRESHNESS — the committed `docs/rfc/INDEX.md` byte-matches a fresh render
|
|
* from the tree, so every RFC is listed exactly once, under the heading
|
|
* matching its path, with its H1 title and filename date. The fix for a
|
|
* stale index is `pnpm run gen-rfc-index`, never a hand edit. This is
|
|
* checker, not fixer: it reports and never rewrites.
|
|
* 3. NO STRAY ROWS — `docs/rfc/README.md` (the curated front door) carries no
|
|
* index-shaped table rows; the list lives only in the generated INDEX.md.
|
|
*
|
|
* Run: `tsx scripts/verify-rfc-classification.ts`.
|
|
*/
|
|
|
|
import { readFileSync } from 'node:fs'
|
|
import { resolve } from 'node:path'
|
|
import { INDEX_ROW, renderIndex, rfcRoot, walkRfcTree } from './rfc-index.ts'
|
|
|
|
const { rfcs, errors } = walkRfcTree()
|
|
|
|
if (errors.length === 0) {
|
|
let index: string | undefined
|
|
try {
|
|
index = readFileSync(resolve(rfcRoot, 'INDEX.md'), 'utf8')
|
|
} catch {
|
|
// A missing INDEX.md is reported below as staleness, exactly like a drifted one.
|
|
}
|
|
if (renderIndex(rfcs) !== index) {
|
|
errors.push('index: docs/rfc/INDEX.md is stale or missing — run `pnpm run gen-rfc-index` and commit the result')
|
|
}
|
|
const readme = readFileSync(resolve(rfcRoot, 'README.md'), 'utf8')
|
|
for (const line of readme.split('\n')) {
|
|
if (INDEX_ROW.test(line)) {
|
|
errors.push(`readme: index-shaped row in the curated README (the list lives in INDEX.md): ${JSON.stringify(line.slice(0, 80))}`)
|
|
}
|
|
}
|
|
}
|
|
|
|
if (errors.length === 0) {
|
|
console.log(`verify-rfc-classification: ${rfcs.length} RFC(s) checked, structure and index consistent.`)
|
|
process.exit(0)
|
|
}
|
|
|
|
console.error('verify-rfc-classification: violations found:')
|
|
for (const e of errors) console.error(` ${e}`)
|
|
process.exit(1)
|