From 226a8b5e4cc8872c9c438515498d376550440c77 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 4 Jul 2026 15:10:22 +0800
Subject: [PATCH] fix(scripts): enforce the invariants the index gate claims

Codex review found three gaps between the documented contract and what
the gate enforced, each proven by a failing probe before this fix:

- a generated region must sit directly under its own '## {Lifecycle}'
  heading (the last H2 above the begin marker), so a drifted heading
  can no longer leave the tables filed under the wrong section;
- the lifecycle set is closed like the class set: an unknown directory
  under docs/rfc/ is a structure error, not an invisible subtree;
- an index-shaped table row linking into a lifecycle folder OUTSIDE the
  generated regions is an error (prose links to RFCs stay legal), so
  'listed exactly once' cannot be violated by a hand-added row.
---
 scripts/rfc-index.ts | 44 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 38 insertions(+), 6 deletions(-)

diff --git a/scripts/rfc-index.ts b/scripts/rfc-index.ts
index d9a4538b38..e14eea5c59 100644
--- a/scripts/rfc-index.ts
+++ b/scripts/rfc-index.ts
@@ -16,7 +16,7 @@
  * filename. Prose outside the markers is curated by hand and never touched.
  */
 
-import { readFileSync } from 'node:fs'
+import { readFileSync, readdirSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { globSync } from 'node:fs'
 
@@ -53,13 +53,20 @@ export interface Rfc {
 
 /**
  * Walk the RFC tree, enforcing the structure rules. Returns every valid RFC
- * plus one error string per violation (unknown class folder, bad depth, bad
- * filename, missing/malformed H1). Callers treat a non-empty error list as
- * fatal — the index is only generated from a structurally valid tree.
+ * plus one error string per violation (unknown lifecycle or class folder, bad
+ * depth, bad filename, missing/malformed H1). Callers treat a non-empty error
+ * list as fatal — the index is only generated from a structurally valid tree.
  */
 export function walkRfcTree(): { rfcs: Rfc[]; errors: string[] } {
   const rfcs: Rfc[] = []
   const errors: string[] = []
+  // The lifecycle set is closed too: any directory under docs/rfc/ that is not
+  // a known lifecycle would otherwise hold RFCs invisible to the walk below.
+  for (const entry of readdirSync(rfcRoot, { withFileTypes: true })) {
+    if (entry.isDirectory() && !(LIFECYCLES as readonly string[]).includes(entry.name)) {
+      errors.push(`structure: ${entry.name}/ — unknown lifecycle folder (allowed: ${LIFECYCLES.join(', ')})`)
+    }
+  }
   for (const lifecycle of LIFECYCLES) {
     for (const match of globSync(`${lifecycle}/**/*.md`, { cwd: rfcRoot }).sort()) {
       const segs = match.split('/')
@@ -120,11 +127,16 @@ function renderLifecycle(rfcs: Rfc[], lifecycle: string): string {
 
 /**
  * Splice freshly rendered regions into the README text. Throws when a marker
- * pair is missing, duplicated, or out of order — the markers are part of the
- * curated prose and must exist exactly once per lifecycle.
+ * pair is missing, duplicated, or out of order, when a region does not sit
+ * under its own `## {Lifecycle}` heading, or when an index-shaped table row
+ * (a `| [title](lifecycle/…)` line) appears OUTSIDE the generated regions —
+ * the markers are part of the curated prose, the heading above each region is
+ * the one its lifecycle names, and index rows live only inside the regions
+ * (prose links to RFCs remain fine anywhere).
  */
 export function spliceReadme(readme: string, rfcs: Rfc[]): string {
   let out = readme
+  const regions: Array<{ from: number; to: number }> = []
   for (const lifecycle of LIFECYCLES) {
     const { begin, end } = markers(lifecycle)
     const beginAt = out.indexOf(begin)
@@ -135,7 +147,27 @@ export function spliceReadme(readme: string, rfcs: Rfc[]): string {
     if (out.indexOf(begin, beginAt + 1) !== -1 || out.indexOf(end, endAt + 1) !== -1) {
       throw new Error(`README.md has a duplicated ${lifecycle} index marker`)
     }
+    // The region must sit directly under its own lifecycle heading: the last
+    // H2 above the begin marker is `## {Heading(lifecycle)}`, or the heading
+    // itself has drifted while the generated table stayed put.
+    const before = out.slice(0, beginAt)
+    const lastH2 = [...before.matchAll(/^##\s+(.+?)\s*$/gm)].at(-1)?.[1]
+    if (lastH2 !== heading(lifecycle)) {
+      throw new Error(`README.md: the ${lifecycle} index region is not under a "## ${heading(lifecycle)}" heading (found "## ${lastH2 ?? '<none>'}")`)
+    }
     out = `${out.slice(0, beginAt + begin.length)}\n${renderLifecycle(rfcs, lifecycle)}\n${out.slice(endAt)}`
+    regions.push({ from: out.indexOf(begin), to: out.indexOf(markers(lifecycle).end) + markers(lifecycle).end.length })
+  }
+  // Index rows are generated state: a table row linking into a lifecycle
+  // folder anywhere OUTSIDE the regions is a hand-added index entry the
+  // generator would never reconcile.
+  let offset = 0
+  for (const line of out.split('\n')) {
+    const inRegion = regions.some(r => offset >= r.from && offset < r.to)
+    if (!inRegion && /^\|\s*\[[^\]]+\]\((?:proposed|implemented|rejected)\//.test(line)) {
+      throw new Error(`README.md: index-shaped row outside the generated regions: ${JSON.stringify(line.slice(0, 80))}`)
+    }
+    offset += line.length + 1
   }
   return out
 }