schema-normalizer

スキーマ正規化（NO PROSE）

トリガーとルーティング

• トリガー：schema normalize、jsonl contract、interface drift、join drift、字段不一致、schema 规范化。
• 使用する場合：C2-C4 の JSONL 成果物（outline/briefs/bindings/packs/anchors）を生成済みで、自己ループや執筆の前にフィールドを決定的かつ安定した状態にしたい場合。

目的：スキル優先のパイプラインでよく発生する問題、つまり JSONL 成果物間のスキーマドリフトを解消します。

フィールドに一貫性がない場合（ID／タイトルの欠落、引用キー形式の混在など）、後続のスキルはベストエフォートの結合や脆弱な解析を始めます。 このスキルはインターフェースを明示し、決定的なものにします。

入力

• outline/outline.yml（セクション／サブセクションの ID とタイトルの信頼できる情報源）
• 任意（引用キーの整合性確認用）：citations/ref.bib
• 正規化するデフォルトの JSONL 成果物（arxiv-survey(-latex) C4 ブリッジ）：
  • outline/subsection_briefs.jsonl
  • outline/chapter_briefs.jsonl
  • outline/evidence_bindings.jsonl
  • outline/evidence_drafts.jsonl
  • outline/anchor_sheet.jsonl
• 任意（ライターパックの生成後に実行）：
  • outline/writer_context_packs.jsonl

出力

• output/SCHEMA_NORMALIZATION_REPORT.md（必ず書き出されます。PASS／FAIL と変更内容を記載）
• 処理対象の JSONL ファイルはその場で正規化されます（変更が適用される場合は .bak.* が作成されます）。

正規化される内容

1）ID とタイトル（結合キー）

sub_id: "<H2>.<H3>" を含むレコードの場合：

• section_id が存在することを確認します（ドットより前のプレフィックスから導出）
• title と section_title が存在することを確認します（outline/outline.yml から補完）

section_id: "<H2>" を含むレコードの場合：

• section_title が存在することを確認します（outline/outline.yml から補完）

2）引用キーの形式（解析のドリフトを軽減）

これらの C2-C4 JSONL 成果物内の引用キーを、生の BibTeX キー（@ プレフィックスなし）に正規化します：

• "citations": ["smith2023", "jones2024"]

注：

• 最終的な文章では、Markdown の引用形式を引き続き使用します：[@smith2023]。
• このスキルは引用を追加／削除せず、形式のみを正規化します。

実行するタイミング

arxiv-survey(-latex) での推奨配置：

• evidence-draft と anchor-sheet の後、writer-context-pack と evidence-selfloop の前に実行します。
• これにより、ドラフトパックの作成前に outline/evidence_drafts.jsonl と outline/anchor_sheet.jsonl のスキーマが安定します。

失敗モード

• outline/outline.yml が見つからない、または解析できない場合、スキルは FAIL します。
• 対象の JSONL に無効な JSON 行が含まれる場合、スキルは該当行を報告して FAIL します（破損した成果物で処理を続行しないでください）。

スクリプト（任意）

クイックスタート

• uv run python .codex/skills/schema-normalizer/scripts/run.py --help
• C4 ブリッジ成果物を正規化します：
  • uv run python .codex/skills/schema-normalizer/scripts/run.py --workspace <workspace>

すべてのオプション

• --workspace <dir>
• --unit-id <U###>
• --inputs <semicolon-separated>
• --outputs <semicolon-separated>
• --checkpoint <C#>

例

• デフォルトの C4 成果物（ID／タイトルと引用形式）を正規化します：

  • uv run python .codex/skills/schema-normalizer/scripts/run.py --workspace <workspace> --inputs outline/outline.yml;citations/ref.bib;outline/subsection_briefs.jsonl;outline/chapter_briefs.jsonl;outline/evidence_bindings.jsonl;outline/evidence_drafts.jsonl;outline/anchor_sheet.jsonl --outputs output/SCHEMA_NORMALIZATION_REPORT.md

• ライターパックも正規化します（writer-context-pack の後に実行する場合）：

  • uv run python .codex/skills/schema-normalizer/scripts/run.py --workspace <workspace> --inputs outline/outline.yml;citations/ref.bib;outline/writer_context_packs.jsonl --outputs output/SCHEMA_NORMALIZATION_REPORT.md