pipeline-auditor

Pipeline Auditor（草案監査＋回帰）

トリガーとルーティング

• トリガー：auditor、audit、regression test、quality report、監査、回帰テスト。
• 使用する場合：LaTeX/PDF 化する前に決定論的な合格／不合格レポートを得たい場合で、output/DRAFT.md が存在するとき。

目的は、執筆段階の決定論的な「回帰テスト」です。

次の点を確認します。

• プレースホルダーやプランナーの記述が残っていないか？
• 引用の範囲がずれていないか？
• 草案が生成器のような文体（ナビゲーション／ナレーションのテンプレート）に戻っていないか？
• サーベイ形式の草案として、引用の密度と健全性は十分か？

このスキルは分析のみを行います。内容は編集しません。すべてのサーベイ系プロファイルでは、スタイル／引用形式の違反はデフォルトでブロッキングです。

入力

• output/DRAFT.md
• outline/outline.yml
• 任意（推奨）：
  • outline/evidence_bindings.jsonl
  • citations/ref.bib

出力

• output/AUDIT_REPORT.md
• output/TEMPLATE_RESIDUE_SCORECARD.json

検査項目（決定論的）

A150++ の引用目標（監査で使用）：

• H3 ごと：独自の引用が 12 件以上（deep：14 件以上）。
• 全体：ドラフト全体で独自の引用が 150 件以上（推奨目標：165 件、deep の下限：165 件）。

コース論文の目標：

• H3 ごと：独自の引用が 4 件以上、引用以外の文字数が 1600 文字以上。

• 全体：独自の引用が 24 件以上（推奨目標：32 件）。

• プレースホルダーの残存：省略記号（...、…）、TODO マーカー、スキャフォールドタグ。

• アウトラインとの整合性：セクション／サブセクションの順序と outline/outline.yml の比較。

• サーベイ表：course_paper では Markdown 表が 1 つ以上、survey／deep では 2 つ以上必要です（section-merger が outline/tables_appendix.md から挿入します。インデックス表は内部用です）。

• 論文の文体におけるアンチパターン：

  • 語りのテンプレート（This subsection ...、In this subsection ...）
  • スライドの案内文（Next, we move ...、We now turn to ...）
  • 明らかなパイプライン調の表現（this run、this workspace）
  • this pipeline、this stage、quality gate などの曖昧な用語は、同じ文にチェックポイント、Unit ID、Harness ロック、試行台帳、テンプレートの残存物などの Harness アンカーが含まれる場合にのみブロックします。通常の分野固有の用法は、ブロック対象外の警告にとどまります。

• エビデンスポリシーに関する免責事項の乱用：H3 本文内で「abstract-only/title-only/provisional」という定型文を繰り返すこと。

• サーベイのメタガイダンス表現：survey synthesis/comparisons should ...。

• 統合文の書き出しの繰り返し：Taken together, ... など、信号性の高い生成テンプレートの書き出しを繰り返すこと。

• 数値主張の文脈：最小限の評価文脈を示すトークン（ベンチマーク／データセット／指標／予算／コスト）を伴わない数値。

• 引用の健全性（citations/ref.bib が存在する場合）：未定義のキー、重複、基本的な書式上の問題。

• 引用形式の必須ゲート：隣接する引用ブロック（[@a] [@b]）および 1 つのブロック内でのキーの重複（[@a; @a]）がないこと。文中引用の比率は、course_paper で 20% 以上、survey／deep で 30% 以上です。

• 引用の範囲（outline/evidence_bindings.jsonl が存在する場合）：H3 ごとに使用する引用は、割り当てられたエビデンスの範囲内に収める必要があります。

• ドラフト全体における決定論的なテンプレート残存：読者向けの英語文と CJK 文を分け、この Run で選択されたテンプレートアセットの固定フレーズと各文を比較し、Workflow の上限を超えた場合は不合格とします。

• テンプレートソースの来歴：選択されたフロントマターアセットとハッシュを output/FRONT_MATTER_CONTEXT.json に記録することを必須とし、さらに、テンプレートを所有する 3 つの Skill 実装が .harness/harness.lock.json と一致することを必須とします。来歴情報の欠落、旧形式のロック、リポジトリの不整合は、受け入れをブロックします。

JSON スコアカードには、測定された比率、件数、しきい値、選択されたアセットのハッシュ、見出しを考慮した例、実装ロックの結果が記録されます。通常の Harness 実行中、Completion はその判定と各評価項目を .harness/evaluations/ledger.jsonl に反映します。失敗した Attempts も記録されるため、Run Audit は PASS／FAIL に集約するのではなく、最新の測定結果を提示できます。スコアカードファイルは完全なエビデンスオブジェクトとして保持され、台帳は意図的に簡潔なものになっています。現在の 10% という上限は、初期のポリシー目標です。公開済みの Survey 再生では、現在の 31 項目のチェック契約が残存物 0/226 で完了しており、保持された Artifact セット 1 件で達成可能であることを示しています。クリーンな状態からの実行、無関係なトピック、プロファイルをまたいだ調整については、引き続き検証が必要です。

レポートの使い方（ルーティングテーブル）

output/AUDIT_REPORT.md は「次に何を修正するか」を示すルーターとして扱います。

よくある FAIL の種類 -> 担当ステージ／スキル：

• プレースホルダー／漏れ出した骨組み

  • 修正：C2–C4 の成果物がクリーンではありません。subsection-briefs ／ evidence-draft ／ writer-context-pack に戻し、該当するセクションを書き直します。

• 概要テーブルの不足（選択したプロファイルのテーブル最小数を下回る）

  • 修正：table-schema と appendix-table-writer により outline/tables_appendix.md が作成されていることを確認します（コースペーパーテーブルを1つ以上、サーベイ／詳細テーブルを2つ以上含み、引用に裏付けられ、プレースホルダーがない状態）。その後、section-merger を再実行します。

• つなぎやナレーターのブリッジにおけるプランナーの語り

  • 修正：transition-weaver を再実行します（ブリーフに bridge_terms ／ contrast_hook が含まれていることも確認してください）。その後、再度マージします。

• H3 内のナレーションテンプレート／スライドナビゲーション

  • 修正：writer-selfloop（ローカル、セクション単位）または subsection-polisher を使って、問題のある sections/S*.md を書き直します。

• エビデンスポリシーに関する免責事項の繰り返し

  • 修正：エビデンスポリシーは Intro／Related Work（フロントマター）に一度だけ残し、H3 内の繰り返しを削除します（draft-polisher またはローカルでのセクション書き直しを使用します）。

• 引用の範囲の逸脱（対象範囲外の bibkey）

  • 修正：（a）対象範囲内にとどまるようサブセクションを書き直すか、（b）マッピング／バインディング（section-mapper → evidence-binder）を修正してパックを再生成します。

• 全体で固有の引用が少なすぎる

  • 修正：citation-diversifier → citation-injector（新しい事実の追加は禁止）を実行し、その後 draft-polisher を実行します。

• Intro／Related Work の内容が薄い／引用が少なすぎる

  • 修正：対応する sections/S<sec_id>.md のフロントマターファイルを、密度の高い位置づけと手法の段落を用いて writer-selfloop（フロントマターのパス）で書き直します。

• ワークフローの上限を超える、ドラフト全体のテンプレート残存

  • 修正：各スコアカード例の見出し、セクションの種類、セクションの担当者、テンプレートの担当者を使って、該当するフロントマター、章の導入部、または H3 の範囲を特定します。元のセクションを書き直し、マージ済みドラフトを再生成して、監査を再実行します。既存の Run を通すためにテンプレートアセットを弱めたり、名前を変更したりしないでください。

予防ガイダンス（上流の執筆者向け）

重い推敲ループなしで監査に PASS させたい場合：

• 各 H3 は内容に関する主張と論旨から始めます（ナレーションテンプレートは避けます）。
• 明示的な対比と、少なくとも1つの評価の基準となる段落を使います。
• 主張ごとに引用を埋め込みます（末尾に引用をまとめるのは避けます）。
• エビデンスポリシーの制限事項は各 H3 ではなく、フロントマターに一度だけ記載します。

スクリプト

クイックスタート

• uv run python .codex/skills/pipeline-auditor/scripts/run.py --help
• uv run python .codex/skills/pipeline-auditor/scripts/run.py --workspace <workspace>

すべてのオプション

• --workspace <dir>
• --unit-id <U###>（任意。ログ用）
• --inputs <semicolon-separated>（まれな上書き用。デフォルト設定を推奨）
• --outputs <semicolon-separated>（まれな上書き用。デフォルトでは output/AUDIT_REPORT.md と output/TEMPLATE_RESIDUE_SCORECARD.json に書き込みます）
• --checkpoint <C#>（任意）

例

• global-reviewer の実行後、LaTeX／PDF 化の前に監査を実行します：
  • uv run python .codex/skills/pipeline-auditor/scripts/run.py --workspace <workspace>

トラブルシューティング

問題：未定義の引用が原因で監査に失敗する

修正：

• citation-verifier で引用を再生成し、citations/ref.bib に引用されたすべてのキーが含まれていることを確認します。

問題：ナレーション調のナビゲーション表現が原因で監査に失敗する

修正：

• 問題のある sections/* ファイル内で、論旨をつなぐブリッジ（内容を伴う受け渡しであり、ナビゲーションの解説を含まない）に書き直し、その後、再度マージします。

問題：「固有の引用が少なすぎる」ことが原因で監査に失敗する

修正：

• citation-diversifier を実行して、output/CITATION_BUDGET_REPORT.md を作成します。
• citation-injector で適用します（output/DRAFT.md を編集し、output/CITATION_INJECTION_REPORT.md を書き込みます）。
• その後、draft-polisher → global-reviewer → 監査を実行します。