=== Workflow Outcome Watchdog ===
Contributors: pixeldustinteractive
Tags: automation, monitoring, cron, workflow, woocommerce
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Verify that scheduled WordPress workflows produced the expected business outcome, then alert or request a retry when they did not.

== Description ==

Workflow Outcome Watchdog monitors measurable results instead of trusting that a scheduled hook, importer, sender, or publishing routine completed successfully.

Create rules such as:

* At least 20 posts published during each 60-minute window.
* At least two successful WordPress mail handoffs per hour.
* At least five WooCommerce orders created in selected statuses.
* At least 10 successful Action Scheduler executions for a specific hook.
* At least one completion action fired by a custom plugin.
* At least 30 outcomes reported by an external automation.

When a completed window misses its target, the plugin can:

* Send an email alert.
* Send a JSON webhook alert.
* Fire a namespaced WordPress retry action.
* POST to a retry webhook.
* Send a recovery notification after a later window succeeds.
* Keep event and check history for auditing.

Built-in outcome sources:

1. Published posts and public custom post types.
2. Successful `wp_mail()` handoffs with optional in-memory recipient and subject filters.
3. WooCommerce orders queried through `wc_get_orders()` for HPOS compatibility.
4. Successful Action Scheduler executions filtered by hook and/or group.
5. A specific WordPress action hook. Hook arguments are not stored.
6. Custom outcomes recorded through PHP, WP-CLI, or a token-authenticated REST heartbeat.

The evaluation engine runs every five minutes, uses a site-wide overlap lock, and evaluates fixed windows that begin when a monitor is saved or resumed. A configurable grace period allows late-running work to finish.

This MVP runs entirely inside WordPress and does not require an external account.

Version 0.2.0 adds a guided administration experience with contextual help tooltips on the dashboard, monitor editor, activity history, heartbeat credentials, and settings. Each screen also includes plain-language instructions at the bottom, source-selection guidance, common recipes, status explanations, and a safe testing procedure.

= Important limitations =

Because the plugin runs inside WordPress, it cannot send alerts while the entire site, server, database, DNS, or PHP runtime is unavailable. Use an external uptime monitor for complete outage detection.

WP-Cron is request-driven and can run late on low-traffic sites. Critical monitoring should use a real server scheduler to request `wp-cron.php` every five minutes.

A successful `wp_mail()` event confirms that WordPress handed the message to its mailer without an immediate error. It does not prove recipient delivery.

== Installation ==

1. Upload the plugin ZIP through Plugins > Add New > Upload Plugin.
2. Activate Workflow Outcome Watchdog.
3. Open Outcome Watchdog > Add Monitor.
4. Define the expected result, fixed window, grace period, and source.
5. Configure email, webhook, and optional retry behavior.
6. Confirm scheduler health under Outcome Watchdog > Settings.

The first conclusive automatic check occurs after one complete window plus its grace period. Saving or resuming a monitor begins a fresh window.

== Frequently Asked Questions ==

= Does this merely prove that a cron hook fired? =

No. The strongest source types inspect or receive the result itself, such as published posts, orders, or a completion heartbeat. A WordPress hook monitor proves only that the configured completion hook fired, so integrations should fire that hook after committing the real outcome.

= What counts as an email? =

One successful WordPress `wp_mail()` call counts as one outcome, regardless of the number of recipients. Watchdog alert emails do not count toward mail monitors.

= Does it store email addresses or message contents? =

Captured mail events do not store recipients, subjects, bodies, or headers. Optional recipient and subject filters are saved as monitor configuration because they are required to select which calls count.

= How do custom integrations report success? =

Use `workflow_outcome_watchdog_record()`, fire the `wout_record_outcome` action, run `wp outcome-watchdog record`, or POST to the token-authenticated heartbeat endpoint shown on the monitor screen.

= How does a WordPress retry work? =

Enter a retry key such as `outreach_sender`. The plugin fires `wout_retry_outreach_sender` and passes the monitor ID and monitor object. The listening integration must implement safe, idempotent retry behavior.

= Is WooCommerce HPOS supported? =

The plugin uses the public `wc_get_orders()` API rather than querying WooCommerce order tables directly.

= Will it detect a completely down website? =

No. Software inside a failed site cannot report its own failure. Use an external uptime service alongside this plugin.

== Privacy ==

The plugin stores monitor configuration, aggregate outcome events, check results, and timestamps in custom WordPress database tables. Mail event records exclude recipients, subjects, bodies, and headers. Custom integration developers control optional messages and metadata and should not submit personal or secret information.

Alert emails and webhooks transmit monitor names, counts, statuses, timestamps, site URL, and failure details to destinations configured by an administrator.

Heartbeat tokens are displayed once and stored only as HMAC hashes.

== Changelog ==

= 1.1.1 =
* Fixed Windows-built release archives so WordPress can extract and activate them on Linux hosts.
* Added a release check that rejects non-portable ZIP entry paths.
* Added real WordPress activation tests for the minimum and current supported environments.

= 1.1.0 =
* Added a deliberate test alert for each saved monitor.
* Reported email and webhook results separately without claiming inbox delivery.
* Kept test alerts out of monitor status and activity history.
* Used successful tests to clear current delivery warnings and failed tests to update them.
* Clarified that saved destinations are tested and unsaved alert edits must be saved first.

= 1.0.0 =
* Rewrote alert subjects and bodies in calm, outcome-oriented language.
* Displayed observation windows in the WordPress site timezone.
* Recorded email and webhook delivery problems in result history.
* Added a persistent dashboard warning for affected monitors.
* Cleared delivery warnings after all configured alert channels recover.

= 0.9.0 =
* Replaced raw retention days and repeat-alert hours with human presets.
* Preserved exact custom settings through progressive disclosure.
* Added an explicit confirmation before enabling uninstall data deletion.
* Kept the irreversible warning visible whenever deletion is enabled.
* Clarified that default alert changes do not rewrite existing monitors.

= 0.8.0 =
* Added a calm first-run state while the initial automatic check is scheduled.
* Separated automatic-check health from monitored workflow outcomes.
* Distinguished missing schedules from overdue checks.
* Added the first or latest completed check time directly to system feedback.
* Renamed schedule recovery controls and confirmations around automatic checks.

= 0.7.0 =
* Made row-action menus viewport-aware so they are never clipped by the table.
* Added monitor-specific accessible action labels and Escape focus restoration.
* Replaced the phone-width monitor table with readable, labeled cards.
* Preserved Edit as the first action and grouped secondary actions consistently on mobile.
* Aligned dashboard headings around monitoring details, expected results, and latest results.

= 0.6.0 =
* Made dashboard timing human-readable and removed internal monitor IDs.
* Renamed ambiguous statuses to Waiting, Missed target, and Check error.
* Removed the unavailable manual-check action from paused monitors.
* Added specific pause, resume, busy, and paused-check feedback.
* Replaced raw event-source codes with readable labels.

= 0.5.0 =
* Replaced technical evidence-source names with shorter, task-oriented labels.
* Added common interval and grace-period presets while preserving custom minute values.
* Made save and manual-check notices describe the actual result.
* Added a direct review path from failed and errored activity entries.
* Added the monitor name to irreversible deletion confirmation.

= 0.4.0 =
* Simplified the dashboard around one primary action and immediately understandable status.
* Moved webhook, recovery, retry, history, and scheduler details behind progressive disclosure.
* Clarified monitor setup, activity, empty states, confirmations, and scheduler feedback.
* Preserved observation windows when only alert settings change.
* Improved keyboard behavior, focus, spacing, and responsive form layout.

= 0.3.0 =
* Added scheduler self-repair, an overdue warning, and a manual repair action.
* Added heartbeat idempotency keys so safe client retries do not double-count.
* Added idempotency keys to retry webhooks and separated retry cadence from alert cadence.
* Added automated product regression checks and a Windows release builder.

= 0.2.0 =
* Added accessible contextual help tooltips throughout all administration screens.
* Added a four-step onboarding overview, common monitor recipes, and status explanations.
* Added detailed bottom-of-screen instructions to Monitors, Add/Edit Monitor, Activity, and Settings.
* Added source-strength labels, caveats, configuration guidance, and a safe test procedure.
* Added a full plain-language user guide.

= 0.1.0 =
* Initial MVP.
* Added six outcome sources: published content, WordPress mail, WooCommerce orders, Action Scheduler completions, WordPress action hooks, and secure custom heartbeats.
* Added fixed windows, grace periods, overlap protection, failure and recovery alerts, retry requests, history retention, Site Health integration, REST reporting, and WP-CLI commands.
