[Phase 8] Portfolio Healthビューと状態変化通知を実装する

[ootakazuhiko]

Parent: #276

目的

公開catalogを母数として、全書籍の運用状態を一画面で確認できるPortfolio Health生成・通知契約を実装する。GitHub API由来の動的値をcatalog正本やmainへ保存せず、Workflow/Pages artifactで生成する。

収集項目

• repository、visibility、publication scope
• default branch SHA（privateは公開出力でredact）
• Open Issue / PR数
• 最新Book QA
• 最新Pages deployment、build type、status
• 公開HTTP
• lastReviewedAt
• scheduled maintenance alert
• security / freshness / QA / visual / build debt
• 次の推奨作業

実装チェックリスト

• catalogのstatus=publishedを決定的な母数にする
• portfolio-health.jsonと単一画面HTMLを生成する
• workflow summaryとartifactを生成する
• manual dispatchとscheduleを提供する
• Pages build artifactにも生成時snapshotを含める
• API値をcatalogまたはmainへcommitしない
• bot commitを行わない
• healthy / attention / blocked / scheduledを根拠付きで算出する
• rate limit、secondary limit、retry、sanitized cache、partial failureを扱う
• 状態変化時だけ通知し、重複alert Issueを作らない
• private書籍はcatalogで公開済みの識別情報と集計値以外を出力しない
• 正常、異常、partial failure、private redaction、duplicate/recovery alertのfixture testを追加する

検証

• local unit / fixture test
• catalog published母数と出力件数が一致
• JSON schema/contract確認
• HTML escape / private leak反証
• actionlint
• npm verify
• PR review本文、inline、suggestion、threadを全件確認
• unresolved / mismatch / missing各0
• PR CI、merge後main、Deploy Pages、production smoke成功
• 公開Portfolio Health viewとbuild-info markerを確認
• task branch / artifact cleanup

対象外

• 各書籍の本文修正
• catalogへAPI snapshotを保存すること
• 定期bot commit
• private Issue本文、PR title、commit SHA、workflow URL、error詳細の公開
• Phase 9 / #271の前倒し

[ootakazuhiko]

Phase 8開始監査（2026-07-23 JST）

• live state: Phase 7対象5 repositoryのOpen PR 0、Phase 8に競合する既存Issue / PR 0
• source Issue: [Phase 8] Portfolio Healthビューと状態変化通知を実装する #278
• catalog母数: docs/_data/catalog.jsonのstatus=published（実装前にfixtureとliveで件数固定）
• PR分割: source Issue [Phase 8] Portfolio Healthビューと状態変化通知を実装する #278 = 1 PR。生成器・fixture test・scheduled/manual workflow・Deploy Pages artifact統合を同じPortfolio Health契約として実装
• 動的API値はtmp / Workflow artifact / Pages build artifactだけへ出力し、catalogやmainへcommitしない
• private repoはcatalog公開済み識別情報と集計値だけを許可し、default branch SHA、Issue/PR本文・title、workflow URL、API error詳細をredact
• alertはportal内の単一open Issueをstate fingerprintで更新し、同一状態では通知せず、回復時はcomment後closeする。重複Issueを禁止
• APIは低並列、指数backoff、rate-limit待機、sanitized cache、repo単位partial failureで処理
• acceptance: normal/abnormal/private/partial/duplicate/recovery fixture、local full verify、actionlint、全review thread、PR/main/Pages/HTTP/marker

この計画コメント後にlatest mainからbranch/worktreeを作成して編集を開始します。Phase 9には着手しません。

[ootakazuhiko]

実装・ローカル検証完了（PR #279）

• PR: feat: add portfolio health monitoring #279
• head: 34b7738342a1ceb33cffba3d8def151ffcfc6ce9
• 母数: catalog status=published 42冊（private 2冊はcatalog公開済み識別情報以外の動的値をredact）
• 実装: JSON / 単一画面HTML / Markdown、schedule/manual workflow、workflow summary/artifact、Pages build snapshot、state fingerprint alert、retry/backoff、sanitized cache、partial failure
• cache境界: namespace v2、published public allowlistによるprune、artifactからcacheを除外
• local live read-only collection: 42 records / partial 0 / private dynamic leak 0 / stale private cache削除確認
• npm ci: 0 vulnerabilities
• npm run verify: success（Portfolio Health 16、production smoke 11、Pages drift 7、Playwright 48を含む）
• actionlint / git diff --check: success
• 独立correctness review / security review: blocker 0

次はPR CIとGitHub reviewを全件処理し、unresolved 0確認後に通常merge、main / Pages / 公開HTTP / build-infoを確認します。

[ootakazuhiko]

進捗: 横断読み取り認証をfail-closed化

PR #279 のreviewで、portal repositoryのgithub.tokenは他repositoryのActions / Deployments / Pages / Issuesを読めず、Pages snapshotが全public書籍partialになる問題を確認しました。branch protection変更、個人用PATの転用、広権限tokenの保存は行っていません。

head 33edf99 で次へ変更済みです。

• read-only GitHub App installation tokenをworkflow実行中だけ短期発行
• App権限をActions / Contents / Deployments / Issues / Pages / Pull requestsのread onlyに限定
• 横断read tokenとportal Alert write用github.tokenを分離
• App設定欠落時はpartialへ黙って退避せずfail closed
• App IDはrepository variable、private keyはActions secretとして参照し、値をlog / Issue / PR / artifactへ出力しない
• 個人用PAT、既存CLI OAuth token、固定installation tokenは保存しない

再検証:

• local full verify成功（Portfolio Health 19 tests、production smoke 11、Pages drift 7、E2E 48を含む）
• actionlint / diff check成功
• read token相当のlive収集: published 42 / public 40 / private 2 / partial 0 / private dynamic leak 0 / cache 40

現在の外部前提

repository管理者 ootakazuhiko が、PR本文・Runbookに記載したread-only GitHub Appを作成し、catalogのpublished public repositoryへ限定installしたうえで、portal repositoryへ次を設定する必要があります。

• variable PORTFOLIO_HEALTH_APP_ID
• secret PORTFOLIO_HEALTH_APP_PRIVATE_KEY

再開条件は、値を表示せずgh variable list / gh secret listで両方の存在を確認でき、App installationの対象とread-only permissionsを確認できることです。それまではPR #279をmergeせず、Pagesを失敗させない状態を維持します。

[ootakazuhiko]

2026-07-24 JST live再監査: GitHub App設定blocker継続

PR #279をexpected head 4aec7e8 で再確認しました。

• PR: OPEN / non-draft / MERGEABLE / CLEAN
• PR checks: 3/3 success
• review completeness: reviews 28 / comments 34 / threads 17
• unresolved 0 / generated mismatch 0 / missing review 0
• exact-head Copilot review: 16/16 files、new comment 0
• local: npm ci、npm run verify、npm audit 0、Portfolio Health 20 tests、production smoke 11、Pages drift 7、Playwright 48、actionlint、git diff --checkがsuccess
• worktree: clean

値を取得・表示せずrepository設定名だけを確認した結果、次の両方が存在しません。

• required variable PORTFOLIO_HEALTH_APP_ID: missing
• required Actions secret PORTFOLIO_HEALTH_APP_PRIVATE_KEY: missing

このため、GitHub App installation tokenを発行できず、Appの実効permissionsとpublished public repositoryへのinstallation coverageも検証できません。未設定のままmergeするとmainのDeploy Pagesがfail closedになるため、PR #279はmergeしていません。

Owner: ootakazuhiko
再開条件:

1. read-only GitHub Appをpublished public repositoryへ限定installする
2. Actions / Contents / Deployments / Issues / Pages / Pull requestsがread onlyである
3. organization / administration permissionがない
4. 上記variableとsecretの名前がrepository設定で確認できる
5. private key、installation token、secret値をIssue / PR / logへ出力しない

Ethereum PR #136、Issue #135 / #137、Phase 1〜5、Phase 6の既完了部分には変更していません。admin bypass、branch protection変更、push、merge、rebaseも行っていません。

[ootakazuhiko]

2026-08-05 JST 再開監査: GitHub App設定blocker継続

white-hat-cyber-intelligence-bookの割り込み作業完了後、Phase 8をlive GitHub状態から再監査しました。

• PR feat: add portfolio health monitoring #279: OPEN / non-draft / MERGEABLE / CLEAN
• head: 4aec7e8dd19afd61aa82e967e0c1a8356b3f0f31（前回固定headから変更なし）
• PR checks: 3/3 success
• review completeness: reviews 28 / comments 34 / threads 17
• unresolved 0 / generated mismatch 0 / missing review 0
• local worktree: clean / exact head
• repository variable名一覧: PORTFOLIO_HEALTH_APP_IDなし
• repository secret名一覧: PORTFOLIO_HEALTH_APP_PRIVATE_KEYなし
• 現在のCLI actor権限: maintain（portal repositoryのadminではない）
• OAuth CLI tokenからのGitHub App installation一覧取得はGitHub APIが403を返すため、App ID未設定の現状では対象Appの実効permissionsとinstallation coverageを安全に特定できない

未設定のままmergeすると、Deploy Pagesおよびscheduled/manual Portfolio Health workflowがApp token発行時にfail closedになります。このため、PR #279へのpush、rebase、merge、admin bypass、repository rule変更は行っていません。

Owner: ootakazuhiko

再開条件:

1. read-only GitHub Appを作成する
2. repository permissionsをActions / Contents / Deployments / Issues / Pages / Pull requestsのread onlyだけにする
3. organization permissionとadministration permissionを付与しない
4. catalogのstatus=publishedかつpublicなrepositoryだけへselected installationする
5. portal repositoryにvariable PORTFOLIO_HEALTH_APP_IDとsecret PORTFOLIO_HEALTH_APP_PRIVATE_KEYを設定する
6. private key、installation token、secret値をIssue / PR / logへ出力しない
7. 設定名とApp installation契約をread-onlyで確認後、PR #279の通常merge、main / Pages / manual workflow / 公開HTTP検証を再開する