@carllee1983/dbcli 1.32.0 → 1.37.0

package/.github/skills/dbcli/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.

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.0] - 2026-06-22 - Rollback Scenario & Nested Shell Completions
+
+### Added
+
+- **`dbcli verify rollback` 情境執行器(第三個內建 verify 情境)。** 透過已穩定的 scenario registry 註冊,以 preflight / after-write 兩種模式驗證「還原變更後資料庫是否回到預期的先前狀態」,且**永遠不執行**還原寫入 / DDL——只分析 `--statement` 並執行回讀斷言。以必填的 `--kind <ddl|dml>` 選擇還原語句文法:`ddl` 複用 `migration` 的單語句 `ALTER TABLE` 契約,`dml` 複用 `safe-backfill` 的 `UPDATE` plan 契約。安全邏輯完全複用兩個 sibling 情境的 classifier,無重複實作。artifact 沿用既有 subject kind(`ddl→migration`、`dml→backfill`)並以 `subject.command = 'verify rollback'` 記錄出處,因此 artifact schema 與版本不變。
+- **巢狀 bash / zsh / fish shell 補全。** 以遞迴 command-tree metadata model 從指令樹生成巢狀子指令與旗標補全,並由共用 registry 驅動 REPL 的補全與分派;補全會排除 denylisted 指令。
+
+### Changed
+
+- **REPL 補全 / 分派改由共用 registry 驅動。** 補全與指令分派統一從同一份 command registry 取得,降低 CLI 與 REPL 之間補全行為漂移的風險;`buildProgram` 抽成可重用 factory 並消除補全啟動噪音。
+
+## [1.36.0] - 2026-06-22 - Verification Scenario Runner Suite
+
+### Added
+
+- **`dbcli verify safe-backfill` 情境執行器。** 以 preflight / after-write 兩種模式驗證安全回填工作流，並**永遠不執行回填寫入**：preflight 依序跑黑名單、schema、目標表與唯讀 verify-query 防護後回傳 `ready` / `blocked` 並印出精確的 after-write 指令；after-write 重跑防護、執行回讀斷言，並寫入 v1 `VerificationArtifact`（狀態對應 `verified` / `not_verified` / `indeterminate`，防護失敗為 `blocked`）。
+- **`dbcli verify migration` 情境執行器。** 對 schema migration 做 preflight / after-write 驗證，且**永遠不執行 DDL**：分析提案的 `ALTER TABLE`、跑唯讀防護、要求 DDL 目標與 `--table` 相符（schema-aware），after-write 後記錄 `migration` 主體的證據。MVP 僅接受單語句 `ALTER TABLE`，並阻擋 `CREATE TABLE` / `DROP TABLE` / `CREATE INDEX` 及多語句 DDL。
+- **`ALTER TABLE` 目標識別字契約。** `verify migration` 的目標擷取改用 quote-aware tokenizer：支援 `table` / `schema.table` / `catalog.schema.table`，每區段可為未加引號名稱或雙引號 / 反引號 / 方括號識別字（含 `""`、`]]` 跳脫），因此 `"user accounts"`、`"tenant-1"."orders"` 等含空白或連字號的名稱皆可接受。無法完整解析的目標（未封閉引號、不支援的跳脫、超過三段）會 fail closed 並以「目標無法解析」為由阻擋，與 `must match --table` 的不符原因明確區分。
+- **`verification summary --latest-only` 交接選項。** 於既有 summary 輸出之上額外回傳最新一筆有效 artifact，方便 agent 在交接時直接引用最新證據；無 artifact 時回傳 `latest: null` 並維持 exit 0，無效檔案不會被升入 `latest`。
+
+### Changed
+
+- **抽取共用情境原語至 `src/core/verify/scenario.ts`。** 防護排序、all-guards-passed 判定、有界原因、狀態對應、shell-quote 與證據遮蔽等共用邏輯集中於此，`safe-backfill` 重構為消費這些原語且**對外行為零變更**，降低後續情境的重複實作風險。
+
+## [1.35.0] - 2026-06-19 - Verification Inspect & Prune Surface
+
+### Added
+
+- **`dbcli assert --write-verification-artifact` 橋接（opt-in）。** `assert` 的判定結果（verdict）現在可選擇性地寫成一份結果型 `VerificationArtifact`：透過 subject 解析器將斷言主體對應到 artifact 的 `subject`、依 pass/fail 對應驗證狀態，並以既有的原子寫入器落地於 `.dbcli/verification/`。省略旗標時行為完全不變、不寫入任何檔案；`safe-backfill-verify` 仍維持 plan-only。artifact 路徑一律相對於 cwd，與 `--config` 無關。
+- **唯讀 `verification` 指令介面（inspect + 生命週期）。** 新增核心 artifact 讀取器（含 schema 驗證、filter / summarize / find 輔助函式），並以此建構出 `verification list`（表格輸出，支援 subject-kind 篩選）、`verification show`、`verification summary` 等唯讀檢視指令，讓 agent 能直接讀取與彙整既有驗證證據，而非自行解析檔案。
+- **`verification prune` 保留期清理。** 依保留期（duration 解析）與全域 `--keep-latest` 規則挑選清理候選，全域 keep-latest 優先於各項篩選；具刪除安全防護（缺少 mtime 的檔案排除在外、預設 dry-run 預覽、`--execute` 才實際刪除），並在 execute 模式輸出 deleted / skipped 明細表。
+- **完整 v1 證據驗證。** 對 `subject` / `evidence` / 選用欄位進行完整驗證，並加入執行期 evidence-kind 防護，確保讀取與寫入兩端對 schema v1 的解讀一致。
+
+## [1.34.0] - 2026-06-18 - Verification Artifact Writer
+
+### Added
+
+- **驗證證據建構器（`buildVerificationArtifact`）。** 純函式，產生 schema v1 的 `VerificationArtifact`：可注入 `now` / `idFactory` 以利測試確定性、證據文字欄位上限 2000 字元（超過截斷並標註）、證據筆數上限 20（超過保留前 19 筆並補一筆 `manual` 截斷標記）；拒絕非法狀態、空白 summary、空證據。集中化證據裁切,讓後續寫入器與指令介面不必各自重複截斷決策。
+- **`safe-backfill-verify` 計畫的「已規劃」驗證中繼資料。** `dbcli skill tasks plan safe-backfill-verify --format json` 現在輸出一個 `verification` 區塊（`status: "planned"`,取計畫中最後一個 `assert` 步驟作為證據)。此為**已規劃**證據,**不代表**驗證已執行或通過,與結果型 `VerificationArtifact` 明確區隔。其他 task pack 不受影響。
+- **驗證證據寫入器（`writeVerificationArtifact`）。** 將建構出的 artifact 以原子方式寫入 `.dbcli/verification/verification-<YYYYMMDD-HHMMSS>-<short-id>.json`：檔名完全由 artifact 內部產生（UTC 時間戳 + `[a-z0-9]` 淨化短 id,杜絕路徑穿越)、缺少目錄時自動建立、以 `link()` 獨佔建立確保不會靜默覆寫既有檔案、回傳寫入路徑。
+- **`recover --apply --write-verification-artifact`（opt-in)。** 僅在 verify 步驟實際執行時,將 recovery 驗證結果寫成一份 `recovery-verify` artifact（狀態取合約 `verificationStatus`,附 `recoveryRef`)。省略旗標時行為完全不變、不寫入任何檔案;寫入失敗只記到 stderr,不影響結束碼。保留既有 `verifyStatus`、不嵌入任何指令輸出或機密。
+
+## [1.33.0] - 2026-06-18 - Workflow Pack Expansion
+
+### Added
+
+- **4 個新的 plan-only Agent Task Pack（皆唯讀)。** `pr-database-review`（PR 變更持久化路徑、查詢、migration 的資料庫風險審查)、`migration-review`（在套用 DDL 前擷取變更前 schema 證據並預覽 migration)、`safe-backfill-verify`（規劃安全 backfill 並產生 read-back `assert` 驗證指令)、`slow-endpoint-investigation`（串接 proxy / explain / missing-index 證據調查慢端點)。每個 pack 都以 `safety.mode: plan-only`、`risk: readonly` 步驟組成,只產生計畫、永不寫入;SQL 類 pack 先支援 `postgres` 與 `mysql`。
+- **Skill 路由更新（en / zh-TW)。** 在 `SKILL.md` 與 `SKILL.zh-TW.md` 的 Agent Task Packs 段落各加入一段精簡導引,讓 agent 在自行組合手動的審查、migration、backfill、效能流程前,先選擇對應的 workflow pack;已重新同步所有 plugin / platform skill 副本。
+
 ## [1.32.0] - 2026-06-18 - Agent Task Packs Expansion & Skill Parity Guards
 
 ### Added

package/README.md

@@ -890,6 +890,12 @@ dbcli completion --install zsh   # Install for specific shell
 
 **Supported shells:** bash, zsh, fish
 
+Installed completions cover **nested subcommands** — for example `dbcli queries list --<TAB>`, `dbcli migrate add-column --<TAB>`, and `dbcli verify safe-backfill --<TAB>`.
+
+Inside `dbcli shell`, command completion follows the current command surface, so newly added commands (`q`, `queries`, `inspect`, `verify`, `proxy`, `snapshot`, …) complete and dispatch automatically.
+
+`--install` is **marker-managed**: it writes a single block to your shell rc file and re-running it replaces that block rather than duplicating it.
+
 ---
 
 #### `dbcli upgrade`

package/README.zh-TW.md

@@ -788,6 +788,12 @@ dbcli completion --install zsh   # 指定 shell 安裝
 
 **支援 shell：** bash、zsh、fish
 
+已安裝的補全支援**巢狀子指令**，例如 `dbcli queries list --<TAB>`、`dbcli migrate add-column --<TAB>` 與 `dbcli verify safe-backfill --<TAB>`。
+
+在 `dbcli shell` 中，指令補全會依照目前的指令範圍運作，因此新增的指令（`q`、`queries`、`inspect`、`verify`、`proxy`、`snapshot` 等）會自動補全並可被執行。
+
+`--install` 採用**標記區塊管理**：它只會在 shell 設定檔寫入單一管理區塊，重新執行時會「取代」該區塊，而不會重複新增。
+
 ---
 
 #### `dbcli upgrade`

package/assets/SKILL.md

@@ -31,6 +31,13 @@ the CLI package has not been installed globally.
      - `failed` — verifier exited non-zero or timed out.
      - `indeterminate` — verifier exited 0 but the heuristic could not confirm the fix (JSON parse failure, missing field, gate skip).
      Verify is **only run when** `finalStatus === 'ok'`. Pass `--no-verify` to skip it. Heuristic is intentionally cheap; agents should still re-run their own check against the original failing operation when correctness matters.
+
+Verification outcome vocabulary: use `verified` only when required evidence matched;
+use `not_verified` when the check ran and contradicted the expected state; use
+`indeterminate` when the check ran but evidence was ambiguous; use `blocked` when
+verification could not run because of config, permission, schema, placeholder, or
+safety gates.
+
    - **v1.17.0 P2 Multi-turn `--next`.** When `--apply` is too coarse — interactive blocks it, the plan needs per-step inspection, or the agent wants to drive recovery with its own tools — execute steps one at a time and ask dbcli for the next:
 
      ```bash
@@ -83,6 +90,14 @@ recent audit activity. Additional read-only packs: `audit-permissions`,
 `safe-backfill`, `schema-drift-review`, `connection-health` — run
 `dbcli skill tasks list` for the full set.
 
+Review & verification packs: `pr-database-review` (assess a PR's changed queries,
+migrations and blacklist risk), `migration-review` (capture pre-change schema and
+preview DDL), `safe-backfill-verify` (backfill planning with a read-back `assert`),
+and `slow-endpoint-investigation` (chain `proxy analyze` → `explain` →
+`guide missing-index-for`). All are read-only `plan-only` — pick the pack matching the
+user's situation before improvising, and run any index/DDL proposal through
+`migration-review` before writing.
+
 Tasks live under `assets/tasks/` (builtin), `.dbcli-shared/tasks/` (shared), and
 `.dbcli/tasks/` (local override).
 
@@ -136,6 +151,16 @@ Developer workflow guardrails:
   command, and read-back or snippet verification.
 - Do not create indexes directly from a performance suggestion; turn them into reviewed migrations.
 - Do not print credentials, copied connection strings, or blacklisted values.
+- To persist result evidence for a read-back assertion, run `assert ... --write-verification-artifact --verification-subject <kind:name>` (kinds: `recovery`, `task-pack`, `assertion`, `migration`, `backfill`, `manual`).
+- Inspect result evidence (read-only): `dbcli verification summary --format json`
+  (also `verification list` / `verification show <id>`). Reclaim old artifacts with
+  `dbcli verification prune --older-than 30d` (dry-run; add `--execute --force` to delete).
+- `tasks plan safe-backfill-verify` — when the user needs a plan only.
+- `verify safe-backfill` — before a real safe backfill (preflight) and after it
+  (`--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.
+- `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).
 
@@ -310,6 +335,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `diff` | query-only+ | SQL only. Save/compare schema snapshots. |
 | `snapshot` | query-only+ | **(v1.25)** SQL only. Capture a result fingerprint (`rowCount` + per-column null/distinct/min/max/sum + order-independent checksum). `--out` (default `.dbcli/snapshots/snap-<ts>.json`), `--rows`, `--stdout`, `--format`, `--no-limit`. Baseline for `assert --against`. |
 | `assert` | query-only+ | **(v1.25)** SQL only. Verify an invariant; exit 1 on failure unless `--no-fail`. `--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`, `--vs <query> --compare rows\|value` (reconcile), `--against <snapshot> --tolerance <pct>`. |
+| `verification` | n/a | Inspect and manage local verification artifacts. `list` / `show <id-or-path>` / `summary` are read-only; `prune` is dry-run by default and deletes only with `--execute --force`. Reads `<cwd>/.dbcli/verification/`; no DB connection, no audit writes. |
 | `proxy` | n/a | **(v1.26)** MySQL/MariaDB/PostgreSQL only. Local-dev observability proxy — relays app traffic to the real DB and appends query/latency/byte/error events to `.dbcli/proxy/events.jsonl`. Subcommands: `mysql` \| `mariadb` \| `postgresql`. `--listen`, `--target`, `--events` (default `.dbcli/proxy/events.jsonl`), `--slow-ms` (default `1000`), `--redact none\|literals` (default `none`). Observe-only. **(v1.27)** `proxy analyze` aggregates the event log offline into a JSON/text report (summary, byFingerprint with suggestedCommands, slowest, errors, hotTables, N+1) — `--format`, `--top`, `--slow-ms`, `--n-plus-one`. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and **(v1.23)** human-readable `hints`). `--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |

package/assets/SKILL.zh-TW.md

@@ -28,6 +28,11 @@ description: 為 AI 代理設計、具權限控管的資料庫 CLI。可用於
      - `failed` — 驗證器以非零退出或逾時。
      - `indeterminate` — 驗證器以 0 退出,但啟發式判斷無法確認修復(JSON 解析失敗、欄位缺失、門控略過)。
      Verify **僅在** `finalStatus === 'ok'` 時執行。傳 `--no-verify` 可略過。啟發式刻意輕量;正確性重要時,代理仍應自行對原始失敗操作再驗證一次。
+
+驗證結果詞彙:只有在必要證據符合預期時才使用 `verified`;檢查已執行但結果違反預期時使用
+`not_verified`;檢查已執行但證據不足或模糊時使用 `indeterminate`;因 config、權限、schema、
+placeholder 或安全閘門導致驗證無法執行時使用 `blocked`。
+
    - **v1.17.0 P2 Multi-turn `--next`(多輪逐步執行)。** 當 `--apply` 顆粒度過粗(interactive 卡住、計畫需要逐步檢視,或代理希望用自有工具驅動復原)時,可逐步執行步驟並向 dbcli 詢問下一步:
 
      ```bash
@@ -70,6 +75,12 @@ dbcli skill tasks plan <task> --param key=value --format json     # 產生計畫
 
 內建套件:`diagnose-slow-query` 與 **(v1.23)** `analyze-table-perf` — 後者是 read-only 的 `plan-only` 套件,需帶入必填的 `table` 參數,依序執行 `blacklist list` → `schema <table> --format json` → `guide index-usage`。`dbcli inspect` 會針對近期 audit 活動中最熱門的資料表自動建議 `analyze-table-perf`。其他唯讀套件:`audit-permissions`、`safe-backfill`、`schema-drift-review`、`connection-health` — 用 `dbcli skill tasks list` 瀏覽完整清單。
 
+審查與驗證套件:`pr-database-review`(評估 PR 變更的查詢、遷移與 blacklist 風險)、
+`migration-review`(擷取變更前 schema 並預覽 DDL)、`safe-backfill-verify`(backfill 規劃
+搭配 read-back `assert`),以及 `slow-endpoint-investigation`(串接 `proxy analyze` →
+`explain` → `guide missing-index-for`)。全部為唯讀 `plan-only` — 先選擇符合使用者情境的
+套件再行動,任何索引/DDL 提案都應先經 `migration-review` 再寫入。
+
 任務檔放在 `assets/tasks/`(內建)、`.dbcli-shared/tasks/`(共享)與 `.dbcli/tasks/`(本地覆寫)。
 
 ## 開發者工作流
@@ -116,6 +127,14 @@ dbcli inspect --for-agent --no-connect --format json
 - 寫入與 backfill 必須包含 scope count、dry-run preview、execution command，以及 read-back 或 snippet verification。
 - 不要直接從 performance suggestion 建 index；應轉成經過 review 的 migration。
 - 不要列印 credentials、複製的連線字串或 blacklisted 值。
+- 若需持久化 read-back 斷言的結果佐證，執行 `assert ... --write-verification-artifact --verification-subject <kind:name>`（允許的 kind：`recovery`、`task-pack`、`assertion`、`migration`、`backfill`、`manual`）。
+- 檢視驗證佐證（唯讀）：`dbcli verification summary --format json`
+  （亦可用 `verification list` / `verification show <id>`）。以 `dbcli verification prune --older-than 30d` 回收舊文物（dry-run；加上 `--execute --force` 才刪除）。
+- `tasks plan safe-backfill-verify` — 當使用者只需要計畫時使用。
+- `verify safe-backfill` — 在真實 backfill 前（preflight）及執行後（`--after-write`）使用，需要持久佐證時必用。永不執行寫入。
+- `tasks plan migration-review` — 當使用者只需要 migration 計畫時使用（僅輸出計畫，不執行 DDL）。
+- `verify migration` — 預檢 schema migration（分析 DDL、執行防護），並在外部套用 migration 後（`--after-write`）記錄佐證。永不執行 DDL。
+- `verification show <id>` — 引用最終文物。
 
 完整旗標、每個指令的可貼上範例、`migrate` DDL、互動式 `shell` 與 MongoDB / Redis / ES 教學在 [reference.md](reference.md)(安裝時與本檔放在一起)。
 
@@ -259,6 +278,7 @@ dbcli init --use-env-refs \
 | `diff` | query-only+ | 僅 SQL。儲存 / 比較 schema snapshot。 |
 | `snapshot` | query-only+ | **(v1.25)** 僅 SQL。擷取結果指紋(`rowCount` + 每欄 null/distinct/min/max/sum + 順序無關 checksum)。`--out`(預設 `.dbcli/snapshots/snap-<ts>.json`)、`--rows`、`--stdout`、`--format`、`--no-limit`。作為 `assert --against` 的基準。 |
 | `assert` | query-only+ | **(v1.25)** 僅 SQL。驗證不變量;失敗時 exit 1,除非 `--no-fail`。`--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`、`--vs <query> --compare rows\|value`(對帳)、`--against <snapshot> --tolerance <pct>`。 |
+| `verification` | n/a | 檢視與管理本機驗證 artifact。`list`/`show`/`summary` 為唯讀檢視;`prune` 預設 dry-run，僅在 `--execute --force` 時刪除。讀取 `<cwd>/.dbcli/verification/`；不需 DB 連線，不寫入 audit log。 |
 | `proxy` | n/a | **(v1.26)** 僅 MySQL/MariaDB/PostgreSQL。本地端開發觀測代理 — 中繼應用程式流量至真實資料庫,並將查詢 / 延遲 / 位元組 / 錯誤事件附加到 `.dbcli/proxy/events.jsonl`。子指令:`mysql` \| `mariadb` \| `postgresql`。`--listen`、`--target`、`--events`(預設 `.dbcli/proxy/events.jsonl`)、`--slow-ms`(預設 `1000`)、`--redact none\|literals`(預設 `none`)。僅作觀測,不改寫或封鎖。 |
 | `status` | query-only+ | 安全 JSON / 文字摘要(不含憑證)。 |
 | `inspect` | query-only+ | 唯讀脈絡快照(連線、權限、blacklist、物件、snippets、建議指令)。`--for-agent` / `--no-connect` / `--require-schema-cache`。支援 `--recovery`。 |