# Ruo Supabase Mutation Audit > Convert every proposed RUO Peptides/PeptraLabs Supabase mutation into a validated Hermes-main/default instruction set while keeping Codex read-only. Use after ruo-supabase-guardrails for data, schema/config/RLS/storage/RPC, dashboard sync, runtime access, or migration changes. ANTI-PATTERN: Never treat HANDOFF_READY as permission for Codex to execute a Supabase mutation. - Skill: `cryptopafi/ruo-supabase-mutation-audit` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add cryptopafi/ruo-supabase-mutation-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/cryptopafi/ruo-supabase-mutation-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: cryptopafi (https://skillmd.com/u/cryptopafi) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/cryptopafi/ruo-supabase-mutation-audit --- # RUO Supabase Mutation Handoff Audit Use this skill automatically whenever a RUO Peptides / PeptraLabs Supabase mutation is proposed. It converts the requested change into a validated instruction set for Hermes, the sole Supabase mutation owner. This skill is a pre-handoff audit layer. It never authorizes Codex, Claude Code, Genie, or another non-Hermes agent to execute a mutation. Always apply `ruo-supabase-guardrails` first; if the two skills conflict, the stricter read-only rule wins. ## Enforcement Boundary This skill enforces behavior at the agent workflow and skill-selection layer. It does not revoke credentials or create a database trigger. Technical separation requires non-Hermes runtimes to lack write-capable credentials and to use only read-only or Hermes-mediated access. ## Quick Rule A mutation request can produce only one of these preparing-agent outcomes: - `READ_ONLY_NO_HANDOFF_REQUIRED` - `DRAFT_AWAITING_PAFI_APPROVAL` - `HANDOFF_BLOCKED` - `HANDOFF_READY` `HANDOFF_READY` means the instruction set is complete enough to deliver to Hermes. It does not authorize the preparing agent to execute anything. ## Mutation Surfaces Classify every request: | Surface | Examples | Required review | |---|---|---| | `data_row` | insert/update/upsert/delete rows | exact table, IDs/filter, values, expected count, read-back | | `financial_stock` | payments, expenses, treasury, restocks, stock movements, SKU state, customer credit | financial audit controller, stock/account invariants, stale-output checks | | `schema_config` | columns, constraints, triggers, migrations, settings contracts | compatibility, backfill, rollback, regression plan | | `rls_policy` | RLS, policies, grants, service-role exposure | least privilege, read/write blast radius, regression plan | | `storage` | bucket/object upload/delete, visibility rules | object scope, retention, public/private exposure, rollback | | `rpc_function` | RPC, Edge Function, cron, trigger code | input validation, idempotency, timeout/failure behavior, dry-run | | `runtime_secret_config` | Supabase URLs/keys and agent/runtime access | no secret values, ownership, least privilege, restart/read-back | | `dashboard_sync` | dashboard state written back to Supabase | source snapshot, generated diff, no silent mutation | Read-only selects, exports, checksums, diffs, and schema inspection return `READ_ONLY_NO_HANDOFF_REQUIRED`. ## Hermes Supabase Mutation Instruction Set The packet is a typed inter-agent contract: ```text contract_version: hermes-supabase-instruction.v1 instruction_set_id: stable unique reference execution_owner: Hermes-main executor: hermes executor_profile: default codex_direct_write_forbidden: true approval_explicit: true approval_source: exact chat/thread/channel/message or approval artifact approval_timestamp: ISO timestamp operation: insert/update/upsert/delete/migration/config/storage/rpc/rls/runtime_config/dashboard_sync surface: one mutation surface from the table above objects: exact tables, rows, buckets, policies, functions, config objects, or artifacts scope: exact IDs or precise filters expected_count: exact number of rows/objects expected to change payload_summary: redacted business description mutation_steps: ordered operations containing object, operation, scope, and intended values preflight_diff: observed current state versus intended state required_markers: Pafi-authorized plus Hermes owner attribution idempotency: approval ID, unique reference, checksum, or duplicate-detection rule rollback: precise undo or compensating plan domain_invariants: applicable money/stock/account/config/compliance checks post_write_verification: exact read-back queries/checks and expected result artifact_sync: required follow-up surfaces or explicit no-sync reason return_contract: structured execution evidence Hermes must return ``` Packets must not contain credentials, secret values, or unnecessary raw PII. Secret references are owner-managed handles, never values. If Pafi has not approved the exact business mutation, prepare a non-executable draft with `approval_explicit: false` and return `DRAFT_AWAITING_PAFI_APPROVAL`. Do not send it to Hermes as executable. ## Mandatory Executor Checks The deterministic validator must block unless: - `contract_version` is `hermes-supabase-instruction.v1`; - `execution_owner` is `Hermes-main` and `executor_profile` is `default`; - `executor` is exactly `hermes`; - `codex_direct_write_forbidden` is exactly `true`; - exact Pafi approval exists for the requested mutation; - scope and `expected_count` are precise; - `mutation_steps` are non-empty and target only the declared objects; - rollback, idempotency, invariants, read-back, and return evidence are specified; and - the packet contains no likely secret value. Any `actor_path` or marker that says Codex/API/Pafi agent will execute is a policy violation. The validator blocks all known legacy direct-API actor paths, preparing-agent performer markers, and API-only approval markers. ## Audit Workflow 1. **Classify** the request as read-only or mutation. 2. **Load guardrails** and confirm the preparing runtime is read-only. 3. **Preflight read-only state** using the narrowest technically read-only path. If unavailable, instruct Hermes to perform the preflight. 4. **Apply domain controls** such as `ruo-financial-audit-controller` for money, stock, balance, cost, or published-audit changes. 5. **Assemble the instruction set** without secrets or unnecessary PII. 6. **Run deterministic validation**: ```bash python3 scripts/validate_mutation_packet.py packet.json ``` 7. **Block or draft** missing approval, unclear scope, contradictory source authority, missing invariants, or unsafe credentials. 8. **Deliver only `HANDOFF_READY` packets to Hermes** through the configured cross-agent channel. If Hermes is unavailable, return a ready-to-send packet and report the delivery failure. 9. **Wait for Hermes evidence**. Do not infer success from delivery or acceptance. 10. **Independently verify read-only** when possible. A mismatch creates a new Hermes instruction set; the preparing agent never repairs it directly. ## Hermes Return Contract Hermes must return a structured result containing: ```text instruction_set_id execution_owner: Hermes-main executor: hermes executor_profile: default status: executed_verified/executed_rolled_back/blocked/failed started_at completed_at affected_objects affected_ids_or_filters affected_count redacted_before_after audit_actor_and_markers idempotency_result post_write_readback domain_invariant_results rollback_status artifact_sync_status exceptions ``` The preparing agent may report `HERMES_EXECUTION_REPORTED` only from this evidence. It may report `INDEPENDENTLY_VERIFIED` only after its own read-only check. ## Domain Constraints - Airtable remains frozen legacy evidence; new RUO operational state belongs in Supabase only through Hermes. - Account and finance instructions must use the RUO account-ledger contract and full propagation matrix. - Stock instructions must respect location ownership: Bucharest/main uses `skus.stock_qty`; Ibiza/other locations use `location_stock.qty`; `v_stock_by_location` composes both. - Financial, stock, SKU, participant balance, customer credit, restock, pricing-control, batch/COA, and proof/reference changes require the financial audit controller or equivalent invariant checks. - Runtime/config instructions must preserve read-only credentials for every non-Hermes agent. ## Output Contract For read-only: ```text Mode: READ_ONLY_NO_HANDOFF_REQUIRED Reason: ... Supabase writes performed: none ``` For an unapproved draft: ```text Mode: DRAFT_AWAITING_PAFI_APPROVAL Instruction set: ... Hermes delivery: not executable Supabase writes performed: none ``` For a blocked handoff: ```text Mode: HANDOFF_BLOCKED Surface: ... Missing/failed checks: ... Supabase writes performed: none ``` For a validated handoff: ```text Mode: HANDOFF_READY Executor: Hermes Instruction set ID: ... Approval/surface/objects/scope: ... Expected diff: ... Rollback/idempotency/invariants: ... Required Hermes return evidence: ... Supabase writes performed by preparing agent: none ``` For Hermes evidence: ```text Mode: HERMES_EXECUTION_REPORTED Hermes status/read-back/invariants: ... Independent verification: verified/not_run/exception Residual exceptions: ... Supabase writes performed by preparing agent: none ``` ## Bundled Helper `scripts/validate_mutation_packet.py` validates instruction-set structure only. It never contacts Supabase, dispatches Hermes, or authorizes execution. Expected helper statuses: - `READ_ONLY_NO_HANDOFF_REQUIRED` - `DRAFT_AWAITING_PAFI_APPROVAL` - `HANDOFF_READY` - `BLOCKED` ## Test Cases 1. Read-only schema inspection returns `READ_ONLY_NO_HANDOFF_REQUIRED`; a packet labeled read-only that also contains mutation intent returns `BLOCKED`. 2. A complete packet with `executor=hermes` returns `HANDOFF_READY`. 3. A complete packet with `executor=codex`, a legacy API-only actor path, or `codex_direct_write_forbidden=false` returns `BLOCKED`. 4. A packet without exact approval returns `DRAFT_AWAITING_PAFI_APPROVAL` only when all non-approval fields are complete; otherwise it is `BLOCKED`. 5. A financial/stock packet without money/stock/account invariants returns `BLOCKED`. 6. A schema/config packet without compatibility and rollback checks returns `BLOCKED`. ## When to Use vs Alternatives - **This skill**: prepare and validate a Hermes handoff for any RUO Supabase mutation. - **ruo-supabase-guardrails**: always use first for the read-only credential and executor boundary. - **ruo-financial-audit-controller**: use for money, stock, balances, costs, and published audit propagation. - **audit-pro**: use when changing this skill, its procedure, or its validator; not for every mutation request.