@carllee1983/dbcli 1.37.0 → 1.38.1

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,135 @@ 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.
+
+#### `verify constraint`
+
+(v1.38.0+) Preflight or after-write verification that a **data-integrity invariant holds**
+across your change — foreign-key consistency, NOT NULL coverage, uniqueness, or a custom
+violation query. **This command never executes a write** — it only runs read-only
+`COUNT(*)` violation queries against the live table and (in after-write mode) records
+evidence. Four check kinds, selected by `--check`:
+
+- `--check fk` — counts orphaned rows in the child table. Requires `--column` (the child
+  FK column) and `--references <table.column>` (the referenced parent column).
+- `--check not-null` — counts rows where the column value is NULL. `--column` is
+  repeatable; each column is checked independently.
+- `--check unique` — counts duplicate values in one or more columns. `--column` is
+  repeatable; all listed columns are combined into a single uniqueness check.
+- `--check custom` — executes the caller-supplied `--violation-query <sql>`, which must
+  be a plain read-only `SELECT` returning a single integer count of violations.
+
+```bash
+# FK preflight — verify no orphaned orders before a migration.
+dbcli verify constraint \
+  --table orders \
+  --check fk \
+  --column customer_id \
+  --references customers.id
+
+# NOT NULL preflight — verify the column is fully populated.
+dbcli verify constraint \
+  --table users \
+  --check not-null \
+  --column email
+
+# After the write is applied externally — record evidence.
+dbcli verify constraint --table orders --check fk --column customer_id \
+  --references customers.id --after-write
+
+# JSON output for agents.
+dbcli verify constraint --table users --check not-null --column email --format json
+```
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--table <table>` | yes | Table the invariant is checked on. |
+| `--check <kind>` | yes | Constraint kind: `fk` \| `not-null` \| `unique` \| `custom`. |
+| `--column <name>` | yes (fk/not-null/unique) | Column to check. Repeatable for `not-null`/`unique`; the child FK column for `fk`. |
+| `--references <table.column>` | yes (fk only) | Referenced `<table>.<column>` for the FK parent lookup. |
+| `--violation-query <sql>` | yes (custom only) | Read-only `SELECT` returning a single integer count of violations. |
+| `--allow-preexisting` | no | Tolerate pre-existing violations: verified when `count ≤ --baseline` (default: `false`). |
+| `--baseline <n>` | no | Baseline violation count measured at preflight (use with `--allow-preexisting`). |
+| `--after-write` | no | Re-run the violation count and write a v1 verification 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 (after-write mode). |
+
+**Verdict rules.** Preflight returns `ready` or `blocked`; **`ready` is not `verified`**.
+After-write maps the violation count to `verified` (violations ≤ threshold) or
+`not_verified` (violations > threshold), and a failed guard to `blocked`; a query error
+yields `indeterminate`. The default threshold is `0` (strict: zero violations allowed).
+With `--allow-preexisting`, the threshold is the `--baseline` count captured at preflight,
+so the no-regression rule passes as long as the after-write count does not exceed the
+preflight count.
+
+**MVP restrictions.** SQL engines only (PostgreSQL / MySQL / MariaDB — requires an active
+`--config` connection). FK checks support a single child column; composite FK constraints
+are not yet supported. The command never executes any write or DDL statement.
+
+The artifact uses `subject.kind = 'table'` and `subject.command = 'verify constraint'`,
+so `verification` filters and retention are unaffected by the new scenario.
+
 ### verification
 
 (v1.33.0+) Local **VerificationArtifact** inspection and lifecycle surface over

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.38.1] - 2026-06-23 - Redis delete 能力對齊 & SKILL.md 任務路由重構
+
+### Fixed
+
+- **Redis `delete` 能力宣告由 `unsupported` 修正為 `limited` / `db-write`。** `delete.ts` 早已具備完整的 Redis 刪除分支（`DEL` / `HDEL` / `LREM` / `SREM` / `ZREM`、data-admin 權限閘、`--dry-run`、黑名單、稽核），但 `capabilities.ts` 仍宣告為 `unsupported`，與實作矛盾，導致能力表低報 Redis 刪除支援。改宣告為 `limited`（`db-write`，標註「基本刪除，需 data-admin、支援 `--dry-run`」）以對齊實作。於 SKILL.md 的 src 驗證期間發現。
+
+### Changed
+
+- **`assets/SKILL.md` 重構為任務路由決策樹。** 由原先結構改寫為以任務為導向的決策樹（task-routing decision tree），讓安裝 skill 的 agent 能依任務類型快速定位對應的指令工作流。純文件結構調整，無程式行為更動。
+
+## [1.38.0] - 2026-06-22 - verify constraint Scenario
+
+### Added
+
+- **`dbcli verify constraint` 情境執行器（第四個內建 verify 情境）。** 以 preflight / after-write 兩種模式驗證「資料完整性不變式是否成立」，且**永遠不執行寫入或 DDL** — 只執行唯讀 `COUNT(*)` 違規查詢。以 `--check <kind>` 選擇四種限制類型：`fk`（孤兒列，需 `--column` + `--references <table.column>`）、`not-null`（NULL 值統計，`--column` 可重複）、`unique`（重複值統計，`--column` 可重複）、`custom`（呼叫端自訂的唯讀 `--violation-query <sql>`）。預設 threshold 為 `0`（嚴格：零違規即通過）；啟用 `--allow-preexisting` + `--baseline <n>` 可改為無回退模式（after-write 筆數 ≤ preflight baseline 即通過）。文物沿用 `subject.kind = 'table'`、`subject.command = 'verify constraint'`，artifact schema 與版本不變。MVP 僅限 SQL 引擎，FK 僅支援單一子欄位。
+
+## [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