@opengsd/gsd-core 1.10.0 → 1.12.0

package/scripts/gen-features.cjs

@@ -0,0 +1,836 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generates `docs/FEATURES.md` — BOTH its table of contents and every feature
+ * section body — from per-feature fragments under `docs/features/`.
+ *
+ * WHY THIS EXISTS (#3840). `docs/FEATURES.md` was hand-maintained, and every
+ * feature PR had to write into TWO shared mutable cells in it: the `### N.`
+ * heading (whose integer was hand-allocated at authoring time, so concurrent
+ * PRs all picked the same next number) and the hand-maintained table of
+ * contents (which collides even between PRs that picked DIFFERENT numbers).
+ * #3831 was renumbered 165 -> 166 -> 167 -> 168 across successive rebases, the
+ * last collision landing mid-verification; because every rebase invalidates the
+ * sha-keyed pass marker, each collision also cost a full remote matrix run.
+ *
+ * The fix is the pattern this repo already uses twice for exactly this problem
+ * (`.changeset/` for CHANGELOG.md, `tests/emitted-drift-acks/` for #2914): one
+ * file per contribution, consolidated by a generator. A contributor adds ONE
+ * new file under `docs/features/` and touches no shared file, so there is
+ * nothing to collide on. `docs/FEATURES.md` itself becomes a DERIVED artifact:
+ * when two branches both regenerate it the conflict is resolved by re-running
+ * `--write`, not by hand-renumbering and re-editing a TOC.
+ *
+ * NUMBER ALLOCATION. `id` is declared in the fragment's own frontmatter and is
+ * FROZEN once merged, so inbound `#N-slug` anchors from other docs keep
+ * resolving. It does NOT have to be contiguous or maximal — the corpus already
+ * skips 58, 113 and 131 and carries the non-integer ids `6.5`, `27a` and `27b`.
+ * The only rule is uniqueness, which `--check` enforces with a typed violation
+ * rather than leaving a human to notice. Because any unique id is legal, an
+ * author can use their issue number and never revisit the choice after a
+ * rebase: the number-chase is gone, not merely serialized.
+ *
+ * GROUPS ARE DERIVED TOO. A fragment names its `group` (the `##` heading) and
+ * groups are ordered by their lowest-ordered member, so there is no shared
+ * group list to edit either. Optional per-group prose lives in
+ * `docs/features/_groups/<slug>.md`, which a feature-adding PR never touches.
+ *
+ * Invariants enforced (see CONTRIBUTING.md "Adding a feature to
+ * `docs/FEATURES.md`"):
+ *   1. Every fragment declares `id`, `title` and `group` in its frontmatter.
+ *   2. Ids are unique across the corpus, and so are the anchors they generate.
+ *   3. A fragment body never opens a heading at depth <= 3 — `##` would forge a
+ *      group and `###` would forge a sibling section, both silently.
+ *   4. Every `_groups/` note names a group that some fragment is a member of.
+ *   5. Every inbound `FEATURES.md#anchor` link from the repo's own markdown
+ *      resolves to a heading this generator emits.
+ *   6. The committed `docs/FEATURES.md` equals the generated one.
+ *
+ * Invariant 5 is what makes the number freeze REAL rather than a promise. This
+ * repo has no link checker, so broken anchors shipped silently: the migration
+ * found `FEATURES.md#runtime-identity` (never a heading) and
+ * `#143-spec-phase-edge-completeness-probe` (off by one) already live on `next`.
+ * Since a fragment can now change its own `id` in a one-line edit, an unchecked
+ * anchor would be a much easier thing to break than it was to break by hand.
+ *
+ * Usage:
+ *   node scripts/gen-features.cjs              # print the generated region to stdout
+ *   node scripts/gen-features.cjs --write      # rewrite the region in docs/FEATURES.md
+ *   node scripts/gen-features.cjs --check      # exit 1 if stale or invalid
+ *   node scripts/gen-features.cjs --json       # --check semantics; JSON report on stdout
+ *   node scripts/gen-features.cjs --write --force   # write despite violations
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const FEATURES_DIR = path.join(ROOT, 'docs', 'features');
+const GROUP_NOTES_DIR = path.join(FEATURES_DIR, '_groups');
+const FEATURES_PATH = path.join(ROOT, 'docs', 'FEATURES.md');
+
+const START_MARKER =
+  '<!-- FEATURES:START — generated by scripts/gen-features.cjs; do not edit by hand -->';
+const END_MARKER = '<!-- FEATURES:END -->';
+
+/**
+ * The shallowest heading depth a fragment BODY may open.
+ *
+ * `##` and `###` are structural in the rendered document: the generator emits
+ * `## <group>` and `### <id>. <title>` itself, so a body line at either depth
+ * would forge a group or a sibling section that has no fragment, no id and no
+ * TOC entry — and would do it silently, because markdown renders it fine.
+ * `####` and deeper nest INSIDE a section and are always legal.
+ */
+const MIN_BODY_HEADING_DEPTH = 4;
+
+/**
+ * Stable reason codes for every violation this gate can emit.
+ *
+ * Tests assert `assert.equal(v.reason, REASON.X)` over the `--json`
+ * `violations` array rather than regex-matching stderr prose — see
+ * CONTRIBUTING.md "Prohibited: Raw Text Matching on Test Outputs".
+ */
+const REASON = Object.freeze({
+  FILENAME_INVALID: 'filename_invalid',
+  FRONTMATTER_MISSING: 'frontmatter_missing',
+  FIELD_MISSING: 'field_missing',
+  FIELD_UNKNOWN: 'field_unknown',
+  ID_INVALID: 'id_invalid',
+  ID_DUPLICATE: 'id_duplicate',
+  ORDER_INVALID: 'order_invalid',
+  ANCHOR_DUPLICATE: 'anchor_duplicate',
+  BODY_EMPTY: 'body_empty',
+  BODY_HEADING_TOO_SHALLOW: 'body_heading_too_shallow',
+  GROUP_NOTE_ORPHAN: 'group_note_orphan',
+  GROUP_NOTE_DUPLICATE: 'group_note_duplicate',
+  INBOUND_ANCHOR_UNRESOLVED: 'inbound_anchor_unresolved',
+  BODY_FORGES_REGION_MARKER: 'body_forges_region_marker',
+  DIRENT_NOT_REGULAR_FILE: 'dirent_not_regular_file',
+  DIRENT_UNREADABLE: 'dirent_unreadable',
+});
+
+/**
+ * Substrings a fragment body may never contain.
+ *
+ * `spliceIntoFeatures` finds the region boundaries by scanning `docs/FEATURES.md`
+ * for these markers. A fragment that PLANTS one gets it rendered verbatim into
+ * the generated region, where it becomes an earlier (or later) match than the
+ * real boundary on the NEXT run — so a subsequent `--write` splices against the
+ * forged boundary and silently freezes everything past it as "hand-authored",
+ * a corruption that survives deleting the offending fragment. Fragments arrive
+ * through fork PRs, so this is attacker-reachable input, not a typo class.
+ *
+ * Defence is in depth: this rejects the forgery at the source, and
+ * `spliceIntoFeatures` independently anchors on the LAST end marker so a
+ * marker that reaches the document some other way still cannot shrink the
+ * region it governs.
+ */
+const FORBIDDEN_BODY_SUBSTRINGS = Object.freeze(['<!-- FEATURES:START', '<!-- FEATURES:END']);
+
+/** Which forbidden marker (if any) `body` contains. */
+function forgedRegionMarker(body) {
+  return FORBIDDEN_BODY_SUBSTRINGS.find((marker) => String(body).includes(marker)) || null;
+}
+
+/**
+ * Directories the inbound-anchor scan walks, relative to the repo root.
+ *
+ * Deliberately does NOT include `.planning/`, `node_modules/`, or anything
+ * outside version control. Locale subtrees under `docs/` ARE walked, but their
+ * links are filtered by RESOLVED TARGET (below), so `docs/ja-JP/x.md` pointing
+ * at its own sibling `docs/ja-JP/FEATURES.md` is correctly ignored — those
+ * translations carry different section counts and are not in this gate's scope.
+ */
+const LINK_SCAN_DIRS = Object.freeze(['docs']);
+const LINK_SCAN_ROOT_FILES = Object.freeze(['README.md', 'CONTRIBUTING.md', 'CONTEXT.md']);
+
+/** `[text](path/FEATURES.md#anchor)` — the only inbound form this gate checks. */
+const INBOUND_LINK_RE = /\(([^()\s]*FEATURES\.md)#([A-Za-z0-9._-]+)\)/g;
+
+/** Frontmatter fields a feature fragment may declare. */
+const FRAGMENT_FIELDS = Object.freeze(['id', 'title', 'group', 'order']);
+/** Frontmatter fields a group-note fragment may declare. */
+const GROUP_NOTE_FIELDS = Object.freeze(['group']);
+
+/**
+ * A legal feature id: an integer, optionally followed by a single lowercase
+ * letter (`27a`) or a single decimal part (`6.5`). All three shapes are LIVE in
+ * the corpus today — freezing the migrated numbers required accepting them, and
+ * the letter/decimal forms are exactly how a feature gets inserted between two
+ * already-published numbers without renumbering either.
+ */
+const ID_RE = /^(?:0|[1-9][0-9]*)(?:\.[0-9]+|[a-z])?$/;
+
+/**
+ * A legal explicit `order`: an optionally-signed decimal literal.
+ *
+ * `order` was the only field validated by COERCION rather than by shape, and
+ * `Number()` is far more liberal than a docs ordering field has reason to be:
+ * `Number('')` and `Number(' ')` are 0, and `0x10`, `0b11`, `0o17`, `1e3`, `1.`
+ * and `.5` all coerce to finite numbers. A fragment declaring `order:` with
+ * nothing after it therefore sorted to position 0 — ahead of every real
+ * feature — with no violation and exit 0, in a gate whose whole contract is a
+ * typed violation rather than a silent guess. Shape first, then coerce,
+ * mirroring how ID_RE guards `id`.
+ */
+const ORDER_RE = /^[+-]?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/;
+
+/** The fragment filename shape: a kebab slug, mirroring `docs/adr/`'s rule. */
+const FRAGMENT_FILENAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.md$/;
+
+const FRONTMATTER_KEY_RE = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * GitHub's heading-anchor algorithm, as applied to the FULL rendered heading
+ * text (`27b. Existing Codebase Onboarding` -> `27b-existing-codebase-onboarding`).
+ *
+ * Deriving the anchor from the same string that is rendered is the whole point:
+ * a hand-written TOC could disagree with its heading and nothing would notice,
+ * which is how `docs/FEATURES.md` came to be missing TOC entries for `6.5`,
+ * `27a` and every section from 163 up. Here the two cannot diverge.
+ *
+ * Reproduces GitHub's rule: lowercase, drop everything that is not a word
+ * character, a space or a hyphen, then map spaces to hyphens. Note the drops
+ * happen BEFORE the space->hyphen mapping, which is why `Token Count & Git`
+ * yields the double hyphen in `#152-statusline-token-count--git-segment`.
+ */
+function slugify(headingText) {
+  return String(headingText)
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s/g, '-');
+}
+
+/**
+ * Render a frontmatter value.
+ *
+ * JSON-quoted only when a bare form would not survive the round trip: an empty
+ * value, one with significant leading/trailing whitespace, one that would be
+ * mistaken for a quoted value, or one carrying a newline (which would forge a
+ * second frontmatter line). Everything else stays bare so the common case
+ * reads as ordinary YAML.
+ */
+function renderScalar(value) {
+  const s = String(value);
+  if (s === '' || s !== s.trim() || s.startsWith('"') || /[\r\n]/.test(s)) return JSON.stringify(s);
+  return s;
+}
+
+/** Inverse of `renderScalar`. */
+function parseScalar(raw) {
+  if (raw.startsWith('"')) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === 'string') return parsed;
+    } catch {
+      // Fall through: an unparseable quoted-looking value is taken literally
+      // rather than crashing the whole corpus scan on one bad fragment.
+    }
+  }
+  return raw;
+}
+
+/**
+ * Serialize `{key: string}` into a fragment's `---`-delimited frontmatter block
+ * plus body. The exact inverse of `parseFrontmatter`; the pair is property
+ * tested for bijectivity.
+ */
+function renderFrontmatter(data, body) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(data)) lines.push(`${key}: ${renderScalar(value)}`);
+  lines.push('---', '');
+  return `${lines.join('\n')}\n${body}`;
+}
+
+/**
+ * Split fragment text into `{data, body}`.
+ *
+ * Returns `data: null` when the document does not open with a `---` fence — the
+ * caller turns that into a typed FRONTMATTER_MISSING violation rather than
+ * guessing at a body-only fragment.
+ */
+function parseFrontmatter(text) {
+  const normalized = String(text).replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---\n')) return { data: null, body: normalized };
+
+  const end = normalized.indexOf('\n---\n', 3);
+  if (end === -1) return { data: null, body: normalized };
+
+  const data = {};
+  for (const line of normalized.slice(4, end + 1).split('\n')) {
+    if (line.trim() === '') continue;
+    const sep = line.indexOf(':');
+    if (sep === -1) continue;
+    const key = line.slice(0, sep).trim();
+    if (!FRONTMATTER_KEY_RE.test(key)) continue;
+    data[key] = parseScalar(line.slice(sep + 1).trim());
+  }
+
+  // `+5` clears "\n---\n"; the blank line renderFrontmatter emits after the
+  // closing fence is consumed here so body text starts at its first real line.
+  let body = normalized.slice(end + 5);
+  if (body.startsWith('\n')) body = body.slice(1);
+  return { data, body };
+}
+
+/**
+ * Line numbers (1-based, relative to `body`) of every heading opened at a depth
+ * shallower than `MIN_BODY_HEADING_DEPTH`, ignoring fenced code blocks.
+ *
+ * Fence tracking is not decoration: several migrated bodies embed shell and
+ * markdown samples, and a `## ` inside a fenced sample is content, not a
+ * forged group heading. Both ``` and ~~~ fences are honored, and a fence only
+ * closes on a marker of the same character at least as long as the opener —
+ * the CommonMark rule, so a ```` ``` ```` inside a ```` ```` ```` block does
+ * not end it.
+ */
+function shallowBodyHeadings(body) {
+  const hits = [];
+  let fenceChar = null;
+  let fenceLen = 0;
+
+  String(body)
+    .split('\n')
+    .forEach((line, i) => {
+      const fence = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+      if (fence) {
+        const [char, len] = [fence[1][0], fence[1].length];
+        if (fenceChar === null) {
+          fenceChar = char;
+          fenceLen = len;
+          return;
+        }
+        if (char === fenceChar && len >= fenceLen && line.slice(fence[0].length).trim() === '') {
+          fenceChar = null;
+          fenceLen = 0;
+        }
+        return;
+      }
+      if (fenceChar !== null) return;
+      const heading = /^(#{1,6})\s/.exec(line);
+      if (heading && heading[1].length < MIN_BODY_HEADING_DEPTH) {
+        hits.push({ line: i + 1, depth: heading[1].length });
+      }
+    });
+
+  return hits;
+}
+
+/**
+ * Default sort key for a fragment that declares no explicit `order`: the id's
+ * numeric part. `27a` and `6.5` therefore land where a reader expects without
+ * anyone writing an `order`; only a fragment whose frozen position CONTRADICTS
+ * its number (`27b` precedes `27a` in the published document) needs one.
+ */
+function defaultOrder(id) {
+  return Number.parseFloat(id);
+}
+
+/** Every `*.md` directly under a directory, sorted, tolerating a missing dir. */
+function markdownFilesIn(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.name.endsWith('.md'))
+    .map((e) => ({ name: e.name, regular: e.isFile() && !e.isSymbolicLink() }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Whether a `docs/features/` entry may be READ at all.
+ *
+ * `readdirSync(..., {withFileTypes:true})` reports dirent types WITHOUT
+ * following symlinks (it is `lstat`-shaped), so `isFile()` is already false for
+ * a symlink — but relying on that alone reads as an accident. This states the
+ * rule outright: only a regular file is a fragment.
+ *
+ * The threat is concrete. A fork PR can commit `docs/features/evil.md` as a
+ * symlink to any path the process can read (`~/.ssh/id_rsa`, a CI secret file,
+ * anything outside the repo). The generator INLINES a fragment's bytes into the
+ * committed `docs/FEATURES.md`, so following one link would exfiltrate that
+ * file's contents into a public document on the next `regen:derived`. Refusing
+ * non-regular entries is what keeps the fragment corpus to files a reviewer can
+ * actually see in the diff.
+ */
+function refuseNonRegular(entry, rel, add) {
+  if (entry.regular) return false;
+  add(REASON.DIRENT_NOT_REGULAR_FILE, rel, {});
+  return true;
+}
+
+/**
+ * Read every fragment and group note off disk into the intermediate
+ * representation the renderer and the validator both consume.
+ *
+ * `--json` exposes this IR's violations, and the test suite asserts against the
+ * IR rather than against rendered markdown text (CONTRIBUTING.md forbids
+ * grepping generated output): the parse result is the contract, the markdown is
+ * one projection of it.
+ */
+function readCorpus() {
+  const violations = [];
+  const add = (reason, file, detail) => violations.push({ reason, file, ...detail });
+
+  const fragments = [];
+  for (const entry of markdownFilesIn(FEATURES_DIR)) {
+    const name = entry.name;
+    const rel = path.posix.join('docs/features', name);
+    if (!FRAGMENT_FILENAME_RE.test(name)) {
+      add(REASON.FILENAME_INVALID, rel, {});
+      continue;
+    }
+    if (refuseNonRegular(entry, rel, add)) continue;
+    let text;
+    try {
+      text = fs.readFileSync(path.join(FEATURES_DIR, name), 'utf8');
+    } catch {
+      add(REASON.DIRENT_UNREADABLE, rel, {});
+      continue;
+    }
+
+    const { data, body } = parseFrontmatter(text);
+    if (data === null) {
+      add(REASON.FRONTMATTER_MISSING, rel, {});
+      continue;
+    }
+    for (const key of Object.keys(data)) {
+      if (!FRAGMENT_FIELDS.includes(key)) add(REASON.FIELD_UNKNOWN, rel, { field: key });
+    }
+    let missing = false;
+    for (const field of ['id', 'title', 'group']) {
+      if (!data[field]) {
+        add(REASON.FIELD_MISSING, rel, { field });
+        missing = true;
+      }
+    }
+    if (missing) continue;
+
+    if (!ID_RE.test(data.id)) {
+      add(REASON.ID_INVALID, rel, { id: data.id });
+      continue;
+    }
+
+    let order = defaultOrder(data.id);
+    if (data.order !== undefined) {
+      order = Number(data.order);
+      // Both guards are load-bearing: the regex rejects the shapes `Number`
+      // would silently accept, and `isFinite` still catches a well-shaped
+      // literal long enough to overflow to Infinity.
+      if (!ORDER_RE.test(data.order) || !Number.isFinite(order)) {
+        add(REASON.ORDER_INVALID, rel, { order: data.order });
+        continue;
+      }
+    }
+
+    const trimmed = body.replace(/\s+$/, '');
+    if (trimmed === '') {
+      add(REASON.BODY_EMPTY, rel, {});
+      continue;
+    }
+    for (const hit of shallowBodyHeadings(trimmed)) {
+      add(REASON.BODY_HEADING_TOO_SHALLOW, rel, { line: hit.line, depth: hit.depth });
+    }
+    const forged = forgedRegionMarker(trimmed);
+    if (forged !== null) {
+      add(REASON.BODY_FORGES_REGION_MARKER, rel, { marker: forged });
+      continue;
+    }
+
+    fragments.push({
+      file: rel,
+      id: data.id,
+      title: data.title,
+      group: data.group,
+      order,
+      explicitOrder: data.order !== undefined,
+      body: trimmed,
+      anchor: slugify(`${data.id}. ${data.title}`),
+    });
+  }
+
+  const notes = new Map();
+  for (const entry of markdownFilesIn(GROUP_NOTES_DIR)) {
+    const name = entry.name;
+    const rel = path.posix.join('docs/features/_groups', name);
+    if (refuseNonRegular(entry, rel, add)) continue;
+    let text;
+    try {
+      text = fs.readFileSync(path.join(GROUP_NOTES_DIR, name), 'utf8');
+    } catch {
+      add(REASON.DIRENT_UNREADABLE, rel, {});
+      continue;
+    }
+    const { data, body } = parseFrontmatter(text);
+    if (data === null) {
+      add(REASON.FRONTMATTER_MISSING, rel, {});
+      continue;
+    }
+    for (const key of Object.keys(data)) {
+      if (!GROUP_NOTE_FIELDS.includes(key)) add(REASON.FIELD_UNKNOWN, rel, { field: key });
+    }
+    if (!data.group) {
+      add(REASON.FIELD_MISSING, rel, { field: 'group' });
+      continue;
+    }
+    if (notes.has(data.group)) {
+      add(REASON.GROUP_NOTE_DUPLICATE, rel, { group: data.group });
+      continue;
+    }
+    const trimmed = body.replace(/\s+$/, '');
+    if (trimmed === '') {
+      add(REASON.BODY_EMPTY, rel, {});
+      continue;
+    }
+    const forgedNote = forgedRegionMarker(trimmed);
+    if (forgedNote !== null) {
+      add(REASON.BODY_FORGES_REGION_MARKER, rel, { marker: forgedNote });
+      continue;
+    }
+    notes.set(data.group, { file: rel, group: data.group, body: trimmed });
+  }
+
+  return { fragments, notes, violations };
+}
+
+/** Every `*.md` under `dir`, recursively, as repo-relative POSIX paths. */
+function markdownFilesUnder(dir) {
+  const found = [];
+  const walk = (abs) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const joined = path.join(abs, e.name);
+      if (e.isDirectory()) walk(joined);
+      else if (e.isFile() && e.name.endsWith('.md')) {
+        found.push(path.relative(ROOT, joined).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(path.join(ROOT, dir));
+  return found.sort();
+}
+
+/**
+ * Every inbound `docs/FEATURES.md#anchor` reference in the repo's own markdown,
+ * with the anchors this generator actually emits subtracted.
+ *
+ * Links are matched by RESOLVED TARGET, not by textual prefix: a link is only
+ * checked when the path it names resolves to `docs/FEATURES.md` itself. That is
+ * what keeps the locale trees out of scope without a hardcoded skip list —
+ * `docs/ja-JP/README.md` linking `FEATURES.md#…` resolves to
+ * `docs/ja-JP/FEATURES.md` and is left alone.
+ */
+function checkInboundAnchors(emittedAnchors) {
+  const violations = [];
+  const files = [
+    ...LINK_SCAN_DIRS.flatMap((d) => markdownFilesUnder(d)),
+    ...LINK_SCAN_ROOT_FILES.filter((f) => fs.existsSync(path.join(ROOT, f))),
+  ];
+
+  for (const rel of files) {
+    let text;
+    try {
+      text = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    } catch {
+      violations.push({ reason: REASON.DIRENT_UNREADABLE, file: rel });
+      continue;
+    }
+    const dir = path.posix.dirname(rel);
+    for (const m of text.matchAll(INBOUND_LINK_RE)) {
+      const target = path.posix.normalize(path.posix.join(dir, m[1]));
+      if (target !== 'docs/FEATURES.md') continue;
+      if (!emittedAnchors.has(m[2])) {
+        violations.push({ reason: REASON.INBOUND_ANCHOR_UNRESOLVED, file: rel, anchor: m[2] });
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * Corpus-wide checks that need every fragment in hand, plus the assembled
+ * group/section ordering the renderer walks.
+ *
+ * Sections sort by `order`, ties broken by id string, so the arrangement is a
+ * total order that does not depend on readdir sequence. Groups sort by their
+ * lowest-ordered member — which is what removes the last shared list: nobody
+ * has to edit a group registry to add a release bucket.
+ */
+function buildCorpus() {
+  const { fragments, notes, violations } = readCorpus();
+
+  const byId = new Map();
+  for (const f of fragments) {
+    const prior = byId.get(f.id);
+    if (prior) violations.push({ reason: REASON.ID_DUPLICATE, file: f.file, id: f.id, first: prior.file });
+    else byId.set(f.id, f);
+  }
+
+  const byAnchor = new Map();
+  for (const f of fragments) {
+    const prior = byAnchor.get(f.anchor);
+    if (prior && prior.id !== f.id) {
+      violations.push({ reason: REASON.ANCHOR_DUPLICATE, file: f.file, anchor: f.anchor, first: prior.file });
+    } else if (!prior) {
+      byAnchor.set(f.anchor, f);
+    }
+  }
+
+  const grouped = new Map();
+  for (const f of fragments) {
+    if (!grouped.has(f.group)) grouped.set(f.group, []);
+    grouped.get(f.group).push(f);
+  }
+
+  for (const note of notes.values()) {
+    if (!grouped.has(note.group)) {
+      violations.push({ reason: REASON.GROUP_NOTE_ORPHAN, file: note.file, group: note.group });
+    }
+  }
+
+  const bySection = (a, b) => a.order - b.order || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  const groups = [...grouped.entries()]
+    .map(([title, sections]) => {
+      sections.sort(bySection);
+      const note = notes.get(title);
+      return {
+        title,
+        anchor: slugify(title),
+        order: sections[0].order,
+        note: note ? note.body : null,
+        sections,
+      };
+    })
+    .sort((a, b) => a.order - b.order || (a.title < b.title ? -1 : a.title > b.title ? 1 : 0));
+
+  const emitted = new Set([...groups.map((g) => g.anchor), ...fragments.map((f) => f.anchor)]);
+  violations.push(...checkInboundAnchors(emitted));
+
+  return { fragments, groups, notes, anchors: emitted, violations };
+}
+
+/** Human one-liners for the `--check` stderr report, keyed off the typed reason. */
+function describeViolation(v) {
+  switch (v.reason) {
+    case REASON.FILENAME_INVALID:
+      return `${v.file}: filename must be a kebab-case slug, e.g. runtime-identity.md`;
+    case REASON.FRONTMATTER_MISSING:
+      return `${v.file}: missing the '---' frontmatter block`;
+    case REASON.FIELD_MISSING:
+      return `${v.file}: frontmatter is missing required field '${v.field}'`;
+    case REASON.FIELD_UNKNOWN:
+      return `${v.file}: unknown frontmatter field '${v.field}'`;
+    case REASON.ID_INVALID:
+      return `${v.file}: id '${v.id}' is not an integer, integer+letter (27a) or decimal (6.5)`;
+    case REASON.ID_DUPLICATE:
+      return `${v.file}: id '${v.id}' is already used by ${v.first} — pick another (any unique id is legal)`;
+    case REASON.ORDER_INVALID:
+      return `${v.file}: order '${v.order}' is not a decimal number (an optionally-signed integer or decimal)`;
+    case REASON.ANCHOR_DUPLICATE:
+      return `${v.file}: anchor '#${v.anchor}' collides with ${v.first}`;
+    case REASON.BODY_EMPTY:
+      return `${v.file}: body is empty`;
+    case REASON.BODY_HEADING_TOO_SHALLOW:
+      return `${v.file}: body line ${v.line} opens an h${v.depth}; use h${MIN_BODY_HEADING_DEPTH} or deeper inside a feature`;
+    case REASON.GROUP_NOTE_ORPHAN:
+      return `${v.file}: names group '${v.group}', which no fragment belongs to`;
+    case REASON.GROUP_NOTE_DUPLICATE:
+      return `${v.file}: a second note for group '${v.group}'`;
+    case REASON.INBOUND_ANCHOR_UNRESOLVED:
+      return `${v.file}: links docs/FEATURES.md#${v.anchor}, which no heading provides`;
+    case REASON.BODY_FORGES_REGION_MARKER:
+      return `${v.file}: body contains the generated-region marker '${v.marker}'`;
+    case REASON.DIRENT_NOT_REGULAR_FILE:
+      return `${v.file}: not a regular file (a symlink is never followed)`;
+    case REASON.DIRENT_UNREADABLE:
+      return `${v.file}: unreadable`;
+    default:
+      return `${v.file}: ${v.reason}`;
+  }
+}
+
+/** Render the generated region: the table of contents, then every section. */
+function renderFeatures(corpus) {
+  const out = [START_MARKER, '', '## Table of Contents', ''];
+
+  for (const g of corpus.groups) {
+    out.push(`- [${g.title}](#${g.anchor})`);
+    for (const s of g.sections) out.push(`  - [${s.title}](#${s.anchor})`);
+  }
+
+  for (const g of corpus.groups) {
+    out.push('', '---', '', `## ${g.title}`, '');
+    if (g.note) out.push(g.note, '');
+    g.sections.forEach((s, i) => {
+      if (i > 0) out.push('---', '');
+      out.push(`### ${s.id}. ${s.title}`, '', s.body, '');
+    });
+  }
+
+  out.push(
+    '---',
+    '',
+    '_Generated by `scripts/gen-features.cjs` — add a fragment under `docs/features/` and run `--write`._',
+    '',
+    END_MARKER,
+  );
+  return out.join('\n');
+}
+
+/**
+ * Replace the generated region of `doc` with `region`.
+ *
+ * The end boundary is the LAST occurrence, not the first. With `indexOf`, a
+ * forged `<!-- FEATURES:END -->` anywhere inside the region would become the de
+ * facto boundary and everything after it would be preserved as if hand-authored
+ * — permanently, since the next run splices against the same forged marker.
+ * `lastIndexOf` makes the true trailing marker win, so the generated region can
+ * only ever GROW to swallow a forgery, never shrink to be governed by one.
+ * `FORBIDDEN_BODY_SUBSTRINGS` rejects the forgery upstream; this is the second
+ * layer, and it also covers a marker that reached the document by hand.
+ */
+function spliceIntoFeatures(doc, region) {
+  const start = doc.indexOf(START_MARKER);
+  const end = doc.lastIndexOf(END_MARKER);
+  if (start === -1 || end === -1) {
+    throw new ExitError(
+      1,
+      `docs/FEATURES.md is missing the generated-region markers.\nExpected:\n  ${START_MARKER}\n  ${END_MARKER}\n`,
+    );
+  }
+  return doc.slice(0, start) + region + doc.slice(end + END_MARKER.length);
+}
+
+/**
+ * Parse CLI flags. FAIL-CLOSED on an unrecognized flag: falling through to the
+ * no-flags "print the region" behavior would mask a typo (`--wirte`) as a clean
+ * run. Mirrors `scripts/gen-adr-index.cjs`.
+ */
+function parseArgs(argv) {
+  const opts = { write: false, check: false, json: false, force: false };
+  for (const arg of argv) {
+    if (arg === '--write') opts.write = true;
+    else if (arg === '--check') opts.check = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--force') opts.force = true;
+    else {
+      throw new ExitError(
+        1,
+        `unknown flag: ${arg}\nRecognized flags: --write, --check, --json, --force.`,
+      );
+    }
+  }
+  return opts;
+}
+
+function main() {
+  const { write, check, json, force } = parseArgs(process.argv.slice(2));
+
+  const corpus = buildCorpus();
+  const { violations } = corpus;
+  const region = renderFeatures(corpus);
+
+  if (json) {
+    // `--json` implies `--check` semantics but always computes BOTH facts
+    // (violations AND staleness) rather than short-circuiting, so a consumer
+    // gets the complete picture in one shot.
+    const doc = fs.readFileSync(FEATURES_PATH, 'utf8');
+    const stale = spliceIntoFeatures(doc, region) !== doc;
+    const ok = violations.length === 0 && !stale;
+    process.stdout.write(
+      JSON.stringify({
+        ok,
+        featureCount: corpus.fragments.length,
+        groupCount: corpus.groups.length,
+        indexStale: stale,
+        violations,
+      }) + '\n',
+    );
+    return ok ? 0 : 1;
+  }
+
+  // FAIL-CLOSED. `--write` used to render the region regardless, warning only
+  // on stderr and exiting 0 — so a `--write && git commit` chain would happily
+  // commit a docs/FEATURES.md carrying two colliding `### 7.` sections. Every
+  // other gate in this repo refuses rather than degrades, and a generator that
+  // emits a known-corrupt artifact is worse than one that emits none: the
+  // corruption is what gets reviewed. `--force` remains for the deliberate
+  // "write it anyway so I can see what it looks like" case, and says so.
+  if (violations.length > 0 && !(write && force)) {
+    process.stderr.write(
+      `docs/features/ has ${violations.length} fragment violation(s).\n` +
+        'See CONTRIBUTING.md "Adding a feature to `docs/FEATURES.md`" for the contract.\n' +
+        (write ? 'Refusing to write a corrupt docs/FEATURES.md; pass --force to override.\n' : '') +
+        '\n',
+    );
+    for (const v of violations) process.stderr.write(`  ✗ ${describeViolation(v)}\n`);
+    process.stderr.write('\n');
+    throw new ExitError(1);
+  }
+
+  // `--write` takes precedence over a co-supplied `--check`, matching
+  // gen-adr-index.cjs: the flags are documented to be used one at a time.
+  if (write) {
+    const doc = fs.readFileSync(FEATURES_PATH, 'utf8');
+    fs.writeFileSync(FEATURES_PATH, spliceIntoFeatures(doc, region));
+    process.stdout.write(
+      `Wrote ${corpus.fragments.length} features in ${corpus.groups.length} groups into ${FEATURES_PATH}.\n`,
+    );
+    if (violations.length > 0) {
+      // Only reachable under --force; the guard above rejects otherwise.
+      process.stderr.write(
+        `\n${violations.length} violation(s) written anyway under --force — --check will fail:\n\n`,
+      );
+      for (const v of violations) process.stderr.write(`  ✗ ${describeViolation(v)}\n`);
+    }
+  } else if (check) {
+    const doc = fs.readFileSync(FEATURES_PATH, 'utf8');
+    if (spliceIntoFeatures(doc, region) !== doc) {
+      process.stderr.write(
+        'docs/FEATURES.md is stale. Run:\n  node scripts/gen-features.cjs --write\n\n',
+      );
+      throw new ExitError(1);
+    }
+    process.stdout.write(
+      `docs/FEATURES.md is up to date (${corpus.fragments.length} features, ${corpus.groups.length} groups).\n`,
+    );
+  } else {
+    process.stdout.write(region + '\n');
+  }
+}
+
+// Guarded: the test suite requires this module for its pure parser/renderer, so
+// loading it must not also run the generator.
+if (require.main === module) runMain(main);
+
+module.exports = {
+  REASON,
+  MIN_BODY_HEADING_DEPTH,
+  FRAGMENT_FIELDS,
+  START_MARKER,
+  END_MARKER,
+  slugify,
+  parseFrontmatter,
+  renderFrontmatter,
+  shallowBodyHeadings,
+  forgedRegionMarker,
+  FORBIDDEN_BODY_SUBSTRINGS,
+  defaultOrder,
+  checkInboundAnchors,
+  buildCorpus,
+  renderFeatures,
+  spliceIntoFeatures,
+  describeViolation,
+};