@carllee1983/dbcli 1.52.1 → 1.53.0

package/.cursor/rules/dbcli.mdc

@@ -110,8 +110,8 @@ still stop where those gates require human confirmation.
 term, or relationship/join intent instead of a physical table or field name, first run
 `dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
 section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
-to look up a specific term. If no semantic section exists or search returns no result,
-fall back to `blacklist` → `schema` mapping and tell the user that optional
+to look up a specific term. If `contracts` is present, use only its approved terms and
+their descriptive evidence policy; it never authorizes an assertion or query. If no semantic section exists or search returns no result, fall back to `blacklist` → `schema` mapping and tell the user that optional
 `dbcli.semantic.json` can make future requests consistent. Never create, update, or
 migrate that file without an explicit human request; semantic vocabulary never replaces
 schema confirmation or the normal query/write safety gates.
@@ -159,6 +159,7 @@ in **How to use dbcli** still applies.
 | 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. |
 | Schema design, no database yet | `design init --output ./dbcli.design.json` → edit → `design validate` → `design render --format mermaid`. With existing ORM models, reconcile via `design diff --against-orm <path>` first. |
 | Design drift on a live database | `blacklist list` → `schema --format json` → `design diff --against-cache` → `design propose --against-cache`, then hand the plan to a human before any migration. |
+| PR schema-change review | `blacklist list` → `impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn`; optionally add explicit `--events ./.dbcli/proxy/events.jsonl` for advisory redacted workload table evidence (never SQL/log rendering or a blocker), then review declared findings, coverage gaps, and the optional reviewed `dbcli.data-access.json` (declared operations only; never source parsing). |
 | 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` → `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`. |
@@ -201,7 +202,9 @@ Guardrails:
 - Durable evidence: `assert … --write-verification-artifact --verification-subject <kind:name>`;
   inspect with `verification summary` / `list` / `show <id>`. The `verify safe-backfill` /
   `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>`
-  family runs preflight + `--after-write` checks and **never executes the write**. Full flags
+  family runs preflight + `--after-write` checks and **never executes the write**. Add
+  `--evidence-receipt <workspace-relative-path>` only after after-write for a safe provenance
+  receipt; it is never approval to execute a write. Full flags
   and the per-command blocks are in [reference.md](../skills/dbcli/reference.md#commands).
 
 ## Audit log
@@ -415,6 +418,7 @@ Full flags and edge cases: see [reference.md](../skills/dbcli/reference.md#init)
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
+| `contract` | n/a | Validate, inspect approved context, search, or inspect drift for optional project-root `dbcli.contracts.json`. Contracts add ownership and a descriptive evidence policy to canonical semantic references; they are offline, never execute SQL, and cannot create verification or query authority. `skill context` includes only valid approved contracts. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

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

@@ -38,6 +38,7 @@ never the right move.
 [check](#check) ·
 [diff](#diff) ·
 [design](#design) ·
+[impact assess](#impact-assess) ·
 [snapshot](#snapshot) ·
 [assert](#assert) ·
 [proxy](#proxy) ·
@@ -51,12 +52,14 @@ never the right move.
 [verify](#verify) ·
 [verification](#verification) ·
 [backfill](#backfill) ·
+[evidence](#evidence) ·
 [doctor](#doctor) ·
 [completion](#completion) ·
 [upgrade](#upgrade) ·
 [shell](#dbcli-shell) ·
 [migrate](#migrate) ·
 [semantic](#semantic) ·
+[contract](#contract) ·
 [skill](#skill) ·
 [skill context](#skill-context) ·
 [skill tasks](#skill-tasks-agent-task-packs)
@@ -1189,6 +1192,7 @@ dbcli design validate [--file <path>] [--format <format>]
 dbcli design render [--file <path>] [--format <format>]
 dbcli design diff (--against-cache | --against-orm <paths>) [options]
 dbcli design propose (--against-cache | --against-orm <paths>) [options]
+dbcli impact assess --design <path> (--against-cache | --against-orm <paths>) --output <path> [options]
 ```
 
 ```bash
@@ -1200,6 +1204,7 @@ dbcli design render --format mermaid
 dbcli design diff --against-cache --format markdown
 dbcli design diff --against-orm ./prisma/schema.prisma --format markdown
 dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
+dbcli impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn
 ```
 
 | Option | Applies to | Default | Meaning |
@@ -1216,6 +1221,10 @@ dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
 `diff` and `propose` require **exactly one** comparison target; passing both or
 neither is an error.
 
+### impact assess
+
+Writes an offline JSON or Markdown report for the known declared impact of a design change. It requires `--design`, exactly one baseline (`--against-cache` or `--against-orm`), and an explicit workspace-contained `--output`. `--format` is `json` (default) or `markdown`; `--fail-on` is `error`, `warn`, or `never` (default). The threshold changes only the successful command exit code after the report is written. The report is limited to declared/partial coverage and never claims complete coverage. It may join the optional reviewed `dbcli.data-access.json` manifest only after validating its canonical semantic references and existing workspace-relative source paths; it never reads those sources. An optional explicit `--events <path>` is bounded and streamed through a redaction-first projection that retains recent safe table metadata only. It never starts a proxy, reads a rotated log, renders SQL/literals/errors/sessions/paths, or makes the command fail solely because workload evidence is absent or advisory. It reads no database, executes no SQL, and never reads saved-query bodies.
+
 #### Artifact shape
 
 This example validates clean (0 errors, 0 warnings):
@@ -1939,7 +1948,7 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 ### verify
 
 Run a verification scenario. `verify` **runs** verification scenarios (safe-backfill,
-migration, rollback) and never executes writes/DDL. `verification` **inspects and manages**
+migration, rollback, constraint) and never executes writes/DDL. `verification` **inspects and manages**
 the local result artifacts those scenarios produce under `.dbcli/verification/`.
 
 ```bash
@@ -1951,7 +1960,8 @@ dbcli verify safe-backfill \
   --expect "value == 0"
 
 # After-write: re-run guards, run the read-back assertion, write a v1 artifact.
-dbcli verify safe-backfill ... --after-write
+# An optional receipt is provenance only, never approval to execute a write.
+dbcli verify safe-backfill ... --after-write --evidence-receipt .dbcli/evidence/verify-receipt.json
 
 # JSON for agents.
 dbcli verify safe-backfill ... --format json
@@ -1959,7 +1969,11 @@ 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>`.
+`--subject-name <name>`, `--summary <text>`, `--evidence-receipt <workspace-relative-path>`
+(after-write only). A receipt is safe provenance for the already-executed verification,
+not approval to execute a write. Its `succeeded`/`failed` outcome remains distinct from
+the artifact status (`verified`, `not_verified`, `indeterminate`, or `blocked`); task-pack
+`planned` evidence stays plan-only.
 
 Guard constraints (fail closed): `--verify-query` must be a **plain `SELECT`** —
 `EXPLAIN`/`EXPLAIN ANALYZE`, `SHOW`, `DESCRIBE`, and data-modifying CTEs are rejected
@@ -2464,6 +2478,66 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### evidence
+
+Compose a canonical, offline **Evidence Pack** from existing verification artifacts
+and audit entries. This command never opens a database connection. A pack retains only
+safe pointers and outcome fields: it excludes SQL, targets, audit metadata, verification
+summaries, result data, and credentials. Claims are external statements, never dbcli
+verification verdicts.
+
+#### `evidence compose`
+
+```bash
+dbcli evidence compose --claims ./claims.json --verification ver_abcd --audit 1a2b \
+  --receipt .dbcli/evidence/verify-receipt.json \
+  --output .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--claims <file>` | Required JSON file with exactly `subject` and `claims`; every claim has an `id` and plain-language `text`. SQL-shaped text, credentials, error content, and blacklisted identifiers are rejected. | — |
+| `--verification <selector...>` | One or more verification artifact ids, unique prefixes, filenames, or in-bounds paths. | none |
+| `--audit <selector...>` | One or more audit ids or unique prefixes (minimum four characters) from the active connection. | none |
+| `--receipt <path...>` | Explicit workspace-relative receipt path(s). Receipts contribute safe provenance only; they are not execution approval. | none |
+| `--output <path>` | Required new JSON path under the current workspace. Existing files and paths outside the workspace are refused. | — |
+| `--format <json\|markdown>` | Compose receipt format printed to stdout. | `json` |
+
+At least one `--verification`, `--audit`, or `--receipt` reference is required. The resulting pack
+contains a canonical SHA-256 integrity digest and `coverage.completeForDeclaredEvidence:
+true` for its explicitly selected references.
+
+#### `evidence validate`
+
+```bash
+dbcli evidence validate --file .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Validation report format. | `json` |
+
+Exit `0` when digest and all selected sources are valid. If a referenced audit or
+verification artifact later rotates, is cleared, disappears, or belongs to a different
+active connection, output stays parseable with `integrity: "valid"` and
+`references: "source-expired"`, then exits `1`.
+
+#### `evidence render`
+
+```bash
+dbcli evidence render --file .dbcli/evidence/review.json --format markdown
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Render format. | `markdown` |
+
+`render` validates the pack digest and active blacklist policy but does not resolve its
+original references. It is therefore available for historical review after `validate`
+reports `source-expired`, unless an exposed pack field is now blacklisted.
+
 ### semantic
 
 Validate or print the optional, version-controlled `dbcli.semantic.json` in the
@@ -2590,6 +2664,39 @@ limits, audit, and recovery safeguards remain in force.
 
 **Permission:** n/a (local files only; no database connection).
 
+### contract
+
+Inspect the optional, version-controlled `dbcli.contracts.json` without opening a
+database connection. A contract adds a reviewed owner and descriptive evidence policy
+to canonical semantic references; it is not an executable data contract, assertion,
+query, or verification scenario.
+
+```bash
+dbcli contract validate --format json
+dbcli contract context --format json
+dbcli contract context --format markdown
+dbcli contract search customer --format json
+dbcli contract drift --format json
+```
+
+The strict v1 artifact contains `version` and `contracts`. Each contract has a unique
+canonical `name`, `status` (`draft`, `approved`, or `deprecated`), bounded plain-text
+`description` and `owner`, one or more canonical semantic `subjects`, optional aliases,
+and an `evidencePolicy` of `none`, `receipt-required`, or `verification-required`.
+Subjects must remain in the existing visible semantic registry; protected identifiers,
+unknown keys, duplicate names or subjects, SQL-like text, credentials, and stale
+references fail closed without exposing protected names.
+
+`contract validate` requires an explicit valid artifact. `contract context` and
+`contract search` return only valid approved contracts; draft and deprecated contracts
+remain local review artifacts. `contract drift` reports `valid`, `stale`, `invalid`, or
+`unavailable` evidence offline and exits non-zero except for `valid`. A missing default
+file is allowed by `skill context` and leaves ordinary semantic context unchanged; a
+present invalid file fails closed. No contract command writes a file, opens a database
+connection, widens a `QueryDraft`, or changes permission/blacklist behavior.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an

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

@@ -110,8 +110,8 @@ still stop where those gates require human confirmation.
 term, or relationship/join intent instead of a physical table or field name, first run
 `dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
 section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
-to look up a specific term. If no semantic section exists or search returns no result,
-fall back to `blacklist` → `schema` mapping and tell the user that optional
+to look up a specific term. If `contracts` is present, use only its approved terms and
+their descriptive evidence policy; it never authorizes an assertion or query. If no semantic section exists or search returns no result, fall back to `blacklist` → `schema` mapping and tell the user that optional
 `dbcli.semantic.json` can make future requests consistent. Never create, update, or
 migrate that file without an explicit human request; semantic vocabulary never replaces
 schema confirmation or the normal query/write safety gates.
@@ -159,6 +159,7 @@ in **How to use dbcli** still applies.
 | 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. |
 | Schema design, no database yet | `design init --output ./dbcli.design.json` → edit → `design validate` → `design render --format mermaid`. With existing ORM models, reconcile via `design diff --against-orm <path>` first. |
 | Design drift on a live database | `blacklist list` → `schema --format json` → `design diff --against-cache` → `design propose --against-cache`, then hand the plan to a human before any migration. |
+| PR schema-change review | `blacklist list` → `impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn`; optionally add explicit `--events ./.dbcli/proxy/events.jsonl` for advisory redacted workload table evidence (never SQL/log rendering or a blocker), then review declared findings, coverage gaps, and the optional reviewed `dbcli.data-access.json` (declared operations only; never source parsing). |
 | 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` → `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`. |
@@ -201,7 +202,9 @@ Guardrails:
 - Durable evidence: `assert … --write-verification-artifact --verification-subject <kind:name>`;
   inspect with `verification summary` / `list` / `show <id>`. The `verify safe-backfill` /
   `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>`
-  family runs preflight + `--after-write` checks and **never executes the write**. Full flags
+  family runs preflight + `--after-write` checks and **never executes the write**. Add
+  `--evidence-receipt <workspace-relative-path>` only after after-write for a safe provenance
+  receipt; it is never approval to execute a write. Full flags
   and the per-command blocks are in [reference.md](reference.md#commands).
 
 ## Audit log
@@ -415,6 +418,7 @@ Full flags and edge cases: see [reference.md](reference.md#init).
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
+| `contract` | n/a | Validate, inspect approved context, search, or inspect drift for optional project-root `dbcli.contracts.json`. Contracts add ownership and a descriptive evidence policy to canonical semantic references; they are offline, never execute SQL, and cannot create verification or query authority. `skill context` includes only valid approved contracts. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

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

@@ -38,6 +38,7 @@ never the right move.
 [check](#check) ·
 [diff](#diff) ·
 [design](#design) ·
+[impact assess](#impact-assess) ·
 [snapshot](#snapshot) ·
 [assert](#assert) ·
 [proxy](#proxy) ·
@@ -51,12 +52,14 @@ never the right move.
 [verify](#verify) ·
 [verification](#verification) ·
 [backfill](#backfill) ·
+[evidence](#evidence) ·
 [doctor](#doctor) ·
 [completion](#completion) ·
 [upgrade](#upgrade) ·
 [shell](#dbcli-shell) ·
 [migrate](#migrate) ·
 [semantic](#semantic) ·
+[contract](#contract) ·
 [skill](#skill) ·
 [skill context](#skill-context) ·
 [skill tasks](#skill-tasks-agent-task-packs)
@@ -1189,6 +1192,7 @@ dbcli design validate [--file <path>] [--format <format>]
 dbcli design render [--file <path>] [--format <format>]
 dbcli design diff (--against-cache | --against-orm <paths>) [options]
 dbcli design propose (--against-cache | --against-orm <paths>) [options]
+dbcli impact assess --design <path> (--against-cache | --against-orm <paths>) --output <path> [options]
 ```
 
 ```bash
@@ -1200,6 +1204,7 @@ dbcli design render --format mermaid
 dbcli design diff --against-cache --format markdown
 dbcli design diff --against-orm ./prisma/schema.prisma --format markdown
 dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
+dbcli impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn
 ```
 
 | Option | Applies to | Default | Meaning |
@@ -1216,6 +1221,10 @@ dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
 `diff` and `propose` require **exactly one** comparison target; passing both or
 neither is an error.
 
+### impact assess
+
+Writes an offline JSON or Markdown report for the known declared impact of a design change. It requires `--design`, exactly one baseline (`--against-cache` or `--against-orm`), and an explicit workspace-contained `--output`. `--format` is `json` (default) or `markdown`; `--fail-on` is `error`, `warn`, or `never` (default). The threshold changes only the successful command exit code after the report is written. The report is limited to declared/partial coverage and never claims complete coverage. It may join the optional reviewed `dbcli.data-access.json` manifest only after validating its canonical semantic references and existing workspace-relative source paths; it never reads those sources. An optional explicit `--events <path>` is bounded and streamed through a redaction-first projection that retains recent safe table metadata only. It never starts a proxy, reads a rotated log, renders SQL/literals/errors/sessions/paths, or makes the command fail solely because workload evidence is absent or advisory. It reads no database, executes no SQL, and never reads saved-query bodies.
+
 #### Artifact shape
 
 This example validates clean (0 errors, 0 warnings):
@@ -1939,7 +1948,7 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 ### verify
 
 Run a verification scenario. `verify` **runs** verification scenarios (safe-backfill,
-migration, rollback) and never executes writes/DDL. `verification` **inspects and manages**
+migration, rollback, constraint) and never executes writes/DDL. `verification` **inspects and manages**
 the local result artifacts those scenarios produce under `.dbcli/verification/`.
 
 ```bash
@@ -1951,7 +1960,8 @@ dbcli verify safe-backfill \
   --expect "value == 0"
 
 # After-write: re-run guards, run the read-back assertion, write a v1 artifact.
-dbcli verify safe-backfill ... --after-write
+# An optional receipt is provenance only, never approval to execute a write.
+dbcli verify safe-backfill ... --after-write --evidence-receipt .dbcli/evidence/verify-receipt.json
 
 # JSON for agents.
 dbcli verify safe-backfill ... --format json
@@ -1959,7 +1969,11 @@ 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>`.
+`--subject-name <name>`, `--summary <text>`, `--evidence-receipt <workspace-relative-path>`
+(after-write only). A receipt is safe provenance for the already-executed verification,
+not approval to execute a write. Its `succeeded`/`failed` outcome remains distinct from
+the artifact status (`verified`, `not_verified`, `indeterminate`, or `blocked`); task-pack
+`planned` evidence stays plan-only.
 
 Guard constraints (fail closed): `--verify-query` must be a **plain `SELECT`** —
 `EXPLAIN`/`EXPLAIN ANALYZE`, `SHOW`, `DESCRIBE`, and data-modifying CTEs are rejected
@@ -2464,6 +2478,66 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### evidence
+
+Compose a canonical, offline **Evidence Pack** from existing verification artifacts
+and audit entries. This command never opens a database connection. A pack retains only
+safe pointers and outcome fields: it excludes SQL, targets, audit metadata, verification
+summaries, result data, and credentials. Claims are external statements, never dbcli
+verification verdicts.
+
+#### `evidence compose`
+
+```bash
+dbcli evidence compose --claims ./claims.json --verification ver_abcd --audit 1a2b \
+  --receipt .dbcli/evidence/verify-receipt.json \
+  --output .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--claims <file>` | Required JSON file with exactly `subject` and `claims`; every claim has an `id` and plain-language `text`. SQL-shaped text, credentials, error content, and blacklisted identifiers are rejected. | — |
+| `--verification <selector...>` | One or more verification artifact ids, unique prefixes, filenames, or in-bounds paths. | none |
+| `--audit <selector...>` | One or more audit ids or unique prefixes (minimum four characters) from the active connection. | none |
+| `--receipt <path...>` | Explicit workspace-relative receipt path(s). Receipts contribute safe provenance only; they are not execution approval. | none |
+| `--output <path>` | Required new JSON path under the current workspace. Existing files and paths outside the workspace are refused. | — |
+| `--format <json\|markdown>` | Compose receipt format printed to stdout. | `json` |
+
+At least one `--verification`, `--audit`, or `--receipt` reference is required. The resulting pack
+contains a canonical SHA-256 integrity digest and `coverage.completeForDeclaredEvidence:
+true` for its explicitly selected references.
+
+#### `evidence validate`
+
+```bash
+dbcli evidence validate --file .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Validation report format. | `json` |
+
+Exit `0` when digest and all selected sources are valid. If a referenced audit or
+verification artifact later rotates, is cleared, disappears, or belongs to a different
+active connection, output stays parseable with `integrity: "valid"` and
+`references: "source-expired"`, then exits `1`.
+
+#### `evidence render`
+
+```bash
+dbcli evidence render --file .dbcli/evidence/review.json --format markdown
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Render format. | `markdown` |
+
+`render` validates the pack digest and active blacklist policy but does not resolve its
+original references. It is therefore available for historical review after `validate`
+reports `source-expired`, unless an exposed pack field is now blacklisted.
+
 ### semantic
 
 Validate or print the optional, version-controlled `dbcli.semantic.json` in the
@@ -2590,6 +2664,39 @@ limits, audit, and recovery safeguards remain in force.
 
 **Permission:** n/a (local files only; no database connection).
 
+### contract
+
+Inspect the optional, version-controlled `dbcli.contracts.json` without opening a
+database connection. A contract adds a reviewed owner and descriptive evidence policy
+to canonical semantic references; it is not an executable data contract, assertion,
+query, or verification scenario.
+
+```bash
+dbcli contract validate --format json
+dbcli contract context --format json
+dbcli contract context --format markdown
+dbcli contract search customer --format json
+dbcli contract drift --format json
+```
+
+The strict v1 artifact contains `version` and `contracts`. Each contract has a unique
+canonical `name`, `status` (`draft`, `approved`, or `deprecated`), bounded plain-text
+`description` and `owner`, one or more canonical semantic `subjects`, optional aliases,
+and an `evidencePolicy` of `none`, `receipt-required`, or `verification-required`.
+Subjects must remain in the existing visible semantic registry; protected identifiers,
+unknown keys, duplicate names or subjects, SQL-like text, credentials, and stale
+references fail closed without exposing protected names.
+
+`contract validate` requires an explicit valid artifact. `contract context` and
+`contract search` return only valid approved contracts; draft and deprecated contracts
+remain local review artifacts. `contract drift` reports `valid`, `stale`, `invalid`, or
+`unavailable` evidence offline and exits non-zero except for `valid`. A missing default
+file is allowed by `skill context` and leaves ordinary semantic context unchanged; a
+present invalid file fails closed. No contract command writes a file, opens a database
+connection, widens a `QueryDraft`, or changes permission/blacklist behavior.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.53.0] - 2026-08-09 - Offline evidence, semantic contracts, and impact assessment
+
+### Added
+
+- **Offline evidence packs.** `dbcli evidence compose`, `validate`, and `render` create, verify, and render workspace-contained evidence packs from safe claim text plus existing verification artifacts, audit entries, and optional assert receipts. Packs omit SQL, rows, targets, credentials, audit metadata, and verification summaries; source retention loss remains visible without preventing historical rendering.
+- **Evidence receipts for post-write assertions.** `assert --evidence-receipt <path>` atomically records safe provenance only after the verdict, audit attempt, and optional verification artifact are authoritative. Receipts are workspace-contained, contain no SQL or returned data, cannot be used as execution approval, and may be composed into an evidence pack.
+- **Reviewable semantic contracts.** `dbcli contract validate|context|search|drift` governs optional `dbcli.contracts.json` evidence expectations for canonical semantic terms. The commands are offline and read-only; only valid approved contracts enter ordinary agent context.
+- **Offline impact assessment.** `dbcli impact assess` creates a declared-coverage report for a design change against exactly one local schema-cache or ORM baseline, optionally incorporating reviewed data-access metadata and redaction-first proxy workload evidence. It never connects, executes SQL, or claims complete coverage.
+
+### Changed
+
+- **Shared execution and adapter boundaries.** Query execution now uses an injectable command runtime, SQL adapters share readiness and driver-error handling, and doctor accepts a non-SQL collector runtime. These internal changes keep the CLI behavior stable while making offline evidence and impact workflows testable.
+- **Documentation and agent skills cover the new surfaces.** English and Traditional Chinese Markdown and HTML guides, installed skill copies, and reference material document evidence packs, assert receipts, semantic contracts, and impact assessment.
+
+### Fixed
+
+- **Release audit no longer resolves a vulnerable `nanoid`.** The build-only PostCSS and Tailwind dependencies now resolve `nanoid@3.3.18`, satisfying the security advisory without adding a runtime dependency.
+
 ## [1.52.1] - 2026-08-08 - Skill audit: correct claims, per-platform install, drift gate
 
 ### Fixed

package/assets/SKILL.md

@@ -110,8 +110,8 @@ still stop where those gates require human confirmation.
 term, or relationship/join intent instead of a physical table or field name, first run
 `dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
 section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
-to look up a specific term. If no semantic section exists or search returns no result,
-fall back to `blacklist` → `schema` mapping and tell the user that optional
+to look up a specific term. If `contracts` is present, use only its approved terms and
+their descriptive evidence policy; it never authorizes an assertion or query. If no semantic section exists or search returns no result, fall back to `blacklist` → `schema` mapping and tell the user that optional
 `dbcli.semantic.json` can make future requests consistent. Never create, update, or
 migrate that file without an explicit human request; semantic vocabulary never replaces
 schema confirmation or the normal query/write safety gates.
@@ -159,6 +159,7 @@ in **How to use dbcli** still applies.
 | 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. |
 | Schema design, no database yet | `design init --output ./dbcli.design.json` → edit → `design validate` → `design render --format mermaid`. With existing ORM models, reconcile via `design diff --against-orm <path>` first. |
 | Design drift on a live database | `blacklist list` → `schema --format json` → `design diff --against-cache` → `design propose --against-cache`, then hand the plan to a human before any migration. |
+| PR schema-change review | `blacklist list` → `impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn`; optionally add explicit `--events ./.dbcli/proxy/events.jsonl` for advisory redacted workload table evidence (never SQL/log rendering or a blocker), then review declared findings, coverage gaps, and the optional reviewed `dbcli.data-access.json` (declared operations only; never source parsing). |
 | 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` → `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`. |
@@ -201,7 +202,9 @@ Guardrails:
 - Durable evidence: `assert … --write-verification-artifact --verification-subject <kind:name>`;
   inspect with `verification summary` / `list` / `show <id>`. The `verify safe-backfill` /
   `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>`
-  family runs preflight + `--after-write` checks and **never executes the write**. Full flags
+  family runs preflight + `--after-write` checks and **never executes the write**. Add
+  `--evidence-receipt <workspace-relative-path>` only after after-write for a safe provenance
+  receipt; it is never approval to execute a write. Full flags
   and the per-command blocks are in [reference.md](reference.md#commands).
 
 ## Audit log
@@ -415,6 +418,7 @@ Full flags and edge cases: see [reference.md](reference.md#init).
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
+| `contract` | n/a | Validate, inspect approved context, search, or inspect drift for optional project-root `dbcli.contracts.json`. Contracts add ownership and a descriptive evidence policy to canonical semantic references; they are offline, never execute SQL, and cannot create verification or query authority. `skill context` includes only valid approved contracts. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

package/assets/SKILL.zh-TW.md

@@ -84,7 +84,8 @@ blacklist、schema、permission、dry-run、production 選取或寫入確認閘
 **業務語言探索：** 當使用者以業務別名、metric、反覆出現的術語或 relationship/join 意圖，
 而非實體 table 或 field 名稱提出需求時，先執行 `dbcli skill context --format json`。若輸出含有
 `semantic`，將該已檢閱的區塊視為受治理詞彙；需查找特定術語時，用
-`dbcli semantic search <terms> --format json`。若沒有 semantic 區塊，或搜尋沒有結果，就退回
+`dbcli semantic search <terms> --format json`。若有 `contracts` 區塊，只能使用其中 approved 術語
+及描述性的 evidence policy；它絕不授權 assertion 或 query。若沒有 semantic 區塊，或搜尋沒有結果，就退回
 `blacklist` → `schema` 對照，並告知使用者可選用的 `dbcli.semantic.json` 能讓後續需求保持一致。
 除非人類明確要求，絕不可建立、更新或 migrate 此檔案；語意詞彙不能取代 schema 確認或正常的
 query/write 安全閘門。
@@ -117,6 +118,7 @@ dbcli skill tasks plan <task> --param key=value --format json     # generate pla
 | ORM 或 migration | `schema --format json` → `diff --against-orm <orm-schema>` → 審查 error-level drift → 透過 `migrate` 取得提案（dry-run）→ `migration-review` task pack → 套用後執行 `diff --against <snapshot>`。 |
 | 資料庫設計（尚未有 DB） | `design init --output ./dbcli.design.json` → 編輯 → `design validate` → `design render --format mermaid`。已有 ORM 模型時，先用 `design diff --against-orm <path>` 對齊。 |
 | 既有資料庫的設計漂移 | `blacklist list` → `schema --format json` → `design diff --against-cache` → `design propose --against-cache`，計畫交人類審查後才執行 migration。 |
+| PR schema 變更審查 | `blacklist list` → `impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn`；可選擇加入明確的 `--events ./.dbcli/proxy/events.jsonl` 取得 advisory、已 redaction 的 workload table evidence（不輸出 SQL/log，也不作為 blocker），再檢閱已宣告 findings、coverage gaps 與可選且已審閱的 `dbcli.data-access.json`（僅 declared operations；絕不解析 source）。 |
 | PR 資料庫風險審查 | 審查變更的 persistence path，並針對每個重要主張提出具體 `schema`、`plan`、`dry-run`、`report` 或 `guide` 指令。 |
 | 慢 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`。 |
@@ -153,7 +155,7 @@ dbcli inspect --for-agent --no-connect --format json
 - 不要直接從 performance suggestion 建 index；應轉成經過 review 的 migration。
 - 不要執行 `design propose` 計畫裡的 `commands`；未經人類要求，也不要建立或改寫 `dbcli.design.json`。
 - 不要列印 credentials、複製的連線字串或 blacklisted 值。
-- 持久化佐證：`assert … --write-verification-artifact --verification-subject <kind:name>`；以 `verification summary` / `list` / `show <id>` 檢視。`verify safe-backfill` / `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>` 系列執行 preflight + `--after-write` 驗證，**永不執行寫入**。完整旗標與每個指令的區塊詳見 [reference.md](reference.md#commands)。
+- 持久化佐證：`assert … --write-verification-artifact --verification-subject <kind:name>`；以 `verification summary` / `list` / `show <id>` 檢視。`verify safe-backfill` / `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>` 系列執行 preflight + `--after-write` 驗證，**永不執行寫入**。僅可在 after-write 後加入 `--evidence-receipt <工作區相對路徑>` 寫入安全 provenance receipt；它不代表核准執行寫入。完整旗標與每個指令的區塊詳見 [reference.md](reference.md#commands)。
 
 ## Audit Log 使用
 
@@ -329,6 +331,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `shell` | (與 query 同) | 互動式 REPL。SQL 引擎、MongoDB 與 Redis（單行；`.no-limit on/off`）。Elasticsearch 開啟 Kibana Dev Tools 風格的 REPL（`<METHOD> /<path>` + 可選 JSON body，空白行送出）。 |
 | `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，正常操作不需要）。 |
 | `semantic` | n/a | 驗證、搜尋、檢查漂移、遷移至 v2 或輸出可選的專案根目錄 `dbcli.semantic.json`。把已檢閱的 context 交給外部 agent，但 provider 憑證、prompt 與 agent context 都留在 dbcli 外。`semantic draft validate --input <file|-> [--format text\|json]` 只會以本機 semantic/schema/saved-query metadata 離線驗證明確提交、不受信任的 `QueryDraft`；只回傳安全的 hash/reference/violation code，絕不執行或回顯 candidate SQL。先檢閱原始 draft，若要執行再另行呼叫 `explain` 或 `query`。 |
+| `contract` | n/a | 驗證、檢視 approved context、搜尋或檢查可選專案根目錄 `dbcli.contracts.json` 的漂移。契約為 canonical semantic reference 加上 owner 與描述性的 evidence policy；完全離線、絕不執行 SQL，也不能建立 verification 或 query 權限。`skill context` 只納入有效且 approved 的契約。 |
 | `migrate` | admin | 僅 SQL。**DDL；預設 dry-run** — 需 `--execute`。 |
 
 任何指令都可使用 root 層級的 `dbcli --use <name> <command>`；`query`、`schema`、`list`、`export`、`check` 也接受指令層級的 `--use`。兩種寫法都只把本次目標切到 v2 連線，不改變預設值。`--recovery` 被 `query`、`q`、`insert`、`update`、`delete`、`export`、`schema`、`inspect`、`lint` 與 `diff --against-orm` 支援（見上方**失敗時**）。