build-readmelisted

# build-readme README を「system が何であるか」の観測可能な事実の集合として書く。 決定の物語・レビューへの弁明・実装の how は README の管轄外（PR / ADR / code の管轄）。 悪い文の variation は無限にあるため、匂い狩り（denylist）ではなく **書いてよい文の allowlist** で判定する。該当しない文は書かない。 README の有無で変えるのは fact の収集経路だけ。新規作成では system から収集し、 全面再構築では既存 README を文単位で解体して候補を救出する。 どちらも同じ allowlist・section composition・形式・完了チェックを適用する。 ## ルール ### allowlist — 書いてよい文は4種だけ 1. **観測可能な挙動** — system の外から black-box で確認できる事実。現在形の叙述文 2. **値と限界** — threshold・timeout・保持期間・課金・上限。表にできるもの。 ただし**読者が観測・体感できる値に限る**（request が切られる timeout、課金に効く保持期間 など）。管理下 component の内部 config（queue の batch window・visibility timeout 等）は terraform / code が SoT。「値だから」は内部実装を列挙する免罪符にならない 3. **外部依存の宣言** — system が前提とするが**管理しない**外部リソース （GitHub App・org project・手動作成の secret など）。管理下のリソースは terraform / code が SoT なので列挙しない 4. **読者の操作** — setup / run / deploy / rotate / repository edit で読者自身が行う手順 例外として、値の出典 link 1行（例: threshold は Prow size plugin の default）は bikeshedding 防止として許可する。 判定に迷ったら: **その文を消したとき、読者の行動や期待が変わるか？** 変わらないなら弁明なので落とす。変わるなら（保証・非自明な挙動）残す。 ### section composition ```markdown # <name> <prose は h1 直下の lead 1-2文のみ> <fact から必要な section だけを選んで構成する> ``` allowlist は「その fact を書いてよいか」、section は「読者がその fact をどこで探すか」を決める。 両者を1対1に対応させない。必須なのは h1 と lead だけで、固定骨子は持たない。 1. allowlist を通った fact を、読者の関心ごとに cluster 化する 2. 各 cluster の内容を最も具体的に表す header を付ける 3. 内容がない section は作らない 4. 同じ関心を generic header と specific header に分けない 5. README の主要な利用 task に沿って section を並べる （例: 理解 → 前提 → 操作 → 結果・影響 → 保守。対象