Update skills for deletion protection and deploy inspection

01-readonly-inventory/SKILL.md

@@ -22,11 +22,13 @@ Allowed by default:
 - Read Postgres roles and non-secret role metadata.
 - Read backup schedules and restore metadata.
 - Read branch schema.
+- Read database and branch deletion-protection state.
+- Inspect deploy request queue, operation, and deployment details.
 - Inspect live connection/session metadata with the Connections CLI view.
 - Inspect repository files for frameworks, ORMs, migrations, SQL tagging, and connection config.
 - Inspect Terraform or other infrastructure-as-code definitions for
-  PlanetScale roles, backups, backup policies, Postgres parameters, and
-  supported extensions.
+  PlanetScale roles, backups, backup policies, deletion protection, Postgres
+  parameters, and supported extensions.
 
 Not allowed without explicit approval:
 
@@ -74,6 +76,11 @@ Verified interface notes (recheck against the docs when a command fails):
   returns generated report metadata, not live patterns.
 - Traffic budgets: `.../branches/{branch}/traffic/budgets`. The CLI has no
   `pscale traffic-control budget list`; use the API for inventory.
+- Vitess deploy request inspection: `pscale deploy-request queue <database>`,
+  `pscale deploy-request operations <database> <number>`, and
+  `pscale deploy-request deployment <database> <number>` are read-only
+  inventory commands. `pscale deploy-request throttler update ...` is a
+  mutation and is outside read-only inventory.
 - Postgres roles: list via `.../branches/{branch}/roles`; fetch a single
   role by ID, not name (`pscale role get <db> <branch> <role-id>`).
 - IP restrictions: database-level
@@ -111,6 +118,7 @@ Record:
 - Region and cloud provider.
 - Production/development branch status.
 - Branch protection and safe workflow state.
+- Database and branch deletion-protection state.
 - Size and cluster shape.
 
 ### Branches and schema workflow
@@ -120,13 +128,17 @@ For Vitess, record:
 - Production branch.
 - Whether safe migrations are enabled for production and staging branches.
 - Open deploy requests.
+- Active deploy request queue position, operations, deployment progress, and
+  throttler settings when a deploy request is in flight.
 - Deploy request approval setting.
 - Pending schema changes.
+- Deletion-protection state for production and other long-lived branches.
 - Whether branch strategy has a staging branch with safe migrations enabled.
 
 For Postgres, record:
 
 - Branch list.
+- Deletion-protection state for production and other long-lived branches.
 - Whether branches were created from backup or empty.
 - Whether schema changes are managed manually, through migrations, or through an ORM.
 - Whether a separate branch is used for migration testing.

02-vitess-safety-review/SKILL.md

@@ -34,6 +34,8 @@ Check:
 - Whether teams use gated deployments for cutover control.
 - Whether “deploy instantly” is used and whether the team understands it removes the gated-deployment/revert shape.
 - Whether cutover is regularly delayed by long-running transactions.
+- Whether active deploy requests have clear queue, operation, deployment, and
+  throttler state when they are being monitored or tuned.
 - Whether deploy request events are subscribed to via webhooks.
 
 Recommend:
@@ -46,6 +48,10 @@ Recommend:
   approval permission.
 - Prefer normal safe deployments over instant deployments unless the migration is known to be instant-safe and the rollback story is acceptable.
 - Use gated deployment when cutover timing matters.
+- Use `pscale deploy-request queue`, `operations`, and `deployment` as
+  read-only evidence when diagnosing active deploys. Treat per-request
+  throttler updates as operational changes that require approval, especially
+  when production traffic is affected.
 - Treat “force cutover now” as an operator-controlled action for delayed
   cutovers: it aggressively stops running transactions to complete schema
   cutover. Recommend reviewing the blocking workload and incident context
@@ -71,9 +77,27 @@ Recommend a branch topology:
 - `staging` branch based from production with safe migrations enabled.
 - Short-lived development branches based from staging.
 - Deploy requests from development to staging, then staging to production when appropriate.
+- Deletion protection enabled on the database and on production or other
+  long-lived branches where accidental removal would be disruptive.
 
 Do not create branches without approval.
 
+### Deletion protection
+
+Check whether deletion protection is enabled on the database and on critical
+branches.
+
+Recommend:
+
+- Enable deletion protection for production databases, production branches, and
+  other long-lived branches that should not be removable in a single step.
+- If Terraform manages branches, keep `deletion_protected` in Terraform for
+  `planetscale_vitess_branch` resources so disabling protection is reviewed as
+  infrastructure code before a branch resource can be removed.
+
+Do not disable deletion protection or delete protected resources without
+explicit approval and target confirmation.
+
 ### Query Insights
 
 Review Insights for:

03-postgres-safety-review/SKILL.md

@@ -17,6 +17,8 @@ Check:
 
 - Whether a development or test branch exists.
 - Whether branches are empty or restored from backup.
+- Whether deletion protection is enabled for the database and critical
+  branches.
 - Whether migrations are tested against a branch before production.
 - Whether application migrations are reversible or have a documented rollback strategy.
 - Whether production DDL is manually reviewed.
@@ -27,8 +29,14 @@ Recommend:
 - Run migration validation and application tests against that branch.
 - Treat production migration application as an explicit human-approved deployment step.
 - Use PITR/backup restore branches for incident recovery, not as an automatic rollback mechanism.
-
-Do not create branches, run migrations, or restore backups without approval.
+- Enable deletion protection for production databases, production branches, and
+  other long-lived branches that should not be removable in a single step.
+- If Terraform manages branches, keep `deletion_protected` in Terraform for
+  `planetscale_postgres_branch` resources so disabling protection is reviewed
+  as infrastructure code before a branch resource can be removed.
+
+Do not create branches, run migrations, disable deletion protection, delete
+protected resources, or restore backups without approval.
 
 ## Roles and least privilege
 

07-schema-recommendations-agent-loop/SKILL.md

@@ -55,9 +55,12 @@ Recommended path:
 2. Apply the schema change to that branch only after approval.
 3. Open a deploy request only after approval.
 4. Use deploy request review to inspect schema, shard impact, data-loss warnings, lint errors, and conflicts.
-5. Use normal safe migration path unless instant deployment is explicitly justified.
-6. Deploy only after approval.
-7. Monitor Insights and anomaly state after deployment.
+5. When monitoring an active deploy request, use queue, operations, and
+   deployment inspection as read-only evidence before proposing any throttler
+   change.
+6. Use normal safe migration path unless instant deployment is explicitly justified.
+7. Deploy only after approval.
+8. Monitor Insights and anomaly state after deployment.
 
 Default output before approval: issue or PR with migration proposal, not a live deploy request.
 

09-mcp-agent-operating-model/SKILL.md

@@ -53,6 +53,8 @@ Allowed by default:
 - Read schema metadata.
 - Read existing webhooks and Traffic Control configuration.
 - Read branch metadata.
+- Read deletion-protection state.
+- Inspect deploy request queue, operations, and deployment details.
 - Inspect repository code.
 - Correlate query patterns with code.
 - File issues.
@@ -80,6 +82,8 @@ Not allowed by default (the review-gate actions and non-reviewable mutations):
 - Rotate credentials.
 - Change roles.
 - Change IP restrictions or private connectivity.
+- Change deploy request throttler settings.
+- Disable deletion protection.
 - Restore or promote branches.
 
 ## Agent loops
@@ -158,7 +162,8 @@ for the same fingerprint/recommendation ID).
   covers only the mechanical deploy.
 - **Branch hygiene** (weekly): delete development branches older than the
   authorized age bound with no open deploy request; never touch
-  production or protected branches. 
+  production or deletion-protected branches, and never disable deletion
+  protection to make a branch eligible for hygiene deletion.
 - **Warn-budget gardener** (weekly): create warn-mode Traffic Control
   budgets for newly identified expensive slices matching the allowlist;
   report warn counts on existing budgets. Enforce mode is never entered

11-change-gates-and-approval-contract/SKILL.md

@@ -16,6 +16,7 @@ Prevent accidental or autonomous changes that can affect availability, safety, s
 Allowed without approval:
 
 - List databases, branches, keyspaces, webhooks, backups, roles, traffic budgets, schema recommendations, deploy requests, and Insights data.
+- Inspect deploy request queue, operations, deployment details, and deletion-protection state.
 - Inspect repository code.
 - Read schema metadata.
 - Read non-sensitive database metadata.
@@ -56,6 +57,8 @@ Always requires explicit approval:
 - Change connection pooling behavior.
 - Change IP restrictions, PrivateLink, PSC, or public access.
 - Change backup schedule or retention.
+- Enable deletion protection, or disable deletion protection on non-production targets.
+- Adjust deploy request throttler settings on non-production targets.
 - Create restore branch.
 - Create backup beyond automatic backups.
 - Change branch size or replica topology.
@@ -69,7 +72,9 @@ Requires explicit approval, named target confirmation, rollback plan, and ideall
 - Production DML.
 - Applying schema recommendation to production.
 - Queueing or applying Vitess deploy request to production.
+- Adjusting deploy request throttler settings for a production deploy request.
 - Promoting or restoring branches.
+- Disabling deletion protection on a production database or branch.
 - Deleting branches, databases, roles, webhooks, backups, or traffic rules.
 - Enforcing Traffic Control on production.
 - Changing production network access.

12-best-practices-matrix/SKILL.md

@@ -68,6 +68,16 @@ Recommend:
 - Test before production.
 - Apply only through approved workflow.
 
+### Deletion protection
+
+Recommend for production databases, production branches, and other long-lived
+branches where accidental deletion would be disruptive. If Terraform is the
+source of truth, manage branch deletion protection with `deletion_protected` on
+`planetscale_vitess_branch` and `planetscale_postgres_branch`; deleting a
+protected Terraform-managed branch should be a reviewed two-step change that
+first sets `deletion_protected = false` and applies before removing the
+resource.
+
 ## Vitess-specific recommendations
 
 ### Safe migrations
@@ -77,6 +87,8 @@ Recommend for production branches and staging branches that accept deploy reques
 ### Deploy requests
 
 Recommend for schema changes into protected branches.
+For active deploys, use deploy-request queue, operations, and deployment
+inspection as evidence before changing strategy or throttler settings.
 
 ### Force cutover discipline
 

13-autonomous-execution-mode/SKILL.md

@@ -54,7 +54,8 @@ containing:
   recommendations; deploy with revert window; additive only (ADD INDEX,
   ADD COLUMN NULL)". Invalid: "keep the schema optimized".
 - Numeric bounds where applicable: max changes per run, max branch age
-  for deletion, budget modes permitted (warn only vs enforce).
+  for deletion, deletion-protection handling, budget modes permitted
+  (warn only vs enforce), and deploy-request throttler bounds.
 - Expiry date. Expired authorization = report-only mode. Recommended
   review interval: 90 days.
 
@@ -78,7 +79,7 @@ Before the first mutation, produce and show an **execution plan**:
 
 1. **Order by dependency, then by risk.** Prerequisites first (e.g. stop the app's boot-time DDL before enabling safe migrations, add an index before dropping the one it replaces). Among independent changes, lowest-risk first so early failures cost the least.
 2. **Pre-flight each change.** Re-read the live state immediately before mutating (branch flags, recommendation state, webhook config). If the state no longer matches the report evidence, the change is **stale**: skip it, mark it `BLOCKED — state drift`, and continue with independent changes.
-3. **Safety prerequisites are steps, not assumptions.** Before any Class D DDL: confirm a backup completed within the retention window, confirm safe migrations or a deploy request is the vehicle where the engine supports it, and prefer revertible mechanisms (deploy requests with revert window, warn-mode before enforce-mode for Traffic Control).
+3. **Safety prerequisites are steps, not assumptions.** Before any Class D DDL: confirm a backup completed within the retention window, confirm safe migrations or a deploy request is the vehicle where the engine supports it, and prefer revertible mechanisms (deploy requests with revert window, warn-mode before enforce-mode for Traffic Control). Before any branch deletion, verify the branch is non-production, has no open deploy request, and is not deletion-protected unless the standing authorization explicitly names disabling protection.
 4. **One atomic change at a time.** Never batch unrelated mutations into one command. Never parallelize Class D steps.
 5. **Verify after each step.** Read the state back and confirm the expected effect before moving on. A change is not "done" when the command exits 0; it is done when the read-back matches the expected state.
 
@@ -89,7 +90,7 @@ The operator handed over control; visibility is what they get in return. Emit st
 - **Plan announcement** — numbered steps, each with target, exact command/interface, expected effect, rollback mechanism, and class. This is the last thing shown before execution begins.
 - **Per-step, before**: `[step 3/7] STARTING VIT-3a — deploy request: add idx_orders_on_user_id to storefront-demo/main (Class D, revert window available)`
 - **Per-step, after**: `[step 3/7] DONE — deploy request #4 deployed, index visible in schema read-back (took 2m 10s)`
-- **Long-running operations** (deploy requests, migrations, restores): poll and report progress at a sensible cadence, not just at completion. Include queue position/state transitions.
+- **Long-running operations** (deploy requests, migrations, restores): poll and report progress at a sensible cadence, not just at completion. Include deploy request queue position, operations, deployment progress, throttler state, and other state transitions when available.
 - **Skips and blocks**: report immediately with the reason (`BLOCKED — state drift`, `EXCLUDED — Class E`, `SKIPPED — prerequisite failed`), never silently.
 - **Run summary** — the post-execution report from the change-gates skill: what changed, when, evidence of success, warnings, rollback state, follow-up monitoring. Plus the acknowledgment quote and the autonomy level used.
 
@@ -107,6 +108,7 @@ Stop-the-line rules. When any of these fires, finish or safely abort the current
 4. **State drift on a production target** (someone else changed it mid-run) → halt the run.
 5. **Scope pressure** — anything needed that is outside the acknowledged scope → do not do it; report it.
 6. **Error on a destructive step** → never auto-retry. Retries are permitted only for idempotent reads and transient network failures on non-destructive calls.
+7. **Deletion protection blocks a destructive step** → halt that step. Do not disable protection unless the authorization explicitly names that target and action.
 
 After a halt: report state of every step (done / rolled back / blocked / not started), current database state, and what re-acknowledgment would be needed to resume. Never resume a halted run on the original acknowledgment.
 

14-pscale-cli-automation/SKILL.md

@@ -50,6 +50,24 @@ browser; use `pscale auth login --format json`.
   sql … --force`). There is no global `--force` or `PSCALE_FORCE`.
 - **`--format json` alone never skips confirmations** — add `--force` on the
   destructive subcommand after explicit user approval.
+- A failed delete may be an intentional safety signal from deletion protection.
+  Do not disable protection or retry with a destructive workflow unless the
+  operator explicitly approved that target and action.
+
+## Deploy request inspection
+
+For Vitess deploy request monitoring, these commands are read-only and suitable
+for inventory or status reporting:
+
+```bash
+pscale deploy-request queue <database> --org <org> --format json
+pscale deploy-request operations <database> <number> --org <org> --format json
+pscale deploy-request deployment <database> <number> --org <org> --format json
+```
+
+`pscale deploy-request throttler update <database> <number> --ratio <percent>`
+changes live throttling for that deploy request. Treat it as an approved
+operational mutation, not as inspection.
 
 ## Typical workflow