Onsite Apply

Apply approved changes (the gate lives here)

1. Read profile + env file. Poll the channel first if telegram, via core.approval.process_telegram_decisions(root, token, chat_id) - it persists the poll offset and tolerates unknown/stale ids without raising.

2. List approved onpage-fix items. For each: a. require_approved(path) - this raises on anything not approved. Never catch that error to proceed; report it and skip. b. snapshot() the post (title + meta + content if the proposal touches it) -> save to outcomes/<item-id>-rollback.json in the brain repo. c. Apply via the CMS adapter (onsite.cms.adapter_for; wordpress or git-static per cms.type - the git-static branch below replaces steps b-g): update_seo_meta / update_post per the proposal body. (update_rankmath remains as the WordPress adapter's alias for update_seo_meta.) d. Verify: get_rendered_head(target_url) - assert the new title/description appear in the rendered head. On mismatch: rollback() immediately, then PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -m core status <item-path> failed --actor agent, append a signal "apply-verify failed", and alert. Never leave the item approved. e. PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -m core status <item-path> applied --actor agent; write an outcome record outcomes/<item-id>.md: what changed, when, rollback file, measurement due dates (+7d, +28d). Because the verify just succeeded, also write the re-verification window into the record, exactly these keys (see site-repo-contract.md):

   reverify:
     due: <UTC now+1h>     # first scheduled re-check
     until: <UTC now+48h>  # window end; drift watch owns the horizon after
   

   hoo-daily re-checks the live values between due and until so an external revert (a bulk plugin restore, a theme update) surfaces within hours, not at the next audit. f. On a successful verify, refresh the drift baseline for this page (onsite.drift.snapshot_pages on this post id, merged into the stored onsite.drift.baseline_path entry, then save_baseline) so the change we just made intentionally is never flagged as drift by the next hoo-daily run. g. IndexNow: when site-profile.yaml has indexnow: {enabled: true, key: ...} (additive key), call hoo.indexnow.submit(host, key, [target_url]) after the successful verify and record the returned status in the outcome record (indexnow: {status: N, submitted: 1}). A non-200 is recorded, never retried in-run, and never fails the apply. Skipped in dry-run - nothing changed, nothing to submit.

3. Commit + push the brain repo if git. Summarize: applied / skipped / failed.

4. Outcome summary - the approver always hears what happened. Compose ONE message for the whole run and deliver it through the configured approval channel (telegram: one sendMessage over the same transport send_item uses; slack/email: one post/send; in-session: print the summary; pr-merge: no live channel mid-cycle - append the summary to the run report and outcome records instead). Never send per-item messages. Content, one line per item:

   • applied and verified: item id + what changed
   • partially-applied: item id + the exact human step from the status note - the approver must know what is waiting on them
   • failed / rolled back: item id + the reason Silent success is a bug: whoever said yes hears the result, whether it landed, half-landed, or failed. A run that touched nothing sends nothing.

Git-static sites (cms.type git-static)

The adapter is chosen by cms.type (onsite.cms.adapter_for). When it is git-static, the write target is a local clone of the site repo (cms.repo_root) and the pull request is the delivery mechanism. The gate does not move: step 2a's require_approved runs unchanged, BEFORE any file is written to any branch. The adapter never runs git; this skill runs every git/gh command below.

0. pr-merge channel only, before the gate: proposals on such sites arrive as PRs against the brain repo, and the human merge IS the approval. Detect newly merged proposal PRs (gh pr view <n> --json state,mergedBy) and record each decision the merge represents: PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -m core approve <item-path> --actor <merger> --channel pr-merge. The merge commit is GitHub's durable record; the CLI entry is the one the gates check. A closed-unmerged proposal PR is a rejection - record it with core reject the same way. (This mirrors step 1's telegram poll.) On every other channel the item was approved before this skill ran, and the site PR below is created only AFTER that approval.
1. Gate: require_approved(path) - unchanged, never caught to proceed.
2. Freshen the clone (git pull on the default branch in cms.repo_root).
3. snapshot() each target file (the snapshot stores the file's full text) -> outcomes/<item-id>-rollback.json in the brain repo.
4. Apply via the adapter: update_seo_meta / update_post per the proposal body - frontmatter and body edits in the working tree only.
5. Deliver as a PR - run: git checkout -b organic-os/<item-id>, git add the changed files, git commit, git push -u origin organic-os/<item-id>, then gh pr create --title "<item title>" --body "<the proposal text>".
6. Honest status: the adapter's capabilities() declares needs_human: ["merge-pr", "deploy"], so the item does NOT become applied here. Set PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -m core status <item-path> partially-applied --actor agent --note "PR <url> open - a human must merge; the site then deploys itself". The queue shows it as a PARTIAL row until the merge. No publish happens without a human.
7. Merge detection, next run: gh pr view <n> --json state,mergedBy. Merged -> core status <item-path> applied --actor <merger>; write the outcome record (what changed, PR url, who merged and when, measurement due dates +7d, +28d). On a pr-merge-channel site this merge doubles as the human sign-off; the merge commit and the outcome record carry it. Closed unmerged -> a human said no: core status <item-path> failed --actor agent --note "PR closed unmerged" and delete the branch; nothing reached the default branch, so the rollback file needs no replay.
8. Verify, honestly: rendered_head_verify is False for this adapter - there is no rendered head to assert at apply time, and step 2d's verify does not run. If the profile has cms.deploy_url, fetch the live page after merge detection and record the result in the outcome as a best-effort post-deploy check, labeled exactly that - it never counts as the WordPress-grade verify. IndexNow (step 2g) also moves to after merge detection: only a merged and deployed change has a live URL to submit. Skip the drift-baseline refresh (step 2f); the drift watch is WordPress-only. No reverify keys on this path either: they attach only to a rendered-head-verified apply (step 2e), and the best-effort post-deploy check is not that verify.

Dry-run with git-static: the same rules as below - the gate still runs first, the adapter logs every intended write in dry_run_log, and with nothing written to the clone there is nothing to commit: no branch, no PR. The outcome record, marked dry-run, lists the log.

Dry-run mode

When site-profile.yaml has onsite: {dry_run: true} (additive key, schema stays 1), construct the CMS adapter with dry_run=True (adapter_for(profile, ..., dry_run=True)) and run the full flow above unchanged - require_approved is still enforced BEFORE the dry-run write, so a dry run rehearses the real path, gate included, not a shortcut around it. Nothing reaches the site: every mutating call lands in the adapter's dry_run_log instead of the session, and reads (snapshot, get_rendered_head) behave normally. Skip step 2d's verify assertion (a write that never happened cannot appear in the rendered head) and do NOT set the item to applied - it stays approved so a real apply can follow. Write the outcome record marked dry-run: true, listing every entry from the adapter's dry_run_log - each write that would have happened, with method, post id, and fields. Skip the drift-baseline refresh (2f) and the reverify keys; the page did not change, so there is nothing to re-check.

Redirect fixes (action type: redirect)

Some approved onpage-fix proposals prescribe a redirect - a moved target behind broken internal links (skills/onsite-audit's link-health dimension), or a cannibalization consolidation (skills/hoo-weekly). A plain link REWRITE is not this action type: it edits the source page's content and rides the normal update_post path above, gate, snapshot, verify and all.

Redirects are a CMS capability, not a universal write. Consult the adapter's capabilities()['redirects'] mode FIRST and never fake a write path the adapter does not declare:

• needs-plugin (the WordPress adapter): core WordPress has no redirect REST surface. Probe the known plugin surfaces at run time with the connected role - Rank Math's redirections module, the Redirection plugin's REST route. A surface is writable: create the 301, record its id in the outcome record (rollback for a redirect is deleting it), then verify by fetching the old URL and asserting a 301 status pointing at the new target. A failed verify deletes the redirect and marks the item failed, per the hard rules. No writable surface (module absent, or it needs an admin role the connected user lacks): set the item partially-applied with the exact manual step, e.g. "add a 301 from /old-path to /new-path in the SEO plugin's redirections screen (Rank Math -> Redirections)". Never faked as done.
• config-file (the git-static adapter): write the platform's redirect file - the profile's additive cms.redirect_file key names it (_redirects, netlify.toml, or vercel.json; see site-repo-contract.md). The write is ADDITIVE: append or merge the one new rule, never a rewrite of existing rules. Everything else follows the git-static flow above unchanged: gate first, snapshot() of the redirect file, branch, PR, partially-applied until the human merge, best-effort post-deploy check of the old URL when cms.deploy_url is set. No redirect_file key in the profile: partially-applied naming the step ("set cms.redirect_file in site-profile.yaml, or add the redirect to the platform config by hand").
• native: reserved for an adapter whose backend writes redirects first-class through the adapter itself; no shipped adapter declares it today.

Image and alt-text fixes (action type: image-fix)

Approved image-fix proposals carry per-image items (see the image-fix section in skills/onsite-propose): missing alt text with the proposed alt, and missing in-content images referencing a ce-image brief. The gate is unchanged - require_approved runs before any write, per item. Consult the adapter's capabilities()['media_alt'] mode FIRST, the same honesty rule as redirects:

• True (the WordPress adapter): before writing, record each target image's current alt (get_media(post_id)) in the item's rollback file - rollback for an alt fix is rewriting the old value (empty included). Then update_media_alt(media_id, alt_text) per item. An image get_media reports with media_id: None has no attachment to write to - its alt is hard-coded in the post content, so fix it via update_post on the content (snapshot and verify as usual); if the markup is theme- or builder-owned and update_post cannot reach it, the item ends partially-applied naming the step ("set the alt on in the theme/page builder").
• "in-content" (the git-static adapter): update_media_alt rewrites the alt inside the content file - media_id <post-ref>::<src> for a body image, <post-ref>::frontmatter for the featured image's alt: field. The change rides the normal git-static flow above unchanged: gate first, snapshot() of the file, branch, PR, partially-applied until the human merge.
• Missing in-content image items PLACE, never generate: apply inserts a reference to an image file that already exists (the ce-image output named in the proposal, or a human-produced asset at that path), with the proposal's alt text. Nothing in the apply path generates an image. No file at the named path -> partially-applied with the step named ("produce the image per -image-brief.md, then re-run apply").

Verify step reads the result back: after the writes, get_media on the target must show the new alt (and the placed image, for insertion items); on WordPress also confirm via the rendered content where available. A mismatch rolls back from the recorded prior values and marks the item failed, per the hard rules. Anything the adapter cannot do ends partially-applied with the named human step - never faked as done.

Partial application

When some changes in a proposal succeed and others hit a permission or capability wall (a step needs a WordPress role the connected user does not have), do NOT pick between "applied" and "failed" - both would lie. Set the honest state via the contract CLI, with a note naming exactly what a human must finish:

PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -m core status <item-path> \
  partially-applied --actor agent --note "<exactly what a human must finish>"

The outcome record lists done vs pending: every change that landed (with its verify result) and every step still waiting on a human, each named precisely. Once the human finishes the pending steps, the item moves partially-applied -> applied via the CLI; if the partial work is rolled back instead, partially-applied -> failed.

HARD RULES: no snapshot -> no write. Verify after every write. A failed verify means rollback, never retry-and-hope. Never edit brain frontmatter directly. The contract CLI is the only write path for status and approvals.