seo-fix-apply

seo-fix-apply (writer protocol)

This file is the authoritative protocol; agents/seo-fixer-writer.md carries the in-context summary — keep the two in sync. Edit, Write and Bash are deliberately not pre-approved here: Claude Code's native diff and command prompts must reach the user for every write, and the guard-write / guard-bash hooks run on top of them.

You apply what was already confirmed. You do not decide what to fix, you do not improve a diff you were given, and you never widen the change set.

Inputs

The fix command dispatches you with a JSON envelope:

Read plan.json for the Change records. A change you were not given an id for does not get applied, previewed again, or "helpfully" included.

Protocol (per confirmed change, in order)

1. Git pre-flight. git status --porcelain in PROJECT_ROOT. Dirty tree and no force: true ⇒ do not write: return the finding with its pre-fix status and skipped_dirty_tree in evidence.observed. Never stash, checkout or reset — the user's uncommitted work is theirs.
2. Backup before the first write. Local files: copy to <DATA>/backups/<run-id>/<relative path> (the adapter's apply does this itself; when you write with Edit/Write, do it yourself with mkdir -p + cp before the first edit of that file). Remote resources: the adapter writes before/<change_id>.json. Record nothing in the project.
3. Local diffs — Edit/Write, not the adapter. For target.kind: file changes whose strategy is AUTO (html-head, front-matter, config-file, liquid), apply the previewed diff with Edit (or Write for a new file) so the native diff prompt and guard-write engage. Apply exactly the preview: same insertion point, same text, no reformatting, no extra content, TODO:<field> placeholders preserved verbatim. A JSX/TSX or other non-AUTO strategy arrives as skipped_unready from the adapter and is yours to apply by hand — still exactly as previewed.
4. Remote targets — the adapter CLI, with its ticket. Anything whose target.kind is not file goes through node "<SCRIPTS_DIR>/adapters/<adapter>.mjs" apply --run "<RUN_DIR>" --change <id> --ticket <ticket> --data "<DATA>" --json. The ticket is required and one-shot; a missing or expired one is a real failure, not something to route around. Never emulate an adapter with ad-hoc curl, wp, or shopify commands — the guard-bash hook blocks them and it is right to. If no adapter exists for that target, keep the finding's pre-fix status with skipped_unready plus the manual path from preview/.
5. Idempotent. If the change is already present (the JSON-LD block, the marker comment, the field's value), make no edit: report status: pass with skipped_idempotent in evidence.observed. Re-running must never duplicate or corrupt content.
6. Re-verify. Run verify --run "<RUN_DIR>" --change <id> and the finding's verification.reproduce verbatim. Record the assertion's pass/fail. A stale CDN or page cache is pending_cache in evidence.observed with status: warn — never a claimed pass. A local framework target with no dev server is a source-level pass: say "source verified, re-audit after deploy" rather than claiming the live page changed.
7. Publish — only with publish: true and its own ticket. Publishing is what makes staged work public (shopify theme publish, a Webflow site publish, a HubSpot draft push-live). It is a separate op with a separate confirmation and a separate ticket: node "<SCRIPTS_DIR>/adapters/<adapter>.mjs" publish --run "<RUN_DIR>" --ticket <publish ticket> --data "<DATA>". Without both, leave the change staged and say so in the finding. Never pass --allow-live, --live or -a to the Shopify CLI: that path is blocked and publishing has its own op.
8. Log. One NDJSON line per change in <RUN_DIR>/log.ndjson (change id, files or resource, result). Redact anything credential-shaped; the adapters' own logging already does.
9. On failure, stop widening. A failed change is reported as fail with the error text; do not retry with a different method, a different file, or a broader edit. Rollback is rollback --run "<RUN_DIR>" --change <id> and it needs its own ticket.