@carllee1983/dbcli 12.0.0 → 12.1.0

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/.cursor/rules/dbcli.mdc

@@ -152,6 +152,14 @@ dbcli capabilities check --require schema.read,query.read         # gate your wo
 dbcli capabilities check --require data.delete --format json      # machine-readable
 ```
 
+`connection.tls` derives support from the engine matrix and maps to existing
+connection command surfaces, supporting PostgreSQL, MySQL and MariaDB. It adds
+no TLS subcommand. Check with
+`dbcli capabilities check --require connection.tls --format json`.
+`available` establishes tool support only, not TLS configuration, readable CA,
+a successful handshake or authorization. Catalog/check stay offline, read no CA
+and change no configuration. Older binaries without this ID return `unknown`.
+
 For a copyable Bun/TypeScript consumer with strict parsing, schema pins, exit handling,
 Operation Envelope handling, Task Pack `safety.requires`, and correlation/evidence guidance,
 start with `assets/integration-kit/README.md`.
@@ -326,6 +334,44 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
 > If a `.dbcli` already contains `{"$env": "..."}` references, **do not** rerun
 > `init` to "fill them in" — the env-ref form is intentional for CI/multi-env.
 
+### PostgreSQL, MySQL and MariaDB verified TLS
+
+When verified TLS is required, use the named `init` entry with both
+`--sql-tls verify-full --sql-tls-ca <path>`. PostgreSQL, MySQL and MariaDB support this SQL
+contract; explicit requests on other engines fail. The saved
+`sqlTls: { mode: 'verify-full', caPath: '/absolute/path/root-ca.pem' }` uses an
+absolute literal PEM path; `init` resolves relative paths from cwd. CA environment
+references are unsupported. Existing host/user environment references and profiles
+without `sqlTls` keep their behavior. V1 directory/v2 reads, normal `init` import
+from a V1 directory and `migrateV1ToV2` preserve TLS. Legacy V1 single-file TLS
+profiles remain readable/usable in human mode; automatic `init` import refuses
+before connecting or writing, preserving the original. Migrate that case by
+creating a verified named profile in a separate config directory, verifying it,
+then selecting it; preserve `sqlTls` throughout.
+
+Ambient TLS settings cannot weaken verification or supply another profile’s trust.
+Each connection reloads its own CA and verifies encryption, trust, validity and the
+configured DNS/IP identity; explicit SQL TLS refuses Unix sockets. Failures stop
+before the user query. Repair the CA, hostname or certificate; keep verification
+and TLS required. On binary rollback, stop TLS-required workflows or retain a
+supporting version: older binaries may strip `sqlTls`. Local fixture evidence does
+not establish real RDS acceptance. Configured permitted reads work in agent mode;
+`init` and other configuration changes remain refused.
+
+For TLS error recovery, repair certificates while retaining TLS, then explicitly
+select `--config <path>` or `--global`; v2 also requires `--use <name>` or
+`DBCLI_CONNECTION`. The selected profile must retain `sqlTls.mode: verify-full`.
+Missing, ambiguous or plaintext selections block live steps. Saved envelopes
+redact original selectors, so current targeting does not establish original
+provenance. Apply and verification use the current CLI binary. Example:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+For the complete configuration, example and failure contract, read
+[SQL verified TLS](../skills/dbcli/reference.md#verified-tls-for-postgresql-mysql-and-mariadb).
+
 ### Decision tree (ask before writing)
 
 1. **What is the connection name?** Every new connection uses named v2, even

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

@@ -157,7 +157,7 @@ Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `
 
 New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
 
-**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+**Key options:** `--sql-tls verify-full`, `--sql-tls-ca <path>`, `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
@@ -193,6 +193,57 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
 
+#### Verified TLS for PostgreSQL, MySQL and MariaDB
+
+Use both SQL TLS flags when creating a named PostgreSQL, MySQL or MariaDB profile. This example prompts for the password and tests the connection before saving:
+
+```bash
+dbcli init --conn-name verified-pg --system postgresql \
+  --host db.example.com --port 5432 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/root-ca.pem
+dbcli --use verified-pg blacklist list
+dbcli --use verified-pg schema public.events --format json
+dbcli --use verified-pg query "SELECT id FROM public.events LIMIT 10" --format json
+```
+
+MySQL and MariaDB use the same flags, with separate named profiles and CA paths. Select the corresponding profile, then check blacklist and schema before an authorized query:
+
+```bash
+dbcli init --conn-name verified-mysql --system mysql \
+  --host mysql.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mysql-ca.pem
+dbcli init --conn-name verified-mariadb --system mariadb \
+  --host mariadb.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mariadb-ca.pem
+```
+
+Replace the host, database and table with your authorized target; confirm real columns through schema before querying. The saved connection includes this dedicated SQL object (shown as a connection fragment):
+
+```json
+{
+  "sqlTls": {
+    "mode": "verify-full",
+    "caPath": "/absolute/path/to/certs/root-ca.pem"
+  }
+}
+```
+
+`--sql-tls verify-full` and `--sql-tls-ca <path>` are required together. Empty values, other modes and unsupported engines fail explicitly. PostgreSQL, MySQL and MariaDB support this SQL TLS contract; all other engines reject an explicit request. MongoDB's `tls` and Elasticsearch's TLS settings remain separate. Existing profiles without `sqlTls` keep their previous behavior; no global TLS policy is added. V1 directory and v2 profile reads, normal `init` import from a V1 directory to v2, and the public `migrateV1ToV2` helper preserve the TLS object. A legacy V1 single-file TLS profile remains readable and usable in human mode, but automatic `init` import explicitly refuses it before connecting or writing and leaves the original untouched. For that case, create a verified named profile in a separate configuration directory, verify it, then select it; preserve `sqlTls` throughout migration.
+
+`init` resolves a relative CA path against its current working directory before saving. Saved `caPath` must be a nonempty absolute literal path to a PEM CA bundle; it accepts no environment-variable reference. Existing environment references in host/user and other supported fields remain usable. Explicit TLS uses only the selected profile’s CA and identity settings; ambient TLS settings cannot weaken verification or supply another profile’s trust. Each new connection reads the CA bundle again; an unreadable, empty or invalid bundle stops before connecting. `--skip-test` skips only the initialization test, not verification on subsequent use.
+
+`verify-full` requires encryption, a trusted certificate chain, valid certificate dates and certificate identity matching the configured DNS name or IP address. Unix sockets are refused for explicit SQL TLS. Untrusted, expired or mismatched certificates and servers without TLS fail before the user query; there is no plaintext retry or verification downgrade. Correct the CA, target hostname or certificate validity before retrying. A cipher alone does not prove identity verification.
+
+For TLS error recovery, keep TLS configured and repair the CA, hostname or certificate first. Then deliberately select the configuration with `--config <path>` (or `--global`) and, for v2, the named profile with `--use <name>` (`DBCLI_CONNECTION` is also accepted). The selected profile must still have `sqlTls.mode: verify-full`; missing, ambiguous or plaintext selections block live recovery steps instead of falling back to a default plaintext connection. Saved recovery envelopes redact the original selectors: your current selection is deliberate targeting, not proof of the original target. Recovery apply and verification use the current CLI binary, avoiding an older `dbcli` on PATH. For the MySQL example above:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+Permitted reads through an already configured profile remain usable in agent mode; `init` and other configuration mutations remain refused under `DBCLI_AGENT_MODE=1`. TLS does not bypass explicit production selection, native database authorization, permission, blacklist, write-gate or audit controls.
+
+For binary rollback, stop workflows that require verified TLS or keep a supporting version. Older binaries may strip `sqlTls`; retaining the profile after downgrading does not preserve the guarantee. Removing TLS settings or retrying in plaintext cannot restore compliance. Local isolated PostgreSQL, MySQL and MariaDB fixture results are not evidence of real RDS acceptance; RDS remains unverified.
+
 ### use
 
 Set, clear, or display the default database connection (v2 multi-connection config).
@@ -1731,6 +1782,8 @@ Every actionable block carries machine-readable next steps so an agent can move
 
 ### capabilities
 
+`connection.tls` reports PostgreSQL, MySQL and MariaDB support from the engine capability matrix and maps to the existing connection command surfaces; it adds no TLS subcommand. Check with `dbcli --use verified-pg capabilities check --require connection.tls --format json`. `available` means tool support only: it does not prove that this profile configures TLS, the CA is readable, the handshake succeeds, or the operation is authorized. Catalog/check remain offline, read no CA bundle, perform no handshake and change no configuration. Other engines do not report this capability as available; older binaries without the ID return `unknown`. Configuration mutation still requires its own authorization.
+
 Discovery. Lists the static dbcli capability catalog — what this tool can do,
 described in a versioned shape an external Skill can parse before it starts
 working. It never opens a database connection and never writes anything.

package/.cursor-plugin/plugin.json

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

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

@@ -152,6 +152,14 @@ dbcli capabilities check --require schema.read,query.read         # gate your wo
 dbcli capabilities check --require data.delete --format json      # machine-readable
 ```
 
+`connection.tls` derives support from the engine matrix and maps to existing
+connection command surfaces, supporting PostgreSQL, MySQL and MariaDB. It adds
+no TLS subcommand. Check with
+`dbcli capabilities check --require connection.tls --format json`.
+`available` establishes tool support only, not TLS configuration, readable CA,
+a successful handshake or authorization. Catalog/check stay offline, read no CA
+and change no configuration. Older binaries without this ID return `unknown`.
+
 For a copyable Bun/TypeScript consumer with strict parsing, schema pins, exit handling,
 Operation Envelope handling, Task Pack `safety.requires`, and correlation/evidence guidance,
 start with `assets/integration-kit/README.md`.
@@ -326,6 +334,44 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
 > If a `.dbcli` already contains `{"$env": "..."}` references, **do not** rerun
 > `init` to "fill them in" — the env-ref form is intentional for CI/multi-env.
 
+### PostgreSQL, MySQL and MariaDB verified TLS
+
+When verified TLS is required, use the named `init` entry with both
+`--sql-tls verify-full --sql-tls-ca <path>`. PostgreSQL, MySQL and MariaDB support this SQL
+contract; explicit requests on other engines fail. The saved
+`sqlTls: { mode: 'verify-full', caPath: '/absolute/path/root-ca.pem' }` uses an
+absolute literal PEM path; `init` resolves relative paths from cwd. CA environment
+references are unsupported. Existing host/user environment references and profiles
+without `sqlTls` keep their behavior. V1 directory/v2 reads, normal `init` import
+from a V1 directory and `migrateV1ToV2` preserve TLS. Legacy V1 single-file TLS
+profiles remain readable/usable in human mode; automatic `init` import refuses
+before connecting or writing, preserving the original. Migrate that case by
+creating a verified named profile in a separate config directory, verifying it,
+then selecting it; preserve `sqlTls` throughout.
+
+Ambient TLS settings cannot weaken verification or supply another profile’s trust.
+Each connection reloads its own CA and verifies encryption, trust, validity and the
+configured DNS/IP identity; explicit SQL TLS refuses Unix sockets. Failures stop
+before the user query. Repair the CA, hostname or certificate; keep verification
+and TLS required. On binary rollback, stop TLS-required workflows or retain a
+supporting version: older binaries may strip `sqlTls`. Local fixture evidence does
+not establish real RDS acceptance. Configured permitted reads work in agent mode;
+`init` and other configuration changes remain refused.
+
+For TLS error recovery, repair certificates while retaining TLS, then explicitly
+select `--config <path>` or `--global`; v2 also requires `--use <name>` or
+`DBCLI_CONNECTION`. The selected profile must retain `sqlTls.mode: verify-full`.
+Missing, ambiguous or plaintext selections block live steps. Saved envelopes
+redact original selectors, so current targeting does not establish original
+provenance. Apply and verification use the current CLI binary. Example:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+For the complete configuration, example and failure contract, read
+[SQL verified TLS](reference.md#verified-tls-for-postgresql-mysql-and-mariadb).
+
 ### Decision tree (ask before writing)
 
 1. **What is the connection name?** Every new connection uses named v2, even

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

@@ -157,7 +157,7 @@ Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `
 
 New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
 
-**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+**Key options:** `--sql-tls verify-full`, `--sql-tls-ca <path>`, `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
@@ -193,6 +193,57 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
 
+#### Verified TLS for PostgreSQL, MySQL and MariaDB
+
+Use both SQL TLS flags when creating a named PostgreSQL, MySQL or MariaDB profile. This example prompts for the password and tests the connection before saving:
+
+```bash
+dbcli init --conn-name verified-pg --system postgresql \
+  --host db.example.com --port 5432 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/root-ca.pem
+dbcli --use verified-pg blacklist list
+dbcli --use verified-pg schema public.events --format json
+dbcli --use verified-pg query "SELECT id FROM public.events LIMIT 10" --format json
+```
+
+MySQL and MariaDB use the same flags, with separate named profiles and CA paths. Select the corresponding profile, then check blacklist and schema before an authorized query:
+
+```bash
+dbcli init --conn-name verified-mysql --system mysql \
+  --host mysql.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mysql-ca.pem
+dbcli init --conn-name verified-mariadb --system mariadb \
+  --host mariadb.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mariadb-ca.pem
+```
+
+Replace the host, database and table with your authorized target; confirm real columns through schema before querying. The saved connection includes this dedicated SQL object (shown as a connection fragment):
+
+```json
+{
+  "sqlTls": {
+    "mode": "verify-full",
+    "caPath": "/absolute/path/to/certs/root-ca.pem"
+  }
+}
+```
+
+`--sql-tls verify-full` and `--sql-tls-ca <path>` are required together. Empty values, other modes and unsupported engines fail explicitly. PostgreSQL, MySQL and MariaDB support this SQL TLS contract; all other engines reject an explicit request. MongoDB's `tls` and Elasticsearch's TLS settings remain separate. Existing profiles without `sqlTls` keep their previous behavior; no global TLS policy is added. V1 directory and v2 profile reads, normal `init` import from a V1 directory to v2, and the public `migrateV1ToV2` helper preserve the TLS object. A legacy V1 single-file TLS profile remains readable and usable in human mode, but automatic `init` import explicitly refuses it before connecting or writing and leaves the original untouched. For that case, create a verified named profile in a separate configuration directory, verify it, then select it; preserve `sqlTls` throughout migration.
+
+`init` resolves a relative CA path against its current working directory before saving. Saved `caPath` must be a nonempty absolute literal path to a PEM CA bundle; it accepts no environment-variable reference. Existing environment references in host/user and other supported fields remain usable. Explicit TLS uses only the selected profile’s CA and identity settings; ambient TLS settings cannot weaken verification or supply another profile’s trust. Each new connection reads the CA bundle again; an unreadable, empty or invalid bundle stops before connecting. `--skip-test` skips only the initialization test, not verification on subsequent use.
+
+`verify-full` requires encryption, a trusted certificate chain, valid certificate dates and certificate identity matching the configured DNS name or IP address. Unix sockets are refused for explicit SQL TLS. Untrusted, expired or mismatched certificates and servers without TLS fail before the user query; there is no plaintext retry or verification downgrade. Correct the CA, target hostname or certificate validity before retrying. A cipher alone does not prove identity verification.
+
+For TLS error recovery, keep TLS configured and repair the CA, hostname or certificate first. Then deliberately select the configuration with `--config <path>` (or `--global`) and, for v2, the named profile with `--use <name>` (`DBCLI_CONNECTION` is also accepted). The selected profile must still have `sqlTls.mode: verify-full`; missing, ambiguous or plaintext selections block live recovery steps instead of falling back to a default plaintext connection. Saved recovery envelopes redact the original selectors: your current selection is deliberate targeting, not proof of the original target. Recovery apply and verification use the current CLI binary, avoiding an older `dbcli` on PATH. For the MySQL example above:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+Permitted reads through an already configured profile remain usable in agent mode; `init` and other configuration mutations remain refused under `DBCLI_AGENT_MODE=1`. TLS does not bypass explicit production selection, native database authorization, permission, blacklist, write-gate or audit controls.
+
+For binary rollback, stop workflows that require verified TLS or keep a supporting version. Older binaries may strip `sqlTls`; retaining the profile after downgrading does not preserve the guarantee. Removing TLS settings or retrying in plaintext cannot restore compliance. Local isolated PostgreSQL, MySQL and MariaDB fixture results are not evidence of real RDS acceptance; RDS remains unverified.
+
 ### use
 
 Set, clear, or display the default database connection (v2 multi-connection config).
@@ -1731,6 +1782,8 @@ Every actionable block carries machine-readable next steps so an agent can move
 
 ### capabilities
 
+`connection.tls` reports PostgreSQL, MySQL and MariaDB support from the engine capability matrix and maps to the existing connection command surfaces; it adds no TLS subcommand. Check with `dbcli --use verified-pg capabilities check --require connection.tls --format json`. `available` means tool support only: it does not prove that this profile configures TLS, the CA is readable, the handshake succeeds, or the operation is authorized. Catalog/check remain offline, read no CA bundle, perform no handshake and change no configuration. Other engines do not report this capability as available; older binaries without the ID return `unknown`. Configuration mutation still requires its own authorization.
+
 Discovery. Lists the static dbcli capability catalog — what this tool can do,
 described in a versioned shape an external Skill can parse before it starts
 working. It never opens a database connection and never writes anything.

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [12.1.0] - 2026-10-23
+
+版本為 **12.1.0**。新增 PostgreSQL、MySQL 與 MariaDB 的驗證式 TLS 設定（verified TLS profiles），
+支援以 `--sql-tls verify-full --sql-tls-ca <path>` 指定 CA 憑證路徑，並於連線時嚴格驗證信任鏈、有效期與目標主機身分（DNS/IP SAN）。
+本版本維持向下相容，未啟用 TLS 的既有連線 profile 行為不變。
+
+### Added
+
+- **PostgreSQL / MySQL / MariaDB 驗證式 TLS 連線支援**：具名連線設定增加 `sqlTls: { mode: 'verify-full', caPath: string }` 規格；
+  `init` 命令新增成對參數 `--sql-tls verify-full --sql-tls-ca <path>`。連線建立時重新讀取 CA bundle 並驗證伺服器憑證主機身分與信任鏈；
+  任何驗證失敗立即中止，不降級、不重試明文、不關閉身分驗證。
+- **離線 capabilities 發現更新**：`connection.tls` capability matrix 宣告支援 PostgreSQL、MySQL 與 MariaDB，
+  支援透過離線 inspect／check 查詢能力。
+
+### Changed
+
+- **工作流程精簡**：正式退役 ForgePilot 流程，採用 Warrant 授權導向工作流程；精簡 release 驗證門檻與證據交接規範。
+
 ## [12.0.0] - 2026-10-18
 
 版本為 **12.0.0**。SQL 單一物件 `schema` 現在將含點號的輸入解析為完整名稱，

package/README.md

@@ -1756,10 +1756,9 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for full setup, testing, and release pr
 
 ## Governance
 
-For people changing this repository. dbcli itself depends on none of the tools
-below: `package.json` and `src/` never mention them, `.forgepilot/` is
-gitignored local state, and a clone without any of them runs `make verify`
-normally.
+For people changing this repository. Warrant governs approved intent;
+`make verify` and human review establish whether that intent is satisfied.
+Work is selected directly by a human and needs no external scheduler.
 
 ### How work is specified: Warrant
 
@@ -1767,26 +1766,30 @@ Each unit of work is a Story: one file, `specs/stories/<slug>.md`, with exactly
 three sections — Goal, Out of Scope, and Acceptance Criteria. A Story is
 approved only when a human commits it to the default branch or explicitly
 assigns it in the current session; an agent never approves its own. The
-contract agents follow is the `## Warrant` section of `AGENTS.md`, and
+contract agents follow is the intent, verification and review section of `AGENTS.md`, and
 `specs/stories/README.md` describes the format. The `DBCLI-*` directories under
 `specs/stories/` are legacy records from an earlier protocol, not pending work.
 
 Warrant defines what a Story must contain and what counts as evidence: every
 acceptance criterion needs a reproducible observation, and the requirements,
-criteria, and scope stay as the human approved them. ForgePilot and
-`make verify` decide when it is done.
+criteria, and scope stay as the human approved them.
 
-### When work is done: ForgePilot and `make verify`
+### When work is done: `make verify` and human review
 
 `make verify` is the automated completion authority. Passing it makes work
 *eligible* for human review; it does not approve or merge anything. Do not
 bypass verification or delete failing tests to obtain a pass.
 
-ForgePilot is an operator tool that holds the work queue and the verification
-evidence. It runs this repository's own `make verify` inside a detached worktree
-at an exact commit, so a recorded pass is bound to that revision rather than
-meaning "it passes on a machine that already has everything installed". It has
-no completion command — only a human can approve.
+Verification and review must refer to the same candidate. A clean committed PR
+may use CI evidence for its actual checkout revision. An uncommitted candidate
+uses a local handoff with reconstructable source content, verification output,
+criterion observations and human review. Follow the
+[evidence paths](docs/development/agent-workflow.md#choose-one-evidence-record);
+a passing run for different source content does not verify the current work.
+
+ForgePilot is no longer used by this project. Its ignored `.forgepilot/` data
+and historical records remain available; global tools and skills are unaffected.
+The decision is recorded in [ADR-0051](docs/adr/ADR-0051-retire-forgepilot-from-the-repository-workflow.md).
 
 ### Where decisions live: `docs/adr/`
 

package/assets/SKILL.md

@@ -152,6 +152,14 @@ dbcli capabilities check --require schema.read,query.read         # gate your wo
 dbcli capabilities check --require data.delete --format json      # machine-readable
 ```
 
+`connection.tls` derives support from the engine matrix and maps to existing
+connection command surfaces, supporting PostgreSQL, MySQL and MariaDB. It adds
+no TLS subcommand. Check with
+`dbcli capabilities check --require connection.tls --format json`.
+`available` establishes tool support only, not TLS configuration, readable CA,
+a successful handshake or authorization. Catalog/check stay offline, read no CA
+and change no configuration. Older binaries without this ID return `unknown`.
+
 For a copyable Bun/TypeScript consumer with strict parsing, schema pins, exit handling,
 Operation Envelope handling, Task Pack `safety.requires`, and correlation/evidence guidance,
 start with `assets/integration-kit/README.md`.
@@ -326,6 +334,44 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
 > If a `.dbcli` already contains `{"$env": "..."}` references, **do not** rerun
 > `init` to "fill them in" — the env-ref form is intentional for CI/multi-env.
 
+### PostgreSQL, MySQL and MariaDB verified TLS
+
+When verified TLS is required, use the named `init` entry with both
+`--sql-tls verify-full --sql-tls-ca <path>`. PostgreSQL, MySQL and MariaDB support this SQL
+contract; explicit requests on other engines fail. The saved
+`sqlTls: { mode: 'verify-full', caPath: '/absolute/path/root-ca.pem' }` uses an
+absolute literal PEM path; `init` resolves relative paths from cwd. CA environment
+references are unsupported. Existing host/user environment references and profiles
+without `sqlTls` keep their behavior. V1 directory/v2 reads, normal `init` import
+from a V1 directory and `migrateV1ToV2` preserve TLS. Legacy V1 single-file TLS
+profiles remain readable/usable in human mode; automatic `init` import refuses
+before connecting or writing, preserving the original. Migrate that case by
+creating a verified named profile in a separate config directory, verifying it,
+then selecting it; preserve `sqlTls` throughout.
+
+Ambient TLS settings cannot weaken verification or supply another profile’s trust.
+Each connection reloads its own CA and verifies encryption, trust, validity and the
+configured DNS/IP identity; explicit SQL TLS refuses Unix sockets. Failures stop
+before the user query. Repair the CA, hostname or certificate; keep verification
+and TLS required. On binary rollback, stop TLS-required workflows or retain a
+supporting version: older binaries may strip `sqlTls`. Local fixture evidence does
+not establish real RDS acceptance. Configured permitted reads work in agent mode;
+`init` and other configuration changes remain refused.
+
+For TLS error recovery, repair certificates while retaining TLS, then explicitly
+select `--config <path>` or `--global`; v2 also requires `--use <name>` or
+`DBCLI_CONNECTION`. The selected profile must retain `sqlTls.mode: verify-full`.
+Missing, ambiguous or plaintext selections block live steps. Saved envelopes
+redact original selectors, so current targeting does not establish original
+provenance. Apply and verification use the current CLI binary. Example:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+For the complete configuration, example and failure contract, read
+[SQL verified TLS](reference.md#verified-tls-for-postgresql-mysql-and-mariadb).
+
 ### Decision tree (ask before writing)
 
 1. **What is the connection name?** Every new connection uses named v2, even

package/assets/reference.md

@@ -157,7 +157,7 @@ Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `
 
 New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
 
-**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+**Key options:** `--sql-tls verify-full`, `--sql-tls-ca <path>`, `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
@@ -193,6 +193,57 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
 
+#### Verified TLS for PostgreSQL, MySQL and MariaDB
+
+Use both SQL TLS flags when creating a named PostgreSQL, MySQL or MariaDB profile. This example prompts for the password and tests the connection before saving:
+
+```bash
+dbcli init --conn-name verified-pg --system postgresql \
+  --host db.example.com --port 5432 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/root-ca.pem
+dbcli --use verified-pg blacklist list
+dbcli --use verified-pg schema public.events --format json
+dbcli --use verified-pg query "SELECT id FROM public.events LIMIT 10" --format json
+```
+
+MySQL and MariaDB use the same flags, with separate named profiles and CA paths. Select the corresponding profile, then check blacklist and schema before an authorized query:
+
+```bash
+dbcli init --conn-name verified-mysql --system mysql \
+  --host mysql.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mysql-ca.pem
+dbcli init --conn-name verified-mariadb --system mariadb \
+  --host mariadb.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mariadb-ca.pem
+```
+
+Replace the host, database and table with your authorized target; confirm real columns through schema before querying. The saved connection includes this dedicated SQL object (shown as a connection fragment):
+
+```json
+{
+  "sqlTls": {
+    "mode": "verify-full",
+    "caPath": "/absolute/path/to/certs/root-ca.pem"
+  }
+}
+```
+
+`--sql-tls verify-full` and `--sql-tls-ca <path>` are required together. Empty values, other modes and unsupported engines fail explicitly. PostgreSQL, MySQL and MariaDB support this SQL TLS contract; all other engines reject an explicit request. MongoDB's `tls` and Elasticsearch's TLS settings remain separate. Existing profiles without `sqlTls` keep their previous behavior; no global TLS policy is added. V1 directory and v2 profile reads, normal `init` import from a V1 directory to v2, and the public `migrateV1ToV2` helper preserve the TLS object. A legacy V1 single-file TLS profile remains readable and usable in human mode, but automatic `init` import explicitly refuses it before connecting or writing and leaves the original untouched. For that case, create a verified named profile in a separate configuration directory, verify it, then select it; preserve `sqlTls` throughout migration.
+
+`init` resolves a relative CA path against its current working directory before saving. Saved `caPath` must be a nonempty absolute literal path to a PEM CA bundle; it accepts no environment-variable reference. Existing environment references in host/user and other supported fields remain usable. Explicit TLS uses only the selected profile’s CA and identity settings; ambient TLS settings cannot weaken verification or supply another profile’s trust. Each new connection reads the CA bundle again; an unreadable, empty or invalid bundle stops before connecting. `--skip-test` skips only the initialization test, not verification on subsequent use.
+
+`verify-full` requires encryption, a trusted certificate chain, valid certificate dates and certificate identity matching the configured DNS name or IP address. Unix sockets are refused for explicit SQL TLS. Untrusted, expired or mismatched certificates and servers without TLS fail before the user query; there is no plaintext retry or verification downgrade. Correct the CA, target hostname or certificate validity before retrying. A cipher alone does not prove identity verification.
+
+For TLS error recovery, keep TLS configured and repair the CA, hostname or certificate first. Then deliberately select the configuration with `--config <path>` (or `--global`) and, for v2, the named profile with `--use <name>` (`DBCLI_CONNECTION` is also accepted). The selected profile must still have `sqlTls.mode: verify-full`; missing, ambiguous or plaintext selections block live recovery steps instead of falling back to a default plaintext connection. Saved recovery envelopes redact the original selectors: your current selection is deliberate targeting, not proof of the original target. Recovery apply and verification use the current CLI binary, avoiding an older `dbcli` on PATH. For the MySQL example above:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+Permitted reads through an already configured profile remain usable in agent mode; `init` and other configuration mutations remain refused under `DBCLI_AGENT_MODE=1`. TLS does not bypass explicit production selection, native database authorization, permission, blacklist, write-gate or audit controls.
+
+For binary rollback, stop workflows that require verified TLS or keep a supporting version. Older binaries may strip `sqlTls`; retaining the profile after downgrading does not preserve the guarantee. Removing TLS settings or retrying in plaintext cannot restore compliance. Local isolated PostgreSQL, MySQL and MariaDB fixture results are not evidence of real RDS acceptance; RDS remains unverified.
+
 ### use
 
 Set, clear, or display the default database connection (v2 multi-connection config).
@@ -1731,6 +1782,8 @@ Every actionable block carries machine-readable next steps so an agent can move
 
 ### capabilities
 
+`connection.tls` reports PostgreSQL, MySQL and MariaDB support from the engine capability matrix and maps to the existing connection command surfaces; it adds no TLS subcommand. Check with `dbcli --use verified-pg capabilities check --require connection.tls --format json`. `available` means tool support only: it does not prove that this profile configures TLS, the CA is readable, the handshake succeeds, or the operation is authorized. Catalog/check remain offline, read no CA bundle, perform no handshake and change no configuration. Other engines do not report this capability as available; older binaries without the ID return `unknown`. Configuration mutation still requires its own authorization.
+
 Discovery. Lists the static dbcli capability catalog — what this tool can do,
 described in a versioned shape an external Skill can parse before it starts
 working. It never opens a database connection and never writes anything.