doc-bdd-fixer

doc-bdd-fixer

目的

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

レイヤー：4（BDD の品質改善）。 上流：BDD ドキュメントと .aidoc/audit/04_BDD-audit.md。 下流：修正済み BDD と BDD-NN.F_fix_report_vNNN.md。

使用するタイミング

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

入力契約

.aidoc/audit/04_BDD-audit.md レポートを読み込みます。編集前に BDD をバックアップし（tmp/backup/BDD-NN_<ts>/）、エラーが発生した場合は復元します。要素 ID の標準は ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に記載されています。構造と YAML シナリオスキーマは ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml および README.md に記載されています。

修正モード

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

team mode（REVIEW_TEAM.md §Operations §Remediate に準拠）

1. .aidoc/audit/04_BDD-audit.md の監査レポートを読み、さらに、 .aidoc/review/04_BDD/<BDD-id>/（<BDD-id> は BDD-01 などの短い アーティファクト ID）のペルソナ別スロットが存在する場合は、それも読みます。

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

2. 各指摘事項の担当レンズを特定します。各ブロッキング指摘事項（P0 + P1）には、 synthesizer の簡略形式の personas 配列が含まれているか、ペルソナ別スロットの メンバーシップから推定できます。ディスパッチのルール：

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

   BDD のレンズ → エージェントの対応表：

   レンズ	エージェント
   qa_lead	aidoc-flow:test-architect
   tech_lead	aidoc-flow:solutions-architect
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer
   operator	aidoc-flow:devops-release-engineer
   auditor	aidoc-flow:traceability-auditor

   BDD クルーの重み：{qa_lead: 35, tech_lead: 25, chaos_engineer: 14, security_engineer: 6, operator: 10, auditor: 10}。

   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/04_BDD/<BDD-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 インデックスの両方を含む BDD-NN.F_fix_report_vNNN.md を保存します。

single_pass mode（フォールバック）

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

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

Saga との連携

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

開始時

開始時に、修正担当の開始時刻（エポック秒）を書き込みます。

Bash: mkdir -p .aidoc/review/04_BDD/<BDD-id>/ && date +%s > .aidoc/review/04_BDD/<BDD-id>/.skill-start.fixer

.aidoc/review/04_BDD/<BDD-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 の「Break-circuit policy」に従い、修正担当のチェックポイント境界は複数レンズによる検証のディスパッチ間にあります（ブロッキング対象の指摘ごとのレンズ検証が、それぞれ1つの境界になります）。次の検証をディスパッチする前に：

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/04_BDD/<BDD-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-bdd-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/04_BDD/<BDD-id>/saga.json が存在しない場合（ユーザーが autopilot ループの外で /aidoc-flow:doc-bdd-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 は 1500s （ORCHESTRATOR_TIMEOUT=1800s から 300s のバッファを差し引いた値）です。

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

修正フェーズ

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

フェーズ	対象範囲	代表的なアクション
0 — 構造	フォルダー／インデックスルール	BDD を docs/04_BDD/BDD-NN_{slug}/ に移動する；フォルダー名を ID に合わせて変更する；インデックスが存在することを確認する；移動後に相対リンクを修正する
1 — 欠落ファイル	参照先が存在しないファイル	テンプレートから用語集／インデックスのプレースホルダーを作成する
2 — リンク	リンク切れ／絶対パス	相対パスを再計算する；絶対パスを相対パスに変換する
3 — 要素 ID	旧式／無効な ID	BDD.NN.SS.xxxx を再導出する（セクション＋コンテンツハッシュ）；旧式の BDD.NN.xxxx、数値のタイプコード、SCEN-XXX／STEP-XXX のプレフィックスを削除する
4 — コンテンツ	プレースホルダー、フィールド、しきい値	テンプレートの日付を入力する；欠落しているシナリオフィールド（type／priority／ears／id）を追加する；インラインの WITHIN @threshold: を追加する；[TODO]／[TBD] と欠落している given／when／then のフェーズリスト（BDD-SCHEMA-001）に手動での補完が必要であることを示す
5 — 参照	トレーサビリティ	各シナリオに要素レベルの ears: リスト（LAYER_REGISTRY.yaml の必要な上流契約に基づく BDD の required_tags）が含まれていることを確認する；ドキュメント間のパスを修正する；spec_trace を追加／修正する；トレーサビリティマトリクスを更新する
6 — 上流	メタデータ＋ドリフト	deliverable_type／document_type／upstream_mode を修正する；上流の EARS にドリフトがある場合は、段階的なドリフトマージを適用する（下記）
7 — スタイル	STY01 禁止表現、STY02/03 の過剰に長い文章、FM01 のフロントマター不一致	埋め草を置き換える；フラグが付いた最上級表現を置き換える；1つのセクションに禁止表現が 3 つ以上ある場合は段落を箇条書きにまとめる；フロントマターと Document Control の行を整合させる；STY02/03 — カテゴリの境界で過剰に長い Scenario ブロックを分割するか、manual_required とマークする。規範：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

要素 ID の再導出： BDD.{doc_id}.{section_id}.{hash} — セクション内で一意となる安定した 4 桁の 16 進数識別子を割り当てます（HASH01）。衝突する場合は 8 桁に拡張します。ここで SHA-256 を計算しないでください。ハッシュ形式は決定論的なツール処理で生成される正規化の TARGET であり、バイト単位で正確なフィールド抽出が定義されているのは BRD §7 のみです（BDD ではフェーズ 2 以降）。有効な既存 ID は保持してください。再導出すると、後続のすべての引用が壊れます。 規範：framework/governance/ID_NAMING_STANDARDS.md。ドキュメントレベルの参照（SPEC-NN、ADR-NN、IPLAN-NN）はダッシュ形式のままにします。シナリオはセクション 03 に配置します。

コンテンツの保持： シナリオのステップテキスト（given／when／then）や examples のデータは決して変更しないでください。欠落しているフィールド／メタデータの追加と、ハードコードされた値をインラインの @threshold: 参照に置き換えることだけを行います。欠落しているフィールド／構造にはフラグを付けます。内容を創作してはいけません。Gherkin から移行する場合は、各 @scenario-id をシナリオの id: にそのままコピーしてください。ハッシュを再計算してはいけません（後続の @bdd: を安定させるためです）。

段階的な上流ドリフト（BDD 作成後の EARS の変更）：変更が 5% 未満 → Tier 1：新しいシナリオを自動マージする（パッチバージョンを上げる）；5～15% → Tier 2：詳細な変更履歴を付けて自動マージし、変更されたソースに由来するシナリオにレビュー対象のマークを付ける（マイナーバージョンを上げる）；15% 超 → Tier 3：現在のものをアーカイブし、オートパイロットで再生成する（メジャーバージョンを上げる）。上流で削除されたシナリオは決して削除しないでください。@deprecated のマークを付け、トレーサビリティのために保持します。 結果を .drift_cache.json に記録します。

信頼度の分類

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

信頼度	意味
auto-safe	決定的で、意味上のリスクが低い修正（リンク／パス、タグの移動、ID変換、しきい値の置換）
auto-assisted	一部の前提に基づくテンプレートの挿入（シナリオ／セクションのひな形作成、デフォルトの優先度タグ）
manual-required	ドメインの内容を推測できないもの（未解決のTODO/TBD、Given-When-Thenの不足、ステップの意味）

コンテンツ保持ルール

• 既存のシナリオ内容を削除しないでください。セクションまたはシナリオが存在しない場合や、最小構成を満たしていない場合にのみ、テンプレートブロックを挿入します。
• シナリオの上流トレースは @タグではなく、ears: リストフィールドとして引き継ぎます。重複させないでください。
• 採番や再構成は同じドキュメント内でのみ行います。相互参照アンカーが壊れる場合はフラグを立てます。

修正レポートの形式

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

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

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

テーブルセル内にシェルのパイプを含むコードスパンを出力するすべてのレポート行に適用します。MD056を引き起こすカスケード出力はSKILLの不具合であり、markdownlintの過剰な厳格さによるものではありません。lintを無視するのではなく、ここで修正してください。

BDD-NN.F_fix_report_vNNN.md を作成し、概要（問題数／修正数／残件数、作成／変更したファイル）・適用した修正（コード、問題、修正、ファイル、信頼度）・手動レビューキュー・修正後の検証（修正前→修正後のスコア／エラー／警告）・クリーンアップの概要（置き換えられた修正レポートの削除）・次のステップ（doc-bdd-audit を再実行）を記載します。スコアがしきい値以上になるまで、または最大反復回数に達するまで繰り返します。

適応

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

関連リソース

• 監査（入力）：../doc-bdd-audit/SKILL.md · 作成：../doc-bdd/SKILL.md
• オーケストレーション：../doc-bdd-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 準拠先：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md