git:20261112.6eaa66e to git:20261114.7ec3565

4 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: geo-software-eval
description: 地図プロダクトの正しさを、人間のコードレビューに頼らずに評価する仕組み (評価ハーネス) を設計し、動かす。昼に人間と一緒に、利用者が達成したいことを外から観測できるシナリオにし、実装から切り離して置く。夜は実装とは別の評価者がシナリオを手元と本番で動かし、観測した振る舞いで判定し、症状だけを実装に返す。評価そのものが正しいかも確かめる。「完成の条件を決めたい」「受け入れテストを作って」「シナリオを書いて」「評価して」「本当に動くか確かめて」と言われたとき、ダークファクトリーの昼の擦り合わせと、夜の geo-software-build と geo-software-deploy の間で使う。
---
# geo-software-eval
ダークファクトリーの中心は、AI がコードを書くことではなく、ソフトウェアの正しさを人間のコードレビュー以外の方法で評価し、その結果で開発を進めることにある ([WHAT_IS_DARK_FACTORY.md](../../../WHAT_IS_DARK_FACTORY.md))。評価基準と検証の仕組みは不要にならず、むしろ人間が先に設計する必要が高まる。このスキルは、その評価の設計 (昼) と実行 (夜) を扱う。
| reference | 読むとき | 中身 |
|---|---|---|
+ | [design-review](references/design-review.md) | 実装前に設計案を別の文脈で確かめるとき、設計と実装のずれを調べるとき | 会話を知る設計者と初見のレビュー者の役割、指摘の扱い、振る舞いの独立評価との違い |
| [scenarios](references/scenarios.md) | 昼に評価を設計するとき | シナリオの書き方、粒度、本人と決めること、置き場所 |
| [map-observables](references/map-observables.md) | シナリオの観測と判定を書くとき | 地図のアプリで外から観測できるもの (描画、地物、タイル、帰属表示、現在地、端末) |
| [judging](references/judging.md) | 判定の仕方を決めるとき、夜に評価するとき | 機械の判定と LLM の判定の使い分け、評価者の独立、実装への返し方 |
| [twins](references/twins.md) | 外部のサービスに頼る機能を評価するとき | 地図のタイル、認証、ジオコーダなどの代役と、その限界 |
| [progress](references/progress.md) | 進み具合を報告するとき、群れを動かしているとき | マージ数でなく、価値づけされ、検証され、届き、持ちこたえた変更で測る。逃げた不具合の数え方 |
| [brakes](references/brakes.md) | 人間の確認を減らすかを決めるとき | ブレーキ (人間の確認) を評価の証拠で 1 つずつ外し、崩れたら戻す。外さないブレーキ |
| [eval-of-eval](references/eval-of-eval.md) | 評価を作ったとき、評価が全部通ったとき | 評価そのものが正しいかの確かめ方 (壊した版で落ちるか、甘い判定の見つけ方) |
| [scripts/geocheck.py](scripts/geocheck.py) | 配る GeoJSON を判定するとき | 形、度の範囲、緯度経度の取り違え、範囲の外、リングの閉じと自己交差、必ず要る属性を、プログラムで判定する (標準ライブラリだけ) |
| [scripts/run_eval.py](scripts/run_eval.py) | 夜に評価者として動かすとき | 実装の外に置いた JSON のシナリオ (http、geojson、command、llm) を動かし、報告を評価者の側に、症状だけを実装のリポジトリの `eval-feedback.md` に書く。根拠の無い LLM 合格と割れた判定は不合格に倒し、置き場所の取り違えを拒む |
| [scripts/dark_factory.py](scripts/dark_factory.py) | 夜の前の検査、評価の評価、夜の自律ループ、朝の報告を通しで動かすとき | `preflight` (概要・シナリオ・停止スイッチ・隔離の検査)、`eval-of-eval` (手本と壊した版の確かめ)、`run` (実装者と評価者のループとクリーン checkout の最終判定)、`report` (`eval-report.md` と `morning-report.md` の生成) |
| [isolation](references/isolation.md) | 夜に、実装者と評価者を動かす前に | 別のコンテナに分け、依頼と症状の 2 つのディレクトリだけで受け渡す。[assets/isolation/compose.yaml](assets/isolation/compose.yaml)、評価者の待ち受け [scripts/eval_watch.py](scripts/eval_watch.py)、隔離を目印で試す [scripts/check_isolation.py](scripts/check_isolation.py) |
| [scripts/twin.py](scripts/twin.py) | 外部のサービスの代役が要るとき | 手元のタイルと決まった答えを配り、障害 (5xx、429、空、途中で切れる、遅れ) を回数で決めて起こす。要求を記録する |
| [assets/scenario-template.md](assets/scenario-template.md) | シナリオを書くとき | シナリオ 1 本のひな形 |
| [assets/eval-report-template.md](assets/eval-report-template.md) | 評価の結果を残すとき | 評価の証跡のひな形 |
## 評価の原則
1. 外から観測できる振る舞いで判定する。コードを読んで正しそうかを判断しない。画面、通信、保存されたデータ、本番の URL で確かめる。
2. 評価は実装から切り離す。シナリオは実装のリポジトリの外 (または実装者が書き換えない場所) に置き、実装者に本文を見せない。実装者に返すのは、どの振る舞いがどう違ったかという症状だけにする。テストを書き換えて通すこと、シナリオに合わせ込むことを防ぐ (機械学習のホールドアウトと同じ考え方)。
3. 評価者は実装者と別にする。別の文脈 (別のエージェント、別のセッション) で動かし、できれば別のモデルにする。同じ前提を持つ評価者は同じ誤りを見逃す。
4. 評価の基準は人間が昼に決める。何をもって利用者の役に立ったとするかは、価値の判断を含む。夜のエージェントは基準を足してよいが、緩めない。
5. 評価そのものを疑う。全部通ったら、まず評価が甘くないかを確かめる ([eval-of-eval](references/eval-of-eval.md))。
6. 証跡を残す。何を、いつ、どの版に対して、どう判定したかを残し、朝に人間が読めるようにする。評価が走ったことは評価者の自己申告でなく記録で確かめ、結果が無いものは未評価とする。
7. 判定は遅れて覆ることがある。合格したものも、時間を置いて別の場面で確かめ直し、逃げた不具合を数える ([progress](references/progress.md))。
## 進め方
### 昼: 評価を設計する
+ 設計上の選択が後戻りしにくい場合や、見落としの影響が大きい場合は、設計案を会話履歴のない別の文脈で確かめる ([design-review](references/design-review.md))。設計レビューと、実装後の振る舞いの独立評価は分ける。
+
1. プロダクト概要の価値の芯と Must の機能から、利用者が達成したいことを並べる。1 つの達成したいことを 1 本のシナリオにする ([scenarios](references/scenarios.md))。
2. 各シナリオに、始まりの状態、利用者の操作、観測すること、合格の判定を書く。観測と判定は [map-observables](references/map-observables.md) から選び、機械で判定できる形を優先する。
3. 本人と一緒に確かめる。シナリオの一覧を見せ、価値の芯を表しているか、抜けている場面がないかを、選択肢で聞く。ここが人間の主な仕事になる。
4. 見た目の基準 (参考の画面、余白、色) は、言葉だけでなく画像や数値でもらう。言葉だけの見た目の基準は読み違えやすい。
5. 外部のサービスに頼るシナリオは、代役で動かすか本物で動かすかを決める ([twins](references/twins.md))。本物でしか確かめられないものは、本番の確認に回す。
6. シナリオを実装のリポジトリの外に置き、置き場所をプロダクト概要の「完成の条件」に書く。
### 夜: 評価を動かす
1. 実装者 (geo-software-build) とは別の評価者を立て、シナリオを手元の版に対して動かす。
2. 判定する ([judging](references/judging.md))。機械で判定できるものは機械で、できないもの (見た目の妥当さ、文言の自然さ) は LLM の判定で、根拠の観測を添えて。
3. 落ちたシナリオは、症状 (どの画面で、何を期待し、何が観測されたか、スクリーンショット) だけを実装者に返す。シナリオの本文と判定の閾値は渡さない。
4. 実装者が直したら、全シナリオを動かし直す (直したところ以外が壊れていないか)。
5. 全部通ったら、[eval-of-eval](references/eval-of-eval.md) で評価が甘くないかを確かめる。
6. デプロイの後、同じシナリオを本番の URL に対して動かす (geo-software-deploy)。
7. 結果を [assets/eval-report-template.md](assets/eval-report-template.md) の形で残し、朝の報告に入れる。
## 出力
- - 昼: シナリオの一式 (置き場所)、判定の方法、代役の方針。プロダクト概要の「完成の条件」に置き場所と要約。
+ - 昼: シナリオの一式 (置き場所)、判定の方法、代役の方針。プロダクト概要の「完成の条件」に置き場所と要約。設計レビューを行った場合は、対象の版、指摘と判断、未実施の観点の置き場所。
- 夜: 評価の報告 (シナリオごとの合否と根拠、評価の評価の結果、証跡の置き場所)。
## 注意
- 評価が通ったことは、正しさや安全性の証明ではない。確かめた範囲を書き、確かめていない範囲 (未確認の端末、本物でしか分からない外部サービス、法令) を書く。
- 評価者に本番の書き込みや削除をさせない。本番での評価は読み出しと、評価用に分けたアカウントやデータの範囲で行う。
- 評価のためのコストを見込む。シナリオの数 × 動かす回数 × (ブラウザ、LLM の判定) の費用と時間を、判断の方針の上限に収める。