設定ドリフト照合器が「毎朝ずっと赤」になるのを止める（照合対象外の値の扱いと guard の当て方）

これは何の指示書か

本番設定（価格パラメータ・機能フラグ・しきい値など）の「決定台帳」を JSON で持ち、 毎日のバッチで実設定と機械照合して差分（ドリフト）を検出する仕組みを運用している人向け。

この仕組みは必ず一度は「常に赤」に落ちる。落ち方の型と、二度と起きないようにする guard の当て方を書く。 AI エージェントに読ませればそのまま設計・修正できる粒度にしてある。

起きること（実例・2026-09）

台帳のエントリはこういう形をしている。

{
  "parameters": {
    "upperPrice": {
      "configPath": "pricing.upperPrice",
      "current": 14100,
      "status": "decided",
      "rationale": "…なぜこの値にしたか…",
      "history": [ { "at": "…", "value": 16000, "note": "…なぜ覆したか…" } ]
    }
  }
}

照合器は configPath を本番設定 API の戻り値に対して split('.') で辿り、 値が一致すれば OK、辿れなければ MISSING、違えば DRIFT を出す。MISSING か DRIFT が1件でもあれば exit 1。

半年運用したあと、本番 API には現れない場所に住む値を台帳へ載せる日が来る。 コード内の定数、管理画面にしかない項目、表計算シートの列などだ。 その時、担当者（または AI）は親切心で configPath に所在の説明文を書く。

"configPath": "PriceCalculator の FLOOR 定数（コード内・API には出ない）"

照合器はこれを設定パスとして split('.') するので、永遠に MISSING を返す。 以後、毎日のバッチは必ず exit 1 で終わり、レポートの冒頭と通知が毎朝 「🚨 前提が崩れています」で始まるようになる。

なぜ致命的か

1. 本物のドリフトが埋もれる。 毎朝赤いので、誰も赤を見なくなる。 照合器は「値が勝手に変わったこと」を捕まえるために作ったのに、その用を成さなくなる。
2. 原因の表示が嘘に見える。 出るのは「台帳と実設定が一致しない」。 実際には設定は正しく、壊れているのは台帳の書き方だけ。読んだ人は本番設定を疑って時間を溶かす。
3. 見つかるのが遅れる。 常駐ジョブが固定の版（ミラーやコンテナイメージ）で走っていると、 台帳の更新が反映されず何日も隠れる。版を揃えた瞬間に初めて出る。

直し方（設計）

照合器に「照合対象外」の第3の状態を持たせ、台帳の書式でそれを表現できるようにする。

• configPath: null → DOC（記録専用。機械照合しない。緑扱い）
• configPath: "a.b.c" → 設定 API を辿って OK / DRIFT / MISSING
• 所在の説明は別キー（location）に書く。configPath には自由文を一切入れない

多くの実装は既に「null なら飛ばす」を持っている。持っているのに使われないのは、 書式の契約が台帳ファイル自身に書かれていないからなので、台帳の先頭 rules 配列にも1行入れる。

"configPath には設定 API のドット区切りパスだけを書く。API に現れない値は configPath を null にし、
 所在は location に書く。説明文を configPath に入れると照合器が MISSING を返し毎朝 exit 1 になる"

直し方（guard・ここが本題）

契約を文章で書いても次の人は破る。機械で止める。

// 設定 API の戻りを辿れる形だけ許す
const DOTTED_PATH = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;

test('configPath は null か設定 API のドット区切りパスだけ（説明文を書かない）', () => {
  const bad = Object.entries(ledger.parameters)
    .filter(([, e]) => e.configPath !== null && !DOTTED_PATH.test(String(e.configPath)))
    .map(([k, e]) => `${k}: ${JSON.stringify(e.configPath)}`);
  assert.deepEqual(bad, []);
});

test('configPath が null の項目は所在を location か sheetCell に持つ', () => {
  const bad = Object.entries(ledger.parameters)
    .filter(([, e]) => e.configPath === null)
    .filter(([, e]) => !e.location?.trim() && !e.sheetCell?.trim())
    .map(([k]) => k);
  // 既存の未記入分は許容し、新しく増えないことだけを守る
  const KNOWN = ['legacyEntryName'];
  assert.deepEqual(bad.filter(k => !KNOWN.includes(k)), []);
});

guard は必ず「落ちる側」で先に検定する。 読み込む台帳のパスを環境変数で差し替えられるようにしておき、

const LEDGER_PATH = process.env.LEDGER_PATH || path.join(HERE, '..', 'config', 'decisions.json');

1. 修正前の台帳に当てて fail すること（何件・どの項目を検出したかまで見る）
2. 修正後の台帳で pass すること

の順で確かめる。この順を守らないと、「常に通る空の検査」を追加して満足する事故が起きる。 assert.deepEqual(bad, []) は対象が0件でも通るので、通ったことは検知できることの証拠にならない。

直すときにやってはいけないこと

• 値を一緒に直さない。 これは書式の修正であって、判断の変更ではない。 current / history / 根拠文は1文字も変えず、機械比較で差分ゼロを確認してからコミットする。

// 修正前後の台帳を突き合わせて「値は動いていない」を証明する
for (const k of Object.keys(next.parameters)) {
  const a = next.parameters[k], b = prev.parameters[k];
  if (JSON.stringify(a.current) !== JSON.stringify(b.current)) diff.push(k);
  if (JSON.stringify(a.history) !== JSON.stringify(b.history)) diff.push(k + ' history');
}

• 照合器の側を緩めない。 「MISSING を警告どまりにする」で赤は消えるが、本物のドリフトも消える。 直すのはデータの書式であって検出器の感度ではない。

検収（この順で確かめる）

1. 修正した台帳で照合器を実走 → exit 0 / MISSING 0 / DRIFT 0
2. guard を旧台帳に当てて fail → 新台帳で pass
3. テスト全体が緑
4. 常駐ジョブが実際に読む場所（ミラー・コンテナ・デプロイ先）を新しい版に揃えてから、そこで照合器を実走 → exit 0 手元のリポジトリで通っても、常駐ジョブが古い版を読んでいれば翌朝また赤くなる

横に効く教訓

• 「毎朝赤い」は壊れているのではなく検出器が死んでいる。赤を見なくなった時点で仕組みが無効になっている
• 自由文と機械が辿る値を同じキーに同居させない。同居させた瞬間、片方が必ず壊れる
• 常駐ジョブが固定版を読む構成では、台帳の不良は版を揃えた日に初めて出る。 「今まで出ていなかった」は「無かった」ではない