@prestyj/cli 5.28.0 → 5.29.0

package/assets/skills/durable/SKILL.md

@@ -1,111 +1,119 @@
 ---
 name: durable
-description: Use when user data must not be lost or corrupted — creating the first database/table/schema, writing migrations, backfilling or importing data, any destructive operation (delete, drop, truncate, overwrite), setting up backups or recovery, or moving data between systems; and for "is my data safe", "will I lose my data", "back up my app" checks on existing projects. Any store — SQL (Postgres, MySQL, SQLite), document (Mongo, Firestore), serverless (Supabase, Neon, Turso), files, queues. Do NOT use for query speed or connection-pool sizing (that is lean), access control over data (that is bulletproof), or privacy/legal deletion regimes (that is compliance-guard).
+description: Use when user data must not be lost or corrupted — creating the first table/schema, writing or running migrations, backfills/imports, any destructive op (delete, drop, truncate, reset, overwrite), before the agent itself runs a command against a database that may hold real data, setting up backups/recovery, or moving data between systems; plus "is my data safe / back up my app" checks. Any store — SQL, document, serverless, files, queues. Do NOT use for query speed or pool sizing (that is lean), access control over data (that is bulletproof), or privacy/legal deletion regimes (that is compliance-guard).
 license: Data-durability engineering guidance, not a DBA certification. Sources and snapshot date are recorded at the foot of each reference file.
-compatibility: Snapshot dated 17 August 2026. Version behaviors (fast-path ALTERs, pooler modes, tool flags) decay — re-verify with web access before asserting them as current.
+compatibility: Snapshot dated 3 October 2026. Version behaviours, provider retention defaults and tool flags decay — re-verify with web access before asserting them as current.
 ---
 
 # Durable
 
-Make user data survive everything: bad migrations, crashed writes, retried webhooks, full disks, dead servers, and the 3am `DELETE` without a `WHERE`. Built for the reality that users forgive slow and ugly; they do not forgive gone.
+**Route first:**
 
-**This skill is on from the first table.** The default mode is the inline gate below — every schema change, import, and destructive path gets the durable treatment as it is written. The full pass is for existing projects and "is my data safe" checks.
-
-## Governing rules
+| You are… | Mode | Do next |
+|---|---|---|
+| About to run *any* command against a database yourself (migrate, reset, push, seed, SQL shell, delete script) | **Agent gate** | Run the agent gate below before the command. Always. |
+| Writing code that touches stored data (table, migration, import, delete endpoint, webhook write, backup cron) | **Inline gate** | Apply binding defaults; one line on the guard you built; keep building. |
+| Asked "is my data safe / back up my app", a migration is about to hit production, or after a data scare | **Full pass** | Run the full-pass workflow. |
 
-1. **The database is the last line of defense, not the app.** Constraints, foreign keys, uniqueness, and NOT NULL live in the store where enforcement cannot be bypassed. App-level validation is UX, not integrity — a bug, a script, or a direct SQL session walks right past it.
-2. **Destructive operations are guilty until proven guarded.** Any `DROP`, `TRUNCATE`, `DELETE`, `UPDATE` without a `WHERE`, or overwrite of a column/file gets: a guard (`WHERE` + `LIMIT`), a dry-run count first, a backup or snapshot when anything of value exists, and an undo path (soft delete, staging table, or copy) for user-facing data.
-3. **Migrations are code that runs on data you cannot recreate.** Checked in from day one, reviewed as SQL before applying (ORM-generated SQL included — generators will happily emit `DROP COLUMN` for a rename), never edited once applied, forward-only in production. `db push`-style sync is for throwaway dev databases only.
-4. **One logical change, one transaction.** Multi-step writes either all land or none do. Anything a retry can hit twice (webhooks, queue jobs, imports, payment callbacks) is idempotent — a dedup key or upsert, not hope.
-5. **Backups you have not restored are fiction.** Automated, off-platform (or at least off-instance), on anything with real user data — and the restore is exercised, timed, and recorded. RPO (how much loss is acceptable) and RTO (how long recovery takes) are stated numbers, not vibes.
-6. **Fail loudly, not corruptly.** Partial imports, half-applied backfills, and crashed jobs leave the system in a state the next run can detect and resume — keyset-resumable batches, recorded checkpoints, no silent skips.
-7. **Respect the writer.** SQLite has one writer; Postgres connections are processes; serverless poolers multiplex transactions and break session state. Designing against the store's real concurrency model is durability work, not just performance work.
-8. **Numbers or silence.** A backup claim without a timed restore run is unverified. Label every claim `RUNTIME` (observed), `CODE` (read in source), `DEDUCED` (inferred), `SNAPSHOT` (dated source). Never claim data is "safe" — say what loss is survivable and what is not.
-9. **Proportionality.** A prototype with test rows needs migrations and little else. The first real user row raises the floor: backups, then tested restore, then PITR-class recovery as the product matters.
+Users forgive slow and ugly; they do not forgive gone. Never say data is "safe" — say what loss is survivable and what is not.
 
-## Two modes
+## Agent gate — binding rules for you, the agent
 
-**Inline gate** — while writing anything that touches stored data: the first table, a schema change, a backfill or import script, a delete/edit endpoint, a webhook that writes, a backup cron. Apply the binding defaults below, say one line about the guard you built, move on. Do not stop the build to lecture, and do not ship the unguarded version intending to "add safety later".
+Coding agents have wiped production data: in July 2025 Replit's agent deleted a live project database during an explicit code freeze, then wrongly said rollback was impossible (`SNAPSHOT`; details in `references/agent-db-safety.md`). The freeze was only a natural-language instruction; nothing mechanical enforced it. These rules are the mechanism.
 
-**Full pass** — triggered by "is my data safe", "will I lose my data if X", "back up my app", a migration about to run on production, or after any data scare. Run the workflow below. Migration and schema detail lives in `references/migrations-and-schema.md`; backups, recovery, and runtime data-safety detail lives in `references/backups-and-runtime.md`.
+1. **Identify the target before every command.** Resolve which database the command will hit (env var, config file, `--url`, ORM config). Classify it `throwaway` / `shared-dev` / `may-hold-real-data` using the detection list in `references/agent-db-safety.md`. Unknown = `may-hold-real-data`.
+2. **On `may-hold-real-data`, read-only by default.** Inspect with `SELECT`/`EXPLAIN`/`\d`, a read-only role, or `BEGIN READ ONLY`. No DDL, no writes, no `migrate dev|reset`, `db push`, `--force`, `--accept-data-loss`, `flush`, `dropDatabase`, `TRUNCATE`, seed scripts.
+3. **Destructive or schema-changing commands on real data require all of:** (a) a backup or PITR point you verified exists *for this database* (`RUNTIME` or provider-console evidence, not assumption), (b) a dry-run count of affected rows shown to the user, (c) the exact command shown, and (d) the user's explicit go-ahead in this conversation for that command. "Go ahead and fix it" does not cover a `DROP`.
+4. **Experiment on a branch, not the original.** Prefer a Neon / Supabase / PlanetScale branch, a restored clone, or a local copy; prove the change there, then hand the production step back with evidence.
+5. **Never bypass a tool's safety interlock yourself.** If a CLI refuses because it detected an agent (e.g. Prisma's AI-consent check) or asks for confirmation, stop and ask — never set a consent variable or pass `--force`/`--yes` on your own initiative.
+6. **Surprising results mean stop, not fix.** Empty tables, missing rows, failed restores: report what you observed and ask. Never "repair" by recreating, reseeding, or fabricating data, and never declare data unrecoverable without checking the provider's backups/PITR.
+7. **Report exactly what you ran** — every command that touched a database, its target, and its result, including mistakes, immediately.
 
-## Binding defaults (build mode)
+Also flag (do not silently fix) setups where the agent's shell holds production write credentials: recommend separate dev/prod credentials, a read-only role for inspection, and production URLs absent from local `.env`.
 
-Apply on every data-touching change, every store:
+## Governing rules
 
-- **Migration tooling from the first table** — checked-in versioned migrations, generated with `--create-only`-style review when the ORM supports it, reviewed as SQL, applied via the tool's deploy path. Never hand-edit an applied migration; write a new one that corrects it.
-- **Destructive ops carry their guard** — `WHERE` + `LIMIT` on mass changes, count-first dry run (`SELECT` the affected rows before `DELETE`/`UPDATE`), and for user-visible data prefer soft delete (`deleted_at`) with partial unique indexes over hard delete until retention policy says otherwise.
-- **Constraints in the store** — `NOT NULL` on required fields, `UNIQUE` where identity lives (email, external IDs), foreign keys with explicit `ON DELETE` behavior chosen (not defaulted), and `CHECK` where a value has a domain. Orphaned rows and duplicate emails are app bugs the DB should have refused.
-- **Transactions around multi-write invariants** — wrap create-order-plus-items, transfer-out-plus-transfer-in, and every read-modify-write that must not interleave. Where the store lacks multi-document transactions, the default is a single-document design or an outbox pattern, never "should be fine".
-- **Idempotency keys on retried writes** — webhook event IDs, job dedup keys, `INSERT ... ON CONFLICT` upserts. Rule of thumb: if it can run twice, assume it will.
-- **Batched, resumable bulk work** — keyset pagination (`WHERE id > last`), fixed batch size, sleep between batches, checkpoint recorded so a crash resumes rather than restarts or double-applies. Never one unbounded `UPDATE` over a production table.
-- **Backups the moment real data exists** — automated (managed-provider backups, `pg_dump` cron, Litestream for SQLite, scheduled snapshots for document stores), retention of days not one copy, at least one copy off the same machine/account. State RPO/RTO in a comment where the backup is configured.
-- **Connection and session hygiene** — close/release connections in `finally`; on serverless, assume transaction-mode pooling (no session state, no prepared statements unless the pooler supports them, no `LISTEN/NOTIFY`, no session advisory locks); one pool per function instance, not per request.
-- **SQLite as SQLite** — WAL mode on, `busy_timeout` set, one writer (route writes through a single instance or a queue), database on local disk not network storage, Litestream-or-scheduled-backup for continuous protection. Do not pretend it is a client-server DB.
+1. **The store is the last line of defence.** `NOT NULL`, `UNIQUE`, foreign keys with a chosen `ON DELETE`, `CHECK` — in the database, where scripts and bugs cannot walk past them.
+2. **Destructive operations are guilty until guarded**: `WHERE` + batch limit, dry-run count first, backup when anything of value exists, undo path (soft delete, staging copy) for user-facing data.
+3. **Migrations run on data you cannot recreate.** Checked in, reviewed as SQL (ORM output included — a rename can become `DROP` + `ADD`), never edited once applied, forward-only in production. Push/sync commands are for throwaway databases.
+4. **One logical change, one transaction; anything retried is idempotent.**
+5. **Backups you have not restored are fiction.** Automated, off-instance, stated RPO/RTO, timed restore drill.
+6. **Fail loudly, not corruptly.** Bulk jobs are keyset-resumable with durable checkpoints.
+7. **Respect the store's concurrency model** — SQLite has one writer; transaction poolers break session state.
+8. **Evidence labels on every claim:** `RUNTIME` (observed), `CODE` (read in source), `DEDUCED` (inferred), `SNAPSHOT` (dated external source).
+9. **Proportionality.** Test rows need migrations; the first real user row raises the floor to backups, then tested restore, then PITR.
+
+## Binding defaults (inline gate)
+
+- **Migration tooling from the first table.** Generate without applying (`prisma migrate dev --create-only`, `drizzle-kit generate`), read the SQL, apply via the deploy path (`prisma migrate deploy`, `drizzle-kit migrate`). Corrections are new migrations.
+- **Destructive code carries its guard**: count-first, `WHERE` + batch, soft delete (`deleted_at` + partial unique index) for user-visible data.
+- **Constraints in the store** per rule 1; integer cents or `NUMERIC` for money; `bigint`/UUID keys (Postgres 18 has built-in `uuidv7()` for time-ordered IDs).
+- **Transactions around multi-write invariants**; across systems, use an outbox.
+- **Idempotency keys on retried writes**: unique event/job IDs + `INSERT … ON CONFLICT`.
+- **Batched, resumable bulk work** (keyset, fixed batch, checkpoint, sleep) — never one unbounded `UPDATE` on production.
+- **Backups the moment real data exists**: confirm the plan actually includes them (free tiers often do not), add an off-account copy, state RPO/RTO where configured. Uploads need bucket versioning — DB backups do not cover objects.
+- **Separate credentials per environment**; production URL never the default in local `.env`.
+- **Serverless connections**: assume transaction-mode pooling (no session state); one pool per instance; release in `finally`.
+- **SQLite as SQLite**: WAL, `busy_timeout`, `foreign_keys=ON` per connection, one writer, local disk, continuous or scheduled backup.
 
 ## Full-pass workflow
 
-### 1. Profile the data from the code
-
-Before asking anything: store type(s) and version, where data files live, ORM/migration tooling present or absent, what writes exist (endpoints, jobs, webhooks, imports), what deletes exist, whether backups are configured anywhere (deploy config, cron, provider settings), and — decisive — whether real user data exists. A repo with seed scripts only is a different engagement than one with a production URL.
-
-### 2. Establish what loss would mean
-
-From the code, answer: what is recreated (cache, derived data), what is user-entered and unrecoverable (posts, uploads, messages, payments), and what links out (files on disk referenced by rows, rows referencing deleted files). The unrecoverable set defines backup urgency; the links define cleanup discipline.
-
-### 3. Sweep the six areas
+1. **Profile from the code.** Stores and versions, migration tooling, every write/delete path, backup config, environments and credentials, and — decisive — whether real user data exists.
+2. **Define loss.** Recreatable (caches, derived) vs unrecoverable (user content, uploads, payments), and what links out (rows ↔ files).
+3. **Sweep the seven areas** (detail in references):
 
-In order of how often each actually loses data. Detection specifics and commands: the two reference files.
-
-| # | Area | What you are hunting |
+| # | Area | Hunting for |
 |---|---|---|
-| 1 | **Backups & recovery** | No backups at all; backups only on the same machine/account; no retention; never-restored backups (the norm); no stated RPO/RTO; single copy of file uploads; managed backups assumed but not enabled |
-| 2 | **Destructive paths** | `DELETE`/`UPDATE` without `WHERE` or `LIMIT`; cascade deletes that sweep further than intended (user → everything they own, intended or not); truncate/drop in scripts; no undo for user-facing deletes; `db push` or sync-style schema changes anywhere near production config |
-| 3 | **Migrations health** | No migration tooling (schema by hand/script); applied migrations edited; pending destructive migration; generated SQL never reviewed; migrations untested against prod-shaped data; drift between schema files and the live DB |
-| 4 | **Transactions & idempotency** | Multi-step writes without a transaction; webhook/job handlers that double-apply on retry; check-then-act races (read, decide, write without a constraint); imports that restart from zero |
-| 5 | **Schema integrity** | Foreign keys absent or off (MySQL engines, SQLite `PRAGMA foreign_keys`); duplicate-prone columns without unique constraints; orphaned rows; `NOT NULL`-in-spirit columns that are nullable in fact; money/IDs stored in lossy types (float money, int IDs near overflow) |
-| 6 | **Runtime data safety** | Transaction-pooled connections using session features; SQLite without WAL/busy_timeout or with concurrent writers across instances; files written non-atomically (no temp-then-rename); jobs that mutate state with no record of having run; queues with no dead-letter path |
+| 1 | Backups & recovery | None; same machine/account only; free tier assumed to be PITR; never restored; no RPO/RTO; unversioned upload buckets |
+| 2 | Destructive paths | Unguarded `DELETE`/`UPDATE`; cascades sweeping too far; reset/push/drop in scripts or CI near production config |
+| 3 | Agent & credential exposure | Prod write URL in local `.env`; agent/CI tokens with DDL rights; no branch/dev DB to experiment on |
+| 4 | Migrations health | No tooling; edited applied migrations; unreviewed destructive SQL; lock-unsafe DDL; drift |
+| 5 | Transactions & idempotency | Multi-writes without a transaction; double-apply on retry; check-then-act races |
+| 6 | Schema integrity | Missing FKs/uniques/`NOT NULL`; orphans; float money; int IDs near overflow |
+| 7 | Runtime data safety | Session state through transaction poolers; SQLite multi-writer; non-atomic file writes; no dead-letter path |
 
-### 4. Rank by survivability
+4. **Rank by survivability.**
 
 | Severity | Meaning |
 |---|---|
-| **Critical** | Loss is certain or one common failure away: real user data with no backups; destructive path unguarded; pending migration that drops data; double-charge/double-apply on retry |
-| **High** | Loss on a plausible bad day: backups exist but never restored; single copy on one machine/account; cascade deletes broader than intended; multi-write flows without transactions |
-| **Medium** | Fragility that bites at scale or during recovery: missing constraints, schema drift, non-idempotent jobs, non-atomic file writes |
-| **Low** | Hygiene: naming, unused staging tables, comments. Do these when adjacent to a real fix. |
-
-Fix Critical and High first; three to five fixes, each verified. A backup you set up is finished only when a restore from it has run and been timed.
-
-### 5. Verify
-
-- **Restore drill for any backup fix**: snapshot state, note the time, make a recognizable change, restore to the noted time into a separate location, verify the change is absent, record the wall-clock duration — that number is the real RTO. `RUNTIME` label or it did not happen.
-- **Guard drill for any destructive fix**: run the guarded path against a copy with a row that must survive and a row that must not; assert both outcomes.
-- **Migration drill**: apply the pending migrations to a copy of production-shaped data (a fresh dump, a seeded volume) before it goes near the real thing.
-- Label what you could not run — no environment, no data copy, managed console you cannot touch — as unverified, and say the exact command the user should run.
-
-### 6. Leave a guard behind
-
-A tested restore cron'd into a weekly job; a CI step that applies migrations to a throwaway DB before merge; a test that a retried webhook applies once; a constraint added to the store; `--create-only` review in the project's migration docs. One mechanical check beats a README paragraph.
-
-### 7. Report
+| Critical | Loss certain or one common failure away: real data with no backups; unguarded destructive path; pending data-dropping migration; agent/CI holding prod write creds with no verified backup; double-charge on retry |
+| High | Loss on a plausible bad day: never-restored backups; single copy; broad cascades; multi-writes without transactions |
+| Medium | Bites at scale or in recovery: missing constraints, drift, non-idempotent jobs, non-atomic writes |
+| Low | Hygiene; fix only when adjacent |
+
+5. **Fix Critical and High first** (three to five, each verified).
+6. **Verify.**
+   - *Restore drill* (any backup fix): note a point, insert a canary, restore to the point **into a separate location**, confirm the canary is absent, record wall-clock time as the real RTO. `RUNTIME` or it did not happen.
+   - *Guard drill* (destructive fix): on a copy, one row that must survive and one that must not; assert both.
+   - *Migration drill*: apply pending migrations to a branch or prod-shaped copy first, with `lock_timeout` set.
+   - Anything you could not run: label it unverified and give the user the exact command.
+7. **Leave a guard behind**: CI applying migrations to a throwaway DB, a migration linter, a scheduled restore test, a constraint, a read-only role for agents.
+8. **Report**: lead with the RPO the user *actually* has ("if this server died now you lose everything since …"); then ranked findings with file:line and fix; then **not checked**; then fixed (with labels) vs needs-the-user (provider settings, paid tiers, retention choices).
+
+## Scaling: one agent or several
+
+| Situation | Policy |
+|---|---|
+| Agent gate, inline gate, small edits | Main thread only. Never spawn. |
+| Full pass, one deployable, one store | Main thread builds the ledger (7 areas × stores/services) and works every row itself. |
+| Full pass, several stores/services/deployables, or more rows than you can read fully | One read-only child per disjoint slice, all in ONE `spawn_agent` call (≤ 6). `owl` for code slices; `researcher` for dated provider/version claims. |
+| Production migration plan or "is my data safe" verdict | Add a fresh-context verifier child that tries to disprove the findings and the restore evidence. |
 
-- Lead with the survivability statement in plain words: "if this server dies right now, you lose everything after [backup point]" — the RPO the user actually has, not the one they think they have.
-- Then findings ranked, each with file/line and the fix.
-- Then what was **not checked** — stores skipped, consoles inaccessible, uploads unexamined.
-- Then what you fixed (with verification labels) vs. what needs the user (provider settings, paid tiers, their call on retention).
-- Label every claim `RUNTIME` / `CODE` / `DEDUCED` / `SNAPSHOT`.
+- **Every ledger row ends** checked-with-findings / checked-clean / not-checked(reason). A child that fails, times out or omits a row → `not checked`, never clean.
+- **Child briefs are self-contained**: absolute skill root, which reference to read, slice paths, owned rows, evidence labels, output schema (findings with file:line, label, severity, fix; `checked` / `not checked` lists), and: *read-only — never connect to or run commands against any database*.
+- **Child output is evidence, not truth**: re-open each file:line before reporting.
+- **Database commands are never parallel.** Migrations, restores, and any write against shared or production data are executed serially by the main thread after the agent gate — never by children. Code fixes are main-thread or `bee` on strictly disjoint files; run checks once after merging.
 
 ## Honesty rules
 
-- Never state or imply data is "safe" or "backed up" without an observed, timed restore. "Backups are configured" is a `CODE` claim; "recoverable" requires a `RUNTIME` one.
-- Never present a retention number, provider tier, or version behavior as current without verifying — provider backup defaults change; mark the snapshot date.
-- Never run a destructive command, however obviously safe, against a database with real data without an explicit backup or the user's go-ahead.
-- "I could not verify this" is a legitimate output. A fabricated restore test is the worst lie this skill could tell.
+- "Backups are configured" is `CODE`; "recoverable" needs a `RUNTIME` restore. Never say "safe".
+- Provider retention, tiers and version behaviour are `SNAPSHOT` with a date — verify before quoting.
+- Never claim data is gone, or restored, without checking. A fabricated restore test is the worst lie this skill could tell.
 
 ## Reference map
 
-Resolve every path from the installed skill root. Load only what the profile triggered.
+Resolve paths from the installed skill root; load only what the profile triggers.
 
-- `references/migrations-and-schema.md` — the migration discipline: expand-contract with concrete lock behavior, batched resumable backfills, index and FK lock-safety, ORM-specific traps (Prisma, Drizzle, and friends), forward-only production, CI and deploy-time application, and schema integrity checks. Read for any migration or schema finding.
-- `references/backups-and-runtime.md` — backup tiers and the restore drill, RPO/RTO, 2026 managed-provider baselines (Supabase, Neon, RDS, Crunchy), self-hosted tooling (pgBackRest, WAL-G, Litestream, restic), file-upload protection, idempotency and outbox patterns, pooling and serverless session-state pitfalls, SQLite runtime rules, and atomic file writes. Read for any backup, recovery, or runtime finding.
+- `references/agent-db-safety.md` — incident record, production-target detection, safe inspection, branch/clone workflow, tool interlocks. Read before any agent-run database command on a non-throwaway target, and for area 3.
+- `references/migrations-and-schema.md` — expand/contract, lock-safety table with `lock_timeout`, Postgres 18 notes, backfills, ORM traps (Prisma 7, Drizzle, framework linters), integrity sweep. Read for areas 2, 4, 6.
+- `references/backups-and-runtime.md` — tiers and restore drill, provider PITR snapshot, Litestream 0.5 and SQLite backups, object versioning/Object Lock, idempotency/outbox, poolers. Read for areas 1, 5, 7.

package/assets/skills/durable/references/agent-db-safety.md

@@ -0,0 +1,69 @@
+# Durable — agent database safety
+
+Load before the agent runs any command against a database that is not provably throwaway, and for full-pass area 3. `SNAPSHOT` = sourced 3 October 2026.
+
+## Why this file exists
+
+`SNAPSHOT` — July 2025, SaaStr founder Jason Lemkin's public "vibe coding" experiment on Replit: the agent deleted a live project database during an explicit, repeated code freeze, produced misleading output (including fabricated records), and said rollback was impossible — which proved false. Replit responded by separating dev and production databases, adding approval for destructive commands, and pointing to tested backups. Lessons this skill encodes:
+
+- A natural-language "don't touch it" is not a control. Credentials, read-only roles, and branches are.
+- Agents misread anomalies (empty results) as problems to fix. Anomaly → stop and report.
+- Agents misreport recoverability. Check backups/PITR before saying anything about loss.
+
+## Classify the target (before every command)
+
+Treat as **`may-hold-real-data`** if any is true; unknown also counts:
+
+- Host is not `localhost`/`127.0.0.1`/a docker-compose service/`file:` under the repo's dev path.
+- Host or name matches a managed provider (`*.supabase.co`, `*.pooler.supabase.com`, `*.neon.tech`, `*.psdb.cloud`/PlanetScale, `*.rds.amazonaws.com`, `*.turso.io`, `mongodb+srv://`, Firestore project IDs) and is not a known branch/preview.
+- Variable or file name contains `prod`, `production`, `live`, `main`; or it is the value in `.env.production`, deploy config, or CI secrets.
+- `NODE_ENV`/`RAILS_ENV`/`APP_ENV`/`DJANGO_SETTINGS_MODULE` points at production.
+- Row counts or timestamps suggest real use (inspect read-only: `SELECT count(*), max(created_at) FROM users`).
+
+**`throwaway`** only when you created it this session, or it is a local container/file seeded by the repo, or a branch you just made.
+
+Never print full connection strings; show host and database name only.
+
+## Read-only inspection
+
+| Store | Read-only pattern |
+|---|---|
+| Postgres | Dedicated role with `SELECT` only; or `psql` with `BEGIN READ ONLY;` / `SET default_transaction_read_only = on` (a session setting, not a security boundary) |
+| MySQL | User with `SELECT` grant only; `START TRANSACTION READ ONLY` |
+| SQLite | Open with `?mode=ro` or `sqlite3 -readonly`; or inspect a copy |
+| MongoDB | User with the `read` role |
+
+Recommend the user create the read-only role; do not create roles on production yourself without the gate.
+
+## Branch / clone first
+
+| Platform | Experiment surface (`SNAPSHOT`, verify flags) |
+|---|---|
+| Neon | Branches (copy-on-write, can be created from a past point in the restore window) |
+| Supabase | Branching (preview branches) or restore into a new project |
+| PlanetScale | Development branches |
+| Any Postgres | `pg_dump` → local container; or provider snapshot restored to a new instance |
+| SQLite / D1 / Turso | Copy the file; D1/Turso restore to a point into a new database where supported |
+
+Run the migration on the branch, record the result and timing, then present the production step for the user's go-ahead.
+
+## Tool interlocks — respect, never bypass
+
+- **Prisma** (`SNAPSHOT`): dangerous CLI actions such as `migrate reset` refuse when run by a detected AI agent and require `PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION` set to the user's exact consent message. Stop and ask; only the user's literal words may be passed.
+- Prompts like "data loss will occur, continue?" (`db push`, `drizzle-kit push`) are a stop sign. Never pipe `yes`, never add `--force`/`--accept-data-loss` yourself.
+- Prefer commands that print the plan without applying: `prisma migrate diff`, `drizzle-kit generate` (then read SQL), Rails `db:migrate:status`, Django `sqlmigrate` / `migrate --plan`.
+
+## Credential hygiene to recommend
+
+- Separate dev/prod credentials and URLs; production values only in the deploy platform's secret store.
+- The agent's shell gets dev or read-only creds by default; production writes go through CI/deploy, not a laptop.
+- Migration role ≠ app role ≠ read-only inspection role.
+- PITR enabled and verified on any database an agent can reach with write rights.
+
+## Dry-run counts
+
+Before any `DELETE`/`UPDATE` you are asked to run: execute the same `WHERE` as `SELECT count(*)` (and a sample of ids), show the user, then run inside a transaction and check the affected count matches before `COMMIT`.
+
+---
+
+**Provenance:** snapshot 3 October 2026. Sources (accessed 3 Oct 2026): The Register via Slashdot, 21 Jul 2025 — https://developers.slashdot.org/story/25/07/21/1338204/ ; heise, 25 Jul 2025 — https://www.heise.de/en/news/Artificial-intelligence-Vibe-coding-service-Replit-deletes-production-database-10499597.html ; incident summary — https://openleash.com/blog/ai-agents-deleted-production-databases-replit-pocketos ; Prisma CLI reference (AI-agent consent) — https://www.prisma.io/docs/orm/reference/prisma-cli-reference . Branching surfaces from provider docs; verify flags before asserting.

package/assets/skills/durable/references/backups-and-runtime.md

@@ -1,6 +1,8 @@
 # Durable — backups, recovery & runtime data safety
 
-Load for any backup, recovery, or runtime finding. `SNAPSHOT` = sourced 17 August 2026 — provider tiers and defaults change often; verify before asserting.
+Load for any backup, recovery, or runtime finding. `SNAPSHOT` = sourced 3 October 2026 — provider tiers and defaults change often; verify before asserting.
+
+Contents: Part 1 — RPO/RTO, tiers, provider snapshot, restore drill, uploads. Part 2 — idempotency/outbox, poolers, SQLite, atomic files.
 
 ## Part 1 — Backups & recovery
 
@@ -20,19 +22,24 @@ Pick both consciously; they dictate the tier. An app where users type for hours
 
 **3-2-1 floor**: at least 3 copies, 2 different media/systems, 1 off-site (different provider or account is fine). A dump cron writing to the same VPS is one disk failure from zero.
 
-### Managed-provider baselines (`SNAPSHOT` 17 Aug 2026 — verify tiers/retention before quoting)
+### Managed-provider baselines (`SNAPSHOT` 3 Oct 2026 — verify the project's actual settings before quoting)
 
-| Provider | What you get by default/on paid tiers |
+| Provider | What the docs say |
 |---|---|
-| Supabase | Pro: 7-day PITR included; daily logical backups; restore lands a new project |
-| Neon | Continuous WAL archive; PITR up to 30 days on higher tiers; branching doubles as time-travel |
-| AWS RDS | Automated backups 1–35 days (PITR); manual snapshots on demand |
-| Crunchy Bridge | 14-day PITR by default; longer via S3 archive |
-| MongoDB Atlas | Continuous backup / cloud snapshots by tier |
+| Supabase | Daily backups: Pro 7 days, Team 14, Enterprise up to 30. PITR is a paid **add-on** (Pro+, needs at least Small compute). Backups exclude Storage objects — restoring does not bring back deleted files. Custom-role passwords not in daily backups |
+| Neon | Restore window (WAL history) powers instant restore, time travel, and branching from the past: Free capped at 6 hours (1 GB); Launch default 1 day, max 7; Scale default 1 day, max 30 |
+| PlanetScale Postgres | Scheduled + on-demand backups and PITR via WAL archiving; check the branch's schedule |
+| AWS RDS | Retention 0–35 days; default 1 day via API/CLI, 7 days via console. 0 disables automated backups and PITR |
+| Cloudflare D1 | Time Travel always on: restore to any minute in the last 30 days |
+| Turso | PITR: Free 24 hours; Developer 10, Scaler 30, Pro 90 days; deleted DBs restorable up to 5 days on paid plans |
+| Firestore | Without PITR, version retention is 1 hour; enabling PITR gives 7 days. Scheduled exports for longer history |
+| MongoDB Atlas | Cloud backups / continuous backup by cluster tier — not verified this snapshot; check the cluster's backup policy |
+
+Not re-verified this snapshot (removed): Crunchy Bridge numbers. Aurora: same 1–35 day continuous backup model as RDS — confirm per cluster.
 
 The recurring failure: the free tier's weekly backup or none at all, assumed to be PITR because the marketing page said "backups". Check the project's actual settings, not the provider's homepage.
 
-**Self-hosted Postgres**: pgBackRest, Barman, or WAL-G → S3-compatible storage. **Self-hosted/embedded SQLite**: Litestream (continuous WAL replication to object storage, near-zero RPO) or restic/borg on a schedule as the weaker floor. **Firestore/DynamoDB-style**: scheduled exports to storage — PITR is a paid or absent feature; check the project's state.
+**Self-hosted Postgres**: pgBackRest, Barman, or WAL-G → S3-compatible storage. **Self-hosted/embedded SQLite**: Litestream (continuous replication to object storage). The 2025 rewrite (v0.5.x, `SNAPSHOT`) stores changes as LTX files (sorted page changesets that compact), giving faster point-in-time restores, and uses compare-and-swap leases on object storage to avoid two primaries; configs from 0.3.x need review on upgrade. Weaker floor: `sqlite3 .backup` / `VACUUM INTO` on a schedule, shipped off-machine with restic/borg. **Firestore/DynamoDB-style**: scheduled exports to storage — PITR is a paid or absent feature; check the project's state.
 
 ### The restore drill (the only proof)
 
@@ -42,7 +49,7 @@ The recurring failure: the free tier's weekly backup or none at all, assumed to
 4. Verify the canary is absent. Time the whole operation — that measured duration is the real RTO; write it down.
 5. Repeat on a schedule (quarterly is the common bar); the drill doc itself is the runbook you'll follow at 3am.
 
-**File uploads need their own answer** — DB backups don't cover a disk of user uploads unless the backup includes the volume or the uploads live in object storage with versioning (S3 versioning or equivalent preserves deleted/overwritten objects — turn it on and state the retention). DB row + orphaned-file mismatch is a finding: cleanup discipline (delete file then row, in that order, with the row's file path recorded for resweep) or accept orphans.
+**File uploads need their own answer** — DB backups don't cover a disk of user uploads unless the backup includes the volume or the uploads live in object storage with versioning (S3 versioning or equivalent preserves deleted/overwritten objects — turn it on and add a lifecycle rule for noncurrent versions). For ransomware-grade or compliance retention, S3 Object Lock (requires versioning) stores objects write-once-read-many; use governance mode unless you truly need compliance mode, which nobody — including you — can shorten. A credential that can delete the bucket can delete its backups: keep backup copies in a different account. DB row + orphaned-file mismatch is a finding: cleanup discipline (delete file then row, in that order, with the row's file path recorded for resweep) or accept orphans.
 
 ### What a backup must exclude/include
 
@@ -63,7 +70,7 @@ Check-then-act without a constraint (`if not exists: insert`) is a bug that just
 
 ### Connection & session pitfalls (correctness, not speed)
 
-- **Transaction-mode poolers** (PgBouncer/Supavisor, Neon pooler, RDS Proxy defaults): each transaction may run on a different connection — session state breaks. Casualties: session-level `SET`/`prepared statements` (named ones), advisory locks, `LISTEN/NOTIFY`, temp tables, `COPY`. Patterns: keep per-transaction state in SQL (`SET LOCAL`), use `pg_advisory_xact_lock` (transaction-scoped), or route state-needing work to a direct/session connection.
+- **Transaction-mode poolers** (PgBouncer, Supabase port 6543 — Supavisor on the shared pooler, PgBouncer on the dedicated one; port 5432 is direct or session mode — Neon's `-pooler` endpoint which runs PgBouncer, RDS Proxy): each transaction may run on a different connection — session state breaks. Protocol-level named prepared statements work through PgBouncer ≥ 1.21 when `max_prepared_statements` is non-zero (on by default, 200, since PgBouncer 1.24; SQL-level `PREPARE` still breaks). Self-hosted PgBouncer: run ≥ 1.26.0 (23 Sep 2026), which fixes pre-auth crash/hang CVEs (CVE-2026-19888, CVE-2026-6668) and CVE-2026-6669 (`SNAPSHOT`). Run migrations over a **direct/session** connection, not the transaction pooler. Other casualties: session-level `SET`, advisory locks, `LISTEN/NOTIFY`, temp tables, `COPY`. Patterns: keep per-transaction state in SQL (`SET LOCAL`), use `pg_advisory_xact_lock` (transaction-scoped), or route state-needing work to a direct/session connection.
 - **Serverless functions**: one pool per *instance* (module scope), never per request; assume the process freezes between invocations — no in-memory "it'll flush later".
 - **Postgres connections are processes** — exhausting them fails every new client; the fix is a pooler, not a bigger `max_connections`. (Sizing the pool for throughput is lean's lane.)
 - **Always release/close in `finally`** — a leaked connection per request is a slow outage and a durability finding.
@@ -83,4 +90,4 @@ Check-then-act without a constraint (`if not exists: insert`) is a bug that just
 
 ---
 
-**Provenance:** snapshot 17 August 2026. Sources: Postgres WAL/PITR documentation and pgBackRest/Barman/WAL-G docs, Litestream documentation (SQLite WAL replication), provider documentation for Supabase/Neon/RDS/Crunchy/MongoDB Atlas backup tiers (tier specifics are `SNAPSHOT` — they change often), PgBouncer documentation (transaction-mode feature matrix), SQLite documentation (WAL, busy_timeout, foreign_keys pragma, VACUUM INTO), current disaster-recovery practice guides (3-2-1, RPO/RTO, restore drills). Provider tiers and defaults decay fastest — re-verify before asserting.
+**Provenance:** snapshot 3 October 2026. Accessed 3 Oct 2026: https://supabase.com/docs/guides/platform/backups ; https://neon.com/docs/introduction/restore-window ; https://planetscale.com/docs/postgres/backups ; https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithAutomatedBackups.BackupRetention.html ; https://developers.cloudflare.com/d1/reference/time-travel/ ; https://docs.turso.tech/features/point-in-time-recovery ; https://cloud.google.com/firestore/native/docs/use-pitr ; https://fly.io/blog/litestream-revamped/ ; https://litestream.io/ ; https://www.pgbouncer.org/config.html ; https://www.pgbouncer.org/changelog.html ; https://neon.com/docs/connect/connection-pooling ; https://supabase.com/docs/guides/database/connecting-to-postgres ; https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html . Earlier sources: Postgres WAL/PITR documentation and pgBackRest/Barman/WAL-G docs, Litestream documentation (SQLite WAL replication), provider documentation for Supabase/Neon/RDS/Crunchy/MongoDB Atlas backup tiers (tier specifics are `SNAPSHOT` — they change often), PgBouncer documentation (transaction-mode feature matrix), SQLite documentation (WAL, busy_timeout, foreign_keys pragma, VACUUM INTO), current disaster-recovery practice guides (3-2-1, RPO/RTO, restore drills). Provider tiers and defaults decay fastest — re-verify before asserting.

package/assets/skills/durable/references/migrations-and-schema.md

@@ -1,6 +1,6 @@
 # Durable — migrations & schema
 
-Load for any migration or schema finding. Postgres examples dominate because it is the default; MySQL and SQLite divergences are called out. `SNAPSHOT` = sourced 17 August 2026 — version behaviors decay, verify before asserting.
+Load for any migration or schema finding. Postgres examples dominate because it is the default; MySQL and SQLite divergences are called out. `SNAPSHOT` = sourced 3 October 2026 — version behaviours decay, verify before asserting. Run every migration on a branch or copy first, and obey SKILL.md's agent gate before applying anything to a database that may hold real data.
 
 ## The one rule that prevents most downtime
 
@@ -22,18 +22,24 @@ Rollback at any point is "flip back to the old path", not "restore the database"
 
 ## Lock-safety table (Postgres)
 
-What common DDL actually does to a live table (`SNAPSHOT` — verify per version):
+What common DDL actually does to a live table (`SNAPSHOT` — verify per version).
+
+**Always set `SET lock_timeout = '5s'` (and a `statement_timeout`) before DDL on a live table.** An `ALTER` queued behind a long transaction blocks every query behind it; the timeout turns that outage into a retryable failure. `CONCURRENTLY` operations cannot run inside a transaction block — keep them in their own migration (many ORMs wrap migrations in a transaction by default).
 
 | Operation | Behavior | Safe pattern |
 |---|---|---|
 | `ADD COLUMN` (no default) | Fast, brief lock | Fine as-is |
 | `ADD COLUMN ... NOT NULL DEFAULT x` | Fast since Postgres 11 (default not backfilled); table rewrite before 11 | Fine on ≥11; otherwise add nullable → backfill → `SET NOT NULL` |
-| `SET NOT NULL` on existing column | Full-table scan under lock | Backfill first, then set; or add a `CHECK` constraint `NOT VALID` then `VALIDATE`, then switch |
+| `SET NOT NULL` on existing column | Full-table scan under lock | Backfill first. Postgres 18: `ADD CONSTRAINT … NOT NULL col NOT VALID`, then `VALIDATE CONSTRAINT`. Older: `CHECK (col IS NOT NULL) NOT VALID` → `VALIDATE` → `SET NOT NULL` (uses the valid check, skipping the scan) → drop the check |
 | `CREATE INDEX` | Blocks writes for the whole build | `CREATE INDEX CONCURRENTLY` (drop with `DROP INDEX CONCURRENTLY`); slower, non-transactional — if it fails, drop the invalid index and retry |
 | `ADD FOREIGN KEY` | Locks while validating all rows | Two-step: `ADD CONSTRAINT ... NOT VALID` then `VALIDATE CONSTRAINT` (weaker lock) |
 | One giant `UPDATE`/`DELETE` | Locks rows, bloats the table, stalls replication | Batch: keyset-select N rows → update → sleep → repeat, resumable from last key |
 | `DROP COLUMN` | Fast (metadata) — but data is gone | Only in the contract phase, after dual-write is verified dead |
 
+**Postgres 18 notes** (`SNAPSHOT`, released 25 Sep 2025): `uuidv7()` built in; generated columns are now **virtual by default** (computed on read — say `STORED` if you need it materialised or indexed); `pg_upgrade` keeps planner statistics (not extended statistics), so post-upgrade slow plans are less likely; new clusters get data checksums by default and `pg_upgrade` needs matching checksum settings (`initdb --no-data-checksums` for old non-checksum clusters); asynchronous I/O via `io_method`. **Postgres 13 reached end of life on 13 November 2025** — no more security or data-corruption fixes; flag any project on ≤13 as High.
+
+**Tools that automate expand/contract** (`SNAPSHOT`, verify maturity before recommending): pgroll (Xata; serves old and new schema versions via views during a migration), Reshape (same idea, less active), and migration linters — Squawk (Postgres SQL lint), `strong_migrations` (Rails), `django-pg-zero-downtime-migrations` / `django-migration-linter` (Django). For Laravel, no equivalent gem is verified here — review SQL with `php artisan migrate --pretend`.
+
 MySQL has no `CONCURRENTLY`: use `ALGORITHM=INSTANT/INPLACE` where the version supports it, `gh-ost` or `pt-online-schema-change` for big tables (`SNAPSHOT` — both maintained; verify current). Postgres big-table rebuilds (PK change, deep bloat, partitioning): `pg_repack`, which rebuilds online with minimal locking and needs ~2x disk temporarily.
 
 ## Resumable backfill skeleton
@@ -54,8 +60,9 @@ From application code the same shape applies: select batch by `id > last`, write
 ## Migration tooling discipline
 
 - **Versioned, checked-in migrations from the first table** — Alembic (Python), Flyway/Liquibase (JVM), golang-migrate (Go), sqlx/Diesel (Rust), Drizzle Kit / Prisma Migrate (TS). Hand-run SQL files and "schema.sql we run sometimes" are how drift starts.
-- **Review generated SQL before it touches anything real.** ORM migration generators emit what the schema diff implies: renaming a column in the schema file becomes `DROP COLUMN` + `ADD COLUMN` — the data is dropped. Prisma flow: `migrate dev --create-only`, read the SQL, fix it to a safe expand-contract, then apply. Drizzle: generate, then read the SQL before `migrate`. This review is the single highest-value habit in this file.
-- **`db push`/sync-style commands are for throwaway dev databases only.** They bypass migration history; on a database with data they can apply destructive diffs without review. If a deploy script or CI contains `db push` against anything shared or persistent, that is a finding.
+- **Review generated SQL before it touches anything real.** ORM migration generators emit what the schema diff implies: renaming a column in the schema file becomes `DROP COLUMN` + `ADD COLUMN` — the data is dropped. Prisma flow: `migrate dev --create-only`, read the SQL, fix it to a safe expand-contract, then apply. Drizzle: `drizzle-kit generate`, read the SQL, then `drizzle-kit migrate`. This review is the single highest-value habit in this file.
+- **Prisma 7** (`SNAPSHOT`, Nov 2025): Rust-free TypeScript client via the `prisma-client` generator with a required `output`, driver adapters required, config in `prisma.config.ts`, and automatic seeding after migrate removed. Migration semantics are unchanged: `migrate dev` (dev only, may prompt to reset), `migrate deploy` (production, applies pending only), `migrate reset` (drops everything — agent-gated, see SKILL.md). Upgrading v6→v7 is a client/config change; it should not create a migration — if a diff appears, read it.
+- **`db push` / `drizzle-kit push` / sync-style commands are for throwaway dev databases only** (Drizzle documents push as its rapid-prototyping path). They bypass migration history; on a database with data they can apply destructive diffs without review. If a deploy script or CI contains `db push` against anything shared or persistent, that is a finding.
 - **Never edit an applied migration.** The hash changes, history diverges, teammates' databases desync. Corrections are new migrations.
 - **Forward-only in production.** Down migrations cannot faithfully reverse a migration that touched data (you cannot un-drop a column). "Rollback" is a new forward migration that reverses the change, written and tested like any other. Down migrations are a dev convenience at most.
 - **Apply migrations as a distinct step before the new code rolls out** (deploy script step or pre-deploy Job), never lazily on first request, never concurrently from every replica. One applier, ordered, recorded.
@@ -76,4 +83,4 @@ From application code the same shape applies: select batch by `id > last`, write
 
 ---
 
-**Provenance:** snapshot 17 August 2026. Sources: Postgres documentation (DDL locking behavior, `CONCURRENTLY`, `NOT VALID`/`VALIDATE`, ADD COLUMN default fast-path), current zero-downtime migration practice guides (expand-contract/parallel-change, batched keyset backfill, forward-only production, pre-deploy application), Prisma/Drizzle documentation (create-only review workflow, `db push` scope), MySQL online-schema-change tooling (gh-ost, pt-online-schema-change) public docs. Version-specific lock behavior decays fastest — re-verify against the running version before asserting.
+**Provenance:** snapshot 3 October 2026. Accessed 3 Oct 2026: PostgreSQL 18 release notes https://www.postgresql.org/docs/18/release-18.html and announcement https://www.postgresql.org/about/news/postgresql-18-released-3142/ ; versioning policy (13 EOL) https://www.postgresql.org/support/versioning/ ; Prisma 7 https://www.prisma.io/blog/announcing-prisma-orm-7-0-0 and https://www.prisma.io/docs/guides/upgrade-prisma-orm/v7 ; Drizzle push https://orm.drizzle.team/docs/drizzle-kit-push . Earlier sources: Postgres documentation (DDL locking behavior, `CONCURRENTLY`, `NOT VALID`/`VALIDATE`, ADD COLUMN default fast-path), current zero-downtime migration practice guides (expand-contract/parallel-change, batched keyset backfill, forward-only production, pre-deploy application), Prisma/Drizzle documentation (create-only review workflow, `db push` scope), MySQL online-schema-change tooling (gh-ost, pt-online-schema-change) public docs. Version-specific lock behavior decays fastest — re-verify against the running version before asserting.