Skip to content
SitePilotDocs

Risk-governed mutation state machine

Status

Section titled “Status”

Accepted (Implemented in 0.1.30)

Context

Section titled “Context”

When autonomous AI agents interact with production WordPress instances via the Model Context Protocol (MCP), unstructured, direct mutations introduce critical risks:

  1. Hallucination & Scope Creep: An LLM agent may inadvertently publish unreviewed content, alter commercial product pricing, or activate vulnerable plugins.
  2. Race Conditions & Stale Overwrites: Multiple agents or human editors modifying site state simultaneously can cause clobbered revisions or inconsistent database state.
  3. Irreversible Site Corruption: Page builders like Enfold ALB and Elementor store complex serialized metadata and shortcode trees; malformed shortcode injection can break page rendering permanently.

Decision

Section titled “Decision”

We decided to implement a Risk-Governed Two-Phase Commit State Machine as the foundational contract for all site mutations:

  1. Four Risk Tiers:

    • Tier 0: Read-only operations. Free execution.
    • Tier 1: Safe staging operations (drafts, media imports, sandboxed HTML compilation). Automatic execution within consented OAuth scopes.
    • Tier 2: Sensitive mutations (publishing, bulk updates, menu reassignment, stock/price changes). Requires explicit human approval.
    • Tier 3: High-risk system operations (plugin/theme activation, user role changes, refunds, core updates). Requires fresh WordPress administrator approval.

  2. State Machine Lifecycle:

    [Plan Change] ──► [Awaiting Approval] (if Tier 2/3) ──► [Approved]
                            │                                  │
                            ▼                                  ▼
                        [Rejected]                        [Executing]
                                                              │
                                                              ▼
                                                         [Validating]
                                                              │
                                         ┌────────────────────┴───────────────────┐
                                         ▼                                        ▼
                                    [Completed]                          [Rolled Back / Failed]

  3. Cryptographic Invariants:

    • Every mutation envelope requires an idempotency_key and an expected_version hash of the site state.
    • Approval records are bound to the SHA-256 hash of the planned change set, expiring strictly after 30 minutes.
    • Pre-mutation snapshots are captured to enable deterministic, one-click rollbacks.

Consequences & Trade-offs

Section titled “Consequences & Trade-offs”

Positive

Section titled “Positive”
  • Safety First: Eliminates unintended production site breakage caused by rogue or hallucinating agents.
  • Auditable: Every mutation has an immutable change set record, diff, approval actor ID, and timestamp.
  • Resilient: Optimistic version checking prevents race conditions and stale writes.
  • Reversible: Tier 1 and Tier 2 changes record precise rollback metadata.

Negative

Section titled “Negative”
  • Latency Overhead: High-tier mutations require human intervention in the WordPress Admin dashboard before execution can proceed.
  • State Storage: Requires dedicated database tables for change sets, approvals, and rollback snapshots.

Public normalization derived from product commit 00c30de825b68dc14535f6455e82c927ad256b47, file docs/adr/0001-risk-governed-mutation-state-machine.md. See source-manifest.json for the source digest and declared normalization classes.