doc-ears-fixer

doc-ears-fixer

目的

最新の監査レポートを読み、EARS ドキュメントに修正を適用します。../doc-ears-audit/SKILL.md と、監査に合格する EARS の間をつなぎ、監査↔修正のサイクルを収束させます。

レイヤー：3（EARS の品質向上）。 上流：EARS ドキュメント + .aidoc/audit/03_EARS-audit.md。 下流：修正済み EARS + EARS-NN.F_fix_report_vNNN.md。

使用するタイミング

doc-ears-audit が FAIL を返した後、監査 → 修正 → 監査のループの一環として使用します。 監査レポートがない場合（先に監査を実行してください）、または新しい EARS を作成する場合（../doc-ears/SKILL.md / ../doc-ears-autopilot/SKILL.md を使用してください）には使用しないでください。

入力仕様

.aidoc/audit/03_EARS-audit.md レポートを読み込みます。編集前に EARS のバックアップを作成してください（tmp/backup/EARS-NN_<ts>/）。エラーが発生した場合は復元します。要素 ID の規則は ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に、構造と構文の規則は ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml と README.md に定められています。

修正モード

.aidoc/profile.yaml から review_mode を解決します。未設定の場合は、${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md の優先順位に従って、フレームワークのデフォルトである team にフォールバックします。同じフォールバックが、その他の適応設定（section_toggles）にも適用されます。

team モード（REVIEW_TEAM.md §Operations §Remediate）

1. .aidoc/audit/03_EARS-audit.mdの監査レポートを読み、さらに、 該当する場合は.aidoc/review/03_EARS/<EARS-id>/配下の ペルソナごとのスロットも読みます（<EARS-id>はEARS-01などの 短い成果物IDです）。

   • 構造化された指摘事項（安定したID、優先度、場所、推奨事項）については、 ペルソナごとのスロットを優先します。
   • スロットは任意です。スロットがない場合（例：single_passの実行で synthesizerの出力が生成されなかった場合）は、監査レポートの Findingsセクションを直接解析します。

2. 指摘事項ごとに担当するレンズを特定します。 ブロッキング指摘事項（P0 + P1）には、 synthesizerの縮約形式によるpersonas配列が含まれるか、レンズごとのスロットの 所属から推定できます。割り当てルールは次のとおりです。

   • 単一レンズの指摘事項（ペルソナが1つ）：そのレンズに割り当てます。
   • 複数レンズの指摘事項（ペルソナが2つ以上）：記載されたすべてのレンズを 並行して割り当てます。それぞれが独自の<persona>.fix_<N>.jsonスロットに 書き込みます。修正が受け入れられるのは、割り当てられたすべてのレンズが 新たなP0/P1を返さない場合に限られます（いずれか1つのレンズで後退があれば、 パッチを元に戻します）。
   • ペルソナなし／孤立した指摘事項（personasが空または未指定）： EARSのクルーで作成者を担当するレンズ（REVIEW_CREWS.yamlによると、 EARSではrequirements_specialist）を、デフォルトの担当レビュアーとして 割り当てます。

   EARSのレンズからエージェントへの対応表：

   レンズ	エージェント
   requirements_specialist	aidoc-flow:requirements-analyst
   tech_lead	aidoc-flow:solutions-architect
   qa_lead	aidoc-flow:test-architect
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer

   EARSクルーの重み：{requirements_specialist: 35, tech_lead: 25, qa_lead: 20, chaos_engineer: 12, security_engineer: 8}。

   P2/P3は助言的な指摘事項のため、レンズによる検証を行わずに決定的に適用します。

3. ブロッキング指摘事項ごとにパッチを提案して適用します。以下の修正フェーズ0～7で パッチの形式を説明します。カタログは両方のモードで共通です。既存のInput Contractに 従い、最初にバックアップを作成してください。

4. 非回帰を検証します。 手順2で特定した担当レンズごとに、パッチ検証モードで Taskサブエージェントを1つ割り当てます。 subagent_type=<mapped agent>、概要にはパッチ適用済みの領域、元の指摘事項、 パッチの差分を含めます。lens_scoreを決める際、レンズは作成者自身による 評価スコア（*_ready_score／*_score／readiness_score／audit_score）を 読んだり、引用したり、重み付けに用いたりしてはなりません （REVIEW_TEAM.md GD-05）。出力は、新しいペルソナ出力レコード （パッチ適用済み領域のlens_scoreと、新たな指摘事項があればその内容）とします。 各レンズの出力を .aidoc/review/03_EARS/<EARS-id>/<persona>.fix_<N>.jsonに保存します （<N>は修正イテレーションの連番で、1から始まります）。複数レンズの指摘事項では、 同じ<N>に対して担当レンズごとに1つずつスロットファイルを作成します。

5. 後退を元に戻します。 いずれかのレンズがパッチに対して新たなP0/P1を返した場合、 そのパッチを元に戻し、元の指摘事項にmanual_requiredのフラグを設定します。 後退を招く修正を黙って残してはなりません。

6. すべてのパッチの検証後に、synthesizerを1回だけ割り当てます （subagent_type=aidoc-flow:synthesizer）。統合された修正レポートを出力させます。 Fixes AppliedテーブルとValidation Slotsインデックスの両方を含む EARS-NN.F_fix_report_vNNN.mdを保存します。

single_passモード（フォールバック）

フェーズ0～7を直接、単独で適用し、レンズによる検証は行いません。従来の動作を変更せず、 プロファイルで指定されている場合、Taskサブエージェントの割り当てが利用できない場合、 またはスロットが存在しない場合に必須となります。

どちらのモードでも、P2/P3の助言的な指摘事項はレンズによる検証なしで適用します。 チームモードでパッチ検証ループの対象となるのは、ブロッキング指摘事項（P0/P1）のみです。

Saga の連携

doc-ears-autopilot から（または直接）呼び出されると、このスキルは ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md に従って、 .aidoc/review/03_EARS/<EARS-id>/saga.json の saga ジャーナルを読み取り、 更新します。修正ツールは saga の修正ステージとして動作します。パッチ検証中に ブランチを BRANCH_COMPENSATING に遷移させ、その後、（検証済みの場合は） BRANCH_COMPLETED に、（リグレッションが検出された場合は） BRANCH_FAILED に戻します。

開始時

開始時に、修正ツールの開始エポックを書き込みます。

Bash: mkdir -p .aidoc/review/03_EARS/<EARS-id>/ && date +%s > .aidoc/review/03_EARS/<EARS-id>/.skill-start.fixer

.aidoc/review/03_EARS/<EARS-id>/saga.json が存在する場合は、読み取ります。現在の saga の status が FANIN_REDUCED（監査後）または BRANCH_FAILED（以前の修正ツールによるリグレッション後の再実行）であることを検証します。 status がそれ以外の場合は、警告をログに記録して処理を続行します。

パッチ検証中（チームモード）

レンズによる検証が必要なブロッキング指摘（P0/P1）ごとに、次の手順を実行します。

1. 担当するレンズ検証ツールをディスパッチする前に、指摘の personas[] リストにある 各レンズについて、次の遷移を追加します。 {"ts": "<now>", "from": "BRANCH_COMPLETED", "to": "BRANCH_COMPENSATING", "scope": "branch:<lens>"}。 branches[<lens>].status を "BRANCH_COMPENSATING" に更新します。 compensation_actions[] に次のエントリを追加します。 {"ts": "<now>", "branch": "<lens>", "reason": "<finding_id>: <message>", "action": "retry"}。
2. 検証 Task サブエージェントからの応答後：
   • パッチが検証済みの場合（リグレッションなし）：BRANCH_COMPLETED に遷移します。 compensation_actions[] の最後のエントリを検証結果で更新します。
   • パッチによってリグレッションが発生した場合（レンズがパッチ適用箇所に新しい P0/P1 を 指摘）：BRANCH_FAILED に遷移します。 compensation_actions[] の最後のエントリの action を "escalate" に設定します。 この指摘は manual_required になります。

統合処理のディスパッチ前

REVIEW_SAGA.md の「ブレーカー方針」に従い、修正ツールのチェックポイント境界は 複数レンズの検証ディスパッチ間にあります（ブロッキング指摘ごとのレンズ検証が それぞれ 1 つの境界です）。 次の検証をディスパッチする前に：

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/03_EARS/<EARS-id>/.skill-start.fixer) ))

経過時間が SOFT_DEADLINE（1500s）を超えている場合：

• 遷移を追加します。{"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "PARTIAL_TIMEOUT", "scope": "run"}。
• saga の status: "PARTIAL_TIMEOUT" を設定します。完了済みの検証はすべて保持します （対応する fix_N.json スロットは永続化されています）。再開時に残りの検証を続行できるよう、 current_phase: "fixer" を設定します。
• updated_at を更新します。saga.json を書き込みます。正常に終了します。

残りの検証は、doc-ears-autopilot の§3.4 の再開ロジックに従い、次回の呼び出し時に 再開されます。

統合処理による集約後

• 遷移を追加します。{"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "BRANCH_COMPLETED", "scope": "run"}（run レベル：修正ツールの パスが完了）。
• saga の status: "BRANCH_COMPLETED" を更新します（autopilot の次のフェーズは re-review になります）。
• updated_at を更新します。saga.json を書き込みます。

単独で呼び出された場合（開始時に saga.json がない場合）

.aidoc/review/03_EARS/<EARS-id>/saga.json が存在しない場合（ユーザーが autopilot ループの外で /aidoc-flow:doc-ears-fixer を直接実行した場合）、saga スキーマ全体を 初期化しないでください。saga.json not present; running fixer without saga journal (standalone mode) を ログに記録します。通常どおり修正フェーズを実行し、修正レポートを書き込みます。 すべての saga.json の遷移をスキップします。スキルの直接呼び出しとの後方互換性を保ちます。

single_pass モードで呼び出された場合

review_mode: single_pass が有効な場合、修正ツールはレンズ検証を行わずに決定論的に パッチを適用し、saga.json も書き込みません。既存の動作を維持します。

ブレークサーキットポリシー

${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md §「ブレークサーキットポリシー」に従い、このスキルは1つのチェックポイント境界で経過した実時間を確認します。つまり、すべての指摘事項ごとのパッチが返された後、シンセサイザーを呼び出す前です。SOFT_DEADLINE は1500秒です（ORCHESTRATOR_TIMEOUT=1800s から300秒のバッファを差し引いた値）。

ソフトデッドラインを超過した場合は、上記の§「シンセサイザーのディスパッチ前」に従い、saga の status: "PARTIAL_TIMEOUT" で正常に終了します。フィクサーの部分的な進捗（すでに書き込まれた fix_N.json スロット）は保持されます。再開時の呼び出しは、ブレークサーキットが作動した箇所から続行します。

修正フェーズ

順番に実行します。後続のフェーズは、先行フェーズが成功していることを前提とします。

フェーズ	対象範囲	代表的なアクション
0 — 構造	ネストされたフォルダーのルール	EARS を docs/03_EARS/EARS-NN_{slug}/ に移動する。フォルダー名を ID に合わせて変更する。移動後に相対リンクを修正する
1 — ファイル不足	参照先が存在しないファイル	テンプレートから用語集／リファレンスのプレースホルダーを作成する
2 — リンク	壊れたパス／絶対パス	相対パスを再計算する。絶対パスを相対パスに変換する。上流の BRD／PRD リンクを修正する
3 — 要素 ID	レガシー／無効な ID	EARS.NN.SS.xxxx を再導出する（セクション番号＋コンテンツハッシュ）。レガシー形式の EARS.NN.xxxx、数値の種別コード（.25／.26）、Event-XXX／State-XXX／UB-XXX／REQ-XXX のプレフィックスを削除する
4 — コンテンツ	プレースホルダー、構文	テンプレートの日付を埋める。見出しをその場で標準化する。SHALL キーワードの不足、WHEN-THE-SHALL 構造の破損、トリガーの不足、曖昧なタイミング、複合的（非アトミック）な文は手動レビューが必要としてフラグを付ける。[TODO]／[TBD] にフラグを付ける
5 — 参照	トレーサビリティ	このレイヤーの required_tags に不足しているタグを追加する（LAYER_REGISTRY.yaml の必須上流契約に従う。EARS では @prd が必要）。@threshold: の形式を修正する。カンマ区切りをパイプ区切りに変換する。トレーサビリティマトリクスを更新する
6 — 上流	メタデータ＋ドリフト	deliverable_type／document_type を修正する。upstream_mode: "ref" の場合は、段階的なドリフトマージ（下記）を適用する
7 — スタイル	STY01 禁止フレーズ、STY02／03 の過剰な長文、FM01 のフロントマター不一致	埋め草を置き換える。フラグが付いた最上級表現を置き換える。1つのセクションに禁止フレーズが3つ以上ある段落は箇条書きにまとめる。フロントマターと Document Control の行を整合させる。STY02／03 — 300語を超えるセクションは、次の要件境界で分割するか、manual_required とマークする。基準：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

要素 ID の再導出： EARS.{doc_id}.{section_id}.{hash} — セクション内で重複しない安定した4桁の16進識別子を割り当てます（HASH01）。衝突した場合は8桁に拡張します。ここでは SHA-256 を計算しないでください。ハッシュ形式は、決定論的なツール処理によって生成される正規化の TARGET です。また、バイト単位で厳密なフィールド抽出が定義されているのは BRD §7 のみです（EARS ではフェーズ2以降）。既存の有効な ID は保持してください。再導出すると、下流のすべての引用が壊れます。 基準：framework/governance/ID_NAMING_STANDARDS.md。セクションは要素の種別（文または品質特性）を示します。レガシーの連番を最終セグメントとして再利用しないでください。ドキュメントレベルの参照（SPEC-NN、ADR-NN、IPLAN-NN）はハイフン形式のままにします。

段階的な上流ドリフト（upstream_mode: "ref" の場合のみ）：変更が5%未満 → ティア1の自動マージ（パッチバンプ）。5～15% → ティア2の自動マージ＋詳細な変更履歴 （マイナーバンプ）。15%超 → ティア3で現行版をアーカイブし、オートパイロットで再生成（メジャーバンプ）。上流で削除された要件は決して削除せず、[DEPRECATED] とマークしてトレーサビリティのために保持します。結果を .drift_cache.json に記録します。

信頼度の分類

適用した修正すべてにタグを付け、レポートに件数を記載してください。

信頼度	意味
auto-safe	決定的で、意味上のリスクが低い（リンク／パス、ヘッダーの正規化、ID 変換、カンマからパイプへの変換）
auto-assisted	部分的な前提に基づくテンプレートの挿入（テーブル／セクションのひな形、しきい値のプレースホルダー）
manual-required	ドメインの内容を推測できない（欠落した SHALL、非アトミックな分割、曖昧な用語の定量化、未解決の TODO/TBD）

コンテンツ保持ルール

• 既存の要件コンテンツは削除しないでください。テンプレートブロックを挿入するのは、セクションが欠落している場合、または最小構造を満たしていない場合に限ります。
• 同等の見出しは、セクションを重複させず、元の位置で正規化してください。
• 再フォーマット時はしきい値を保持してください。番号を振り直す場合は同じセクションファイル内に限り、相互参照のアンカーが壊れる場合はフラグを立ててください。

修正レポートの形式

テーブルのパイプ文字のエスケープ（MD056）

シェルのパイプ文字を含むコードスパン（例：`docker compose ps | grep 'Up'`）を含む Markdown のテーブルセルを出力すると、コードスパン内のエスケープされていない | が markdownlint に列区切りとして解析され、MD056（列数の不一致）が発生します。修正方法は次の 2 つです。

• 推奨： コードスパン内のパイプ文字を \| としてエスケープします。Markdown ビューアーでは | として表示されますが、テーブルが壊れません。 行の例：| OP-02 | ... | `docker compose ps \| grep 'Up'` | ... |
• 代替方法： コードスパンをテーブルセルの外に移動し、脚注またはテーブル下の段落で参照します。セルには「シェルの準備完了ゲート（下記参照）」のような通常の文章を記載します。

テーブルセル内にシェルのパイプ文字を含むコードスパンを出力するすべてのレポート行に適用してください。MD056 を引き起こす Cascade 出力は markdownlint の過剰な厳格さではなく、SKILL のバグです。lint を無視するのではなく、ここで修正してください。

EARS-NN.F_fix_report_vNNN.md を作成し、次を記載してください。Summary（issues in / fixed / remaining、作成／変更したファイル）・Fixes Applied（code、issue、fix、file、confidence）・Manual-Review Queue（例：構文、原子性）・Validation After Fix（修正前→修正後の score/errors/warnings）・Cleanup Summary（置き換えられた修正レポートの削除）・Next Steps（doc-ears-audit の再実行）。スコアがしきい値以上になるか、反復回数が上限に達するまで繰り返してください。

適応

修正を適用する前に、プロジェクトの適応プロファイル（.aidoc/profile.yaml）を読み込んでください。section_toggles を遵守し、プロジェクトで無効化されているオプションのセクションを再導入しないでください。不明なキーや対象範囲外のキーは無視してください。 権限の根拠：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

関連リソース

• Audit（入力）：../doc-ears-audit/SKILL.md · 作成：../doc-ears/SKILL.md
• オーケストレーション：../doc-ears-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 権限の根拠：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md