repo-ops

Imported from Tomy-ch/terraform-aws-boilerplate (.claude/skills/repo-ops/SKILL.md). Install upstream with npx skills add Tomy-ch/terraform-aws-boilerplate --skill repo-ops. Copyright stays with the author.

Repo Ops Runbook

症状から是正手順を引くための索引。手順書ではなく引き表である —— 症状を見つけ、その節を読む。 取り消しの効かない手順（保護ブランチへ触れる、履歴を書き換える、実環境へ適用する）に当たる場合は、 AGENTS.md トリップワイヤ に従って実行せずに止まる。

このリポジトリの症状のほとんどは、次の3つの事実から出る。

1. 検査は2つの場所で走りうる。 RUNNER_MODE=container（既定）は mise.toml から組んだイメージの 中で、RUNNER_MODE=host は用意済みの道具を直接実行する。CI は host で呼ぶ。検査の定義は1箇所に しか無く、差は起動の前置きだけである（ADR-0503 決定8）。
2. ゲートは閉じる方向で落ちる。 pin / cooldown / egress / versions のいずれも、判断できない入力を 「取りこぼし」ではなくエラーとして扱う。自分が触っていないのに落ちるのは、多くの場合それが 正しく働いている。
3. ベースブランチは origin の実状態から解決する。 GitHub のデフォルトブランチは活きている リリース線より遅れており、それを信じた道具は1世代古い答えを返す。

Contract

Symptom index

0. 正本の在処

索引を機能名で検索するだけでは足りない。 AGENTS.md がそう述べている —— 文書は、それが所有する 関心事の名前で置かれているのであって、探し物の名前では置かれていない。

生成された写しを権威として引かない

terraform-docs が README.md の中へ書く区間、make egress-apply / pin-actions-apply / pin-images-apply / versions-apply が書き込むインラインブロック、.terraform.lock.hcl —— いずれも正本ではなく写しである。正本（.github/egress.toml、*-pin.toml、mise.toml）が動いた 後に追随する。tracked なので検索から外れず、正本と同じ順位で出る。

訳文ペアはこのリポジトリには無い（ADR-0701 決定7。正本は1ファイルだけ）。

資料が食い違ったら

AGENTS.md 指示の優先順位 に従う —— AGENTS.md → root の Accepted ADR → modules/<use-case>/ の Accepted ADR → ユーザーの指示。設計意図と実装方針については README > Code > SKILL。権威を主張する2つが食い違っていたら、そこで止まる （トリップワイヤ 5）—— 気づくことが仕事であり、解決することは仕事ではない。

1. make が go: command not found で落ちる

道具は mise が入れており、その shims が PATH に無い。version manager のサブコマンドで包まない （ADR-0501 決定20）—— 直すのは PATH であって wrapper ではない。

eval "$(mise activate zsh)"     # 対話シェル
export PATH="$HOME/.local/share/mise/shims:$PATH"   # 非対話・スクリプト

docker が見つからない場合は別の症状で、RUNNER_MODE=container（既定）がツールランナーを 起動できていない。ホストの道具で済む検査なら RUNNER_MODE=host を付ける。

make go-test RUNNER_MODE=host

ホストでしか成立しない検査がある。 base-branch / release / pin-images-* は RUN_SCRIPT_HOST で定義されており、git の認証情報やホストの docker を要する。これらに RUNNER_MODE=container を強いない。

2. git push が fatal: bad revision '<branch>' で止まる

pre-push の lefthook が、origin/HEAD の指す名前を裸の rev として diff しようとして失敗している。 git clone は既定ブランチのローカル参照を作るが、clone 後にデフォルトブランチが変わった checkout にはそれが無い。

git symbolic-ref --short refs/remotes/origin/HEAD   # 例: origin/release/v0.1.0
git branch release/v0.1.0 origin/release/v0.1.0     # checkout はしない

git branch は参照を作るだけで、保護ブランチの checkout には当たらない（トリップワイヤ 7 は checkout を禁じている）。--no-verify で迂回しない —— それは secret-scan を丸ごと飛ばす。

3. 素の git push が保護ブランチへ向く

git switch -c <new> origin/release/vX.Y.Z は、新しいブランチの上流を保護ブランチに設定する。 この状態で git push を引数無しで打つと、保護ブランチへ向かう。

git config --get branch.$(git rev-parse --abbrev-ref HEAD).merge   # refs/heads/release/... なら該当
git push -u origin <new-branch>                                     # 明示 refspec で上流を張り替える

初回の push は必ず明示 refspec で行う。張り替えた後は素の git push が安全になる。

4. PR が required check を待ったまま進まない

必須 context を報告する job が存在しないか、報告に到達していない。

gh api "repos/<owner>/<repo>/rules/branches/$(make -s base-branch | sed 's|/|%2F|g')" \
  -q '.[] | select(.type=="required_status_checks") | .parameters.required_status_checks[].context' | sort
gh pr checks <PR> | awk -F'\t' '$2=="pass"{print $1}' | sort

差分が「宣言にあって報告されていない」側に出たら、その workflow が存在しないか、on: の フィルタで起動していない。pull_request トリガーに branches: / paths: のフィルタを置かない （ADR-0603 決定16-18）—— 除外された PR では run が起きず、報告の無い check を GitHub は待ち続ける。 起動条件は job の if: に置く。skip された job は skipped を報告し、それは成功として数えられる。

5. 検査が「所見なし」と言うが、見ていない

この形がこのリポジトリで最も高く付く故障である。 実例: trivy-fs が脆弱性 DB を取得できずに FATAL で落ち、ログの下の方だけを読むと「所見なし」に見えていた。egress の許可リストを直したら、 その場で HIGH の CVE が1件出た。

疑ったら、ゲートの終了コードと、走査件数を報告する行を読む。件数を報告しない検査は、 ADR-0702 決定13 に反しているので、それ自体が finding である。

egress-check が落ちるのは、.github/egress.toml（正本）を変えて反映していないとき。

make egress-apply     # 25 箇所の allowed-endpoints ブロックへ反映
make egress-check

同じホストを複数の job が要るなら、extra を繰り返さずクラスを作る —— .github/egress.toml の README がその規則を持つ。

6. cooldown ゲートが、いま宣言した版を拒む

tool-cooldown / go-cooldown は、公開されたばかりの版を採らない。これは誤検知ではない。

窓はツールではなくバックエンドが決める —— GitHub Release 経由は14日、パッケージレジストリ 経由は7日。言語ランタイム（core: バックエンド）は受容したリスクとして除外されている。

理由を書けないものは抑止せず、値そのものを直す（ADR-0501 決定13）。バイパスは期限切れ・ 3ヶ月超・どれにも当たらないエントリのいずれでもゲートを落とすので、失効したバイパスが 通し続けることはない（ADR-0702 決定18）。

7. pin-actions-check / pin-images-check が drift 以外で落ちる

どちらも fail-closed で、drift より広い条件で落ちる。いずれもリポジトリ側の状態の問題で、 上流の問題ではない。

resolve が 既存ピンを維持 と言うのは cooldown が働いた印で、失敗ではない（§6）。

exact なタグの SHA が動いていたら、それは refresh ではなく事象である。 止めて、apply しない。

8. versions-check が落ちる

mise.toml の [tools]（正本）と、その写し（docker/tools/Dockerfile の FROM golang: 2件と FROM node: 1件、scripts/go.mod の go ディレクティブ）がずれている。

make versions-apply

ずれてもイメージのビルドは通る。 落ちるのは、ずれた版に無い機能を使ったときだけである。 だからこの検査が要る —— 無いと「ずれている」と「揃っている」が緑で区別できない。

一致件数は厳密に見るので、写しが増えたときも減ったときも落ちる。FROM を1つ足したり レジストリを前置したりすると、対応表（scripts/versions/main.go の rules）の更新が要る。

9. pre-push secret-scan が自分の足していない秘密を報告する

走査対象は push 予定の commit 範囲で、作業ツリーではない。他人の commit を取り込んでいれば、 それも範囲に入る。

混入を検出した場合の第一手は当該資格情報の失効であり、履歴からの除去ではない （ADR-0302 決定11-12）。push 済みであれば、履歴を書き換えても漏洩の事実は取り消せない。

誤検知なら .gitleaksignore へ。理由を書けないものは足さない。

10. hook の summary が読めない

lefthook run pre-commit --force の summary は、各コマンドを ✔️ か 🥊 で並べる。 🥊 は失敗である —— バナーにも同じ絵文字が出るので、そちらと取り違えない。

lefthook run pre-commit --force; echo "EXIT=$?"

パイプで受けると終了コードが消える。 | tail を付けると tail の成否が返るので、 判定は summary の記号か、パイプ無しの終了コードで読む。

--force が要るのは、commit 済みで作業ツリーが綺麗なときに素の lefthook run pre-commit が 「対象ファイルが無い」で全コマンドを skip するため。

hook は --no-verify で迂回される前提で設計されている（ADR-0501 決定26）。権威は CI である。 hook でのみ成立する検査を作らない。

11. adr-lint が落ちる

ADR-0001 が自らの検証方法として挙げた項目を、そのまま実行している。よくある原因は採番の詰め直しを 途中で止めたこと —— 決定7 は、ファイル名・見出し・索引・相互参照・ADR 以外からの参照を 同一の変更で更新することを要求している。片方だけ直すと、2つのファイルが同じ番号を名乗る。

\b を使って ADR-\d{4} を探すと日本語の直後で一致しない（て も A も \w なので境界が 立たない）。ADR-(\d{4})(?!\d) を使う。

12. ローカルでは通るのに CI で落ちる（またはその逆）

検査の定義は1箇所にしか無い（ADR-0503 決定8）。食い違う原因は定義ではなく、次のどれかである。

CI の結果は、失敗したステップのログから読む。 実行全体のログを引くと、失敗と無関係な出力が 大量に混じる。

Constraints

• ❌ 索引に無い手順を発明する。無いことは finding である（how-to / repo-truth へ）
• ❌ 取り消しの効かない操作を実行する —— force push、rebase、amend してからの push、保護ブランチの checkout、実環境への apply（AGENTS.md トリップワイヤ 7・8）
• ❌ ゲートの判定を、行や件数を落とすフィルタ越しに報告する
• ❌ 理由を書けない抑止を足す（ADR-0501 決定13）
• ✅ 破壊的な手順の前に、何が失われるかを言って待つ
• ✅ 検査が「所見なし」と言ったとき、見たことの証拠（件数・終了コード）を確かめる
• ✅ 日本語で答える