2565133af3
implemented（除 4 篇超长文档随后补）、proposed、rejected 全树配对； 同一流水线 + 二遍校验（paraphrase-back + 仓库上下文一致性）产出。 docs/rfc/implemented/AGENTS.md 与其 CLAUDE.md 符号链接列入排除 （agent 指令文件，与根 AGENTS.md 同策略）。
2.3 KiB
RFC: A gated Known-Limitations section in every package README
English | 中文
Status: implemented
Problem
The documentation standard assigns limitations to package READMEs. Without a shared shape, an omitted section cannot distinguish an audited absence from forgotten documentation, and variant headings prevent a repository-wide search.
Decision
Every package manifest under packages/<group>/<pkg>/package.json has a sibling README with the canonical ## Known Limitations and Deferred Work section. Its bullets record durable consumer gaps and non-obvious maintainer constraints owned by that package; ordinary cleanup remains in its source TODO or owning RFC. The verify-package-readme-limitations gate derives the package set from manifests, rejects missing READMEs, and requires exactly one canonical h2 with at least one top-level bullet. Near-miss headings such as “Limitations,” “Deferred,” “What is NOT here,” or “Non-goals” fail.
A package with nothing to declare is listed in NO_LIMITATIONS and omits the section. Adding a limitation requires removing the entry; renames and removals fail because every entry must name a scanned package.
The gate checks presence, shape, and the allowlist. Review under the documentation and prose standards owns coverage and accuracy. The standing rule lives in packages/AGENTS.md.
Alternatives considered
- Free-form headings — cannot be searched uniformly and still need near-miss detection.
- Require an empty section or “None.” — boilerplate can remain after a package gains a limitation; an allowlist makes absence explicit and reviewable.
- Impose a word ceiling — legitimate limitation counts vary, so review governs this unbudgeted README tier.
Consequences
- New packages declare qualifying limitations or explicitly join the allowlist; missing, drifted, and empty sections fail
doc-synclocally and in CI. - The gate adds one dependency-free TypeScript script to
doc-sync. - Renaming the enforced heading requires changing the script and every package README together.