@carllee1983/dbcli 1.31.0 → 1.37.0

package/assets/reference.md

@@ -616,6 +616,46 @@ dbcli assert "SELECT count(*) FROM orders" --expect "value > 100" --no-fail   #
 **Engines:** SQL only (PostgreSQL / MySQL / MariaDB)
 **Permission:** query-only+
 
+#### Verification artifact (--write-verification-artifact)
+
+Opt-in flag trio that persists a **VerificationArtifact JSON** (schema v1) under `<cwd>/.dbcli/verification/` after the assertion runs. The artifact is always written to `<cwd>/.dbcli/verification/` (relative to the current working directory), regardless of where the `--config` file is located.
+
+| Flag | Required | Description |
+| :--- | :--- | :--- |
+| `--write-verification-artifact` | opt-in | Trigger artifact write. No-op when no verdict has been produced. |
+| `--verification-subject <kind:name>` | yes (when flag is set) | Subject identifier. Format: `<kind>:<name>`. Allowed kinds: `recovery`, `task-pack`, `assertion`, `migration`, `backfill`, `manual`. |
+| `--verification-summary <text>` | no | Free-text summary line stored in the artifact. Default when pass: "Assertion verified the expected state." Default when fail: "Assertion did not verify the expected state." |
+
+**Output contract:**
+
+- `--format json` — `AssertVerdict` gains `verificationArtifactPath: string` pointing to the written file.
+- `--format table` — an extra `Verification artifact: <path>` line is printed after the verdict table.
+- A `--no-fail` assertion that fails still records status `not_verified` and stores `exitCode: 1` in evidence.
+
+**Planned vs Result evidence.** `dbcli skill tasks plan safe-backfill-verify --format json` returns a plan containing a `verification` block with `status: "planned"`. That block is the **planned** evidence definition — it describes which check will run. Running `assert --write-verification-artifact` on the actual data produces **result** evidence (`status: "verified"` or `status: "not_verified"`). The two records are distinct; `"planned"` does **not** indicate that verification has run or passed.
+
+> **Casting note:** Postgres returns `count(*)` and `sum()` as bigint (a string in the result set). `value ==` uses strict equality, so `"0" == 0` is false. Cast to `::int` (`count(*)::int`) to ensure numeric comparison works correctly.
+
+```bash
+dbcli assert "SELECT count(*)::int FROM orders WHERE status IS NULL" \
+  --expect "value == 0" \
+  --write-verification-artifact \
+  --verification-subject backfill:safe-backfill-verify
+
+dbcli assert "SELECT count(*)::int FROM orders WHERE status IS NULL" \
+  --expect "value == 0" \
+  --write-verification-artifact \
+  --verification-subject backfill:safe-backfill-verify \
+  --verification-summary "Post-backfill null-status count is zero."
+
+# --no-fail: exits 0 but still records not_verified on failure
+dbcli assert "SELECT count(*)::int FROM orders WHERE status IS NULL" \
+  --expect "value == 0" \
+  --no-fail \
+  --write-verification-artifact \
+  --verification-subject backfill:safe-backfill-verify
+```
+
 ### proxy
 
 Local-development **observability proxy** for MySQL/MariaDB/PostgreSQL. Inserts dbcli
@@ -1104,6 +1144,243 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 
 **Permission:** n/a
 
+### verify
+
+Run a verification scenario. `verify` **runs** verification scenarios (safe-backfill,
+migration) and never executes writes/DDL. `verification` **inspects and manages** the
+local result artifacts those scenarios produce under `.dbcli/verification/`.
+
+```bash
+# Preflight (default): read-only guards + the exact after-write command. No artifact.
+dbcli verify safe-backfill \
+  --table users \
+  --query "UPDATE users SET status = 1 WHERE status IS NULL" \
+  --verify-query "SELECT count(*)::int AS n FROM users WHERE status IS NULL" \
+  --expect "value == 0"
+
+# After-write: re-run guards, run the read-back assertion, write a v1 artifact.
+dbcli verify safe-backfill ... --after-write
+
+# JSON for agents.
+dbcli verify safe-backfill ... --format json
+```
+
+Options: `--table` (req), `--query` (req, analyzed not executed), `--verify-query`
+(req, **plain SELECT only**), `--expect` (req), `--after-write`, `--format <table|json>`,
+`--subject-name <name>`, `--summary <text>`.
+
+Guard constraints (fail closed): `--verify-query` must be a **plain `SELECT`** —
+`EXPLAIN`/`EXPLAIN ANALYZE`, `SHOW`, `DESCRIBE`, and data-modifying CTEs are rejected
+(on PostgreSQL `EXPLAIN ANALYZE <write>` actually performs the write). The `--query`
+**UPDATE target must equal `--table`**, compared schema-aware (`public.users` ≠
+`audit.users`). The persisted artifact stores only a bounded, literal-free label of the
+verify-query and `--expect` — string, numeric, and dollar-quoted literals are stripped,
+so raw SQL/values are never written to disk. The printed after-write
+command is shell-escaped and carries through `--subject-name`/`--summary`/non-default
+`--format`. For repeated backfills on the same table, pass a unique `--subject-name` so
+each operation is independently traceable (the subject defaults to `backfill:<table>`).
+
+Status: `ready`/`blocked` in preflight (no artifact); `verified`, `not_verified`,
+`blocked`, or `indeterminate` in after-write (artifact written). `blocked` = a guard
+failed (blacklist/schema/plan/verify-query-not-plain-SELECT/target-table-mismatch);
+`not_verified` = the read-back contradicted `--expect`; `indeterminate` = the assertion
+could not produce a trustworthy verdict. Inspect the result with
+`dbcli verification show <artifact-id>`.
+
+#### `verify migration`
+
+Preflight or after-write verification for a schema migration. **This command never
+executes DDL** — it analyzes the proposed `ALTER TABLE`, runs read-only guards, and
+(in after-write mode) records evidence after you apply the migration externally.
+
+```bash
+# Preflight: read-only guards + the exact after-write command. Returns ready or blocked.
+dbcli verify migration \
+  --table users \
+  --ddl "ALTER TABLE users ADD COLUMN verified_at TIMESTAMPTZ" \
+  --verify-query "SELECT count(*)::int AS n FROM users WHERE verified_at IS NOT NULL" \
+  --expect "value == 0"
+
+# After the migration is applied externally, record evidence:
+dbcli verify migration ... --after-write
+
+# JSON for agents.
+dbcli verify migration ... --format json
+```
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--table <table>` | yes | Table affected by the migration. |
+| `--ddl <sql>` | yes | Proposed migration DDL, analyzed but never executed. MVP accepts `ALTER TABLE` only. |
+| `--verify-query <sql>` | yes | Plain `SELECT` for post-migration read-back verification. |
+| `--expect <expr>` | yes | Assertion expression for the read-back result. |
+| `--after-write` | no | Run the post-migration assertion and write a v1 artifact. |
+| `--format <table\|json>` | no | Output format, default `table`. |
+| `--subject-name <name>` | no | Artifact subject name. Default is the table name. |
+| `--summary <text>` | no | Optional artifact summary override. |
+
+Preflight returns `ready` or `blocked` and prints the exact after-write command;
+**`ready` is not `verified`** — it only means the guards passed. After-write maps the
+read-back assertion to `verified` / `not_verified` / `indeterminate`, and a failed
+guard to `blocked`. `CREATE TABLE`, `DROP TABLE`, `CREATE INDEX`, and multi-statement
+DDL are blocked in the MVP.
+
+The `ALTER TABLE` target may be `table`, `schema.table`, or `catalog.schema.table`.
+Each segment is a simple unquoted name (`[A-Za-z_][A-Za-z0-9_]*`) or a quoted
+identifier — double-quoted (`"…"`), backtick-quoted (`` `…` ``), or bracket-quoted
+(`[…]`) — so `"user accounts"` or `"tenant-1"."orders"` are accepted. Targets that
+cannot be fully parsed under this contract (unterminated quotes, unsupported escapes,
+or more than three parts) are blocked before the after-write assertion with a
+"could not be parsed" reason, distinct from the `must match --table` mismatch reason.
+
+### verification
+
+(v1.33.0+) Local **VerificationArtifact** inspection and lifecycle surface over
+`<cwd>/.dbcli/verification/` (always relative to the current working directory,
+regardless of `--config` location). `list`, `show`, and `summary` are read-only;
+`prune` is a local lifecycle command — dry-run by default, deleting only with
+`--execute --force`. Requires no database connection and performs no audit writes.
+
+**Subcommands:** `list` · `show` · `summary` · `prune`
+
+#### `verification list`
+
+List verification artifacts on disk, with optional filters.
+
+```bash
+dbcli verification list --format json
+dbcli verification list --status verified
+dbcli verification list --subject backfill
+dbcli verification list --subject backfill:safe-backfill-verify
+dbcli verification list --limit 20 --format json
+dbcli verification list --include-invalid --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--format <json\|table>` | Output format. | `json` |
+| `--limit <n>` | Maximum number of entries to return. | `20` |
+| `--status <status>` | Filter by status. One of: `verified`, `not_verified`, `indeterminate`, `blocked`. | all |
+| `--subject <kind[:name]>` | Filter by subject kind or exact `kind:name`. Allowed kinds: `recovery`, `task-pack`, `assertion`, `migration`, `backfill`, `manual`. | all |
+| `--include-invalid` | Surface malformed artifact files (normally skipped silently). Invalid files are returned as a separate top-level `invalid` array in JSON output, each entry shaped `{ "path": "...", "filename": "...", "error": "..." }`. When off, `invalid` is `[]`. | off |
+
+**Missing directory:** if `.dbcli/verification/` does not exist, exits `0` with an
+empty result (list: `[]`, summary: zero counts).
+
+**Malformed files:** by default, files that cannot be parsed as valid VerificationArtifact
+JSON are silently skipped. Pass `--include-invalid` to surface them.
+
+#### `verification show`
+
+Print a single verification artifact by its id (the artifact's `id` field) or by
+the path to the artifact file.
+
+```bash
+dbcli verification show abc123 --format json
+dbcli verification show abc123 --format table
+dbcli verification show .dbcli/verification/abc123.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `<id-or-path>` | Positional. The artifact `id` (format `ver_<base36>_<hex>`), a unique id prefix, the artifact filename, or a path to the file inside `.dbcli/verification/`. | required |
+| `--format <json\|table>` | Output format. | `json` |
+
+**Exit codes:**
+- `0` — artifact found and valid.
+- `1` — id or path not found, or the artifact file is malformed (parse error).
+
+#### `verification summary`
+
+Aggregate verification artifacts into status counts, optionally filtered.
+
+```bash
+dbcli verification summary --format json
+dbcli verification summary --status not_verified --format json
+dbcli verification summary --subject migration --format json
+dbcli verification summary --subject migration:add-status-column --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--format <json\|table>` | Output format. | `json` |
+| `--status <status>` | Filter to a single status before summarising. | all |
+| `--subject <kind[:name]>` | Filter by subject kind or exact `kind:name`. | all |
+| `--latest-only` | Narrow to the latest matching valid artifact plus status counts; the `subjects` breakdown is omitted. Missing artifacts return exit `0` with `latest: null`. | off |
+
+**Output shape (JSON):**
+```json
+{
+  "storageDir": "/abs/path/.dbcli/verification",
+  "latest": {
+    "path": "...",
+    "id": "ver_...",
+    "createdAt": "2026-06-19T01:02:03.000Z",
+    "status": "verified",
+    "subject": { "kind": "backfill", "name": "safe-backfill-verify" },
+    "summary": "..."
+  },
+  "counts": { "total": 4, "verified": 2, "not_verified": 1, "indeterminate": 0, "blocked": 1, "invalid": 0 },
+  "subjects": [
+    { "subject": { "kind": "backfill", "name": "safe-backfill-verify" }, "total": 3, "latestStatus": "verified", "latestCreatedAt": "2026-06-19T01:02:03.000Z" }
+  ]
+}
+```
+
+`latest` is `null` when no valid artifacts match the filters.
+
+#### `verification prune`
+
+Preview or delete local verification artifacts under `<cwd>/.dbcli/verification/` by
+explicit retention criteria. **Dry-run by default**; deletes only with `--execute --force`.
+
+```bash
+dbcli verification prune --older-than 30d --format json          # preview candidates
+dbcli verification prune --older-than 30d --execute --force      # delete after preview
+dbcli verification prune --older-than 90d --status verified --keep-latest 50 --execute --force
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--format <format>` | `json` | `json` or `table`. JSON is the authoritative contract. |
+| `--older-than <Nd>` | required | Minimum age in whole days (`7d`, `30d`, `365d`). |
+| `--keep-latest <n>` | `20` | Always protect the latest N valid artifacts across all subjects/statuses before filters. `0` protects none. |
+| `--status <status>` | none | Select only valid artifacts with this status. |
+| `--subject <kind:name>` | none | Select only valid artifacts with this subject. |
+| `--include-invalid` | `false` | Also select malformed `verification-*.json` files, by file mtime. |
+| `--execute` | `false` | Delete instead of preview. Requires `--force`. |
+| `--force` | `false` | Acknowledge deletion; required with `--execute`. |
+
+Safety: deletion is scoped to regular `verification-*.json` files inside
+`.dbcli/verification/`; symlinks, directories, and path escapes are skipped with a
+reason. No database connection is opened and no audit entry is written. JSON output
+includes `storageDir`, `dryRun`, `cutoff`, `criteria`, `protected`, `candidates`,
+`deleted`, and `skipped`.
+
+**Statuses:**
+
+| Status | Meaning |
+|---|---|
+| `verified` | The assertion ran and evidence matched the expected state. |
+| `not_verified` | The assertion ran and evidence contradicted the expected state. |
+| `indeterminate` | The assertion ran but evidence was ambiguous (JSON parse failure, missing field, gate skip). |
+| `blocked` | Verification could not run due to config, permission, schema, placeholder, or safety gates. |
+
+**Subject kinds:**
+
+| Kind | Produced by |
+|---|---|
+| `recovery` | Post-recovery verification assertions. |
+| `task-pack` | Assertions generated by task pack plans. |
+| `assertion` | General-purpose inline assertions. |
+| `migration` | Schema migration pre/post checks. |
+| `backfill` | Data backfill verification assertions. |
+| `manual` | Manually triggered or ad-hoc verification runs. |
+
+**Storage root:** `<cwd>/.dbcli/verification/` (cwd-relative; independent of `--config`).
+
+**Permission:** n/a
+
 ### doctor
 
 Run diagnostic checks on environment, configuration, connection, and data.
@@ -1238,6 +1515,7 @@ dbcli skill --install gemini                 # install to ~/.gemini/skills/dbcli
 dbcli skill --install antigravity            # install to ~/.gemini/antigravity-cli/skills/dbcli/
 dbcli skill --install copilot                # install to .github/skills/dbcli/ (repo-local)
 dbcli skill --install cursor                 # install to .cursor/skills/dbcli/ (repo-local)
+dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 ```
 
 **Options:**
@@ -1247,6 +1525,9 @@ dbcli skill --install cursor                 # install to .cursor/skills/dbcli/
 **Notes:**
 - Both files come straight from `assets/SKILL.md` + `assets/reference.md` inside the dbcli package — no runtime rendering. Keep these in sync when shipping a release.
 - `claude` / `gemini` / `antigravity` install paths are user-global; `copilot` / `cursor` are repo-local under `.github/` / `.cursor/`.
+- Cursor can install through `/add-plugin dbcli-agent` when available in Cursor's plugin marketplace; this repo includes `.cursor-plugin/plugin.json`. Instruction-file fallback options remain documented in `plugins/dbcli-agent/INSTALL.md#cursor`.
+- Codex can consume the repo through the Ponytail-style marketplace layout at `.agents/plugins/marketplace.json` and `.codex-plugin/plugin.json`; plugin installs provide the skill from `skills/dbcli/`, and the skill falls back to `bunx @carllee1983/dbcli` when `dbcli` is not on `PATH`.
+- Agent plugin installation details live in `plugins/dbcli-agent/INSTALL.md`, including Codex, Claude Code, GitHub Copilot CLI, Antigravity (`agy`), and Cursor targets.
 - `gemini` (Gemini CLI) is retained for now but is being phased out in favour of `antigravity` (Antigravity CLI), Google's successor terminal agent.
 - Re-running `--install` overwrites the existing skill atomically; no prompt.
 
@@ -1272,7 +1553,11 @@ dbcli skill tasks plan diagnose-slow-query --param query="..." --format json
 a read-only (`plan-only`) pack taking a required `table` parameter that walks
 `blacklist list` → `schema <table> --format json` → `guide index-usage --format json`.
 `dbcli inspect` suggests `analyze-table-perf` automatically for the hottest table
-in recent audit activity.
+in recent audit activity. Additional read-only packs ship for common agent
+workflows: `audit-permissions` (permission/blacklist audit), `safe-backfill`
+(plan a write with blacklist+schema+risk checks), `schema-drift-review` (cached
+vs live schema diff), and `connection-health` (reachability/config/capacity
+triage). Run `dbcli skill tasks list` for the full set.
 
 ```bash
 dbcli skill tasks plan analyze-table-perf --param table=betting_logs --format json

package/assets/tasks/audit-permissions.md

@@ -0,0 +1,35 @@
+---
+name: audit-permissions
+description: Audit the active permission tier and blacklist coverage before granting an agent write access.
+tags: [security, permissions, readonly]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: false
+    description: Optional table to spot-check column-level blacklist coverage (exact name; confirm via `dbcli list`).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+steps:
+  - type: command
+    command: status
+    reason: Read the current permission tier and connection summary (no credentials).
+    risk: readonly
+  - type: command
+    command: blacklist list
+    reason: Enumerate every protected table and column so sensitive data is accounted for.
+    risk: readonly
+  - type: command
+    command: guide permissions --format json
+    reason: Get the deterministic next-step plan for reviewing what the current tier allows.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task before widening an agent's access (e.g. query-only → read-write) or
+when a user asks "what can this connection touch?". Confirm the permission tier is
+the minimum required and that every sensitive table/column already appears in the
+blacklist. Do not run write operations. If a `table` is supplied, follow up with
+`dbcli schema {{table}} --format json` to verify no sensitive column is exposed.

package/assets/tasks/connection-health.md

@@ -0,0 +1,37 @@
+---
+name: connection-health
+description: Quick read-only health check of the active connection (reachability, config, capacity signals).
+tags: [diagnostics, health, readonly]
+engines: [postgres, mysql]
+params:
+  section:
+    type: string
+    required: false
+    default: health
+    description: Which report section to pull.
+    enum: [health, capacity, perf]
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+steps:
+  - type: command
+    command: status
+    reason: Confirm the connection and permission tier resolve without exposing credentials.
+    risk: readonly
+  - type: command
+    command: doctor
+    reason: Run environment, config, connection and schema-cache diagnostics.
+    risk: readonly
+  - type: command
+    command: report --section {{section}} --for-agent
+    reason: Pull the diagnostic report section for a structured health snapshot.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task as a first-touch triage when a connection "feels" wrong or before a
+larger operation — it answers "can I reach the DB, is the config sane, and are there
+obvious health/capacity red flags?" entirely read-only. If `doctor` reports a stale
+schema cache, refresh it before trusting cached schema. Escalate to
+`dbcli guide capacity` or `dbcli report --section perf` for deeper analysis.

package/assets/tasks/migration-review.md

@@ -0,0 +1,41 @@
+---
+name: migration-review
+description: Capture pre-change schema evidence and preview a migration's DDL before it is applied.
+tags: [migration, schema, readonly]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: true
+    description: The table the migration alters (exact name; confirm via `dbcli list`).
+  ddl:
+    type: string
+    required: true
+    description: The migration DDL statement to preview (not executed by this task).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm the migration's target table and columns are not protected before previewing changes.
+    risk: readonly
+  - type: command
+    command: schema {{table}} --format json
+    reason: Capture the pre-change live schema as evidence to diff against after the migration lands.
+    risk: readonly
+  - type: command
+    command: plan "{{ddl}}"
+    reason: Preview the migration DDL's risk and scope without executing it.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task before applying a schema migration. It only PLANS — it never runs DDL.
+Save the pre-change `schema {{table}} --format json` output as the baseline. After the
+migration is applied (out of band, via your migration tool), re-run
+`schema {{table}} --format json` and diff the two to confirm the change matches intent.
+Always prepare and record an explicit rollback statement before applying. Requires
+data-admin permission to actually run DDL — this task does not grant it.

package/assets/tasks/pr-database-review.md

@@ -0,0 +1,38 @@
+---
+name: pr-database-review
+description: Review a PR's changed persistence paths, queries and migrations for database risk before merge.
+tags: [review, safety, readonly]
+engines: [postgres, mysql]
+params:
+  query:
+    type: string
+    required: true
+    description: The most significant changed SQL/persistence statement to analyze (not executed by this task).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm the tables and columns touched by the PR are protected as expected before reviewing changed queries.
+    risk: readonly
+  - type: command
+    command: inspect --format json
+    reason: Capture connection, permission tier and schema-cache context for the review.
+    risk: readonly
+  - type: command
+    command: plan "{{query}}"
+    reason: Analyze the riskiest changed statement's scope and safety without executing it.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when reviewing a pull request that changes persistence: queries, ORM
+models, migrations, data exports or fixtures. It only PLANS — it never writes. Walk
+the changed files and, for each risky persistence path, re-run `plan "<sql>"` on the
+specific statement. Cross-check the `blacklist list` output against any new columns
+the PR exposes (exports, logs, serializers). For schema/migration changes prefer the
+`migration-review` pack; for index/perf concerns prefer `slow-endpoint-investigation`.
+Do not run write operations or DDL as part of the review.

package/assets/tasks/safe-backfill-verify.md

@@ -0,0 +1,63 @@
+---
+name: safe-backfill-verify
+description: Plan a safe backfill/UPDATE and a read-back assertion that verifies the write achieved its goal.
+tags: [data, write, safety, verification]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: true
+    description: The table the backfill writes to (exact name; confirm via `dbcli list`).
+  query:
+    type: string
+    required: true
+    description: The backfill UPDATE statement to analyze (not executed by this task).
+  verify_query:
+    type: string
+    required: true
+    description: A read-only SELECT (typically count(*)) that proves the backfill's outcome.
+  expect:
+    type: string
+    required: true
+    description: The assertion expression for `assert --expect`, e.g. "rows == 0" or "value > 0".
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm the target table and its columns are not protected before planning a write.
+    risk: readonly
+  - type: command
+    command: schema {{table}} --format json
+    reason: Verify the exact column names and types the backfill will touch.
+    risk: readonly
+  - type: command
+    command: plan "{{query}}"
+    reason: Analyze the UPDATE's risk and scope without executing it.
+    risk: readonly
+  - type: command
+    command: assert "{{verify_query}}" --expect "{{expect}}"
+    reason: Read-back verification — confirm the backfill achieved its goal after the write.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when a backfill must be both safe and provably correct. This task only
+PLANS — the execution sequence the agent runs manually is:
+
+1. Review the `plan "{{query}}"` output and confirm a narrow `WHERE` clause.
+2. Capture the scope: run `assert "{{verify_query}}" --expect "{{expect}}"` BEFORE the
+   write to record the starting count (or run the SELECT directly), so the expected
+   delta is known.
+3. Preview the write with the matching write command, for example
+   `dbcli update <table> --where "<predicate>" --set '<json>' --dry-run`. Keep raw
+   SQL in `plan "{{query}}"`; `query` does not dry-run arbitrary writes.
+4. Execute once the dry-run looks correct: re-run the write command without `--dry-run`
+   and with the required confirmation/force flag for your environment.
+5. Verify: re-run `assert "{{verify_query}}" --expect "{{expect}}"` AFTER the write.
+   `verified` means the read-back matched; anything else means stop and recover.
+
+Requires read-write (or higher) permission to actually execute the write.

package/assets/tasks/safe-backfill.md

@@ -0,0 +1,42 @@
+---
+name: safe-backfill
+description: Plan a safe data backfill/UPDATE with blacklist, schema and risk checks before any write.
+tags: [data, write, safety]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: true
+    description: The table the backfill writes to (exact name; confirm via `dbcli list`).
+  query:
+    type: string
+    required: true
+    description: The backfill UPDATE statement to analyze (not executed by this task).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm the target table and its columns are not protected before planning a write.
+    risk: readonly
+  - type: command
+    command: schema {{table}} --format json
+    reason: Verify the exact column names and types the backfill will touch.
+    risk: readonly
+  - type: command
+    command: plan "{{query}}"
+    reason: Analyze the UPDATE's risk and scope without executing it.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when a user wants to backfill or correct existing rows. This task only
+PLANS — it never writes. After reviewing the plan, run the real backfill manually in
+two steps: first `dbcli update ... --dry-run` (or `dbcli query "<sql>" --dry-run`) to
+preview the generated SQL, then re-run with `--execute` only once the dry-run looks
+correct. Prefer a narrow `WHERE` clause and verify the affected row count with a
+read-only `SELECT count(*)` before writing. Requires read-write (or higher) permission
+to actually execute.

package/assets/tasks/schema-drift-review.md

@@ -0,0 +1,37 @@
+---
+name: schema-drift-review
+description: Detect drift between the cached/committed schema and the live database for one table.
+tags: [diagnostics, schema, readonly]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: true
+    description: The table to compare against its cached schema (exact name; confirm via `dbcli list`).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm the table is inspectable and not protected before reading its schema.
+    risk: readonly
+  - type: command
+    command: doctor
+    reason: Report the schema-cache age so a stale cache can be ruled out as the cause of drift.
+    risk: readonly
+  - type: command
+    command: schema {{table}} --format json
+    reason: Pull the current live schema to diff against the cached/committed definition.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when a migration may have landed out of band, or a query fails on a
+column that "should" exist. Compare the live `schema {{table}}` output against the
+`schema` block committed in the `.dbcli` config (or the cached snapshot). If they
+disagree, the cache is stale or the live DB drifted — surface the specific column
+differences. Do not run write operations or DDL. Refresh the cache before acting on a
+stale snapshot.

package/assets/tasks/slow-endpoint-investigation.md

@@ -0,0 +1,40 @@
+---
+name: slow-endpoint-investigation
+description: Connect proxy, explain and missing-index evidence to investigate a slow endpoint's query.
+tags: [diagnostics, performance, readonly]
+engines: [postgres, mysql]
+params:
+  query:
+    type: string
+    required: true
+    description: The suspected slow SQL statement behind the endpoint (not executed by this task).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm sensitive tables and columns are protected before inspecting query internals.
+    risk: readonly
+  - type: command
+    command: proxy analyze --format json
+    reason: Aggregate observed slow queries and N+1 patterns from the local proxy event log.
+    risk: readonly
+  - type: command
+    command: explain "{{query}}"
+    reason: Inspect the query plan for the suspected statement without running it for effect.
+    risk: readonly
+  - type: command
+    command: guide missing-index-for "{{query}}" --format json
+    reason: Get advisory index candidates that could remove the slow scan.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when an endpoint is slow and you want evidence, not guesses. Start from
+`proxy analyze` (requires that the local observability proxy has captured traffic) to
+find the hottest query/table, then `explain` that statement and review
+`guide missing-index-for` candidates. Index advice is ADVISORY: do not create indexes
+directly — route any proposed index through the `migration-review` pack first, then
+verify before/after with `snapshot`/`assert` or `report --section perf` deltas.