hook-cli-development

入力と判定を追跡する

1. フックの起動形を固定し、ラッパーでの入力受信と子プロセスでの読み取りを別々に記録する。入力の有無と stdin の TTY 判定を確かめれば、入力の欠落を拒否判定と取り違えずに済む。診断に入力本文を使わず、受信の有無が分かる情報を使う。
2. 空入力、解析失敗、解析の打ち切り、差分取得失敗、判定による拒否を個別に発生させ、終了コードと理由を確認する。検査結果を受領証やゲートまで追い、故障が「候補ゼロの検査済み」にならないことを確かめる。拒否リストの読込失敗と未知の構文も含めると、許可条件の漏れを検出できる。
3. 真偽値の意味を変える前に全参照先を検索し、不明を表す値が各分岐でどう扱われるかを追う。設定を外部ファイルへ移す場合も、CLI と関数の直接呼び出しへ同じデータを渡す。呼び出しを一つ残すだけで、判定や検査範囲が食い違うためである。
4. 実行主体を見分ける目印には、設定で常に渡る環境変数が使える。Codex の shell_environment_policy.set は AI_AGENT=1 を必ず渡す。もともと別の目的で入れた設定が、フックや CLI の実行主体がエージェントかを見分ける目印に転用できる。
5. 重複を調べる本文の比較には、文字 bigram の Jaccard 係数が形態素解析なしで使える。同一の証明にはならないが、無関係な本文を弾く下限としては軽くて十分である。

形式ごとの境界を確認する

1. CLI 引数はコマンドと値の位置を区別して解析し、引数の誤りと正常な空結果の終了コードを分ける。値として渡された --help をヘルプ要求と取り違えると、実行したはずの処理が省かれる。
2. ログは読込時に全フィールドを検証し、表示直前にも制御文字を検査する。理由文を先頭に固定し、引用する入力の改行と長さを共通関数で制限する。これにより、入力が偽の通知行を作ったり、理由を画面外へ押し出したりすることを防ぐ。通知は検証済みの値から組み立て、上流の自由文を実行指示へ転用しない。
3. HTML の script 要素へ JSON を埋め込む場合は、すべての < を \u003c にする。終了タグだけの置換では HTML コメントの開始を防げない。パッチ解析では行頭の形式を保ち、除去する末尾文字を明示する。汎用の trim はパスの文字まで変えることがある。
4. バイト上限は正規化前の入力に適用し、繰り返し呼ぶ解析には共通の絶対締切を渡す。呼び出すたびに時間枠を作り直すと、合計の処理時間が上限を超える。FIFO の可能性があるファイルは O_NONBLOCK で開いてから fstat で種類を確認し、読み取りと書き込みの両方で open 自体の待機を防ぐ。

排他とロックの設計

1. ロックを足しても review で競合の指摘が続くなら、パッチを重ねるのではなく別の排他の仕組みに変える。flock は open した handle に鍵が結びつくので、プロセスが死ねば OS が閉じ、残骸の後始末が要らない。
2. シェルは開いた handle を別のプログラムに渡せないが、継承はできる。bash が exec 9>... で開き、子が同じ fd を継承して lock を取れば、macOS でも追加の install なしに kernel の排他が使える。
3. 子プロセスが継承した flock は、子が生きている限り保持され続ける。外部コマンドへは 9>&- で明示的に閉じて渡すと、lock の寿命を起動側の制御に保てる。
4. 承認（生体認証など）の待ちを終えてから秘密のファイルを作ると、ファイルが VM に存在する時間は数秒に縮む。この並びにしておくと、後始末は「60 秒より古いものを消す」だけで済む。
5. 安全のために足した lock は、残骸の判定、解放時の持ち主確認、signal 処理を芋づる式に必要にさせる。排他を git に任せる手もある。git branch は重複を原子的に拒否するので、この性質を所有の証明に使うと、自前で守るものが減る。失敗した git worktree add は git 自身が後始末し、登録も管理用ディレクトリも残さないため、巻き戻しは「自分が作った branch」1 つに絞れる。
6. 「rename してから作り直す」古い lock の奪取には競合がある。2 つのプロセスがほぼ同時に古い lock を見つけると、片方が作り直した生きた lock を、もう片方の rename が退けてしまう。rename は path への操作で、どのファイルを動いたかまでは保証しない。退避した後に中身を確かめれば、退かしたのが狙った古い lock だったかを判定できる。

台帳の読み取りと追記

1. 範囲の末尾を読むときは、窓の直前の 1 バイトもいっしょに読む。そこが改行なら窓は行の頭から始まっており、改行でなければ窓の最初の行は途中で切れているので捨てる。末尾から改行を探して戻ると、改行の少ない巨大なファイルでは先頭近くまで読み戻すことになり、この 1 バイトでその走査が不要になる。
2. 処理した位置をファイルに残す仕組みがあれば、新しい契機（PreCompact など）を 1 つ足すだけで、その契機のたびに増えた分だけを整理できる。契機ごとの登録は、1 つの契機だけの検査では漏れが出る。どの契機に登録されているかを丸ごと比べる検査にすると、登録の漏れと余計な登録の両方を捕まえられる。
3. 追記型の台帳は O_APPEND で 1 回だけ write する。O_APPEND は末尾への移動と書き込みを kernel が 1 つの操作として行うので、lock なしでも同時の追記で行が消えず、短い行が途中で混ざらない。このリポジトリの approvals.log や off-plan-writes.log は O_APPEND での 1 回の write で書いており、reviewer-runs.log だけが「読む、足す、書き戻す」の作りだったため、その間に別のプロセスが割り込んで、記録を消した。
4. 行数の上限を守ることと、lock なしの追記を安全にすることは両立しない。古い行を捨てるにはファイル全体の書き直しが必要になるためである。上限を入れた理由が commit の本文にも設計記録にも残っていないこともあるので、台帳を読むのが誰で、どこまでの行を読むかを確かめる。台帳を読む処理が現在の round の開始時刻（.round-baseline）以降の行しか読まないなら、上限を手放しても判定は変わらない。
5. 後始末で消す対象は、名前の形で限定する（proc-io-<日時>.csv と d-io-<日時>.etl だけ、など）。名前の形が違うものは同じ場所に置いてあっても消えない。ファイル名の日時を yyyyMMdd-HHmmss にすると、文字列の並べ替えだけで時刻の順になる。更新日時を見ないので、コピーし直して日時が変わっても、古い方の判定はずれない。

共有ディレクトリの後始末

1. /tmp はほかのセッションと共有なので、「古そうだから消す」は危険である。この作業の物だと言える証拠（project の形、試しの文書との hash の一致）がある物だけを消す。
2. rm -rf は symlink の先をたどらず、リンクそのものだけを消す。試しの project の中の node_modules（global な install への symlink）を消しても、依存の本体は残る。

状態の保存と表示を確認する

• 採否を集める画面では、台帳から生成できる固定の本文と利用者が編集する値を分け、データベースには後者だけを保存する。書き戻す際の照合対象を行 id と採否などの必要な値に限定できるためである。
• 推奨と同じ採否が多い画面では、推奨を一括入力し、異なる判断の行だけ修正できる操作を検討する。

1. 状態が属する単位と、結果ごとに変更するフィールドを列挙する。更新直前に保存先の値を取得し直し、対象フィールドだけを変える。共有設定は変更前後から対象キーを除き、残りが等しいことを機械的に比較してから保存する。これにより、別の処理が持つ値を消さずに済む。
2. 保存成功後に実行中の変数を更新し、表示にも判定と同じ検証関数を使う。保存できなかった値や無効な値を案内しないためである。表示用の本文は正本から再生成して現在の本文と比較し、同じなら書き込みを省く。見送りは個別の結果に記録すると、変更なしと誤表示せずに済む。
3. 通信が成功しても結果が空なら、環境変数とデータベースなどの独立した設定値を照合する。通信の到達確認だけでは値の不一致を発見できない。機能を有効にする際は、無効期間に検査されなかった値も検証する。

復旧と出力を確認する

1. 状態を書き換える共通処理の中で変更前の値を取得し、旧バージョンの処理が値を消した場合も検知できるか確かめる。呼び出し元で後から比較すると、先行する処理が変更した事実を取り逃す。
2. 検知条件に該当する不正な値を用意し、案内する復旧手順でその条件が解消することを確認する。復旧対象は書き込み前に symlink か確認し、リンク先へ書き込まない。相手が書き込めるディレクトリから自分の権限でファイルを読んだり動かしたりする処理では、確認してから使う間に symlink を差し替えられる余地（TOCTOU）が残る。ファイルは O_NOFOLLOW で開き、開いた fd に fstat をかけて確かめると、この隙間をほぼ閉じられる。ただしディレクトリへの rename には fd ベースの API が Node に無いので、残る隙間をどう扱うかは明示して security の review に判断を委ねた。機密本文を出力せずに実行し、同じ手順を再実行して変更が有限回で止まるか確かめる。復旧によって再実行が続く問題も検出するためである。
3. 異常時の出力だけを読んで、理由と次に実行する操作が分かるか確認する。手順書を読まずに CLI を直接呼ぶ経路でも、復旧や確認を進められるようにするためである。
4. 対になる異言語実装へ同じ入力を与え、読込バイト数、NUL と末尾文字の除去、上限、防御条件、終了コードを比較する。片方だけの防御で判定が割れることがあるため、標準エラーの警告も実際のプロセスで確認する。

公開前の検査をそろえる

1. 公開する差分だけでなく、最初の push 前にコミット本文と PR 本文も点検する。履歴を書き直しても、公開済みの本文は複製先に残りうるためである。委譲する場合は、公開禁止の表現を機密値を含まない例で示す。「公開しない」とだけ伝えると、修正理由の説明に含まれることがある。
2. 秘密検査が作業ツリーと履歴のどちらを入力にするかを確認し、CI と同じ範囲で実行する。個人の Git 設定による入力差と除外設定の影響も調べる。除外を適用しない検査で検出できることを確認すると、手元でだけ検出されない問題を発見できる。指摘があっても成功を返して蓄積する運用では、その指摘をいつ確認するかも決める。