ln-614-docs-fact-checker

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリを基準とします。

ドキュメント事実確認担当（L3 ワーカー）

種類： L3 ワーカー

ドキュメントから検証可能な主張を抽出し、各主張を実際のコードベースと照合する専門のワーカーです。

目的と範囲

• 正式なドキュメントと主張の多いドキュメントを優先し、その後、Markdown ドキュメントから検証可能な主張を抽出します
• 各主張をコードベースと照合します（Grep／Glob／Read／Bash）
• ドキュメント間の矛盾（同じ事実が異なる形で記述されている状態）を検出します
• 対象範囲に docs/reference/、docs/tasks/、tests/ を含みます
• 1 回の呼び出しで実行します（ドキュメントごとではありません）。そのため、ドキュメント間の確認には全体的な視点が必要です
• 対象範囲との整合性や構造上の品質は確認しません

入力

必須の読み込み： references/audit_worker_core_contract.md、references/docs_quality_contract.md、references/markdown_read_protocol.md、references/mcp_tool_preferences.md を読み込みます。 ルールカタログは任意です。正確なルール ID、パスマトリクス、または許可リストに含まれるプレースホルダーの例外が必要な場合に限り、references/docs_quality_rules.json を読み込みます。 ツールのポリシー：ホストの AGENTS.md が対象範囲に含まれない分離サブエージェントとして実行される場合があるため、ファイルの読み込み、検索、編集には、まず hex-line MCP を使用してください。MCP の動作が不明な場合に限り、references/mcp_integration_patterns.md を読み込みます。

tech_stack、project_root、output_dir を含む contextStore を受け取ります。

ワークフロー

フェーズ 1：コンテキストの解析

contextStore から技術スタック、プロジェクトのルート、output_dir を抽出します。

フェーズ 2：ドキュメントの検出

プロジェクト内の Markdown ドキュメントを Glob で検索します。以下は除外します。

• node_modules/、.git/、dist/、build/
• docs/project/.audit/（監査の出力であり、プロジェクトのドキュメントではありません）
• CHANGELOG.md（設計上、履歴を記録するものです）

docs/project/.context/doc_registry.json が存在する場合：

• 最初に読み込みます
• doc_role=canonical のファイルを優先します
• 主張の種類（パス、エンドポイント、バージョン、コマンド）が多いファイルを優先します
• 矛盾がそれらを参照している場合を除き、ナビゲーションハブの優先度を下げます

フェーズ 3：主張の抽出（レイヤー 1）

検出ポリシー：2 層検出（候補のスキャン、その後のコンテキスト検証）を使用します。検証方法が曖昧な場合に限り、references/two_layer_detection.md を読み込みます。

優先順位を付けた各ドキュメントについて、セクションを優先して読み、Grep／正規表現パターンを使って検証可能な主張を抽出します。

ドキュメントで参照されているコードファイルについては、組み込みの読み取り機能を使う前に、outline() と発見を優先した read_file() を使用します。検証が追加編集に発展した場合に限り、edit_ready=true, verbosity="full" を指定します。エンティティの同一性や参照解決が、マニフェスト／ファイルを直接確認した後も曖昧な場合に限り、hex-graph を使用します。

必ず読み込むこと： 主張の種類ごとの詳細な抽出パターンについて、references/claim_extraction_rules.md を読み込みます。

9 種類の主張：

#	主張の種類	抽出する内容	抽出パターン
1	ファイルパス	ソースファイル、ディレクトリ、設定ファイルへのパス	src/、lib/、app/、docs/、config/、tests/ に一致するバッククォート付きパス、リンク先
2	バージョン	パッケージ／ツール／イメージのバージョン	依存関係／パッケージ／イメージ名の近くにある Semver パターン
3	件数／統計	コードベースに関する数値の主張	`\d+ (modules
4	API エンドポイント	HTTP メソッドとパス	`(GET
5	設定キー／環境変数	環境変数、設定キー	設定のコンテキストにある [A-Z][A-Z_]{2,}、process.env.、os.environ
6	CLI コマンド	シェルコマンド	バッククォートブロック内の npm run、python、docker、make
7	関数／クラス名	コードエンティティへの参照	バッククォート内またはコードのコンテキストにある CamelCase／snake_case
8	行番号参照	file:line 形式のパターン	[\w/.]+:\d+ のパターン
9	Docker／インフラに関する主張	イメージタグ、ポート、サービス名	イメージ名とタグ、Docker のコンテキストにあるポートマッピング

主張ごとの出力形式：{doc_path, line, claim_type, claim_value, raw_context}。

フェーズ 4：主張の検証（レイヤー 2）

抽出した各主張を、コードベースと照合して検証します。

主張の種類	検証方法	検出結果の種類
ファイルパス	Glob または ls で存在を確認	PATH_NOT_FOUND
バージョン	パッケージファイル（package.json、requirements.txt、docker-compose.yml）を Grep し、比較	VERSION_MISMATCH
件数	Glob／Grep で実際のエンティティ数を数え、主張された数と比較	COUNT_MISMATCH
API エンドポイント	ルート／コントローラー定義を Grep	ENDPOINT_NOT_FOUND
設定キー	ソース内で実際の使用箇所を Grep	CONFIG_NOT_FOUND
CLI コマンド	package.json のスクリプト、Makefile のターゲット、バイナリの存在を確認	COMMAND_NOT_FOUND
関数／クラス	ソース内で定義を Grep	ENTITY_NOT_FOUND
行番号	指定行のファイルを読み込み、内容が主張されたコンテキストと一致するか確認	LINE_MISMATCH
Docker／インフラ	docker-compose.yml 内のイメージタグとポートを Grep	INFRA_MISMATCH

偽陽性の除外（レイヤー 2 の推論）：

• テンプレートのプレースホルダー（{placeholder}、YOUR_*、<project>、xxx）→ スキップ
• 例示／仮定上のパス（「e.g.」、「for example」、「such as」に続くもの）→ スキップ
• 未来の予定に関する主張（「will add」、「planned」、「TODO」）→ スキップまたは LOW
• 条件付きの主張（「X を使用する場合は、Y を設定する」）→ X が tech_stack で検出された場合のみ検証
• 外部サービスのパス（URL、外部リポジトリ）→ スキップ
• 他のプロジェクトについて説明する SCOPE／コメントの HTML ブロック内にあるパス → スキップ
• .env.example の値 → スキップ（実際の値と異なるのが想定されるため）

フェーズ 5：ドキュメント間の一貫性

ドキュメント間で抽出した主張を比較し、矛盾を見つけます。

確認項目	方法	検出タイプ
同じパス、異なる場所	ファイルパスに関する主張をグループ化し、すべてが同じ実際のパスを指しているか確認します	CROSS_DOC_PATH_CONFLICT
同じエンティティ、異なるバージョン	エンティティ名ごとにバージョンに関する主張をグループ化し、値を比較します	CROSS_DOC_VERSION_CONFLICT
同じ指標、異なる数値	主題ごとに数に関する主張をグループ化し、値を比較します	CROSS_DOC_COUNT_CONFLICT
仕様書にはあるがガイドにはないエンドポイント	api_spec.md と guides/runbook のエンドポイントに関する主張を比較します	CROSS_DOC_ENDPOINT_GAP

アルゴリズム：

claim_index = {}  # key: normalized(claim_type + entity), value: [{doc, line, value}]
FOR claim IN all_verified_claims WHERE claim.verified == true:
  key = normalize(claim.claim_type, claim.entity_name)
  claim_index[key].append({doc: claim.doc_path, line: claim.line, value: claim.claim_value})

FOR key, entries IN claim_index:
  unique_values = set(entry.value for entry in entries)
  IF len(unique_values) > 1:
    CREATE finding(type=CROSS_DOC_*_CONFLICT, severity=HIGH,
      location=entries[0].doc + ":" + entries[0].line,
      issue="'" + key + "' stated as '" + val1 + "' in " + doc1 + " but '" + val2 + "' in " + doc2)

フェーズ 6：スコアとレポート

必ず読むこと： references/audit_scoring.md を読み込みます。

ペナルティ計算式を使ってスコアを計算します。レポートを作成します。

監査カテゴリ（Checks テーブル用）

ID	確認項目	対象範囲
path_claims	ファイル／ディレクトリのパス	すべてのパス参照をファイルシステムと照合します
version_claims	バージョン番号	パッケージ、ツール、イメージのバージョンをマニフェストと照合します
count_claims	数量と統計	数値に関する記述を実際の数と照合します
endpoint_claims	API エンドポイント	ルート定義をコントローラー／ルーターと照合します
config_claims	設定と環境変数	環境変数と設定キーをソースと照合します
command_claims	CLI コマンド	スクリプトとコマンドを package.json／Makefile と照合します
entity_claims	コード内のエンティティ名	関数とクラスをソース内の定義と照合します
line_ref_claims	行番号参照	file:line を実際のファイル内容と照合します
cross_doc	ドキュメント間の一貫性	ドキュメント間で同じ事実が一致しているか確認します

重大度の対応付け

問題タイプ	重大度	理由
PATH_NOT_FOUND（重要なファイル：AGENTS.md、CLAUDE.md、runbook、api_spec）	CRITICAL	セットアップ／オンボーディングが失敗します
PATH_NOT_FOUND（その他のドキュメント）	HIGH	誤解を招く参照です
VERSION_MISMATCH（メジャーバージョン）	HIGH	根本的に誤っています
VERSION_MISMATCH（マイナー／パッチ）	MEDIUM	表面的なずれです
COUNT_MISMATCH	MEDIUM	誤解を招く指標です
ENDPOINT_NOT_FOUND	HIGH	API 利用者に影響します
CONFIG_NOT_FOUND	HIGH	デプロイが失敗します
COMMAND_NOT_FOUND	HIGH	セットアップ／CI が失敗します
ENTITY_NOT_FOUND	MEDIUM	混乱を招きます
LINE_MISMATCH	LOW	軽微な不正確さです
INFRA_MISMATCH	HIGH	Docker／デプロイに影響します
CROSS_DOC_*_CONFLICT	HIGH	信頼性が損なわれ、ドキュメント間で矛盾が生じます

出力形式

必ず読むこと： references/templates/audit_worker_report_template.md を読み込みます。

references/audit_summary_contract.md に従って JSON サマリーを作成します。管理モードでは、呼び出し元が runId と summaryArtifactPath の両方を渡します。スタンドアロンモードでは、ワーカーが共通コントラクトに従って、実行スコープのアーティファクトパスを独自に生成します。

{output_dir}/ln-614--global.md に、category: "Fact Accuracy" と、次のチェックを含めたレポートを作成します：path_claims、version_claims、count_claims、endpoint_claims、config_claims、command_claims、entity_claims、line_ref_claims、cross_doc。

references/audit_summary_contract.md に従ってサマリーを返します。

summaryArtifactPath がない場合は、スタンドアロンのランタイムサマリーを .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json に書き込み、構造化出力にも同じサマリーを任意で出力します。

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-614--global.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

重要なルール

読み込み済みの references/audit_worker_core_contract.md を適用してください。

• 自動修正しない： 違反のみを報告してください。ユーザー向けにコーディネーターが集約します。
• コードが正： ドキュメントがコードと矛盾する場合、（コードのバグでない限り）ドキュメントが誤りです。
• 証拠が必要： 各指摘に、使用した検証コマンドとその結果を含めてください。
• 誤検出をしない： 誤って報告するくらいなら、問題を見逃すほうが適切です。確信が持てない場合は、注記を添えて LOW に分類してください。
• 位置を正確に示す： プログラムから移動できるよう、必ず file:line を含めてください。
• 広範囲を対象とする： すべての .md ファイルをスキャンしてください。docs/reference/、tests/、タスク用ドキュメントもスキップしないでください。
• 重点的に深掘りする： まず、正規ドキュメントと主張の多いドキュメントの検証に最も注力してください。
• ドキュメント間の整合性も確認する： ドキュメント間の矛盾は、単独のドキュメントの誤りよりも信頼を損ないます。
• 効率よくまとめて処理する： 先にすべての主張を抽出し、その後、種類ごと（すべてのパス、すべてのバージョンなど）にまとめて検証してください。
• 共有プレースホルダーポリシー： docs_quality_rules.json の許可リストにあるセットアップ用プレースホルダーを尊重し、タスクのセットアップ用ドキュメントで問題として報告しないでください。
• 意味の曖昧さがある場合に限り hex-graph を使用する： コードエンティティと参照については、直接のマニフェスト／ファイルの確認でもシンボルの識別や参照の解決が曖昧な場合に限り、繰り返し grep するよりグラフクエリを優先してください。

完了の定義

読み込み済みの references/audit_worker_core_contract.md を適用してください。

• contextStore を正常に解析した（output_dir を含む）
• すべての .md ファイルを検出した（広範囲）
• 9 種類の主張を抽出した
• すべての主張を、証拠を添えてコードベースと照合した
• ドキュメント間の整合性を確認した
• Layer 2 の推論で誤検出を除外した
• ペナルティアルゴリズムを使用してスコアを算出した
• {output_dir}/ln-614--global.md にレポートを書き込んだ（単一の Write 呼び出しによるアトミックな書き込み）
• 契約に従ってサマリーを書き込んだ

参照ファイル

• 監査出力スキーマ： references/audit_output_schema.md
• 検出方法： references/two_layer_detection.md
• 主張抽出ルール：references/claim_extraction_rules.md

---

バージョン： 1.0.0 最終更新日： 2026-03-06