doc-spec-fixer

doc-spec-fixer

目的

最新の監査レポートを読み、SPEC に修正を適用します。これにより、 ../doc-spec-audit/SKILL.md と合格する SPEC をつなぎ、監査↔修正のサイクルが 収束するようにします。

レイヤー：6（SPEC 品質改善）。 上流：SPEC ドキュメントと .aidoc/audit/06_SPEC-audit.md。 下流：修正済み SPEC と SPEC-NN.F_fix_report_vNNN.md。

使用するタイミング

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

入力契約

.aidoc/audit/06_SPEC-audit.md レポートを読み込みます。編集前に SPEC を バックアップし（tmp/backup/SPEC-NN_<ts>/）、エラー時には復元してください。ID 標準は ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md から、構造ルールは ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-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/06_SPEC-audit.md の監査レポートと、 存在する場合は .aidoc/review/06_SPEC/<SPEC-id>/ 配下のペルソナ別スロット （<SPEC-id> は SPEC-01 のような短い成果物 ID）を読みます。

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

2. 指摘事項ごとに担当するレンズを特定します。ブロッキング指摘（P0 + P1）には、 シンセサイザーの簡略形式による personas 配列が含まれるか、レンズ別スロットの 所属から推定できます。ディスパッチのルールは次のとおりです。

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

   SPEC のレンズとエージェントの対応表：

   レンズ	エージェント
   architect	aidoc-flow:solutions-architect
   tech_lead	aidoc-flow:solutions-architect
   integration_lead	aidoc-flow:solutions-architect
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer

   aidoc-flow:solutions-architect に対応する 3 つのレンズ （architect／tech_lead／integration_lead）については、エージェントが 該当レンズに対象を絞って検証できるよう、Task のディスパッチ時に適用するレンズを 検証ブリーフで指定する必要があります。

   SPEC クルーの重み：{architect: 30, tech_lead: 30, integration_lead: 20, chaos_engineer: 10, security_engineer: 10}。

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

3. ブロッキング指摘事項ごとにパッチを提案して適用します。以下の修正フェーズ 0～8 でパッチの形式を説明します。カタログはどちらのモードでも同じです。 既存の 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/06_SPEC/<SPEC-id>/<persona>.fix_<N>.json に保存します（<N> は 1 から始まる連続した修正反復カウンターです）。 複数レンズの指摘事項では、同じ <N> に対して担当レンズごとに 1 つの スロットファイルを生成します。

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

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

single_pass mode（フォールバック）

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

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

Saga の操作

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

開始時

開始時に、フィクサーの開始エポックを書き込みます。

Bash: mkdir -p .aidoc/review/06_SPEC/<SPEC-id>/ && date +%s > .aidoc/review/06_SPEC/<SPEC-id>/.skill-start.fixer

.aidoc/review/06_SPEC/<SPEC-id>/saga.json が存在する場合は読み取ります。現在の saga の status が FANIN_REDUCED（監査後）または BRANCH_FAILED（以前のフィクサーによるリグレッションの後に再実行）であることを検証します。ほかのステータスの場合は、警告を記録して処理を続行します。

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

レンズによる検証が必要な、ブロッキング指摘（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/06_SPEC/<SPEC-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-spec-autopilot の §3.4 の再開ロジックに従って再開されます。

シンセサイザーの reduce 後

• 次の遷移を追加します。{"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "BRANCH_COMPLETED", "scope": "run"（実行レベル：フィクサーの処理が完了）。
• saga の status: "BRANCH_COMPLETED" を更新します（autopilot の次のフェーズは re-review です）。
• updated_at を更新します。saga.json を書き込みます。

スタンドアロンで呼び出された場合（開始時に saga.json がない場合）

.aidoc/review/06_SPEC/<SPEC-id>/saga.json が存在しない場合（ユーザーが autopilot ループの外部で /aidoc-flow:doc-spec-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 — 構造	ネストされたフォルダーのルール	SPEC を docs/06_SPEC/SPEC-NN_{slug}/ に移動する。ID に合わせてフォルダー名を変更する。移動後に相対リンクを修正する
1 — YAML	不正な YAML	インデントや引用符を修正し、重複キーを削除し、SPEC を解析できるよう型を修正する
2 — ファイル不足	参照先が存在しない	テンプレートからインデックス／参照用プレースホルダーを作成する
3 — リンク	リンク切れ／絶対パス	相対パスを再計算する。絶対パスを相対パスに変換する
4 — ID	無効な ID／旧形式 ID	ドキュメントレベルでハイフン形式の SPEC-NN を適用する。上流要素の参照を TYPE.NN.SS.xxxx に修正する。旧形式の STEP-XXX／IF-XXX／DM-XXX、3桁の SPEC-NNN、数値の型コードを削除する
5 — コンテンツ	プレースホルダー、しきい値	テンプレートの日付を入力する。ハードコードされた数値を @threshold: 参照に置き換える。[TODO]／[TBD] には手動での補完が必要であることを示す
6 — 参照	トレーサビリティ	このレイヤーの required_tags に不足しているタグ（LAYER_REGISTRY.yaml の必須上流契約に基づく — SPEC には @ears @bdd @adr が必要）と、下流の @tdd: TDD-NN を追加する。上流パスを修正する。トレーサビリティマトリクスを更新する
7 — 上流	メタデータ＋ドリフト	deliverable_type／document_type を修正する。上流 ADR／BDD との階層化されたドリフトマージを適用する（下記参照）
8 — スタイル	STY01 禁止表現、STY02／03 の長すぎる文章、FM01 のフロントマター不一致	埋め草を置き換える。指摘された最上級表現を置き換える。1つのセクションに禁止表現が3つ以上ある場合は、その段落を箇条書きにまとめる。フロントマターと Document Control の行を整合させる。STY02／03 — Behavior／Interfaces セクションが長すぎる場合、次の契約境界で分割するか、manual_required とする。基準：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

ID のルール： SPEC はドキュメントレベルでハイフン形式の SPEC-NN によって参照します。ドット区切りの SPEC 要素 ID は使用しません。上流の階層参照には、4セグメントの要素形式 TYPE.NN.SS.xxxx（例：BDD.01.03.8f4c）を使用します。ドキュメントレベルでは @adr: ADR-NN を使用します。

上流ドリフトの階層化（参照先の ADR／BDD との比較）：変更が5%未満 → Tier 1 自動マージ（パッチバンプ）。5～15% → Tier 2 自動マージ＋詳細な変更履歴（マイナーバンプ）。15%超 → Tier 3 現行版をアーカイブし、autopilot 経由で再生成（メジャーバンプ）。 上流から削除されたコンテンツを削除してはいけません。トレーサビリティのために [DEPRECATED] とマークして保持します。結果を .drift_cache.json に記録します。

信頼度の分類

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

信頼度	意味
auto-safe	決定的で、意味上のリスクが低い（リンク／パス、YAML の再インデント、ID 変換、しきい値のタグ付け）
auto-assisted	部分的な仮定を伴うテンプレートの挿入（足場となるセクション／インターフェースのスタブ）
manual-required	ドメインコンテンツを推測できない（インターフェースシグネチャ、動作ロジック、未解決の TODO／TBD）

コンテンツ保持ルール

• 既存のインターフェース定義、データモデルのスキーマ、動作ロジックは削除しないでください。テンプレートブロックを挿入するのは、セクションがない場合、または最小限の構造を満たしていない場合に限ります。
• 同等の YAML キー／見出しは、セクションを重複させずにその場で正規化します。YAML コメントは保持してください。
• 番号を振り直すのは同じセクション内に限ります。相互参照アンカーが壊れる場合は指摘してください。

修正レポートの形式

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

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

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

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

SPEC-NN.F_fix_report_vNNN.md を作成し、以下を記載してください。Summary（問題の件数／修正済み／未対応、作成／変更したファイル、修復した YAML ブロック）・Fixes Applied （コード、問題、修正内容、ファイル、確信度）・Manual-Review Queue・Upstream Drift Summary・Validation After Fix（修正前→修正後のスコア／エラー／警告） ・Cleanup Summary（置き換えられた修正レポートを削除）・Next Steps（doc-spec-audit を再実行）。スコアがしきい値以上になるか、最大反復回数に達するまで繰り返してください。

適応

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

関連リソース

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