[Roadmap][Post-#258] 書籍群の供給網・build契約・自動保守・内容鮮度・Pages運用を段階改善する

[ootakazuhiko]

背景

#258 により、対象27リポジトリのrepository管理ActionをNode.js 24対応へ移行し、横断監査・CI・Pages・レビュー証跡を完了した。

一方、ポータル自身のOpen Issue / PRが0件になった後も、各書籍リポジトリには次の品質債務が残っている。

• Book QAが脆弱性を含む旧book-formatter固定SHAを参照する可能性
• dev依存の既知脆弱性
• canonical docsを破壊し得るlegacy build
• scheduled maintenanceの検出結果がIssue作成条件へ伝播しない構造
• workflow成功にもかかわらずPR preview URLが404になるPages source不整合
• 外部API・release・sunset等の時点依存情報
• docs / src / manuscriptの正本・生成契約の不明確さ
• whatwg-encoding、Faraday、Ruby Sass / Jekyll等の非ブロッキングwarning
• GitHub管理legacy Pages workflowのNode.js warning

本Issueは、これらを変更所有権と依存順に分け、Codex CLIで再現可能な小規模バッチとして処理する横断ロードマップである。

関連:

• [P1][Catalog] 正本メタデータ補完・公開表示分離・英語カタログ生成化・旧資料整理 #187 カタログ正本化・公開表示・旧資料整理（完了）
• chore: 書籍CIをNode.js 24対応Actionへ移行する #258 Node.js 24対応Action移行（完了）

原則

• P0の供給網・脆弱性・破壊的buildを先に処理する
• セキュリティpin、build契約、本文更新、警告整理を同一PRへ混在させない
• 1書籍1PRを基本とし、横展開は1回4〜6冊を上限とする
• mutableなbranch/tagではなく監査済みcommit SHA pinを維持する
• 各PRでreview本文・inline・suggestionを全件確認し、unresolved threadを0にする
• PR CI、main CI、Pages、公開HTTP、必要なpost-deploy smokeを確認する
• 既存の書籍Issueを再作成せず、横断Issueから参照する
• 現行のdirty/non-main checkoutを変更しない
• workspace cleanupと最終再監査の証跡を残す

実行順

1. [P0][Supply Chain] Book QAのbook-formatter固定SHAと既知dev依存脆弱性を解消する #266 Book QAのbook-formatter固定SHAとdev依存脆弱性
2. [P0][Automation] canonical build・scheduled maintenance・PR previewの正しさを2冊で確立する #267 practical-auth-bookのcanonical build、2冊のmaintenance、preview、依存warning
3. [P0][Content Freshness] BioinformaticsGuide-bookの外部仕様更新・semantic freshness・再現ラボを完了する #268 BioinformaticsGuide-bookのP0内容鮮度・semantic freshness・再現ラボ
4. [P1][Content Pipeline] canonical authoring source・非破壊build・drift契約を横断確立する #269 canonical authoring source / non-destructive build / drift契約
5. [P2][Build Hygiene] whatwg-encoding・Faraday・Ruby Sass/Jekyll warningをroot cause別に横断整理する #270 Jekyll / npm / Gem warningのroot cause別整理
6. [Review 2026-08-15][Pages] legacy managed runtimeとcustom deployment移行判断を全公開書籍で再評価する #271 2026-08-15の全公開書籍Pages再監査

子Issue

• [P0][Supply Chain] Book QAのbook-formatter固定SHAと既知dev依存脆弱性を解消する #266 — [P0][Supply Chain] Book QAのbook-formatter固定SHAと既知dev依存脆弱性を解消する
• [P0][Automation] canonical build・scheduled maintenance・PR previewの正しさを2冊で確立する #267 — [P0][Automation] canonical build・scheduled maintenance・PR previewの正しさを2冊で確立する
• [P0][Content Freshness] BioinformaticsGuide-bookの外部仕様更新・semantic freshness・再現ラボを完了する #268 — [P0][Content Freshness] BioinformaticsGuide-bookの外部仕様更新・semantic freshness・再現ラボを完了する
• [P1][Content Pipeline] canonical authoring source・非破壊build・drift契約を横断確立する #269 — [P1][Content Pipeline] canonical authoring source・非破壊build・drift契約を横断確立する
• [P2][Build Hygiene] whatwg-encoding・Faraday・Ruby Sass/Jekyll warningをroot cause別に横断整理する #270 — [P2][Build Hygiene] whatwg-encoding・Faraday・Ruby Sass/Jekyll warningをroot cause別に横断整理する
• [Review 2026-08-15][Pages] legacy managed runtimeとcustom deployment移行判断を全公開書籍で再評価する #271 — [Review 2026-08-15][Pages] legacy managed runtimeとcustom deployment移行判断を全公開書籍で再評価する

既存書籍Issueとして継続する後続項目

次は本ロードマップのP0/P1完了後に、既存source Issueで個別に進める。

• podman-book#207 章見出し・本文主題・学習パスの構成ずれ
• podman-book#189 スクリーンショット取得・本文差し込み
• proxmox_book#2 Proxmox VE 9.1スクリーンショット
• BioinformaticsGuide-book#508〜#513の検索、a11y、版管理、canonical manuscript、内容拡張
• book-formatter#93〜#104の標準フォーマット／adapter大型ロードマップ

完了条件

• 子Issueが依存順に完了している
• 監査対象の旧book-formatter pinが0件、または明示的な例外として記録されている
• 既知のmoderate/high dependency vulnerabilityが解消または上流待ちとして期限付き管理されている
• scheduled maintenanceの検出あり／なし／重複／復旧が自動検証されている
• 壊れたPR previewが残っていない
• P0時点依存情報が一次情報に基づいて更新されている
• canonical sourceと生成契約が対象書籍で文書化・CI化されている
• 非ブロッキングwarningがroot cause別に解消または再確認条件付きで整理されている
• Pages再監査結果と移行判断が記録されている
• ポータルと対象書籍でOpen PRが残っていない

Codex CLI運用

各子Issue本文を実行Runbookとして利用する。Codexは空のbootstrap Gitリポジトリから起動し、必要なリポジトリをgh repo cloneで取得する。

共通起動例:

RUNROOT="$HOME/work/iteka-post-258-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$RUNROOT"
cd "$RUNROOT"
git init

codex exec \
  -C "$RUNROOT" \
  --sandbox workspace-write \
  -a on-request \
  "GitHub Issue itdojp/it-engineer-knowledge-architecture#<CHILD_ISSUE> をgh CLIで全文取得してください。親ロードマップIssue #265も確認し、子Issue本文を正本Runbookとしてcloneから調査、Issue/PR、レビュー、CI、merge後確認、証跡、cleanupまで実行してください。対象外を拡大せず、完了条件を満たした場合だけIssueをcloseしてください。"

--dangerously-bypass-approvals-and-sandboxは使用しない。追加clone先はworkspace配下へ置き、workspace外の既存checkoutを変更しない。