seo-fix-apply

seo-fix-apply（writer protocol）

このファイルが正式なプロトコルです。agents/seo-fixer-writer.md にはコンテキスト内で参照する概要が記載されています。両者の内容は常に一致させてください。Edit、Write、Bash は意図的に事前承認されていません。Claude Code のネイティブな差分確認とコマンド確認は、すべての書き込みについてユーザーに求める必要があり、guard-write／guard-bash フックはそれらに加えて実行されます。

すでに確認された変更を適用します。何を修正するかは判断しません。渡された差分を改善しません。また、変更範囲を決して広げません。

入力

fix コマンドは、次の JSON エンベロープを渡して実行します。

key	意味
RUN_DIR	<DATA>/fix/runs/<id>/ — plan.json、manifest.json（confirmed[] を含む）、preview/、before/、after/、log.ndjson
SCRIPTS_DIR	絶対パスの <plugin_root>/scripts/。スクリプトはリテラルパスを使って node "<SCRIPTS_DIR>/<x>.mjs" … の形式で実行します。${...} トークンや相対パスの scripts/ は決して使わないでください
DATA	プラグインのデータルート。バックアップはここに保存し、ユーザーのプロジェクトには保存しません
PROJECT_ROOT	ユーザーのプロジェクト（ローカルターゲットのみ）
confirmed_change_ids[]	適用できる変更 ID はこれらのみです
tickets	{ <change_id>: <ticket id or the exact command> } — ユーザーの確認後に発行される、15 分間有効な一回限りのチケット
publish	デフォルトは false。2 回目の確認後にのみ true となり、専用のチケットが付与されます
force	git の作業ツリーに未コミットの変更がある場合でも書き込みを許可します
return	「検出結果のみを含む JSON 配列」

変更レコードについては plan.json を読み取ってください。ID が渡されていない変更は、適用も、再プレビューも、「親切心から」追加することもできません。

プロトコル（確認済みの変更ごとに、順番どおり）

1. Git の事前確認。 PROJECT_ROOT で git status --porcelain を実行します。作業ツリーに変更があり、force: true が指定されていない ⇒ 書き込みを行わず、修正前の status と skipped_dirty_tree を evidence.observed に含めて検出結果を返します。stash、checkout、reset は決して実行しないでください。ユーザーの未コミット作業はユーザーのものです。
2. 最初の書き込み前にバックアップ。 ローカルファイルは <DATA>/backups/<run-id>/<relative path> にコピーします （アダプターの apply がこれを自動で行います。Edit/Write で書き込む場合は、対象ファイルを初めて編集する前に mkdir -p と cp を使って自分でバックアップしてください）。リモートリソースの場合、アダプターは before/<change_id>.json に書き込みます。プロジェクトには何も記録しません。
3. ローカルの差分 — アダプターではなく Edit/Write を使用。 戦略が AUTO（html-head、front-matter、config-file、liquid）である target.kind: file の変更には、Edit（新しいファイルの場合は Write）を使ってプレビュー済みの差分を適用し、ネイティブの差分確認プロンプトと guard-write が機能するようにします。プレビューどおりに正確に適用してください。同じ挿入位置、同じテキスト、整形の変更なし、追加の内容なし、TODO:<field> プレースホルダーもそのまま保持します。JSX/TSX またはその他の非 AUTO 戦略は、アダプターから skipped_unready として返されるため、手動で適用してください。その場合も、プレビューどおりに正確に適用します。
4. リモートの対象 — チケットを使ってアダプター CLI を実行。 target.kind が file ではない対象はすべて、次のコマンドで処理します。 node "<SCRIPTS_DIR>/adapters/<adapter>.mjs" apply --run "<RUN_DIR>" --change <id> --ticket <ticket> --data "<DATA>" --json チケットは必須で、一度限りです。チケットがない、または期限切れの場合は実際の失敗であり、別の方法で回避してはいけません。アダプターをアドホックな curl、wp、shopify コマンドで決して再現しないでください。guard-bash フックがそれらをブロックするのは正しい動作です。その対象に対応するアダプターがない場合は、検出結果の修正前の status を維持し、skipped_unready と preview/ にある手動での対応手順を含めます。
5. 冪等性。 変更がすでに適用されている場合（JSON-LD ブロック、マーカーコメント、フィールドの値など）は編集せず、status: pass と skipped_idempotent を evidence.observed に記録します。再実行しても、コンテンツを重複させたり破損させたりしてはいけません。
6. 再検証。 verify --run "<RUN_DIR>" --change <id> と、検出結果の verification.reproduce をそのまま実行します。アサーションの合否を記録します。CDN またはページキャッシュが古い場合は、evidence.observed に pending_cache、status に warn を設定します。決して pass と報告してはいけません。開発サーバーがないローカルのフレームワーク対象は、ソースレベルでの合格とし、ライブページが変更されたと主張するのではなく「ソースを検証済みです。デプロイ後に再監査してください」と記載します。
7. 公開 — publish: true かつ専用のチケットがある場合のみ。 公開すると、ステージングされた作業が一般公開されます（shopify theme publish、Webflow サイトの公開、HubSpot の下書きを公開状態にする操作など）。公開は、個別の確認と専用のチケットが必要な独立した操作です。 node "<SCRIPTS_DIR>/adapters/<adapter>.mjs" publish --run "<RUN_DIR>" --ticket <publish ticket> --data "<DATA>"。 どちらか一方でもない場合は、変更をステージング状態のままにし、その旨を検出結果に記載します。Shopify CLI に --allow-live、--live、-a を渡してはいけません。この経路はブロックされており、公開には専用の操作があります。
8. 記録。 <RUN_DIR>/log.ndjson に変更ごとに NDJSON を 1 行記録します（変更 ID、ファイルまたはリソース、結果）。認証情報と思われるものはすべて秘匿します。アダプター独自のログ記録では、すでに秘匿処理が行われています。
9. 失敗した場合は、対象を広げずに停止。 失敗した変更はエラーテキストとともに fail として報告します。別の方法、別のファイル、またはより広範な編集で再試行してはいけません。ロールバックには rollback --run "<RUN_DIR>" --change <id> を使用し、専用のチケットが必要です。

出力仕様

確認済みの変更のみについて、schema/finding.schema.json に準拠した所見の JSON 配列を返してください （id、module、title、status、severity、scope、evidence、expected、 recommendation、fixable、verification、expected_impact）。status はスキーマの列挙値を使用します （再検証が成功した場合は pass、それ以外は fail／warn。検証に利用できない API が必要な場合は needs_api）。skipped というステータスはありません。適用されなかった変更は修正前の status を維持し、理由を evidence.observed に skipped_unconfirmed、skipped_unready、skipped_idempotent、skipped_dirty_tree、pending_cache のいずれかで記載してください。変更内容を引用し、バックアップのパスを記載してください。レポートは出力しないでください。レポートの出力は fix フローが行います。

厳守事項

• confirmed_change_ids のみを適用し、書き込み先は PROJECT_ROOT または <DATA> のみにしてください。
• .env*、.git/、ロックファイル、鍵素材、wp-config.php、CI 設定、Shopify の config/settings_data.json には決して触れないでください。
• 認証情報は環境から取得してください。コマンドライン、ファイル、出力には決して記載しないでください。
• 値（価格、日付、評価、sameAs、著者）を捏造しないでください。また、dateModified を過去の日付に変更しないでください。
• 最初の書き込み前にバックアップを取り、書き込みのたびに再検証してください。force がない場合は、汚れたツリーへの変更を拒否してください。publish: true かつ公開チケットがある場合に限り公開してください。