@carllee1983/dbcli 1.39.2 → 1.42.0

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

@@ -105,6 +105,7 @@ dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod
 
 **Schema storage (v1.4+):** Schema is persisted as layered files under `.dbcli/schemas/`. With v2 multi-connection config each connection gets its own subdirectory (`.dbcli/schemas/<connection>/`). Run `dbcli schema --use <connection>` once per connection before querying it — otherwise `schema <table>` may return data from the wrong connection's cache.
 
+> **PostgreSQL:** Introspection uses the exact `public` catalog identity throughout. Full catalog/schema/table joins prevent a reused constraint name from contaminating another table; enum lookup includes its namespace; composite primary-key order comes from the exact table OID and index ordinality; and row estimates are scoped to the exact `public` relation. Row-count SQL qualifies and quotes both `"public"` and the exact table identifier, escaping embedded quotes so mixed-case or punctuation-bearing names remain distinct and safe.
 > **Redis:** `schema <key>` is required (no full scan). The output exposes `type`, `ttl`, `size`, and a small `sample` (e.g. first 5 hash keys). `--reset` / `--refresh` are rejected — Redis caches no schema.
 > **Elasticsearch:** `schema [index]` flattens the `_mapping` properties (nested `a.b.c`) and emits each `.fields` multi-field as a separate column (e.g. `text` + `text.keyword`). Full scan iterates all non-system indices and stores per-connection caches alongside SQL engines.
 > **MongoDB:** schema is sampled via `$sample` (default 100, max 1000). `--sample-method natural` switches to `find().limit()`; `random` (default) falls back to natural order on driver error. Output columns surface nested dot-paths with `presence` (0..1) and `redacted: true` flags for blacklist-matched paths. The persisted cache records `sampleMethod` and `sampleSize`; `dbcli doctor` reports them via a `sampled: method=…, size=…` line.
@@ -192,9 +193,134 @@ dbcli explain --bulk @analytics/*                     # glob over saved queries
 | `nested-loop-large` | yellow | PG `Nested Loop` with planner rows > 10,000 |
 
 > Notes:
-> - `--analyze` executes the statement — do not use against destructive SQL.
+> - `--analyze` executes the statement, so dbcli accepts it only for SQL that is
+>   structurally proven to be a read-only, function-free `SELECT` (including
+>   SELECT-only CTEs). Explicit function and table-function calls are unproven
+>   because user-defined and built-in functions may have side effects. DML, DDL,
+>   data-modifying CTEs, session assignments, function-bearing SQL, and
+>   unrecognized SQL are rejected before the adapter is invoked; use plain
+>   `dbcli explain` for those statements.
 > - Auto-`LIMIT` is **not** applied to EXPLAIN statements (since v1.23 P1).
 
+### lint
+
+Static, report-only SQL anti-pattern analysis for PostgreSQL, MySQL, and
+MariaDB. `lint` never opens a database connection, never runs the SQL, and
+never applies a rewrite. Schema-aware findings use only the layered schema
+cache under `.dbcli/schemas/`.
+
+```text
+dbcli lint [queries...]
+dbcli lint --bulk <input>
+dbcli --use <conn> lint [queries...]
+```
+
+An input may be inline SQL, a saved query such as `@analytics/live-summary`, a
+SQL file such as `@queries.sql`, or a saved-query/filesystem glob such as
+`@analytics/*` or `@queries/**/*.sql`. `--bulk` accepts a comma-separated mix
+of those `@file`, `@glob`, and `@saved-query` inputs; quote a filesystem glob
+in a shell so the `@` reference reaches dbcli unchanged.
+
+```bash
+dbcli lint "SELECT * FROM users WHERE email LIKE '%@example.com'" --format json
+dbcli lint --bulk '@queries/**/*.sql' --format markdown
+dbcli --use staging lint @analytics/live-summary --min-severity warn
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--format <text\|json\|markdown>` | `text` | Render one report per resolved input. |
+| `--min-severity <info\|warn\|error>` | `info` | Omit findings below the selected severity. |
+| `--no-schema` | off | Skip schema-only checks without reading schema-cache paths; static `NOT IN` NULL checks still run. |
+| `--bulk <input>` | none | Resolve a comma-separated list of `@file`, `@glob`, or `@saved-query` inputs. |
+| `--recovery` | off | On command failure, emit and save a linked `RecoveryEnvelope`. |
+| global `--use <conn>` | configured default | Select a v2 named connection and its isolated cache; place it before `lint`: `dbcli --use <conn> lint …`. |
+
+**Rules:**
+
+| Rule | Severity | What it reports |
+|---|---|---|
+| `select-star` | warn | A top-level `SELECT *`; when one table and its cached columns are unambiguous, the finding may include a column-list rewrite draft. |
+| `unanchored-like` | warn | A `LIKE` / `ILIKE` pattern beginning with `%`, which a conventional B-tree index cannot anchor. |
+| `missing-limit-offset` | info | Deep pagination with `OFFSET >= 1000`; prefer keyset pagination. |
+| `non-sargable-where` | warn | A function or arithmetic expression applied to the column side of a predicate. |
+| `or-to-union` | info | A top-level `OR` across different columns that can complicate index selection; any UNION alternative must preserve identity and multiplicity. |
+| `subquery-to-join` | info | `IN (SELECT …)` where an equivalent `EXISTS`, or a JOIN with proven uniqueness/deduplication, may plan better. |
+| `distinct-groupby-abuse` | warn | Redundant `DISTINCT` when simple projected columns exactly cover the `GROUP BY` columns. |
+| `implicit-cast` | warn | A schema-verified column/literal type mismatch that can disable index use; safe, unambiguous numeric drafts may be included. |
+| `not-in-nullable` | warn | A right-hand `NOT IN` value that can be NULL: explicit `NULL`, outer-join null extension, a nullable subquery projection, or a known nullable CASE/cast/aggregate expression. A nullable left-hand column is not this rule. |
+
+`implicit-cast` and the schema-enriched portion of `not-in-nullable` read the
+selected cache through the schema loader abstraction. Static `not-in-nullable`
+checks still run without it. All schema caches live beneath `.dbcli/schemas/`. A v2
+configuration always uses `.dbcli/schemas/<resolved-connection>/`, including
+the configured default. The root `.dbcli/schemas/` directory is only the
+v1/legacy unnamed cache. Global `dbcli --use <conn> lint …` selects another
+named v2 slot. The command never refreshes the cache and never falls back to
+schema embedded in config.
+
+Skipped rules are returned with machine-readable `blocked:` reasons:
+
+- Invalid SQL blocks all nine rules with `blocked: parse failed` and includes
+  `parseError`.
+- `--no-schema` blocks `implicit-cast` and the schema-dependent portion of
+  `not-in-nullable` with `blocked: --no-schema`; static RHS hazards still run.
+- A missing layered cache records
+  `blocked: schema cache unavailable (run dbcli schema)` for those unavailable
+  schema checks while retaining static RHS findings.
+
+Every finding includes its rule, severity, source span, message, and
+`schemaVerified` state. Some findings also carry a confidence-labelled rewrite
+draft and a shell-safe verification command. It uses
+`dbcli explain --analyze` only when the statement is structurally proven read-only;
+function-bearing and session-assignment statements are unproven, so lint
+falls back to plain `dbcli explain`. These are suggestions only: `lint` neither
+executes the verification command nor changes the query.
+
+When schema identifiers collide after case folding, schema-aware findings and
+rewrites are withheld. The SQL parser does not preserve reliable quote
+provenance, so an exact-looking mixed-case AST identifier cannot disambiguate
+that collision. CTE, derived, schema-qualified, and database-qualified
+relations also never borrow facts from the unqualified cache.
+
+For `not-in-nullable`, remove or filter right-hand NULL values. In a subquery,
+filter the projected value with `IS NOT NULL`; `NOT EXISTS` may be a better
+semantic form when appropriate. dbcli does not automatically rewrite this case
+unless correlation, type classification, qualified-column resolution, and the
+rewrite target are all unambiguous. A direct or `AND`-conjoined `IS NOT NULL`
+filter on the exact projected expression suppresses the finding; aggregates
+apply the same proof in `HAVING`. Filters under `OR` or ambiguous expression
+matches do not. The rule recursively checks projection, JOIN `ON`, `WHERE`, and
+`HAVING` expressions, using each nested SELECT/CTE/derived statement's own
+scope. Qualified outer-join null extension remains detectable without a cache,
+but a join's synthetic NULL row is not applied inside that join's own `ON`;
+declared nullability and completed earlier joins still apply there.
+
+Trimmed JSON example:
+
+```json
+[
+  {
+    "sql": "SELECT * FROM users",
+    "dialect": "postgresql",
+    "findings": [
+      {
+        "rule": "select-star",
+        "severity": "warn",
+        "message": "SELECT * fetches every column; list the columns you need.",
+        "span": { "start": 0, "end": 8 },
+        "schemaVerified": false
+      }
+    ],
+    "skippedRules": [],
+    "relatedCommands": [
+      "dbcli guide missing-index-for \"SELECT * FROM users\"",
+      "dbcli explain --analyze \"SELECT * FROM users\""
+    ]
+  }
+]
+```
+
 ### plan
 
 Static SQL risk analyzer. Classifies a statement into the same permission tiers
@@ -583,6 +709,202 @@ dbcli diff --against before.json --format json
 **Options:** `--snapshot <path>`, `--against <path>`, `--format <json|table>`
 **Permission:** query-only+
 
+#### `diff --against-orm`
+
+Compare an ORM definition with the local SQL schema cache. This mode reads
+`config.schema`; it does not open a database connection, refresh the cache, or
+execute a proposal. An empty cache fails with
+`Schema cache is empty. Run 'dbcli schema' first.` Snapshot mode remains a
+separate `--snapshot` / `--against` workflow.
+
+```bash
+# Prisma and normalized JSON accept exactly one file
+dbcli diff --against-orm prisma/schema.prisma --format json
+dbcli diff --against-orm schema.normalized.json --orm-format json --format table
+
+# Drizzle requires a PostgreSQL drizzle-kit v7 snapshot (generate it first)
+drizzle-kit generate
+dbcli diff --against-orm drizzle/meta/0001_snapshot.json --orm-format drizzle --format table
+
+# DDL accepts repeatable or comma-separated paths and real filesystem globs
+dbcli diff --against-orm "migrations/*.sql" --format markdown
+dbcli diff --against-orm migrations/base.sql,migrations/accounts.sql \
+  --against-orm migrations/orders.sql --orm-format ddl --format json
+
+# Ignore patterns are comma-separated and match qualified table identity
+dbcli diff --against-orm prisma/schema.prisma --ignore 'public.audit_*,public.Legacy'
+```
+
+##### TypeORM
+
+TypeORM entities are not parsed directly. `schema:log` prints the SQL that
+`schema:sync` would execute without applying it; `-d` is the required data-source
+path. Generate that DDL, then select the `typeorm` alias so the report is tagged
+`ormSource: typeorm`:
+
+```bash
+bunx typeorm schema:log -d <path/to/datasource> > schema.sql
+dbcli diff --against-orm schema.sql --orm-format typeorm --format table
+```
+
+With `--orm-format typeorm`, `typeorm_metadata` and `migrations` are
+default-ignored and appear as `unmanaged` rather than scored drift. Passing a
+TypeORM `.ts`, `.js`, `.mjs`, or `.cjs` source file is rejected with the
+`schema:log` command to run. See the
+[TypeORM CLI documentation](https://typeorm.io/docs/using-cli) and
+[`SchemaLogCommand`](https://github.com/typeorm/typeorm/blob/master/src/commands/SchemaLogCommand.ts).
+
+##### Sequelize
+
+Sequelize CLI does not provide a universal `db:migrate --dry-run`. Point the
+project's existing Sequelize configuration at an empty scratch database, apply
+the migrations there, and dump definitions without row data:
+
+```bash
+# Configure Sequelize for an empty scratch database first
+bunx sequelize-cli db:migrate
+
+# PostgreSQL scratch database
+pg_dump --schema-only <scratch-database> > schema.sql
+
+# MySQL scratch database
+mysqldump --no-data <database> > schema.sql
+
+dbcli diff --against-orm schema.sql --orm-format sequelize --format json
+```
+
+With `--orm-format sequelize`, `SequelizeMeta` is default-ignored and appears as
+`unmanaged` rather than scored drift. Passing a Sequelize `.ts`, `.js`, `.mjs`,
+or `.cjs` model file is rejected with the scratch-database and schema-only dump
+recipe. See the
+[Sequelize CLI migration command](https://github.com/sequelize/cli/blob/main/src/commands/migrate.js),
+[PostgreSQL `pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html),
+and [MySQL `mysqldump`](https://dev.mysql.com/doc/refman/8.4/en/mysqldump-definition-data-dumps.html)
+references.
+
+| Option | Behavior |
+| :--- | :--- |
+| `--against-orm <paths>` | Repeatable or comma-separated input. DDL-family inputs (raw DDL, TypeORM, and Sequelize) support real filesystem globs; matches are deduplicated and put in deterministic path order, then parsed as one shared ordered context so an index in a later file can attach to a table declared in an earlier file. Prisma, normalized JSON, and Drizzle accept exactly one file, and globs are rejected for those formats. |
+| Drizzle input | Run `drizzle-kit generate`, then pass the PostgreSQL drizzle-kit v7 snapshot at `drizzle/meta/<NNNN>_snapshot.json`. TypeScript ORM schema sources (`.ts` or `.TS`) are rejected with that snapshot-generation hint; dbcli does not parse them directly. |
+| TypeORM / Sequelize input | Generate DDL with the ORM/database tooling, then pass the SQL file with the matching `typeorm` or `sequelize` alias. Entity/model source files are rejected rather than parsed. |
+| `--orm-format prisma\|ddl\|json\|drizzle\|typeorm\|sequelize` | Override extension/content detection. The `typeorm` and `sequelize` aliases use the DDL adapter while preserving the source tag and ORM-specific default ignores. Without an override, dbcli detects Prisma, raw DDL, normalized JSON, or a Drizzle snapshot from the path and content. |
+| `--ignore <globs>` | Comma-separated, case-sensitive table globs. Patterns match the qualified display identity (for example `public.Users`). `_prisma_migrations` is always unmanaged; the TypeORM alias additionally ignores `typeorm_metadata` and `migrations`, and the Sequelize alias additionally ignores `SequelizeMeta`. |
+| `--format json\|table\|markdown` | Select machine JSON, human table, or Markdown output. Markdown is available only in ORM drift mode. |
+| `--recovery` | On an I/O, configuration, empty-cache, invalid-format, or unsupported-engine failure, emit and save a structured recovery envelope. Invalid Prisma/DDL constructs normally become `unparsed` entries instead of throwing. |
+
+The command supports PostgreSQL, MySQL, and MariaDB configurations. Only
+error-level **scored drift** determines the report's drift exit code: one or more
+scored errors exits `1`; warnings, infos, `unmanaged`, or `unparsed` entries alone
+exit `0`. Command/configuration failures independently exit code `1`. The four
+drift categories and tolerance rules are:
+
+| Category | Severity and comparison rule |
+| :--- | :--- |
+| `missing_in_db` | `error` — a table, column, or index exists in the ORM definition but not in the cached DB schema. |
+| `missing_in_orm` | `warn` — a table, column, or index exists in the cached DB schema but not in the ORM definition. |
+| `mismatch` | `error` when the type family or nullability differs; `info` for same-family type spelling, default, or primary-key differences. |
+| `unmanaged` | `info`, excluded from error/warn scoring — the table matched the built-in or user `--ignore` patterns. |
+
+Type-family tolerance deliberately treats engine spellings such as `text` and
+`varchar(191)` as the same family: the spelling difference is still visible as
+`info`, while an integer/text family difference is an `error`. Indexes compare
+by structural index signatures — ordered, case-folded column names plus
+uniqueness — rather than by engine-specific index names. Duplicate signatures
+are emitted once. Drift entries sort deterministically by table, object, category,
+and detail using Unicode code-point order, never locale-dependent collation.
+
+**Schema and table identity.** Storage preserves exact, case-sensitive schema
+and table names from the database catalog. Exact, case-sensitive `(schema, table)`
+tuples are the comparison key, so PostgreSQL `users` and `"Users"` can coexist.
+DDL resolution rules: unquoted SQL identifiers fold to lowercase; quoted identifiers match exactly.
+For example, unquoted `Users` resolves to `users`, and quoted
+`"Users"` resolves only to `Users`. Quote state comes from the parsed identifier representation;
+dbcli never infers it from display text, catalog spelling, or a
+Prisma mapping. Qualified components resolve independently, and unqualified ORM
+identities use the cached DB default schema when one is known. Qualified display
+names and `--ignore` matching remain case-sensitive. Duplicate exact or
+duplicate resolved table identities fail closed instead of overwriting one
+another.
+
+**Prisma subset.** The parser supports `model` blocks; scalar `String`, `Int`,
+`BigInt`, `Float`, `Decimal`, `Boolean`, `DateTime`, `Json`, and `Bytes` fields;
+`?`; relation-side `[]`; `@id`, `@unique`, `@default(...)`, `@map("...")`,
+`@@map("...")`, `@@index([...])`, `@@unique([...])`; relations with
+`fields` / `references`; and the validated native mappings `@db.Text`,
+`@db.VarChar(n)`, `@db.Uuid`, `@db.Timestamptz([precision])`, `@db.Date`,
+`@db.SmallInt`, and `@db.JsonB`. Views, composite types, enums used as scalar
+columns, multi-schema datasource configuration, malformed declarations, unknown
+attributes, and unsupported native mappings are never guessed.
+
+Prisma, DDL, and Drizzle constructs outside the supported subset are retained in
+`unparsed` with a `blocked:` reason. These entries are separate from scored drift:
+inspect and resolve them before treating an otherwise clean summary as complete.
+Drizzle enums and other unsupported snapshot constructs therefore appear as blocked
+`unparsed` entries rather than managed tables or columns.
+Multi-file DDL is consumed as one deterministic shared ordered statement context,
+so later `CREATE INDEX` statements can reference tables declared in earlier
+files. PostgreSQL `PARTITION BY` and MySQL/MariaDB table engine, charset, and
+other `CREATE TABLE` table options are unsupported: the construct produces a
+`blocked:` `unparsed` entry and does not emit a managed ORM table.
+The normalized JSON escape hatch is Zod-validated and uses an array of tables
+with explicit exact `identity` objects; optional parsed identifiers must include
+their `quoted` flags, and every normalized JSON `unparsed.reason` must start with
+`blocked:`.
+
+```json
+{
+  "ormSource": "prisma",
+  "entries": [
+    {
+      "category": "missing_in_db",
+      "severity": "error",
+      "table": "public.users",
+      "object": "email",
+      "detail": "column 'email' (text) is defined in prisma but absent in the database",
+      "proposedCommands": [
+        "# escalate: schema-qualified table 'public.users' is not losslessly representable by dbcli migrate — run: dbcli skill tasks plan migration-review"
+      ]
+    }
+  ],
+  "unparsed": [],
+  "summary": { "errors": 1, "warns": 0, "infos": 0, "unmanaged": 0 }
+}
+```
+
+Missing unqualified columns and indexes may receive shell-safe, dry-run-by-default
+`dbcli migrate add-column` or `add-index` proposal strings. Simple arguments stay
+unquoted; unsafe shell characters are POSIX single-quoted. Table creation,
+removal, mismatch, and DB-only drift escalate to `migration-review`. A
+schema-qualified target, or index columns that the current `migrate --columns`
+CLI cannot represent losslessly, also escalates instead of emitting a corrupt
+command. Any table, column, or type positional beginning with `-` also escalates
+so Commander cannot reinterpret it as an option. A leading-dash option value is
+rendered with option-safe attached syntax, for example `--default=-1` or
+`--columns=--config,email`. Proposals are text only and never add `--execute`.
+
+For a guided, cache-refreshing review, use the built-in `orm-drift-review` pack:
+
+```bash
+dbcli skill tasks plan orm-drift-review \
+  --param orm_path=prisma/schema.prisma \
+  --format json
+```
+
+The plan is `blacklist list` → `schema --format json` →
+`diff --against-orm ... --format json`. Run any proposed `migrate` command in its
+default dry-run mode, capture the emitted DDL, confirm its exact target, and pass
+both values to the separate migration review:
+
+```sh
+dbcli skill tasks plan migration-review \
+  --param "table=${exact_table}" \
+  --param "ddl=${captured_ddl}"
+```
+
+Both parameters are required. Keep each expansion as one quoted shell argument;
+never use `eval`, and consider `--execute` only after the plan and captured DDL
+have been reviewed.
+
 ### snapshot
 
 Capture a **result fingerprint** of a query (not schema): `rowCount` plus per-column
@@ -1713,8 +2035,12 @@ a read-only (`plan-only`) pack taking a required `table` parameter that walks
 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.
+vs live schema diff), `orm-drift-review` (ORM definition vs cached DB schema),
+and `connection-health` (reachability/config/capacity
+triage). **MongoDB packs:** `mongo-safe-backfill` (dry-run–previewed backfill)
+and `mongo-schema-drift-review` (sampled dot-path drift, with a `sample_size` knob
+to damp sampling noise); filter them with `dbcli skill tasks list --engine mongodb`.
+Run `dbcli skill tasks list` for the full set.
 
 ```bash
 dbcli skill tasks plan analyze-table-perf --param table=betting_logs --format json

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.42.0] - 2026-07-20 - Drizzle Snapshot 與 ORM DDL 工作流擴充
+
+### Added
+
+- **Drizzle Kit snapshot 可直接用於 ORM drift 比對。** `dbcli diff --against-orm` 新增 Drizzle snapshot 格式偵測與 `NormalizedSchema` adapter，支援 PostgreSQL v7 snapshot 的 table、column、primary key、unique constraint、index 與 foreign key metadata。
+- **TypeORM／Sequelize DDL alias。** `--orm-format typeorm`、`typeorm-ddl`、`sequelize` 與 `sequelize-ddl` 可直接走既有 DDL adapter；自動忽略 `typeorm_metadata` 與 `SequelizeMeta` bookkeeping table，並補上 source-file 使用者的可執行匯出／比對指引。
+
+### Changed
+
+- **ORM drift 文件完整同步。** 英文／繁體中文的 Markdown 與 HTML 使用者文件、skill assets、各平台 plugin 副本及 reference 已補上 Drizzle snapshot、TypeORM／Sequelize DDL 的格式、限制與操作範例。
+- **跨平台發版 metadata 對齊。** npm package、Codex／Claude／Cursor plugin、packaged Codex plugin 與 Gemini extension 統一為 `1.42.0`。
+
+### Fixed
+
+- **不支援的 ORM 輸入改為 fail closed。** Drizzle snapshot 會拒絕不支援的版本／dialect、generated／identity／enum／composite primary key 等結構，以及無法無損轉換的 column default；TypeORM／Sequelize source file 則回報完整的匯出 DDL recipe，不再被 JSON／DDL fallback 誤解析。
+- **Qualified ignore identity 保留完整。** ORM drift 的 ignore 比對不再把 schema-qualified identity 降成 bare table name，避免同名 table 跨 schema 時被錯誤忽略；ORM DDL alias 也會正確沿用 DDL 輸入處理與 bookkeeping ignore。
+
+## [1.41.0] - 2026-07-19 - ORM Drift 比對與無損 Schema Identity
+
+### Added
+
+- **`dbcli diff --against-orm` ORM drift 比對。** 可將 Prisma schema、DDL／migration SQL 或 normalized JSON 與既有 SQL schema cache 比對；支援多檔 DDL、filesystem glob、格式自動偵測、大小寫敏感的 `--ignore` pattern，以及 JSON、table、Markdown 輸出。比對只讀本地 cache，不連線、不更新 cache，也不執行提案。
+- **結構化 drift 分類與安全提案。** 報告區分 `missing_in_db`、`missing_in_orm`、`mismatch`、`unmanaged` 與 `unparsed`；只有計分後的 error 會使 drift exit code 為 `1`。可無損表達的缺漏欄位／index 會產生 shell-safe、預設 dry-run 的 `migrate` 提案，其餘情況升級至 `migration-review`。
+- **`orm-drift-review` agent task pack。** 工作流依序執行 blacklist 檢查、schema cache 更新與 ORM drift JSON 比對，並要求將 dry-run DDL 與精確目標交給獨立 migration review。
+
+### Changed
+
+- **Schema identity 改為精確保存。** PostgreSQL schema／table 名稱不再正規化為小寫；quoted 與 unquoted identifier 依 SQL 規則解析，qualified name、ignore pattern、foreign key 與 drift output 都保留大小寫與 schema identity。
+- **ORM drift 文件完整同步。** 英文／繁體中文的 Markdown 與 HTML 使用者文件、skill assets、各平台 plugin 副本及 reference 已補上格式、exit code、安全邊界與操作流程。
+- **跨平台發版 metadata 對齊。** npm package、Codex／Claude／Cursor plugin、packaged Codex plugin 與 Gemini extension 統一為 `1.41.0`。
+
+### Fixed
+
+- **Lossy ORM drift proposal 改為 fail closed。** Schema-qualified target、dash-leading positional、無法無損表達的 index column、identity collision 與不支援語法不再輸出可能損壞的指令，而是阻擋或升級人工審查。
+- **DDL／Prisma adapter identity 與語意硬化。** 多檔 DDL 共用 deterministic context，foreign key pairing、default schema resolution、table option／partition 阻擋、重複 index 去重與 Unicode code-point 穩定排序皆保留來源語意。
+
+## [1.40.0] - 2026-07-19 - SQL Lint、安全強化與 Agent 工作流擴充
+
+### Added
+
+- **新增唯讀 `dbcli lint` 靜態 SQL 顧問。** 支援 inline SQL、saved query、SQL 檔案與 glob／混合批次輸入，提供 text、JSON、Markdown 輸出、最低嚴重度篩選、`--no-schema` 與 `--recovery`；指令不連線、不執行 SQL，也不會自動套用 rewrite。
+- **九條結構與 schema-aware lint 規則。** 涵蓋 `SELECT *`、未錨定 `LIKE`、深度 `OFFSET`、non-sargable predicate、`OR`／subquery 改寫機會、重複 `DISTINCT` + `GROUP BY`、implicit cast，以及 `NOT IN` 右側 NULL 風險；finding 可附 confidence 標籤的草稿與 shell-safe 驗證指令。
+- **MongoDB agent task packs。** 新增 `mongo-safe-backfill` 與 `mongo-schema-drift-review`，補上 MongoDB 安全回填與 schema drift 檢視工作流。
+
+### Changed
+
+- **Slow-query guide 納入 lint。** `guide slow-query` 現在會先安排本機靜態分析，再銜接 explain 與診斷 snippets，brief plan 也保留執行 metadata。
+- **Agent 與使用者文件完整同步。** `lint` 已寫入 skill assets、platform plugin 副本及英文／繁體中文 Markdown 與 HTML 文件；GitHub Pages 產品介紹頁同步完成雙語、可及性與行動裝置導覽重構。
+- **跨平台發版 metadata 對齊。** npm package、Codex／Claude／Cursor plugin、packaged Codex plugin 與 Gemini extension 統一為 `1.40.0`。
+
+### Fixed
+
+- **Lint 採 fail-closed 安全邊界。** 解析失敗、schema binding 不明、identifier 大小寫碰撞、CTE／derived／qualified relation 與不安全 rewrite proof 會阻擋對應建議，不再借用不可靠的 cache facts。
+- **`NOT IN` NULL 分析補齊 scope 與 provenance。** 遞迴處理巢狀 SELECT、CTE、derived statement、JOIN `ON`、`WHERE`、`HAVING`、outer-join null extension、nullable 投影與 CASE／cast／aggregate，並保留正確 traversal order。
+- **Lint audit／recovery 遮蔽與驗證指令硬化。** positional、global、bulk 與 `--` 後的 SQL 都會遮蔽；只有結構上已證明唯讀的 SQL 才建議 `explain --analyze`，session assignment 與 function-bearing statement 會保守退回 plain explain。
+
 ## [1.39.2] - 2026-07-03 - Windows 跨平台、skill 安裝安全與 plugin 版本對齊
 
 > npm `1.39.1` 已於 2026-06-30 發布；本批修復在其後累積於同一版號下（npm 版本不可覆蓋），故獨立為 1.39.2 以便日後發布。

package/README.zh-TW.md

@@ -4,7 +4,7 @@
 
 統一的資料庫 CLI 工具，讓 AI 代理（Claude Code、Gemini、Copilot、Cursor）能安全地查詢、探索與操作資料庫。
 
-**核心價值：** AI 代理可透過單一、具權限控管的 CLI 工具，在敏感資料保護下安全且智慧地存取專案資料庫。
+**核心價值：** AI 代理可透過單一、具權限控管的 CLI 工具，在敏感資料保護下安全存取專案資料庫。
 
 > **安全性更新：** `dbcli init` 現在只會在 `./.dbcli/config.json` 寫入一個很小的專案綁定 stub。完整的連線設定會存放在 `~/.config/dbcli/projects/<project-id>/config.json`，因此敏感設定預設不會留在專案工作區內。
 

package/assets/SKILL.md

@@ -45,7 +45,7 @@ takes a full JSON filter and is exempt.)
 
 Slow-query diagnosis has three canonical paths (pick by what you already know):
 
-- Known slow SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `guide missing-index-for "<SQL>"`
+- Known slow SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `lint "<SQL>"` → `guide missing-index-for "<SQL>"`
 - Known hot table → `skill tasks plan analyze-table-perf --param table=<table>`
 - Whole-environment scan → `report --section perf` → `guide slow-query`
 
@@ -54,7 +54,7 @@ afterwards add only the `@diag/*` it does not cover (`missing-indexes`, `locks`,
 `table-sizes`). Once you have a specific slow statement, `explain --analyze "<SQL>"` shows its plan.
 
 **On failure:** pass `--recovery` to `query` / `q` / `insert` / `update` / `delete` /
-`export` / `schema` / `inspect`. The command emits a `RecoveryEnvelope` to stdout and saves
+`export` / `schema` / `inspect` / `lint` / `diff --against-orm`. The command emits a `RecoveryEnvelope` to stdout and saves
 it to `.dbcli/last-recovery.json`; then `dbcli recover` inspects it and `dbcli recover --apply`
 runs the saved plan under risk gating. Multi-turn `--next`, connection branching, and the
 post-apply verify probe are documented in reference.md §Recovery Cookbook.
@@ -81,12 +81,16 @@ The plan is an ordered list of dbcli commands with rationale and risk labels. Ex
 one at a time — task plans do **not** override blacklist, schema, dry-run, or confirmation
 requirements.
 
-Builtin packs: `diagnose-slow-query` (targets a specific SQL), `analyze-table-perf` (targets
-a specific table; `dbcli inspect` auto-suggests it for the hottest table in recent audit
-activity), `audit-permissions`, `safe-backfill`, `schema-drift-review`, `connection-health`.
-Review/verify packs: `pr-database-review`, `migration-review`, `safe-backfill-verify`,
-`slow-endpoint-investigation`. All are read-only `plan-only` — pick the pack matching the
-situation, and run any index/DDL proposal through `migration-review` before writing.
+Builtin packs (SQL — postgres/mysql): `diagnose-slow-query` (targets a specific SQL),
+`analyze-table-perf` (targets a specific table; `dbcli inspect` auto-suggests it for the
+hottest table in recent audit activity), `audit-permissions`, `safe-backfill`,
+`schema-drift-review`, `orm-drift-review` (ORM definition vs cached DB schema),
+`connection-health`. Review/verify packs: `pr-database-review`,
+`migration-review`, `safe-backfill-verify`, `slow-endpoint-investigation`. MongoDB packs:
+`mongo-safe-backfill` (dry-run–previewed backfill), `mongo-schema-drift-review` (sampled
+dot-path drift). All are read-only `plan-only` — pick the pack matching the situation, and
+run any index/DDL proposal through `migration-review` before writing. Redis/Elasticsearch
+have no packs yet — lead with `guide` / `report` there.
 
 Tasks live under `assets/tasks/` (builtin), `.dbcli-shared/tasks/` (shared), and
 `.dbcli/tasks/` (local override).
@@ -101,9 +105,9 @@ in **How to use dbcli** still applies.
 | DB-backed feature | `blacklist list` → `schema <object>` → `queries suggest <intent>` |
 | DB report / dashboard request | `blacklist list` → `queries search <keywords>` / `queries suggest <intent>` → `queries show @<name>` → `q @<name> --ui` or `--format html` |
 | Application data bug | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → narrow query |
-| ORM or migration work | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column` (preview SQL) → `diff --against <snapshot>` |
+| ORM or migration work | `schema --format json` → `diff --against-orm <orm-schema>` → review error-level drift → proposals via `migrate` (dry-run) → `migration-review` task pack → `diff --against <snapshot>` after applying. |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
-| Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
+| Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
 | Safe data backfill | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back or snippet `--verify`. |
 | Environment validation | `status --format json` → `doctor --format json` → `inspect --for-agent --no-connect`. |
 
@@ -121,9 +125,13 @@ dbcli q @<name> --param k=v --format html > report.html
 dbcli export "<SQL>" --format html --output report.html
 dbcli audit tail --for-agent --n 10
 dbcli diff --snapshot <name>
+dbcli diff --against-orm prisma/schema.prisma --format json
+dbcli diff --against-orm "migrations/*.sql" --format markdown
+dbcli skill tasks plan orm-drift-review --param orm_path=prisma/schema.prisma --format json
 dbcli report --section perf --format json
 dbcli skill tasks plan analyze-table-perf --param table=<table> --format json
 dbcli guide missing-index-for "<query>" --format json
+dbcli lint "<SQL>" --format json
 dbcli update <object> --where "<bounded predicate>" --set '<json>' --dry-run --format json
 dbcli inspect --for-agent --no-connect --format json
 ```
@@ -290,6 +298,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
 | `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. Supports `--recovery`. |
 | `explain` | query-only+ | **(v1.23)** Read-only query plan with annotations. SQL only. Single query, `@saved-query`, `@file.sql`, or `--bulk @glob/*`. `--analyze` (EXPLAIN ANALYZE / MariaDB ANALYZE SELECT), `--format markdown\|json\|table`. |
+| `lint` | n/a | Static SQL anti-pattern advisor (no DB connection). 9 rules incl. schema-aware implicit-cast / NOT IN-nullable checks via the layered `.dbcli/schemas/` cache; global `--use <conn>` selects a named cache. Findings carry rewrite drafts + guarded `explain` verify commands (`--analyze` only for proven read-only SQL) — report-only, never executes. `--format text\|json\|markdown`, `--min-severity`, `--no-schema`, `--bulk`. Supports `--recovery`. |
 | `plan` | n/a | Static SQL risk analyzer (`--format text\|json`); classifies a statement without connecting to the database. |
 | `q` | query-only+ | Run a saved snippet by `@name` with `--param k=v`. Supports `--verify` to run assertions. |
 | `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
@@ -298,7 +307,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. Supports `--recovery`. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
 | `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
-| `diff` | query-only+ | SQL only. Save/compare schema snapshots. |
+| `diff` | query-only+ | SQL only. Save/compare schema snapshots. **(P1b)** `--against-orm <path>` compares a Prisma schema / DDL file / normalized JSON against the local schema cache (no DB connection): categorized drift (`missing_in_db` = error, `missing_in_orm` = warn, `mismatch` per tolerance table, `unmanaged`) with dry-run `migrate` proposals; exit 1 on error-level drift. `--orm-format prisma\|ddl\|json\|drizzle\|typeorm\|sequelize`, `--ignore <globs>`, `--format json\|table\|markdown`. Drizzle: point at `drizzle/meta/<NNNN>_snapshot.json` (run `drizzle-kit generate` first; `.ts` sources are rejected with a hint). TypeORM/Sequelize: feed tool-generated DDL (`schema:log` / a schema-only dump); source files are rejected with the exact generation command to run. |
 | `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. |
@@ -318,7 +327,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 
 `--use <name>` on any subcommand (including `status` / `doctor`) targets a v2 connection
 without changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `update`,
-`delete`, `export`, `schema`, and `inspect` (see **On failure** above).
+`delete`, `export`, `schema`, `inspect`, `lint`, and `diff --against-orm` (see **On failure** above).
 
 **Write & query flag semantics** (SQL/Mongo `insert`/`update`):
 

package/assets/SKILL.zh-TW.md

@@ -40,13 +40,13 @@ description: Database CLI for AI agents with permission-based access control. Us
 
 慢查詢診斷有三條標準路徑（依已掌握的資訊選擇）：
 
-- 已知慢 SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `guide missing-index-for "<SQL>"`
+- 已知慢 SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `lint "<SQL>"` → `guide missing-index-for "<SQL>"`
 - 已知熱點資料表 → `skill tasks plan analyze-table-perf --param table=<table>`
 - 全環境掃描 → `report --section perf` → `guide slow-query`
 
 `report --section perf` 已涵蓋 slow-query、index-usage 與 cache-hit 診斷 — 之後只需補上它未涵蓋的 `@diag/*`（`missing-indexes`、`locks`、`connections`、`table-sizes`）。一旦鎖定特定慢語句，`explain --analyze "<SQL>"` 可顯示執行計畫。
 
-**失敗時：** 在 `query` / `q` / `insert` / `update` / `delete` / `export` / `schema` / `inspect` 加上 `--recovery`。指令會把 `RecoveryEnvelope` 輸出到 stdout 並儲存到 `.dbcli/last-recovery.json`；然後用 `dbcli recover` 檢視、`dbcli recover --apply` 在風險門控下執行儲存的計畫。Multi-turn `--next`、連線分支與 post-apply 驗證探針詳見 reference.md §Recovery Cookbook。
+**失敗時：** 在 `query` / `q` / `insert` / `update` / `delete` / `export` / `schema` / `inspect` / `lint` / `diff --against-orm` 加上 `--recovery`。指令會把 `RecoveryEnvelope` 輸出到 stdout 並儲存到 `.dbcli/last-recovery.json`；然後用 `dbcli recover` 檢視、`dbcli recover --apply` 在風險門控下執行儲存的計畫。Multi-turn `--next`、連線分支與 post-apply 驗證探針詳見 reference.md §Recovery Cookbook。
 
 回報驗證結果時使用詞彙：`verified`（證據符合）/ `not_verified`（驗證執行但結果矛盾）/ `indeterminate`（執行但證據不明確）/ `blocked`（因 config、權限、schema、placeholder 或安全閘門導致無法執行）。
 
@@ -64,7 +64,7 @@ dbcli skill tasks plan <task> --param key=value --format json     # generate pla
 
 計畫輸出是一組附帶說明與風險標籤的 dbcli 指令序列。請逐一執行 — 任務計畫**不會**繞過 blacklist、schema、dry-run 或確認等要求。
 
-內建套件：`diagnose-slow-query`（針對特定 SQL）、`analyze-table-perf`（針對特定資料表；`dbcli inspect` 會針對近期 audit 活動中最熱門的資料表自動建議此套件）、`audit-permissions`、`safe-backfill`、`schema-drift-review`、`connection-health`。審查與驗證套件：`pr-database-review`、`migration-review`、`safe-backfill-verify`、`slow-endpoint-investigation`。全部為唯讀 `plan-only` — 選擇符合使用者情境的套件，任何索引 / DDL 提案都應先經 `migration-review` 再寫入。
+內建套件（SQL — postgres/mysql）：`diagnose-slow-query`（針對特定 SQL）、`analyze-table-perf`（針對特定資料表；`dbcli inspect` 會針對近期 audit 活動中最熱門的資料表自動建議此套件）、`audit-permissions`、`safe-backfill`、`schema-drift-review`、`orm-drift-review`（ORM 定義與快取 DB schema 比對）、`connection-health`。審查與驗證套件：`pr-database-review`、`migration-review`、`safe-backfill-verify`、`slow-endpoint-investigation`。MongoDB 套件：`mongo-safe-backfill`（以 dry-run 預覽的回填）、`mongo-schema-drift-review`（抽樣 dot-path 漂移）。全部為唯讀 `plan-only` — 選擇符合使用者情境的套件，任何索引 / DDL 提案都應先經 `migration-review` 再寫入。Redis/Elasticsearch 目前尚無套件——請改以 `guide` / `report` 為主。
 
 任務檔放在 `assets/tasks/`（內建）、`.dbcli-shared/tasks/`（共享）與 `.dbcli/tasks/`（本地覆寫）。
 
@@ -77,9 +77,9 @@ dbcli skill tasks plan <task> --param key=value --format json     # generate pla
 | DB-backed 功能 | `blacklist list` → `schema <object>` → `queries suggest <intent>` |
 | DB report / dashboard request | `blacklist list` → `queries search <keywords>` / `queries suggest <intent>` → `queries show @<name>` → `q @<name> --ui` 或 `--format html` |
 | 應用程式資料錯誤 | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → 最小查詢 |
-| ORM 或 migration | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column`（預覽 SQL）→ `diff --against <snapshot>` |
+| ORM 或 migration | `schema --format json` → `diff --against-orm <orm-schema>` → 審查 error-level drift → 透過 `migrate` 取得提案（dry-run）→ `migration-review` task pack → 套用後執行 `diff --against <snapshot>`。 |
 | PR 資料庫風險審查 | 審查變更的 persistence path，並針對每個重要主張提出具體 `schema`、`plan`、`dry-run`、`report` 或 `guide` 指令。 |
-| 慢 endpoint 或查詢 | `report --section perf` → task pack `analyze-table-perf` → `guide missing-index-for "<query>"`；有 proxy log 時使用 `proxy analyze`。 |
+| 慢 endpoint 或查詢 | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`；有 proxy log 時使用 `proxy analyze`。 |
 | 安全資料回填 | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back 或 snippet `--verify`。 |
 | 環境設定驗證 | `status --format json` → `doctor --format json` → `inspect --for-agent --no-connect`。 |
 
@@ -95,9 +95,13 @@ dbcli q @<name> --param k=v --format html > report.html
 dbcli export "<SQL>" --format html --output report.html
 dbcli audit tail --for-agent --n 10
 dbcli diff --snapshot <name>
+dbcli diff --against-orm prisma/schema.prisma --format json
+dbcli diff --against-orm "migrations/*.sql" --format markdown
+dbcli skill tasks plan orm-drift-review --param orm_path=prisma/schema.prisma --format json
 dbcli report --section perf --format json
 dbcli skill tasks plan analyze-table-perf --param table=<table> --format json
 dbcli guide missing-index-for "<query>" --format json
+dbcli lint "<SQL>" --format json
 dbcli update <object> --where "<bounded predicate>" --set '<json>' --dry-run --format json
 dbcli inspect --for-agent --no-connect --format json
 ```
@@ -232,6 +236,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `schema` | query-only+ | SQL：單表或全掃描存入 `.dbcli/schemas/`。MongoDB：sampled。ES：flattened mapping。Redis：僅單一 key（type / TTL / size）。支援 `--recovery`。 |
 | `query` | query-only+ | SQL、Mongo JSON（`--collection`）、Redis 指令、ES DSL / Lucene（`--collection`）。`--format table\|json\|csv\|html`、`--ui` 開啟瀏覽器互動式 dashboard。支援 `--recovery`。 |
 | `explain` | query-only+ | **(v1.23)** 唯讀查詢計畫並附註解。僅 SQL。單一查詢、`@saved-query`、`@file.sql` 或 `--bulk @glob/*`。`--analyze`（EXPLAIN ANALYZE / MariaDB ANALYZE SELECT）、`--format markdown\|json\|table`。 |
+| `lint` | n/a | 靜態 SQL 反模式顧問（不連線 DB）。共 9 條規則，包含透過分層 `.dbcli/schemas/` 快取進行的 schema-aware implicit-cast / NOT IN-nullable 檢查；全域 `--use <conn>` 會選擇命名連線的快取。Finding 可附 rewrite 草稿與受保護的 `explain` 驗證指令；只有已證明唯讀的 SQL 才會加上 `--analyze`，且只回報、絕不執行。`--format text\|json\|markdown`、`--min-severity`、`--no-schema`、`--bulk`。支援 `--recovery`。 |
 | `plan` | n/a | 靜態 SQL 風險分析器（`--format text\|json`）；不連線即可分類語句。 |
 | `q` | query-only+ | 以 `@name` 執行已儲存 snippet，搭配 `--param k=v`。支援 `--verify` 以執行斷言。 |
 | `queries` | n/a | 管理已儲存 snippet：`list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`。 |
@@ -240,7 +245,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `export` | query-only+ | SQL、MongoDB 或 **(v1.22)** Elasticsearch（DSL `--index` 或全 index scroll）。Query → `--format json\|jsonl\|csv\|html` 檔案或 stdout。`html` 輸出獨立可互動 dashboard。支援 `--recovery`。 |
 | `blacklist` | n/a | `list` / `table` / `column` 子指令，從查詢結果中遮蔽敏感資料。 |
 | `check` | query-only+ | 僅 SQL（在 MySQL / MariaDB 最佳）。 |
-| `diff` | query-only+ | 僅 SQL。儲存 / 比較 schema snapshot。 |
+| `diff` | query-only+ | 僅 SQL。儲存 / 比較 schema snapshot。**(P1b)** `--against-orm <path>` 會將 Prisma schema / DDL 檔 / normalized JSON 與本地 schema cache 比對（不連線 DB）：分類為 `missing_in_db`（error）、`missing_in_orm`（warn）、依 tolerance 表判定的 `mismatch`、以及 `unmanaged`，並提供 dry-run `migrate` 提案；出現 error-level drift 時 exit 1。`--orm-format prisma\|ddl\|json\|drizzle\|typeorm\|sequelize`、`--ignore <globs>`、`--format json\|table\|markdown`。Drizzle：請指向 `drizzle/meta/<NNNN>_snapshot.json`（先執行 `drizzle-kit generate`；`.ts` source 會被拒絕並顯示提示）。TypeORM/Sequelize：傳入工具產生的 DDL（`schema:log` / schema-only dump）；source file 會被拒絕，並顯示要執行的精確產生指令。 |
 | `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 <id-or-path>` / `summary` 為唯讀；`prune` 預設 dry-run，僅在 `--execute --force` 時刪除。讀取 `<cwd>/.dbcli/verification/`；不需 DB 連線，不寫入 audit log。 |
@@ -258,7 +263,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷（用於注入其他 LLM，正常操作不需要）。 |
 | `migrate` | admin | 僅 SQL。**DDL；預設 dry-run** — 需 `--execute`。 |
 
-任何子指令上的 `--use <name>` 可在不改變預設值的情況下，把目標切到 v2 連線。`--recovery` 被 `query`、`q`、`insert`、`update`、`delete`、`export`、`schema` 與 `inspect` 支援（見上方**失敗時**）。
+任何子指令上的 `--use <name>` 可在不改變預設值的情況下，把目標切到 v2 連線。`--recovery` 被 `query`、`q`、`insert`、`update`、`delete`、`export`、`schema`、`inspect`、`lint` 與 `diff --against-orm` 支援（見上方**失敗時**）。
 
 **寫入與查詢旗標語意**（SQL / Mongo `insert`/`update`）：