@carllee1983/dbcli 1.37.0 → 1.37.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.37.0",
+  "version": "1.37.1",
   "description": "Database CLI skill and command reference for AI agents.",
   "author": {
     "name": "Carl Lee",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.37.0",
+  "version": "1.37.1",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -160,6 +160,7 @@ Developer workflow guardrails:
   (`--after-write`) when durable evidence is required. Never executes the write.
 - `tasks plan migration-review` — when the user needs a migration plan only (plan output, no DDL executed).
 - `verify migration` — preflight a schema migration (analyze DDL, run guards) and after the migration is applied externally (`--after-write`) to record evidence. Never executes DDL.
+- `verify rollback --kind <ddl|dml>` — verify that a reverting change restored the prior state: preflight analyzes the reverting `ALTER TABLE` (`--kind ddl`) or `UPDATE` (`--kind dml`) via `--statement`, and `--after-write` records evidence after you apply it externally. Never executes the statement.
 - `verification show <id>` — cite the final artifact.
 
 Full flags, per-command copy-paste blocks, `migrate` DDL, interactive `shell`, and MongoDB/Redis/ES walkthroughs are in [reference.md](reference.md) (installed next to this file).

package/.cursor/skills/dbcli/reference.md

@@ -1147,8 +1147,8 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 ### 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/`.
+migration, rollback) 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.
@@ -1233,6 +1233,67 @@ cannot be fully parsed under this contract (unterminated quotes, unsupported esc
 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.
 
+#### `verify rollback`
+
+(v1.37.0+) Preflight or after-write verification for an **externally-applied rollback** —
+confirming that after you reverted a change the database is back to the expected prior
+state. **This command never executes the reverting statement** — it analyzes it, runs
+read-only guards, and (in after-write mode) records evidence after you apply the rollback
+externally. One scenario covers both schema and data rollbacks via a required
+`--kind <ddl|dml>` selector:
+
+- `--kind ddl` — revert a schema migration. `--statement` is a single `ALTER TABLE`
+  (e.g. dropping a column a forward migration added). Reuses the `migration` DDL gates.
+- `--kind dml` — revert a data change. `--statement` is a single `UPDATE` that restores
+  prior values. Reuses the `safe-backfill` UPDATE plan gates.
+
+```bash
+# Schema rollback (--kind ddl) — preflight, then record evidence after applying it.
+dbcli verify rollback \
+  --kind ddl \
+  --table users \
+  --statement "ALTER TABLE users DROP COLUMN verified_at" \
+  --verify-query "SELECT count(*)::int AS n FROM information_schema.columns WHERE table_name = 'users' AND column_name = 'verified_at'" \
+  --expect "value == 0"
+dbcli verify rollback --kind ddl ... --after-write
+
+# Data rollback (--kind dml) — revert an UPDATE, then read back.
+dbcli verify rollback \
+  --kind dml \
+  --table users \
+  --statement "UPDATE users SET status = NULL WHERE status = 1" \
+  --verify-query "SELECT count(*)::int AS n FROM users WHERE status = 1" \
+  --expect "value == 0"
+dbcli verify rollback --kind dml ... --after-write
+
+# JSON for agents (both kinds).
+dbcli verify rollback --kind ddl ... --format json
+```
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--kind <ddl\|dml>` | yes | Reverting-statement grammar: `ddl` (single `ALTER TABLE`) or `dml` (single `UPDATE`). Invalid value fails closed before any DB connection. |
+| `--table <table>` | yes | Table affected by the rollback. |
+| `--statement <sql>` | yes | Proposed reverting statement, analyzed but never executed. |
+| `--verify-query <sql>` | yes | Plain `SELECT` for post-rollback read-back verification. |
+| `--expect <expr>` | yes | Assertion expression for the read-back result. |
+| `--after-write` | no | Run the post-rollback 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. |
+
+A single `--statement` flag is used for both kinds (instead of reusing `--ddl` / `--query`)
+to keep the dual-kind surface honest. The guard sequence, statuses (`ready`/`blocked` in
+preflight; `verified` / `not_verified` / `blocked` / `indeterminate` in after-write), and
+exit codes are identical to the other two scenarios. **MVP restrictions:** DML rollback is
+`UPDATE`-only (INSERT/DELETE reverts deferred); DDL rollback is single `ALTER TABLE` only,
+using the same identifier contract as `verify migration`.
+
+The artifact schema is unchanged: a rollback reuses the existing subject kinds —
+`--kind ddl` → `migration`, `--kind dml` → `backfill` — and records its provenance via
+`subject.command = "verify rollback"` plus the summary, so `verification` filters and
+retention are unaffected.
+
 ### verification
 
 (v1.33.0+) Local **VerificationArtifact** inspection and lifecycle surface over

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "1.37.0",
+  "version": "1.37.1",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/SKILL.md

@@ -160,6 +160,7 @@ Developer workflow guardrails:
   (`--after-write`) when durable evidence is required. Never executes the write.
 - `tasks plan migration-review` — when the user needs a migration plan only (plan output, no DDL executed).
 - `verify migration` — preflight a schema migration (analyze DDL, run guards) and after the migration is applied externally (`--after-write`) to record evidence. Never executes DDL.
+- `verify rollback --kind <ddl|dml>` — verify that a reverting change restored the prior state: preflight analyzes the reverting `ALTER TABLE` (`--kind ddl`) or `UPDATE` (`--kind dml`) via `--statement`, and `--after-write` records evidence after you apply it externally. Never executes the statement.
 - `verification show <id>` — cite the final artifact.
 
 Full flags, per-command copy-paste blocks, `migrate` DDL, interactive `shell`, and MongoDB/Redis/ES walkthroughs are in [reference.md](reference.md) (installed next to this file).

package/.github/skills/dbcli/reference.md

@@ -1147,8 +1147,8 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 ### 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/`.
+migration, rollback) 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.
@@ -1233,6 +1233,67 @@ cannot be fully parsed under this contract (unterminated quotes, unsupported esc
 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.
 
+#### `verify rollback`
+
+(v1.37.0+) Preflight or after-write verification for an **externally-applied rollback** —
+confirming that after you reverted a change the database is back to the expected prior
+state. **This command never executes the reverting statement** — it analyzes it, runs
+read-only guards, and (in after-write mode) records evidence after you apply the rollback
+externally. One scenario covers both schema and data rollbacks via a required
+`--kind <ddl|dml>` selector:
+
+- `--kind ddl` — revert a schema migration. `--statement` is a single `ALTER TABLE`
+  (e.g. dropping a column a forward migration added). Reuses the `migration` DDL gates.
+- `--kind dml` — revert a data change. `--statement` is a single `UPDATE` that restores
+  prior values. Reuses the `safe-backfill` UPDATE plan gates.
+
+```bash
+# Schema rollback (--kind ddl) — preflight, then record evidence after applying it.
+dbcli verify rollback \
+  --kind ddl \
+  --table users \
+  --statement "ALTER TABLE users DROP COLUMN verified_at" \
+  --verify-query "SELECT count(*)::int AS n FROM information_schema.columns WHERE table_name = 'users' AND column_name = 'verified_at'" \
+  --expect "value == 0"
+dbcli verify rollback --kind ddl ... --after-write
+
+# Data rollback (--kind dml) — revert an UPDATE, then read back.
+dbcli verify rollback \
+  --kind dml \
+  --table users \
+  --statement "UPDATE users SET status = NULL WHERE status = 1" \
+  --verify-query "SELECT count(*)::int AS n FROM users WHERE status = 1" \
+  --expect "value == 0"
+dbcli verify rollback --kind dml ... --after-write
+
+# JSON for agents (both kinds).
+dbcli verify rollback --kind ddl ... --format json
+```
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--kind <ddl\|dml>` | yes | Reverting-statement grammar: `ddl` (single `ALTER TABLE`) or `dml` (single `UPDATE`). Invalid value fails closed before any DB connection. |
+| `--table <table>` | yes | Table affected by the rollback. |
+| `--statement <sql>` | yes | Proposed reverting statement, analyzed but never executed. |
+| `--verify-query <sql>` | yes | Plain `SELECT` for post-rollback read-back verification. |
+| `--expect <expr>` | yes | Assertion expression for the read-back result. |
+| `--after-write` | no | Run the post-rollback 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. |
+
+A single `--statement` flag is used for both kinds (instead of reusing `--ddl` / `--query`)
+to keep the dual-kind surface honest. The guard sequence, statuses (`ready`/`blocked` in
+preflight; `verified` / `not_verified` / `blocked` / `indeterminate` in after-write), and
+exit codes are identical to the other two scenarios. **MVP restrictions:** DML rollback is
+`UPDATE`-only (INSERT/DELETE reverts deferred); DDL rollback is single `ALTER TABLE` only,
+using the same identifier contract as `verify migration`.
+
+The artifact schema is unchanged: a rollback reuses the existing subject kinds —
+`--kind ddl` → `migration`, `--kind dml` → `backfill` — and records its provenance via
+`subject.command = "verify rollback"` plus the summary, so `verification` filters and
+retention are unaffected.
+
 ### verification
 
 (v1.33.0+) Local **VerificationArtifact** inspection and lifecycle surface over

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.37.1] - 2026-06-22 - Skill Documentation Parity for verify rollback
+
+### Fixed
+
+- **Skill 文件補上 `verify rollback`。** v1.37.0 出貨的 `dbcli verify rollback` 先前未寫進可安裝的 skill 文件，導致安裝 skill 的 agent 不知道此指令存在。於 `assets/SKILL.md` / `assets/SKILL.zh-TW.md` 加入工作流速覽行，並於 `assets/reference.md` 新增完整 `#### verify rollback` 區段（`--kind ddl|dml`、`--statement`、preflight / after-write 雙範例、MVP 限制與 artifact subject 對應）。透過 `plugin:sync` 將內容傳播到所有受管理的平台副本（`skills/`、`.github/skills/`、`.cursor/`、`.windsurf/`、`plugins/`）。純文件變更，無程式行為更動。
+
 ## [1.37.0] - 2026-06-22 - Rollback Scenario & Nested Shell Completions
 
 ### Added

package/assets/SKILL.md

@@ -160,6 +160,7 @@ Developer workflow guardrails:
   (`--after-write`) when durable evidence is required. Never executes the write.
 - `tasks plan migration-review` — when the user needs a migration plan only (plan output, no DDL executed).
 - `verify migration` — preflight a schema migration (analyze DDL, run guards) and after the migration is applied externally (`--after-write`) to record evidence. Never executes DDL.
+- `verify rollback --kind <ddl|dml>` — verify that a reverting change restored the prior state: preflight analyzes the reverting `ALTER TABLE` (`--kind ddl`) or `UPDATE` (`--kind dml`) via `--statement`, and `--after-write` records evidence after you apply it externally. Never executes the statement.
 - `verification show <id>` — cite the final artifact.
 
 Full flags, per-command copy-paste blocks, `migrate` DDL, interactive `shell`, and MongoDB/Redis/ES walkthroughs are in [reference.md](reference.md) (installed next to this file).

package/assets/SKILL.zh-TW.md

@@ -134,6 +134,7 @@ dbcli inspect --for-agent --no-connect --format json
 - `verify safe-backfill` — 在真實 backfill 前（preflight）及執行後（`--after-write`）使用，需要持久佐證時必用。永不執行寫入。
 - `tasks plan migration-review` — 當使用者只需要 migration 計畫時使用（僅輸出計畫，不執行 DDL）。
 - `verify migration` — 預檢 schema migration（分析 DDL、執行防護），並在外部套用 migration 後（`--after-write`）記錄佐證。永不執行 DDL。
+- `verify rollback --kind <ddl|dml>` — 驗證「還原變更」是否讓資料庫回到先前狀態：preflight 透過 `--statement` 分析還原用的 `ALTER TABLE`（`--kind ddl`）或 `UPDATE`（`--kind dml`），並於外部套用後以 `--after-write` 記錄佐證。永不執行該語句。
 - `verification show <id>` — 引用最終文物。
 
 完整旗標、每個指令的可貼上範例、`migrate` DDL、互動式 `shell` 與 MongoDB / Redis / ES 教學在 [reference.md](reference.md)(安裝時與本檔放在一起)。

package/assets/reference.md

@@ -1147,8 +1147,8 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 ### 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/`.
+migration, rollback) 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.
@@ -1233,6 +1233,67 @@ cannot be fully parsed under this contract (unterminated quotes, unsupported esc
 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.
 
+#### `verify rollback`
+
+(v1.37.0+) Preflight or after-write verification for an **externally-applied rollback** —
+confirming that after you reverted a change the database is back to the expected prior
+state. **This command never executes the reverting statement** — it analyzes it, runs
+read-only guards, and (in after-write mode) records evidence after you apply the rollback
+externally. One scenario covers both schema and data rollbacks via a required
+`--kind <ddl|dml>` selector:
+
+- `--kind ddl` — revert a schema migration. `--statement` is a single `ALTER TABLE`
+  (e.g. dropping a column a forward migration added). Reuses the `migration` DDL gates.
+- `--kind dml` — revert a data change. `--statement` is a single `UPDATE` that restores
+  prior values. Reuses the `safe-backfill` UPDATE plan gates.
+
+```bash
+# Schema rollback (--kind ddl) — preflight, then record evidence after applying it.
+dbcli verify rollback \
+  --kind ddl \
+  --table users \
+  --statement "ALTER TABLE users DROP COLUMN verified_at" \
+  --verify-query "SELECT count(*)::int AS n FROM information_schema.columns WHERE table_name = 'users' AND column_name = 'verified_at'" \
+  --expect "value == 0"
+dbcli verify rollback --kind ddl ... --after-write
+
+# Data rollback (--kind dml) — revert an UPDATE, then read back.
+dbcli verify rollback \
+  --kind dml \
+  --table users \
+  --statement "UPDATE users SET status = NULL WHERE status = 1" \
+  --verify-query "SELECT count(*)::int AS n FROM users WHERE status = 1" \
+  --expect "value == 0"
+dbcli verify rollback --kind dml ... --after-write
+
+# JSON for agents (both kinds).
+dbcli verify rollback --kind ddl ... --format json
+```
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--kind <ddl\|dml>` | yes | Reverting-statement grammar: `ddl` (single `ALTER TABLE`) or `dml` (single `UPDATE`). Invalid value fails closed before any DB connection. |
+| `--table <table>` | yes | Table affected by the rollback. |
+| `--statement <sql>` | yes | Proposed reverting statement, analyzed but never executed. |
+| `--verify-query <sql>` | yes | Plain `SELECT` for post-rollback read-back verification. |
+| `--expect <expr>` | yes | Assertion expression for the read-back result. |
+| `--after-write` | no | Run the post-rollback 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. |
+
+A single `--statement` flag is used for both kinds (instead of reusing `--ddl` / `--query`)
+to keep the dual-kind surface honest. The guard sequence, statuses (`ready`/`blocked` in
+preflight; `verified` / `not_verified` / `blocked` / `indeterminate` in after-write), and
+exit codes are identical to the other two scenarios. **MVP restrictions:** DML rollback is
+`UPDATE`-only (INSERT/DELETE reverts deferred); DDL rollback is single `ALTER TABLE` only,
+using the same identifier contract as `verify migration`.
+
+The artifact schema is unchanged: a rollback reuses the existing subject kinds —
+`--kind ddl` → `migration`, `--kind dml` → `backfill` — and records its provenance via
+`subject.command = "verify rollback"` plus the summary, so `verification` filters and
+retention are unaffected.
+
 ### verification
 
 (v1.33.0+) Local **VerificationArtifact** inspection and lifecycle surface over