@carllee1983/dbcli 1.58.0 → 2.1.0

package/.cursor/rules/dbcli.mdc

@@ -43,6 +43,25 @@ condition, first `query` / `export` the target rows' primary keys, then run one
 `update` / `delete --where "id=<pk>"` per key — or escalate to a human. (MongoDB `--where`
 takes a full JSON filter and is exempt.)
 
+**Write gate (2.0.0) — the rule that will refuse you.** Every write is classified into two
+tiers. Ordinary writes (`INSERT`, `UPDATE` / `DELETE` with a `WHERE`, `CREATE`, `ALTER`)
+run unattended exactly as before; `--yes` skips the terminal prompt a human would see.
+**Statements that are not limited to specific rows are refused outright when nobody can
+answer a prompt** — `UPDATE` / `DELETE` with no `WHERE`, `DROP`, `TRUNCATE`, a statement
+the SQL parser cannot read, several statements in one string, and `update` / `delete --where` matching on no primary key and
+no unique index. The process exits `1` with `reason=no_where`, `reason=ddl_destruction`,
+`reason=unparseable`, `reason=multi_table`, `reason=nested_write` or
+`reason=non_unique_where`, and **nothing
+reaches the database**. In `dbcli shell`, a subcommand whose name is a SQL keyword needs a
+`\` prefix (`\delete users --where id=1`) — a bare `delete …` is read as SQL. A write that joins a second table is always tier two: whether it is
+limited to particular rows depends on the data, not on the statement. So is a statement
+carrying a second write inside it — a data-modifying CTE
+(`WITH x AS (DELETE FROM t RETURNING *) INSERT INTO …`) or a `MERGE` with a
+`WHEN … THEN DELETE` / `THEN UPDATE` action.
+**No flag bypasses this** — not `--yes`, not `--force`. To write every row on purpose, put
+the intent in the SQL itself: add `WHERE 1=1` or a `LIMIT`. `DROP` / `TRUNCATE` have no
+unattended route at all; escalate to a human.
+
 > `report` and `guide` already embed an `inspect` snapshot — you do **not** need to run
 > `dbcli inspect` first. Run `dbcli inspect --for-agent` manually only when you want the
 > audit-recent context or to diagnose a connection problem.

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

@@ -334,9 +334,91 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--recovery`
+**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--yes`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Write confirmation gate (2.0.0)
+
+A SQL write passes through a two-tier gate before the connection is opened. The gate is
+separate from the permission axis: permission says what the connection may do, the gate
+says whether this particular statement may run right now.
+
+| Tier | Statements | Interactive terminal | Non-interactive (or `--format json`) |
+| :--- | :--- | :--- | :--- |
+| One | `INSERT`, `UPDATE` / `DELETE` **with** a `WHERE` or `LIMIT`, `CREATE`, `ALTER` | Summary + `y/N`; `--yes` skips it | Runs, exactly as before |
+| Two | `UPDATE` / `DELETE` with **no** `WHERE`, `DROP`, `TRUNCATE`, unparseable statements, several statements in one string, a write nested inside another statement, a destructive `MERGE` | Type the target table name; **no flag skips it** | **Refused**: exit `1`, nothing sent to the database |
+
+A refusal message names a machine-readable reason — `reason=no_where`, `reason=multi_table`,
+`reason=ddl_destruction`, `reason=unparseable`, `reason=multiple_statements`, `reason=nested_write` — so a caller can tell it apart from a
+connection failure or a permission denial.
+
+**A write that joins another table is tier two, whatever its `WHERE` says.** Whether such a
+write is limited to particular rows is not a property of the statement:
+`DELETE p FROM p JOIN o ON p.id = o.ref WHERE o.x > 0` deleted 2 of 5 rows against one
+dataset and all 2000 against another, and a join's `ON` necessarily names the target, so it
+proves nothing. Five rounds of adversarial measurement went into trying to read this off the
+syntax before the rule became "a second table means tier two" (#80, #93). That refuses the
+standard `UPDATE … FROM`, `UPDATE … JOIN … SET` and multi-table `DELETE` idioms for
+unattended callers: rewrite the other table into a subquery in the `WHERE`, or run them
+where someone can confirm.
+
+**A statement is not the keyword it starts with.** PostgreSQL's data-modifying CTEs put an
+arbitrary write in front of the statement the first keyword names, and a `MERGE` carries its
+writes in a `WHEN … THEN` list — measured against a 2000-row table,
+`WITH moved AS (DELETE FROM p RETURNING *) INSERT INTO archive …` and
+`MERGE INTO p USING (SELECT 1 AS x) s ON true WHEN MATCHED THEN DELETE` each emptied it
+while reading as an ordinary `INSERT` (#94, #95). So a write nested inside another statement
+is tier two, `reason=nested_write`, and a `MERGE` is classified by its actions: a
+`THEN DELETE` or `THEN UPDATE` is tier two, `reason=multi_table`, while an insert-only or
+`DO NOTHING` one stays tier one. `ON CONFLICT … DO UPDATE`, `ON DUPLICATE KEY UPDATE` and
+`INSERT … SELECT` are untouched by this — they are not nested writes, whatever they read
+like. The cost is a CTE that deletes one row by primary key, and the ordinary `MERGE` upsert,
+both refused for unattended callers.
+
+**For a single-table write, the `WHERE` has to be about that table.** `UPDATE p SET c = 1
+WHERE id = 1` is an ordinary write; `UPDATE p SET c = (SELECT max(x) FROM o WHERE o.id = 1)`
+is not, because its only `WHERE` restricts the subquery and the write touches every row. A
+*correlated* reference back to the target does count, so
+`DELETE FROM t WHERE EXISTS (SELECT 1 FROM o WHERE o.tid = t.id)` is tier one while
+`DELETE FROM t WHERE EXISTS (SELECT 1 FROM o WHERE o.id = 1)` deletes every row and is tier
+two. A qualifier the subquery binds itself — including the target's own name, as in
+`DELETE FROM sessions WHERE EXISTS (SELECT 1 FROM sessions WHERE …)` — is about the
+subquery's rows, not the write.
+
+This is a lower bound, not a proof: `WHERE id IS NOT NULL` names the target and still touches
+every row, and no static check settles that. What it rules out is the class where nothing in
+the condition is about the table being written.
+
+**When the parser cannot read the statement**, there is no tree to judge and the same rule is
+applied to the text: tier one only when the statement reads as a write to one named table
+with a `WHERE` or `LIMIT` and contains no `SELECT`, `TABLE`, `VALUES`, `JOIN`, `USING`, a
+statement-level `WITH`, or an `UPDATE … FROM`. A keyword inside parentheses is not at
+statement level, so `SUBSTRING(x FROM 2)` and `AGAINST ('a' WITH QUERY EXPANSION)` do not
+trip it. This is written as an allowlist because the denylist that preceded it was defeated
+once per review round — `USING`, then `JOIN`, then a CTE, then a subquery, then `TABLE` as a
+subquery.
+
+**Escape routes.** For a statement that accepts a `WHERE`, put the intent in the SQL:
+
+```bash
+dbcli query "UPDATE users SET banned = 1"                    # refused, reason=no_where
+dbcli query "UPDATE users SET banned = 1 WHERE 1=1"          # runs — intent is explicit
+dbcli query "DELETE FROM sessions LIMIT 1000"                # runs — damage is bounded
+dbcli query "UPDATE users SET banned = 1 WHERE id = 3" --yes # tier one, question skipped
+dbcli query "UPDATE p SET x = 1 FROM o WHERE o.id = 1"       # refused — the WHERE is about o, not p
+```
+
+This is deliberately not a flag. `WHERE 1=1` appended to a statement that already has a
+`WHERE` is a syntax error, so a blanket "always add it" habit breaks on the first ordinary
+statement; a flag would be harmless everywhere and therefore added everywhere. For `DROP`
+and `TRUNCATE` there is no clause to add — the connection's `permission` level decides
+whether they are possible at all, and the typed confirmation must come from a person.
+
+Every tier-two evaluation is written to the audit log with
+`metadata.write_gate_outcome` (`allowed` / `declined` / `refused`) and
+`metadata.write_gate_reason`. `dbcli audit write-gate` summarizes them — that is
+the measurement ADR 0010 stakes this gate on.
+
 > **Elasticsearch tiers by scope.** A read (`GET` / `HEAD`, plus `POST _search` and
 > `POST _count`) is query-only. Indexing or updating a document is read-write.
 > `DELETE /<index>/_doc/<id>` — one document — is data-admin. Everything that removes or
@@ -955,6 +1037,14 @@ dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json
 > target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
 > (MongoDB `--where` accepts a full JSON filter and is exempt.)
 
+> **Tier two for structured writes (2.0.0)** — a `--where` that matches on no primary key
+> and no unique index selects an unknown number of rows, so it is treated the same as a
+> raw statement with no `WHERE`: the target table name must be typed at an interactive
+> terminal, and a non-interactive run is refused with exit `1` and
+> `reason=non_unique_where`. `--force` and `--dry-run` do not affect this; `--force` skips
+> the ordinary confirmation only. Select the primary keys first and write one row at a
+> time, or run it where a person can confirm it.
+
 ### delete
 
 Delete data from a table.
@@ -1946,6 +2036,7 @@ Audit entries are metadata-only by design — never raw SQL bodies, `--param` va
 | `audit show` | `readonly` | Print a single full entry by id prefix or `--recovery-ref`. |
 | `audit clear` | `local-write` | Delete `<conn>.jsonl` + rotated `.jsonl.1` from local disk. Requires `--yes` or interactive confirm. |
 | `audit health` | `readonly` | Render `AuditLogger.getHealth()` snapshot (writer state, lock state, rotation usage). |
+| `audit write-gate` | `readonly` | Summarize tier-two write-gate decisions: how often the gate was reached, by which reason, and how it was answered. |
 
 #### `audit tail`
 
@@ -2006,6 +2097,32 @@ Examples:
 
 Output reports: writer enabled/disabled, last write result, file-lock state, rotation cap usage (`max_bytes` / `max_entries`). When `audit.enabled = false` (D1 opt-out), `tail` / `show` / `health` still exit 0 and print `Audit is disabled (audit.enabled = false in .dbcli). Use 'dbcli audit health' for details.` (E note).
 
+#### `audit write-gate`
+
+Answers the question ADR 0010 stakes the two-tier write gate on: is tier two stopping anything, or has everyone routed around it? The data was always written — `metadata.write_gate_tier` / `write_gate_outcome` / `write_gate_reason` on every evaluation — but reading it meant hand-writing jq over the JSONL.
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--format <fmt>` | `table` \| `json`. | `table` |
+| `--all` | Merge every connection into one measurement. | off |
+| `--for-agent` | Shortcut for `--format json`. | off |
+
+```bash
+dbcli audit write-gate
+dbcli audit write-gate --format json
+dbcli audit write-gate --all
+```
+
+Reports, over the current connection's retained history (rotated `.jsonl.1` included):
+
+- `total` — tier-two evaluations, with `range` giving the interval they span.
+- `outcomes` — `allowed` / `declined` / `refused`. The ratio between them is the line between "the gate is stopping things" and "everyone confirms through it".
+- `reasons` — which criterion sent the statement to tier two. Every known reason is listed, **including the ones that never fired**: a criterion that triggers zero times is the finding, not a row to omit.
+- `scanned` + `window` — the denominator. Two decisions in a week and two in a year are different findings.
+- `tierOne` — counted apart, with its own outcome breakdown, because tier one is recorded only when the operator declined.
+
+When tier two was never reached, the summary says so and names the conclusion ADR 0010 draws from it (the criterion is wrong, not the gate unnecessary) rather than printing an empty table. An entirely empty audit log is reported as a separate case: it supports no conclusion either way.
+
 #### Boundaries
 
 - Entries are append-only JSONL; rotation triggers at `~10 MB` or `~1000` entries (whichever first). Previous segment is preserved as `.jsonl.1`.
@@ -2495,11 +2612,38 @@ dbcli shell --sql    # SQL-only mode
 Inside the shell:
 - Type SQL statements ending with `;` to execute
 - Type dbcli commands without the `dbcli` prefix (e.g., `schema users`)
+- Prefix a subcommand with `\` to force it: `\delete users --where id=1`. Required for the
+  subcommands whose names are also SQL keywords — `insert`, `update`, `delete`, `explain` —
+  because a line starting with one of those is read as SQL,
+  which is what a shell is for. The prefix works on every subcommand, so it is one rule
+  rather than a list of exceptions (#88).
+- A subcommand runs in its own process with no stdin, so its ordinary y/n confirmation reads
+  EOF and cancels. `\insert` / `\update` / `\delete` therefore need `--force` from inside
+  the shell — or type the SQL at the prompt, where the confirmation can actually be
+  answered. Tier two is unaffected either way: it is refused in the child and points you
+  back to the prompt.
 - Use Tab for auto-completion (SQL keywords, table names, column names)
 - Type `.help` for meta commands (.quit, .clear, .format, .history, .timing)
-- Multi-line SQL: keeps accumulating until `;` is found
+- Multi-line SQL: keeps accumulating until `;` is found. Meta commands still work while a
+  statement is accumulating — `.quit` quits, `.clear` abandons the buffer — and Ctrl-C
+  cancels. A line that reads as SQL but names a subcommand and carries a double-dash option prints
+  a note saying which prefix would have reached the subcommand.
 - History persists across sessions (~/.dbcli_history)
 
+> **Tier two applies here (2.0.0)** — on SQL connections a typed `UPDATE` / `DELETE` with
+> no `WHERE`, a `DROP` or a `TRUNCATE` asks for the target table name before it runs.
+> Anything else typed cancels the statement and returns to the prompt; the session stays
+> open, and Ctrl-C withdraws the question itself — the next line is read as a statement,
+> not as the answer. Tier one (the y/N on ordinary writes) is deliberately not wired here — every line
+> is typed by a person. Piped input (`dbcli shell < script.sql`) has nobody to answer, so a
+> tier-two statement is refused and the remaining lines still run. Redis, MongoDB and
+> Elasticsearch shells are unaffected.
+>
+> dbcli **subcommands** typed in the shell (`query "..."`, `delete ...`) run as separate
+> processes with no stdin, so they cannot ask anything: a tier-two statement there is
+> refused with a message pointing you back to the `dbcli>` prompt, where the confirmation
+> can actually be typed.
+
 The REPL flavor depends on the active engine: SQL engines and MongoDB use the
 form above; **Redis** opens a single-line command REPL (see [Redis › Interactive
 shell](#interactive-shell)); **Elasticsearch** opens a Kibana Dev Tools-style

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

@@ -43,6 +43,25 @@ condition, first `query` / `export` the target rows' primary keys, then run one
 `update` / `delete --where "id=<pk>"` per key — or escalate to a human. (MongoDB `--where`
 takes a full JSON filter and is exempt.)
 
+**Write gate (2.0.0) — the rule that will refuse you.** Every write is classified into two
+tiers. Ordinary writes (`INSERT`, `UPDATE` / `DELETE` with a `WHERE`, `CREATE`, `ALTER`)
+run unattended exactly as before; `--yes` skips the terminal prompt a human would see.
+**Statements that are not limited to specific rows are refused outright when nobody can
+answer a prompt** — `UPDATE` / `DELETE` with no `WHERE`, `DROP`, `TRUNCATE`, a statement
+the SQL parser cannot read, several statements in one string, and `update` / `delete --where` matching on no primary key and
+no unique index. The process exits `1` with `reason=no_where`, `reason=ddl_destruction`,
+`reason=unparseable`, `reason=multi_table`, `reason=nested_write` or
+`reason=non_unique_where`, and **nothing
+reaches the database**. In `dbcli shell`, a subcommand whose name is a SQL keyword needs a
+`\` prefix (`\delete users --where id=1`) — a bare `delete …` is read as SQL. A write that joins a second table is always tier two: whether it is
+limited to particular rows depends on the data, not on the statement. So is a statement
+carrying a second write inside it — a data-modifying CTE
+(`WITH x AS (DELETE FROM t RETURNING *) INSERT INTO …`) or a `MERGE` with a
+`WHEN … THEN DELETE` / `THEN UPDATE` action.
+**No flag bypasses this** — not `--yes`, not `--force`. To write every row on purpose, put
+the intent in the SQL itself: add `WHERE 1=1` or a `LIMIT`. `DROP` / `TRUNCATE` have no
+unattended route at all; escalate to a human.
+
 > `report` and `guide` already embed an `inspect` snapshot — you do **not** need to run
 > `dbcli inspect` first. Run `dbcli inspect --for-agent` manually only when you want the
 > audit-recent context or to diagnose a connection problem.

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

@@ -334,9 +334,91 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--recovery`
+**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--yes`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Write confirmation gate (2.0.0)
+
+A SQL write passes through a two-tier gate before the connection is opened. The gate is
+separate from the permission axis: permission says what the connection may do, the gate
+says whether this particular statement may run right now.
+
+| Tier | Statements | Interactive terminal | Non-interactive (or `--format json`) |
+| :--- | :--- | :--- | :--- |
+| One | `INSERT`, `UPDATE` / `DELETE` **with** a `WHERE` or `LIMIT`, `CREATE`, `ALTER` | Summary + `y/N`; `--yes` skips it | Runs, exactly as before |
+| Two | `UPDATE` / `DELETE` with **no** `WHERE`, `DROP`, `TRUNCATE`, unparseable statements, several statements in one string, a write nested inside another statement, a destructive `MERGE` | Type the target table name; **no flag skips it** | **Refused**: exit `1`, nothing sent to the database |
+
+A refusal message names a machine-readable reason — `reason=no_where`, `reason=multi_table`,
+`reason=ddl_destruction`, `reason=unparseable`, `reason=multiple_statements`, `reason=nested_write` — so a caller can tell it apart from a
+connection failure or a permission denial.
+
+**A write that joins another table is tier two, whatever its `WHERE` says.** Whether such a
+write is limited to particular rows is not a property of the statement:
+`DELETE p FROM p JOIN o ON p.id = o.ref WHERE o.x > 0` deleted 2 of 5 rows against one
+dataset and all 2000 against another, and a join's `ON` necessarily names the target, so it
+proves nothing. Five rounds of adversarial measurement went into trying to read this off the
+syntax before the rule became "a second table means tier two" (#80, #93). That refuses the
+standard `UPDATE … FROM`, `UPDATE … JOIN … SET` and multi-table `DELETE` idioms for
+unattended callers: rewrite the other table into a subquery in the `WHERE`, or run them
+where someone can confirm.
+
+**A statement is not the keyword it starts with.** PostgreSQL's data-modifying CTEs put an
+arbitrary write in front of the statement the first keyword names, and a `MERGE` carries its
+writes in a `WHEN … THEN` list — measured against a 2000-row table,
+`WITH moved AS (DELETE FROM p RETURNING *) INSERT INTO archive …` and
+`MERGE INTO p USING (SELECT 1 AS x) s ON true WHEN MATCHED THEN DELETE` each emptied it
+while reading as an ordinary `INSERT` (#94, #95). So a write nested inside another statement
+is tier two, `reason=nested_write`, and a `MERGE` is classified by its actions: a
+`THEN DELETE` or `THEN UPDATE` is tier two, `reason=multi_table`, while an insert-only or
+`DO NOTHING` one stays tier one. `ON CONFLICT … DO UPDATE`, `ON DUPLICATE KEY UPDATE` and
+`INSERT … SELECT` are untouched by this — they are not nested writes, whatever they read
+like. The cost is a CTE that deletes one row by primary key, and the ordinary `MERGE` upsert,
+both refused for unattended callers.
+
+**For a single-table write, the `WHERE` has to be about that table.** `UPDATE p SET c = 1
+WHERE id = 1` is an ordinary write; `UPDATE p SET c = (SELECT max(x) FROM o WHERE o.id = 1)`
+is not, because its only `WHERE` restricts the subquery and the write touches every row. A
+*correlated* reference back to the target does count, so
+`DELETE FROM t WHERE EXISTS (SELECT 1 FROM o WHERE o.tid = t.id)` is tier one while
+`DELETE FROM t WHERE EXISTS (SELECT 1 FROM o WHERE o.id = 1)` deletes every row and is tier
+two. A qualifier the subquery binds itself — including the target's own name, as in
+`DELETE FROM sessions WHERE EXISTS (SELECT 1 FROM sessions WHERE …)` — is about the
+subquery's rows, not the write.
+
+This is a lower bound, not a proof: `WHERE id IS NOT NULL` names the target and still touches
+every row, and no static check settles that. What it rules out is the class where nothing in
+the condition is about the table being written.
+
+**When the parser cannot read the statement**, there is no tree to judge and the same rule is
+applied to the text: tier one only when the statement reads as a write to one named table
+with a `WHERE` or `LIMIT` and contains no `SELECT`, `TABLE`, `VALUES`, `JOIN`, `USING`, a
+statement-level `WITH`, or an `UPDATE … FROM`. A keyword inside parentheses is not at
+statement level, so `SUBSTRING(x FROM 2)` and `AGAINST ('a' WITH QUERY EXPANSION)` do not
+trip it. This is written as an allowlist because the denylist that preceded it was defeated
+once per review round — `USING`, then `JOIN`, then a CTE, then a subquery, then `TABLE` as a
+subquery.
+
+**Escape routes.** For a statement that accepts a `WHERE`, put the intent in the SQL:
+
+```bash
+dbcli query "UPDATE users SET banned = 1"                    # refused, reason=no_where
+dbcli query "UPDATE users SET banned = 1 WHERE 1=1"          # runs — intent is explicit
+dbcli query "DELETE FROM sessions LIMIT 1000"                # runs — damage is bounded
+dbcli query "UPDATE users SET banned = 1 WHERE id = 3" --yes # tier one, question skipped
+dbcli query "UPDATE p SET x = 1 FROM o WHERE o.id = 1"       # refused — the WHERE is about o, not p
+```
+
+This is deliberately not a flag. `WHERE 1=1` appended to a statement that already has a
+`WHERE` is a syntax error, so a blanket "always add it" habit breaks on the first ordinary
+statement; a flag would be harmless everywhere and therefore added everywhere. For `DROP`
+and `TRUNCATE` there is no clause to add — the connection's `permission` level decides
+whether they are possible at all, and the typed confirmation must come from a person.
+
+Every tier-two evaluation is written to the audit log with
+`metadata.write_gate_outcome` (`allowed` / `declined` / `refused`) and
+`metadata.write_gate_reason`. `dbcli audit write-gate` summarizes them — that is
+the measurement ADR 0010 stakes this gate on.
+
 > **Elasticsearch tiers by scope.** A read (`GET` / `HEAD`, plus `POST _search` and
 > `POST _count`) is query-only. Indexing or updating a document is read-write.
 > `DELETE /<index>/_doc/<id>` — one document — is data-admin. Everything that removes or
@@ -955,6 +1037,14 @@ dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json
 > target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
 > (MongoDB `--where` accepts a full JSON filter and is exempt.)
 
+> **Tier two for structured writes (2.0.0)** — a `--where` that matches on no primary key
+> and no unique index selects an unknown number of rows, so it is treated the same as a
+> raw statement with no `WHERE`: the target table name must be typed at an interactive
+> terminal, and a non-interactive run is refused with exit `1` and
+> `reason=non_unique_where`. `--force` and `--dry-run` do not affect this; `--force` skips
+> the ordinary confirmation only. Select the primary keys first and write one row at a
+> time, or run it where a person can confirm it.
+
 ### delete
 
 Delete data from a table.
@@ -1946,6 +2036,7 @@ Audit entries are metadata-only by design — never raw SQL bodies, `--param` va
 | `audit show` | `readonly` | Print a single full entry by id prefix or `--recovery-ref`. |
 | `audit clear` | `local-write` | Delete `<conn>.jsonl` + rotated `.jsonl.1` from local disk. Requires `--yes` or interactive confirm. |
 | `audit health` | `readonly` | Render `AuditLogger.getHealth()` snapshot (writer state, lock state, rotation usage). |
+| `audit write-gate` | `readonly` | Summarize tier-two write-gate decisions: how often the gate was reached, by which reason, and how it was answered. |
 
 #### `audit tail`
 
@@ -2006,6 +2097,32 @@ Examples:
 
 Output reports: writer enabled/disabled, last write result, file-lock state, rotation cap usage (`max_bytes` / `max_entries`). When `audit.enabled = false` (D1 opt-out), `tail` / `show` / `health` still exit 0 and print `Audit is disabled (audit.enabled = false in .dbcli). Use 'dbcli audit health' for details.` (E note).
 
+#### `audit write-gate`
+
+Answers the question ADR 0010 stakes the two-tier write gate on: is tier two stopping anything, or has everyone routed around it? The data was always written — `metadata.write_gate_tier` / `write_gate_outcome` / `write_gate_reason` on every evaluation — but reading it meant hand-writing jq over the JSONL.
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--format <fmt>` | `table` \| `json`. | `table` |
+| `--all` | Merge every connection into one measurement. | off |
+| `--for-agent` | Shortcut for `--format json`. | off |
+
+```bash
+dbcli audit write-gate
+dbcli audit write-gate --format json
+dbcli audit write-gate --all
+```
+
+Reports, over the current connection's retained history (rotated `.jsonl.1` included):
+
+- `total` — tier-two evaluations, with `range` giving the interval they span.
+- `outcomes` — `allowed` / `declined` / `refused`. The ratio between them is the line between "the gate is stopping things" and "everyone confirms through it".
+- `reasons` — which criterion sent the statement to tier two. Every known reason is listed, **including the ones that never fired**: a criterion that triggers zero times is the finding, not a row to omit.
+- `scanned` + `window` — the denominator. Two decisions in a week and two in a year are different findings.
+- `tierOne` — counted apart, with its own outcome breakdown, because tier one is recorded only when the operator declined.
+
+When tier two was never reached, the summary says so and names the conclusion ADR 0010 draws from it (the criterion is wrong, not the gate unnecessary) rather than printing an empty table. An entirely empty audit log is reported as a separate case: it supports no conclusion either way.
+
 #### Boundaries
 
 - Entries are append-only JSONL; rotation triggers at `~10 MB` or `~1000` entries (whichever first). Previous segment is preserved as `.jsonl.1`.
@@ -2495,11 +2612,38 @@ dbcli shell --sql    # SQL-only mode
 Inside the shell:
 - Type SQL statements ending with `;` to execute
 - Type dbcli commands without the `dbcli` prefix (e.g., `schema users`)
+- Prefix a subcommand with `\` to force it: `\delete users --where id=1`. Required for the
+  subcommands whose names are also SQL keywords — `insert`, `update`, `delete`, `explain` —
+  because a line starting with one of those is read as SQL,
+  which is what a shell is for. The prefix works on every subcommand, so it is one rule
+  rather than a list of exceptions (#88).
+- A subcommand runs in its own process with no stdin, so its ordinary y/n confirmation reads
+  EOF and cancels. `\insert` / `\update` / `\delete` therefore need `--force` from inside
+  the shell — or type the SQL at the prompt, where the confirmation can actually be
+  answered. Tier two is unaffected either way: it is refused in the child and points you
+  back to the prompt.
 - Use Tab for auto-completion (SQL keywords, table names, column names)
 - Type `.help` for meta commands (.quit, .clear, .format, .history, .timing)
-- Multi-line SQL: keeps accumulating until `;` is found
+- Multi-line SQL: keeps accumulating until `;` is found. Meta commands still work while a
+  statement is accumulating — `.quit` quits, `.clear` abandons the buffer — and Ctrl-C
+  cancels. A line that reads as SQL but names a subcommand and carries a double-dash option prints
+  a note saying which prefix would have reached the subcommand.
 - History persists across sessions (~/.dbcli_history)
 
+> **Tier two applies here (2.0.0)** — on SQL connections a typed `UPDATE` / `DELETE` with
+> no `WHERE`, a `DROP` or a `TRUNCATE` asks for the target table name before it runs.
+> Anything else typed cancels the statement and returns to the prompt; the session stays
+> open, and Ctrl-C withdraws the question itself — the next line is read as a statement,
+> not as the answer. Tier one (the y/N on ordinary writes) is deliberately not wired here — every line
+> is typed by a person. Piped input (`dbcli shell < script.sql`) has nobody to answer, so a
+> tier-two statement is refused and the remaining lines still run. Redis, MongoDB and
+> Elasticsearch shells are unaffected.
+>
+> dbcli **subcommands** typed in the shell (`query "..."`, `delete ...`) run as separate
+> processes with no stdin, so they cannot ask anything: a tier-two statement there is
+> refused with a message pointing you back to the `dbcli>` prompt, where the confirmation
+> can actually be typed.
+
 The REPL flavor depends on the active engine: SQL engines and MongoDB use the
 form above; **Redis** opens a single-line command REPL (see [Redis › Interactive
 shell](#interactive-shell)); **Elasticsearch** opens a Kibana Dev Tools-style

package/CHANGELOG.md

@@ -5,6 +5,83 @@ 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).
 
+## [2.1.0] - 2026-08-16 - The gate asked the wrong question, and one route never reached it
+
+2.0.0 put a two-tier gate in front of raw SQL. This release is what measuring that gate against real servers found: one entire route into the database bypassed it, its qualification criterion asked whether a `WHERE` existed rather than whether it narrowed anything, and its notion of "what kind of statement is this" was the leading keyword — so a full-table delete wearing an `INSERT` or `WITH` in front of it was treated as routine. Each of the three is a way a statement that empties a table reached the database unattended, and each is closed here. The measurement the gate's own ADR bets on is now a command rather than a `jq` invocation somebody has to remember.
+
+### Changed
+
+- **The gate's qualification criterion now requires positive evidence that the `WHERE` narrows the table being written.** It was `statement.where != null`, which asks whether a `WHERE` exists; the question that matters is whether this `WHERE` restricts the target. `UPDATE p SET c = (SELECT … WHERE …)` has one and rewrites every row. A `WHERE` must now reference a column of the table being written — a correlated reference back to the target counts, unless the name is bound by the subquery itself, since `DELETE FROM sessions WHERE EXISTS (SELECT 1 FROM sessions WHERE …)` speaks about the subquery's own rows and was measured emptying the table. This is a lower bound, not a proof: `WHERE id IS NOT NULL` names the target and touches every row. `WHERE 1=1` remains the supported escape hatch (#80, #93).
+
+- **A multi-table write is tier two regardless of its `WHERE`, under the new reason `multi_table`.** `DELETE p FROM p JOIN o ON p.id = o.ref WHERE o.x > 0` deleted 2 of 5 rows on one dataset and all 2000 on another — the same statement, a different answer, so scope is not decidable from the text. A join's `ON` always mentions the target table, so treating it as evidence would readmit the entire class 2.0.0 exists to stop, `UPDATE p SET … FROM o WHERE p.id = o.ref` included. Four criteria were tried and each was broken by the next ordinary statement, so the tier is now decided by what the statement *is* — which is known — rather than by what it will touch, which is not. The remedy in the refusal says "rewrite as a single-table statement or have somebody confirm it", not "add a `WHERE`" (#80).
+
+- **When the parser cannot read a statement, tier one is now an allowlist rather than a denylist.** Enumerating the keywords that introduce a second table lost one round of adversarial review each: `USING`, `JOIN`, CTEs, subqueries, `TABLE` as a subquery. A statement now has to read as "writes one named table, has a `WHERE` or `LIMIT`" and contain no `SELECT` / `TABLE` / `VALUES` / `JOIN` / `USING`, no statement-level `WITH`, and no `UPDATE … FROM` to qualify. Keywords inside parentheses are not statement-level, so `SUBSTRING(x FROM 2)` and `AGAINST ('a' WITH QUERY EXPANSION)` are not misread (#80).
+
+- **Statement type is decided by shape, not by the leading keyword, so a write hidden in front of one no longer buys tier-one treatment.** Measured on PostgreSQL 16 against a 2000-row table: `WITH moved AS (DELETE FROM p RETURNING *) INSERT INTO archive …` deleted 2000 rows and `MERGE INTO p … WHEN MATCHED THEN DELETE` deleted 2000 — both tier one, both skipped by `--yes`. The same CTE under a `CREATE TABLE … AS` head and `MERGE … WHEN MATCHED THEN UPDATE` behave the same way. The criterion is now a nested write anywhere inside parentheses, which holds because a parenthesised expression that is not the statement body cannot contain a write: `INSERT` / `UPDATE` / `DELETE` are reserved words in both dialects, so a column named that way must be quoted, and quoting is stripped before the read. `MERGE` is the exception, so only `MERGE INTO` is matched. Locking clauses (`SELECT … FOR UPDATE`) and foreign-key referential actions (`ON DELETE` / `ON UPDATE`) are stripped first — the latter after a review round found `ON DELETE CASCADE` blocking every table creation with a foreign key, while the same constraint added via `ALTER TABLE` was allowed, one meaning with two answers. A `MERGE` is classified by its `WHEN … THEN` actions: `THEN DELETE` / `THEN UPDATE` are tier-two `multi_table` because `MERGE` reads its rows from `USING`, while a pure-insert or `DO NOTHING` merge stays tier one, which is what keeps ordinary upserts working (#94, #95).
+
+- **Every gate decision is audited as `db-write`, so filtering the audit log by tier no longer misses two thirds of them.** `side_effect_tier` was read from the command's capability table, so the same `DROP TABLE users` decision was recorded `readonly` when it arrived through `query`, `db-write` through `delete`, and `interactive` through `shell` — and tier is the first filter any audit consumer reaches for. `AuditOutcome` gained `sideEffectTier` so a caller that knows more than the capability table can state what the statement actually does; the type deliberately accepts only `db-write` / `local-write`, because this opening exists to be more accurate, not to downgrade a write. `--dry-run` / `--plan` still win, being an explicit execution mode rather than an outcome. The capability table is unchanged — `interactive` remains a correct description of the `shell` command itself (#83).
+
+#### Automation affected
+
+Three shapes that ran unattended before now exit `1`, all of them full-table writes that 2.0.0 intended to stop and mis-tiered:
+
+| Invocation | Now | Remedy |
+| :--- | :--- | :--- |
+| `UPDATE p SET c = (SELECT … WHERE …)` — `WHERE` only inside a subquery | `reason=no_where` | add a `WHERE` on the target table, or `WHERE 1=1` |
+| `DELETE p FROM p JOIN o …` / `UPDATE p SET … FROM o …` | `reason=multi_table` | rewrite as a single-table statement, or run it where a person can confirm |
+| data-modifying CTEs and `MERGE … THEN DELETE/UPDATE` | `reason=multi_table` | as above; pure-insert `MERGE` upserts are unaffected |
+
+### Added
+
+- **`dbcli shell` now applies the tier-two gate, the last SQL route that bypassed it.** The REPL called the adapter directly with only permission and blacklist checks in the way, so `DELETE FROM users` demanded a typed table name under `dbcli query` and asked nothing at all one prompt over — protection that depended on which entrance the user picked, which is the thing #70 set out to remove. Only tier two is wired in: every line in a shell is hand-typed, so a per-statement `y/N` would become reflex, and tier one exists for batches of routine writes. A refusal prints to stderr and returns to the prompt with the session, connection and buffer intact; piped input (`dbcli shell < script.sql`) has nobody to answer, so that statement is refused and the rest of the file runs. Every tier-two evaluation is audited. Core still writes to neither stdout nor stderr (ADR 0009): `ReplEngine` takes a `ReplWriteGate` callback and `src/commands/shell.ts` supplies it, asking through the REPL's own readline interface — inquirer opens a second reader and was measured consuming each keypress twice. Line handling is queued, because readline emits every line of a paste before the first `await` returns (#78).
+
+- **`dbcli audit write-gate` turns the measurement ADR 0010 bets on into one command.** The ADR does not justify tier two by argument; it bets that in six months the records will say whether it stopped anything. The data was being written all along (`write_gate_tier` / `write_gate_outcome` / `write_gate_reason`) but reading it meant hand-writing `jq` over `.dbcli/audit/*.jsonl` — a measurement nobody performs is a falsification condition that never fires. The summary answers three questions: how often tier two was reached, grouped by reason; how many were allowed, cancelled and refused; and over what span those numbers were measured. Zero is reported as a conclusion rather than an empty table — it is evidence the criterion is wrong, not that the gate was unnecessary — while an empty audit log is stated as yielding no conclusion at all. Reasons that never fired stay on the table showing `0`, since an omitted row can answer "how often" but not "at all". Tier one is counted separately with its outcome distribution rather than a hardcoded label. Counting is a pure core function; reading files and formatting stay in the command layer. A compile-time guard in `src/commands/audit.ts` fails in both directions if the reason or outcome list drifts from the gate's own (#79).
+
+- **`\` calls a subcommand from inside `dbcli shell`, and SQL keywords win the name collision.** Typing `delete users --where status=active` was classified as SQL on its leading keyword, and with no semicolon it entered multiline mode silently — every subsequent line, `.quit` included, was swallowed into the buffer, leaving a shell that could only be killed from outside. A shell is for typing SQL, so `DELETE FROM users WHERE …` must stay typeable; subcommands moved to their own namespace instead. `\` is separate from the existing meta `.` — the latter is implemented by the shell, the former runs a dbcli subcommand in its own process — and it works for every subcommand, so what has to be remembered is a rule rather than a list of the four that actually collide (`insert`, `update`, `delete`, `explain`). The prefix is checked before the SQL rule, so a trailing `;` typed out of muscle memory does not turn it back into SQL. When a line is classified as SQL but starts with a subcommand name and carries a double-dash option, one line says which prefix would have reached the subcommand — unless the second word is a keyword like `FROM` / `SET` / `INTO`, since `--` also opens a SQL comment (#88).
+
+### Fixed
+
+- **Multiline mode no longer hijacks the shell, and Ctrl-C now cancels what it says it cancels.** While a statement is buffering, the shell's own meta commands are handled instead of being appended, and `.quit` / `.clear` also discard the buffer — but not inside an unterminated string literal, where the line is text rather than a command and lifting it out would split the statement; `MultilineBuffer` is the only place that knows the quoting state, so it answers `isInsideLiteral()`. Separately, pressing Ctrl-C at the gate's "type the table name" question invoked the SIGINT listener while readline's `question` stayed mounted, so the next line typed was consumed as the answer. Each question now gets an `AbortController`; SIGINT aborts it and resolves `null`, which prints "cancelled" rather than "input did not match X" — the latter describes an answer that was never given. The audit still records `declined`, because a decision was made. And cancelling a multiline statement only ever printed a message: `MultilineBuffer.reset()` existed with no caller in the repository, so the next statement was appended to the abandoned half and came back as a syntax error pointing at a keyword the user never typed (#85, #88).
+
+- **A subcommand refused inside `dbcli shell` said something untrue, and before that it could not run at all.** `Bun.spawn` gives a child no stdin by default, so every subcommand was judged unattended: tier two was refused with "nobody can confirm this right now, run it in an interactive terminal", said to a person sitting at one. The child now carries `DBCLI_SHELL_SUBCOMMAND=1` and the refusal states the actual situation and offers a route that works — type the statement at the `dbcli>` prompt, where dbcli will ask for the table name. `code` and `reason` are untouched, since agents branch on those; only the prose for humans changed. Verifying it surfaced two defects further upstream that made the situation unreachable: `--config` was placed after the subcommand, but it is a program-level option that `query` / `insert` / `update` / `delete` do not declare, so every write subcommand ended in `unknown option`; and the tokenizer left matched quotes inside tokens, which go straight into `Bun.spawn`'s argv with no shell to strip them, so `query "DELETE FROM users"` arrived as one quoted identifier (#84).
+
+- **`dbcli q` now enforces permission itself instead of relying on another module to do it.** `q.ts` never called `enforcePermission` and the adapter does not check either; nothing broke today only because `saved-queries/parser.ts` rejects snippets at load time that are not `SELECT` / `WITH`, contain write keywords, or hold multiple statements. A property held jointly by two modules, one of which does not know it is holding it, comes apart the first time somebody reasonably asks for snippets that write. This is defence in depth rather than a bug fix — under the current contract every executable snippet still passes. The check reads `prepared.rewrittenSql` rather than the driver SQL, which is a size-guard wrapper and would describe dbcli's wrapping instead of the requested statement, and it runs before the `--dry-run` branch, so a refusal is not worded differently for a statement that was not going to execute anyway. `checkTablesBlacklist` now receives the real statement type instead of a hardcoded `'SELECT'` (#81).
+
+- **518 test files had never been type-checked, and now 519 are.** `tsconfig.json` matched them with `"tests/**/*.{ts,tsx}"`, and TypeScript's include globs support `*`, `?` and `**/` but do not expand braces — `tsc --listFiles | grep -c "/tests/"` returned `0`. Every type-level assertion written in a test file was decoration: a compile-time guard was found still passing after a union member was removed from under it. The pattern was replaced with `tsconfig.tests.json` and `typecheck:tests`, initially covering only the directories that were clean and ratcheting outward over five batches (339 errors across 174 files, now zero), and `typecheck:tests` is in CI and the release checklist. Roughly six in ten were unchecked indexed access, but the pass also found tests that were wrong: an import from a module that does not exist (Bun strips type-only imports without resolving them), `buildSchemaContext()` called with no argument, a `makeEntry` helper whose `...overrides` silently overwrote the two fields written above it, spies typed as bare `ReturnType<typeof spyOn>` and thereby erasing 13 parameters into `any`, mock adapters missing four methods `QueryableAdapter` requires, and `permission: 'read-only'` — not one of the four legal values — standing in for "insufficient permission" and reaching the right verdict for the wrong reason. `tests/helpers/test-config.ts` was producing a value that was not a valid `DbcliConfig` at all, its `Partial` overrides spread after the required fields turning them all optional (#93, #97).
+
+- **The `inspect` leak check no longer fails at random.** It asserted `expect(stdout).not.toContain('5432')` over the whole serialized output; `--no-connect` emits no port field, but an audit entry's UUID ended in `5432` and reddened CI once. Three UUIDs of 32 hex characters each puts this at roughly one run in 700 — rare enough not to look like a real problem, frequent enough to burn a CI run and an investigation now and then. The check now walks the parsed structure: a value must *be* the port, a string must *contain* the host, and credential field names count wherever they appear (the fixture password is the single character `p`, so value matching cannot help there). The connection object's key set is pinned to `name` / `database` / `version`, which is stricter than before — any added field fails — where the old check exploded on the substring "host" appearing anywhere (#92).
+
+## [2.0.0] - 2026-08-14 - A write nobody can confirm does not run
+
+### Changed
+
+- **BREAKING: a statement that is not limited to particular rows is refused when nobody is watching.** `dbcli query "UPDATE users SET banned = 1"` used to execute against any read-write connection without asking anything, and the caller most likely to produce an unqualified `UPDATE` is the agent this product exists to serve. Raw SQL now passes through a two-tier gate before the connection is opened. Tier one is any write — an `INSERT`, an `UPDATE` or `DELETE` that has a `WHERE` or `LIMIT`, a `CREATE`, an `ALTER` — and behaves as it always has for a non-interactive caller; at a terminal it shows what dbcli understood the statement to do and asks, which `--yes` skips. Tier two is `UPDATE` / `DELETE` with no `WHERE`, `DROP`, `TRUNCATE`, several statements in one string — one statement to a classifier reading the leading keyword, two to a driver — and any statement the SQL parser cannot read: at a terminal the operator types the target table name, and **no flag skips it** — not `--yes`, not `--force`. Away from a terminal, or under `--format json`, tier two is refused: exit `1`, a `reason=` a caller can branch on (`no_where`, `ddl_destruction`, `unparseable`, `multiple_statements`), and the statement never sent, because the gate runs before the adapter is built rather than after. A parse failure resolves to tier two rather than tier one; the cost of being wrong is a needlessly typed table name against a needlessly emptied table. The reasoning, the alternatives, and the condition that would falsify it are in `docs/adr/0010-unattended-callers-are-refused-full-table-writes.md` (#70).
+
+- **BREAKING: `dbcli update` / `dbcli delete` refuse a `--where` that matches on nothing unique.** Their `WHERE` is mandatory, so "no `WHERE`" cannot happen — but `--where "status=active"` reads like a filter and writes like a full-table statement. When the conditions cover neither the primary key nor any unique index, the same tier-two treatment applies: type the table name, or be refused with `reason=non_unique_where`. The schema needed to tell the two apart is already in hand at that point, so this costs no extra round trip. `--force` is unaffected in what it always did — skip the ordinary confirmation — and does not open this gate (#70).
+
+- **BREAKING: `admin` permission no longer means "everything runs".** Permission and the gate are separate axes now: permission says what the connection may do, the gate says whether this statement may run right now. An `admin` connection running `DROP TABLE users` from a script is refused, because `DROP` and `TRUNCATE` have no clause to add and therefore no unattended route at all. Whether they are possible in an environment remains a `permission` decision that lives in version control; whether one happens today is a decision a person makes at a terminal (#70).
+
+- **The permission check for raw SQL now runs before the connection is opened.** It ran inside `QueryExecutor`, after `connect()`, so a refusal cost a round trip and arrived after the gate had already asked its question. The command layer now calls the same `enforcePermission` with the same real statement before either — a connection that may not run this at all is told so rather than asked to confirm something it was never going to be allowed to do. The executor still checks; this only moves the verdict earlier (#70).
+
+### Added
+
+- **`dbcli query --yes`** skips the tier-one confirmation, so a long sequence of routine writes does not become a sequence of keypresses. It has no effect on tier two by design: a flag that could be set once and forgotten is exactly what the escape route for a full-table write must not be (#70).
+
+- **Every tier-two evaluation is written to the audit log — allowed, declined and refused alike** — with `metadata.write_gate_outcome` and `metadata.write_gate_reason`. Deliberately unconditional: a log that kept only the refusals could not tell "nobody writes like that" apart from "everybody found a way around it". In six months, whether this gate prevented anything is a query rather than an impression, and if tier two turns out to be almost never reached, the criterion is wrong rather than the gate unnecessary (#70).
+
+### Migration
+
+Automation that performs unqualified full-table writes stops working. Three shapes are affected, and each has a fixed remedy:
+
+| Invocation | Now | Remedy |
+| :--- | :--- | :--- |
+| `dbcli query "UPDATE t SET c = v"` | exit 1, `reason=no_where` | `dbcli query "UPDATE t SET c = v WHERE 1=1"`, or add a `LIMIT` |
+| `dbcli query "DELETE FROM t"` | exit 1, `reason=no_where` | `dbcli query "DELETE FROM t WHERE 1=1"`, or add a `LIMIT` |
+| `dbcli query "DROP TABLE t"` / `TRUNCATE` | exit 1, `reason=ddl_destruction` | run it at a terminal, or apply the schema change through a reviewed migration |
+| `dbcli update t --where "status=x" …` | exit 1, `reason=non_unique_where` | select the primary keys first, then one write per key — or run it where a person can confirm |
+
+`WHERE 1=1` is the supported way to say "yes, every row". It is intentionally not a flag: appended to a statement that already has a `WHERE` it is a syntax error, so it cannot be added blanket-style to a script and forgotten. There is no environment variable that restores the old behaviour — a flag that makes the same version behave differently on different machines makes every later bug report ambiguous, and never gets removed.
+
 ## [1.58.0] - 2026-08-14 - A write that did not happen stops reporting success
 
 ### Changed

package/assets/SKILL.md

@@ -43,6 +43,25 @@ condition, first `query` / `export` the target rows' primary keys, then run one
 `update` / `delete --where "id=<pk>"` per key — or escalate to a human. (MongoDB `--where`
 takes a full JSON filter and is exempt.)
 
+**Write gate (2.0.0) — the rule that will refuse you.** Every write is classified into two
+tiers. Ordinary writes (`INSERT`, `UPDATE` / `DELETE` with a `WHERE`, `CREATE`, `ALTER`)
+run unattended exactly as before; `--yes` skips the terminal prompt a human would see.
+**Statements that are not limited to specific rows are refused outright when nobody can
+answer a prompt** — `UPDATE` / `DELETE` with no `WHERE`, `DROP`, `TRUNCATE`, a statement
+the SQL parser cannot read, several statements in one string, and `update` / `delete --where` matching on no primary key and
+no unique index. The process exits `1` with `reason=no_where`, `reason=ddl_destruction`,
+`reason=unparseable`, `reason=multi_table`, `reason=nested_write` or
+`reason=non_unique_where`, and **nothing
+reaches the database**. In `dbcli shell`, a subcommand whose name is a SQL keyword needs a
+`\` prefix (`\delete users --where id=1`) — a bare `delete …` is read as SQL. A write that joins a second table is always tier two: whether it is
+limited to particular rows depends on the data, not on the statement. So is a statement
+carrying a second write inside it — a data-modifying CTE
+(`WITH x AS (DELETE FROM t RETURNING *) INSERT INTO …`) or a `MERGE` with a
+`WHEN … THEN DELETE` / `THEN UPDATE` action.
+**No flag bypasses this** — not `--yes`, not `--force`. To write every row on purpose, put
+the intent in the SQL itself: add `WHERE 1=1` or a `LIMIT`. `DROP` / `TRUNCATE` have no
+unattended route at all; escalate to a human.
+
 > `report` and `guide` already embed an `inspect` snapshot — you do **not** need to run
 > `dbcli inspect` first. Run `dbcli inspect --for-agent` manually only when you want the
 > audit-recent context or to diagnose a connection problem.

package/assets/SKILL.zh-TW.md

@@ -36,6 +36,23 @@ legacy 單檔 `.dbcli`。若要防護同一 OS 使用者的惡意 process，host
 `update` / `delete --where "id=<pk>"`（逐一等式）— 或升級交給人類處理。（MongoDB 的
 `--where` 接受完整 JSON filter，不受此限。）
 
+**寫入閘門（2.0.0）— 會直接拒絕你的那條規則。** 所有寫入都會分成兩級。一般寫入
+（`INSERT`、帶 `WHERE` 的 `UPDATE` / `DELETE`、`CREATE`、`ALTER`）在無人看管下照跑，
+與過去相同；`--yes` 用來跳過人類在終端機看到的提問。**沒有限定要動哪些列的語句，在沒有
+人能回答提問時會直接被拒絕** — 沒有 `WHERE` 的 `UPDATE` / `DELETE`、`DROP`、`TRUNCATE`、
+SQL parser 讀不懂的語句、一個字串裡塞了多句語句，以及 `update` / `delete --where` 沒有命中主鍵或唯一索引的情況。
+行程以 `1` 結束，訊息點名 `reason=no_where`、`reason=ddl_destruction`、
+`reason=unparseable`、`reason=multi_table`、`reason=nested_write` 或
+`reason=non_unique_where`，而且**什麼都不會
+送到資料庫**。在 `dbcli shell` 裡，名稱與 SQL 關鍵字相同的子指令需要 `\` 前綴
+（`\delete users --where id=1`）——直接打 `delete …` 會被當成 SQL。接了第二張表的寫入一律第二級：它會動到幾列取決於資料而不是語句。
+裡面還夾著另一個寫入的語句也是——資料修改型 CTE
+（`WITH x AS (DELETE FROM t RETURNING *) INSERT INTO …`）與帶
+`WHEN … THEN DELETE` / `THEN UPDATE` 動作的 `MERGE` 都算。
+**沒有任何旗標可以繞過** — `--yes` 不行，`--force` 也不行。真的要寫全表，就把意圖寫進
+SQL 本身：補上 `WHERE 1=1` 或 `LIMIT`。`DROP` / `TRUNCATE` 完全沒有無人看管的路徑，請
+升級交給人類處理。
+
 > `report` 與 `guide` 已內嵌 `inspect` 快照 — **不需要**先跑 `dbcli inspect`。只有在需要 audit-recent 脈絡或診斷連線問題時，才手動跑 `dbcli inspect --for-agent`。
 
 **依任務路由：**