feat(usable): integrate current dbtool implementation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

plans/2026-03-26-cmp-19-mysql-unicode-remediation.md

@@ -0,0 +1,54 @@
+# CMP-19 MySQL 中文输出乱码修复计划
+
+日期：2026-03-26  
+作者：CTO
+
+## 1. 当前真实状态
+
+- 宿主机 Docker smoke 已证明 PostgreSQL / MySQL happy path 能跑通，因此这不是环境不可达问题。
+- 当前剩余问题是 MySQL `query` 输出中文乱码，属于产品质量缺陷，来源于 [CMP-17](/CMP/issues/CMP-17#comment-0cd53e93-25a5-456b-8dba-31ea098c2aa8)。
+- 仓库内 MySQL fixture 已包含多语言数据：`张敏`、`权限验证`、emoji。
+- 当前 MySQL 渲染链路在 `crates/db-drivers/src/lib.rs` 中把 `MySqlValue::Bytes` 直接走 `String::from_utf8_lossy`。
+- 2026-03-26 当前阶段更新：后端子任务 [CMP-22](/CMP/issues/CMP-22) 已提交候选修复和回归测试；当前新的主阻塞已转为 QA 子任务 [CMP-23](/CMP/issues/CMP-23) 的宿主机验证与证据回填。
+- 2026-03-27 新宿主机证据表明：在干净重建并显式 UTF-8 导入后，MySQL 官方 CLI、`dbtool query` 与 `dbtool export` 都能正确显示中文；问题边界已从“dbtool 解码缺陷”收敛为“MySQL bootstrap/import 字符集未显式声明”。
+- 后端已据此将最小修复收敛到 `examples/scripts/bootstrap-mysql.sh`，为导入命令显式添加 `--default-character-set=utf8mb4`。
+
+## 2. 当前技术判断
+
+- 仅凭 CTO 当前 runner 不能直接复现该问题，因为此环境没有可用 MySQL runtime。
+- 本地 vendored `mysql 28.0.0` 源码显示握手响应默认使用 `utf8mb4` collation，因此“完全没有声明 UTF-8”不是充分结论。
+- 更可能的方向是：需要在真实复现场景中确认 MySQL session charset / collation、返回字节序列，以及当前 driver 是否还需要显式 `SET NAMES utf8mb4` 或等价初始化。
+- 在没有复现证据前，不应由 CTO 盲改产品代码。
+- 截至 2026-03-27，根因判断已被宿主机证据更新：当前不再优先怀疑 `dbtool query` / `export` 的结果解码，而是优先怀疑 demo 数据在 MySQL bootstrap/import 路径中因客户端字符集未显式指定而被错误写入。
+
+## 3. 第一轮职责
+
+- 后端：复现问题，定位 session charset 与返回值解码链路，提交最小修复和回归。
+- QA：在修复分支上复跑宿主机 smoke，确认中文结果恢复正常，并回填共享文档。
+- 前端：继续 gated；本轮不进入 CLI 编码缺陷修复路径。
+- CTO：维护优先级、评审根因证据、决定该缺陷是否仍阻塞发布。
+
+## 4. 执行步骤
+
+1. 后端在可运行 MySQL demo 的环境重放 `examples/sql/mysql/happy_path_query.sql`。
+2. 记录 `SHOW VARIABLES LIKE 'character_set_%'` 与 `SHOW VARIABLES LIKE 'collation_%'`。
+3. 对中文字段做最小复现查询，确认是 session 编码、列编码还是驱动渲染问题。
+4. 若 session 协商不稳定，则在连接初始化中显式设置 `utf8mb4`；若是渲染问题，则在 driver 值转换处修复。
+5. 为修复补最小回归证据；优先放在 driver 层，必要时补 CLI 端到端回归。
+6. 2026-03-26 第一轮候选修复曾收敛到 dbtool 连接初始化，但 2026-03-27 的宿主机复核已降低该方向的优先级。
+7. 当前最小仓库修复已切换为 bootstrap/import 侧：`examples/scripts/bootstrap-mysql.sh` 显式传入 `--default-character-set=utf8mb4`，保证 fixture 写入路径可重复。
+8. QA 接续执行 [CMP-23](/CMP/issues/CMP-23)：在 Docker-capable host 上用修复后的 bootstrap 脚本重跑 seed + query + export 路径，并把最终证据回填共享文档。
+
+## 5. 验收标准
+
+- 能稳定复现原问题，且有明确根因说明。
+- 修复后 MySQL 查询结果中的 `张敏`、`权限验证`、emoji 均正常显示。
+- 回归结果被回填到 QA 文档与相关 issue。
+- 未引入 PostgreSQL / SQLite 输出回归。
+- 在 QA 宿主机复核完成前，`CMP-19` 仍保持 blocked，不应因“代码已提交”而提前宣布关闭。
+- 若 QA 复核继续正常，则 `CMP-19` 的关闭结论应明确写成“问题已被重新归因到 bootstrap/import 字符集处理，并由最小 seed 修复关闭”，而不是“dbtool 解码层 bug 已修复”。
+
+## 6. 组织判断
+
+- 当前不建议因 `CMP-19` 扩编。
+- 这是单点产品缺陷与回归闭环问题，不是团队容量瓶颈。

plans/2026-03-26-cmp-20-dbtool-tui-v1-scope-and-boundaries.md

@@ -0,0 +1,222 @@
+# CMP-20 `dbtool-tui-v1` 范围、架构边界与执行建议
+
+日期：2026-03-26  
+作者：CTO
+
+> 状态刷新（2026-03-27）：本文档保留为 `CMP-20` 的边界决策记录。当前共享工作区已落地 `crates/db-app` 与 `apps/tui` 基线；实时推进状态请以 `plans/2026-03-26-dbtool-tui-v1-delivery-tracking.md`、`backlog/dbtool-tui-v1-first-wave-issues.md` 和 `apps/tui/README.md` 为准。
+
+## 1. 当前真实状态
+
+- `dbtool-cli-v1` 已具备 PostgreSQL / MySQL / SQLite 的 `connect`、`inspect`、`query`、`export` 主链路。
+- 当前产品验收范围仍然是 CLI；TUI 不应混入 `dbtool-cli-v1` 的首发完成定义。
+- 当前仓库没有任何 TUI 入口或终端 UI 基线，也没有事件循环、焦点管理、键盘导航或终端渲染代码。
+- 代码层面，`apps/cli/src/main.rs` 仍同时承担参数解析、用例编排和终端文本渲染；这意味着当前“core”还不足以被 TUI 直接复用。
+
+## 2. CTO 结论
+
+### 结论 A：应作为独立 project 推进
+
+- 建议在 Paperclip 中把 TUI 作为独立 project：`dbtool-tui-v1`。
+- 原因不是要分裂代码仓库，而是要分离目标、验收和 owner 节奏。
+- 这样可以明确：
+  - `dbtool-cli-v1` 继续对 CLI 首发负责
+  - `dbtool-tui-v1` 单独承担终端交互层探索和交付
+  - QA 不会把 TUI 误纳入当前 CLI 发布阻塞项
+
+### 结论 B：必须复用现有 Rust core，而不是另写业务逻辑
+
+- TUI 不应重新实现数据库连接、schema inspect、query 执行和 export 语义。
+- TUI 应复用现有 `crates/db-core`、`crates/db-config`、`crates/db-drivers`，并新增一层共享应用编排层。
+- 当前不建议为 TUI 单独建立另一套数据库访问栈，也不建议先走服务化 / 守护进程架构。
+
+### 结论 C：先补“共享应用层”，再做 TUI 界面
+
+- 当前最关键的前置项不是先画界面，而是把 `apps/cli` 中的用例编排抽出。
+- 建议新增 `crates/db-app`（名称可调整），承载跨 CLI / TUI 共享的应用级用例与状态对象。
+- 在这一步完成前，直接进入 TUI 编码会造成：
+  - CLI / TUI 各自复制一套执行编排
+  - 错误模型和状态文案分叉
+  - QA 需要维护两套行为定义
+
+## 3. 推荐边界：Core / CLI / TUI
+
+| 层 | 职责 | 当前状态 | 建议 |
+| --- | --- | --- | --- |
+| `crates/db-core` | 领域对象、请求/响应模型、通用错误、稳定产品语义 | 已存在 | 保持数据库无关，不放任何 UI 代码 |
+| `crates/db-config` | 连接 profile、脱敏摘要、配置抽象 | 已存在 | 继续作为共享配置边界 |
+| `crates/db-drivers` | PostgreSQL / MySQL / SQLite 具体实现 | 已存在 | 继续承载数据库差异 |
+| `crates/db-app` | connect / inspect / query / export 用例编排、会话摘要、可展示执行状态 | 缺失 | 应先补齐，作为 CLI / TUI 共享应用层 |
+| `apps/cli` | flag 解析、stdout/stderr 渲染、退出码 | 已存在但偏重 | 逐步瘦身为“CLI adapter” |
+| `apps/tui` | 终端布局、焦点切换、快捷键、交互状态机、结果浏览 | 尚未开始 | 作为新 app 单独推进 |
+
+## 4. 能力归属建议
+
+### 必须留在 shared core / app 层的能力
+
+- 连接目标建模
+- 连接测试
+- schema / table / column inspect 结果结构
+- query 请求、结果和错误分类
+- export 请求与结果
+- 空结果成功、执行失败、导出失败等标准状态语义
+- 脱敏规则与用户可展示错误摘要
+
+### 应属于 CLI adapter 的能力
+
+- 参数解析
+- `--help` / `--version`
+- 文本表格与命令行输出文案
+- shell 退出码
+- `.sql` 文件路径解析和命令行参数到请求对象的映射
+
+### 应属于 TUI adapter 的能力
+
+- 多 panel 布局
+- 焦点管理
+- 键盘导航与快捷键
+- query editor buffer
+- schema tree 展开 / 折叠 / 搜索
+- results table 翻页与滚动
+- execution banner、status bar、bottom panel
+
+## 5. 推荐技术方案
+
+### 终端渲染与输入
+
+- 推荐：`ratatui` + `crossterm`
+- 原因：
+  - Rust 生态成熟度足够
+  - 易于实现 panel、table、status bar、快捷键
+  - 不需要引入桌面壳或前端运行时
+
+### 状态管理
+
+- 推荐 reducer/event-driven 结构：
+  - `AppState`
+  - `Action`
+  - `update(state, action) -> state`
+- 原因：
+  - 焦点切换、执行状态、结果切页都属于显式 UI 状态变化
+  - 这种结构比把逻辑散落在 widget callback 里更适合 QA 和后续扩展
+
+### 数据执行模型
+
+- 当前数据库 I/O 仍为同步模型，因此 TUI 不应在 UI 线程直接执行 query。
+- 第一阶段建议使用“UI 主循环 + 后台 worker 线程 + channel 回传结果”。
+- 当前不建议为了 TUI 先重构为服务进程或强行引入复杂 async runtime。
+
+### SQL 编辑器
+
+- 第一阶段只需要最小可用多行编辑，不追求完整 IDE 能力。
+- syntax highlight、自动补全、query history search 应继续 gated。
+
+## 6. 与 CLI 共存规则
+
+- 代码仓库可以继续共用当前仓库，不必为了 TUI 单独拆 repo。
+- Cargo workspace 后续可扩展为：
+
+```text
+apps/
+  cli/
+  tui/
+crates/
+  db-core/
+  db-config/
+  db-drivers/
+  db-app/
+```
+
+- CLI 命令形状继续保持兼容演进，不为了 TUI 去打断当前 CLI 用户心智。
+- TUI 不能成为当前 CLI release gate；它应拥有独立 milestone、issue、QA matrix 和完成标准。
+
+## 7. TUI 第一阶段最小范围
+
+### In Scope
+
+- 单连接工作台
+- 左侧 schema browser
+- 中央 query editor
+- 底部 results / problems 区
+- 基本执行状态反馈
+- 调用共享 inspect / query / export 能力
+
+### Out of Scope
+
+- 多连接同时在线
+- 复杂 connection manager
+- 多 query tab
+- query 历史持久化
+- SQL autocomplete / explain / formatter
+- dashboard、图表、AI 助手
+- 桌面 GUI 与 TUI 同期并行实现
+
+## 8. 必须先完成的 gated 前置项
+
+1. `CMP-19` MySQL 中文输出问题收敛，否则 TUI 只会把现有结果渲染缺陷带入新界面。
+2. 抽出共享应用层 `db-app`，避免 CLI / TUI 双份编排。
+3. 固定结构化执行结果：
+   - connect status
+   - inspect tree payload
+   - query success / empty / failure
+   - export success / failure
+4. 明确终端尺寸下限、resize 行为和长结果滚动策略。
+5. 为 TUI 单独建立 QA smoke 与键盘导航验收，不复用 CLI 文本输出验收。
+
+## 9. 第一轮角色职责
+
+- 后端：
+  - 抽出 `db-app`
+  - 统一执行状态和错误对象
+  - 保证 inspect / query / export 结果结构可被 TUI 直接消费
+- 前端 / TUI 工程：
+  - 建立 `apps/tui`
+  - 落地 app shell、panel 布局、焦点管理和快捷键
+  - 不改数据库语义，不复制驱动逻辑
+- QA：
+  - 编写 TUI 最小 smoke
+  - 覆盖 terminal resize、键盘导航、空结果、错误反馈、导出提示
+- CTO：
+  - 维护 CLI / TUI 边界
+  - 防止 scope creep
+  - 评审 shared app 层是否足够稳定再放行 TUI 编码
+
+## 10. 风险与依赖
+
+### P0
+
+- 当前 shared core 仍偏“领域模型 + driver 入口”，尚未形成真正的应用层复用边界。
+- 如果跳过 `db-app`，TUI 项目会立即复制 CLI orchestration。
+
+### P1
+
+- 终端 UI 对长结果集、键盘交互、窗口缩放更敏感，QA 复杂度高于 CLI。
+- 当前代码是同步数据库 I/O，若线程边界设计不清，TUI 容易出现卡顿或状态错乱。
+
+### P2
+
+- `CMP-9` 已定义未来 desktop GUI 基线；若 TUI 和 GUI 同时推进，团队容易把“终端工作台”和“桌面工作台”混为一谈。
+
+## 11. 首批 issue 拆分建议
+
+### 项目级
+
+1. 新建 project：`dbtool-tui-v1`
+2. 立项说明引用本文件与 [CMP-9](/CMP/issues/CMP-9)
+
+### 工程级
+
+1. **Backend**：抽出 `crates/db-app`，承接 connect / inspect / query / export 共享编排
+2. **Backend**：稳定结构化执行状态与错误对象，补回归测试
+3. **Frontend / TUI**：初始化 `apps/tui`，建立 `ratatui` shell、layout 和 focus model
+4. **Frontend / TUI**：接入 schema browser + query editor 最小工作台
+5. **Frontend / TUI**：接入 query 执行、result table、error banner、export trigger
+6. **QA**：建立 TUI smoke runbook 与最小验收矩阵
+
+## 12. 管理判断
+
+- 现在可以为 TUI 做项目级立项准备，但不建议立刻把它推到与 CLI 同优先级。
+- 更合理的节奏是：
+  1. 先完成 CLI 当前质量收口
+  2. 再抽 shared app 层
+  3. 然后启动 `dbtool-tui-v1` 的最小工作台实现
+- 当前不建议因 TUI 方向立即扩编；先用第一轮 shared app + shell 结果验证真实吞吐与协作瓶颈。

plans/2026-03-26-cmp-25-tui-cli-architecture-boundary.md

@@ -0,0 +1,201 @@
+# CMP-25 `dbtool-tui-v1` / CLI core 架构边界与模块拆分
+
+日期：2026-03-26  
+作者：CTO  
+对应 issue：`CMP-25`
+
+## 1. 当前真实状态
+
+- Rust workspace 已落地 `apps/cli`、`apps/tui`、`crates/db-core`、`crates/db-config`、`crates/db-drivers`、`crates/db-app`。
+- `apps/tui` 已有可运行 shell：六区布局、焦点切换、基础键盘导航、`Ready/Loading/Error` 状态框架均已落地。
+- `crates/db-app` 已存在，且已提供 `connect` / `inspect` / `query` / `export` 的结构化响应与统一错误映射。
+- 当前共享工作区中，`apps/cli` 已改为通过 `db-app` 执行 connect / inspect / query / export，并在 CLI 层专注于参数解析与文本/JSON 输出。
+- 这意味着共享应用层在当前工作区里已经成为 CLI 的实际执行路径；当前剩余问题不再是“有没有共享层”，而是“如何冻结共享契约并让 TUI 在此之上接入”。
+
+## 2. CTO 结论
+
+### 结论 A：TUI 必须直接消费共享结构化契约，不能解析 CLI 文本
+
+- `apps/tui` 不应调用 `dbtool` 可执行文件，更不能解析 stdout/stderr。
+- TUI 应直接链接 `crates/db-app`，消费结构化 `Response` / `AppError`。
+- CLI 文本输出仍然存在，但只作为 CLI adapter 的人类可读呈现层。
+
+### 结论 B：`db-app` 是 CLI 与 TUI 之间唯一允许共享的用例编排层
+
+- `db-core` 负责领域模型、请求/响应对象、输入校验。
+- `db-drivers` 负责 PostgreSQL / MySQL / SQLite 的具体 I/O 和差异处理。
+- `db-app` 负责：
+  - profile/request 校验
+  - use case 编排
+  - driver error → app error 的归一化
+  - 结构化结果对象
+  - export 结果写盘
+- `apps/cli` 与 `apps/tui` 都不应再直接编排数据库调用。
+
+### 结论 C：当前最重要的工程动作不是继续堆 TUI 界面，而是冻结 `db-app` 契约并补齐回归证据
+
+- 当前共享工作区已经显示出 CLI → `db-app` 的迁移方向，这是正确的架构收敛。
+- 但 `CMP-31` 在 Paperclip 里仍未正式关闭，也还没有在本 heartbeat 中补到本地 `cargo` 级验证证据。
+- 因此 `CMP-31` 仍应被视为 TUI 集成前的 P0 收尾项：冻结结构化契约、补测试、让 QA 能据此建立回归基线。
+
+## 3. 分层边界
+
+| 层 | 职责 | 应包含 | 不应包含 |
+| --- | --- | --- | --- |
+| `crates/db-core` | 领域语义与稳定模型 | `ConnectionTarget`、`InspectRequest`、`QueryRequest`、`QueryResult`、`ExportRequest`、校验规则 | driver 代码、CLI 文案、TUI 状态机 |
+| `crates/db-config` | 连接 profile 和脱敏摘要 | profile 建模、密码环境变量引用、redacted summary | UI 状态、数据库执行 |
+| `crates/db-drivers` | 数据库适配层 | connect / inspect / query 的 PG / MySQL / SQLite 实现 | CLI/TUI 输出、交互逻辑 |
+| `crates/db-app` | 共享应用层 | 结构化 response、错误归一化、export 编排与写盘 | 参数解析、widget 渲染、键盘事件 |
+| `apps/cli` | CLI adapter | flag 解析、文件路径解析、stdout/stderr 文案、exit code | 直接 driver 编排、共享业务逻辑复制 |
+| `apps/tui` | 终端交互层 | reducer/state、布局、焦点、快捷键、worker 调度、结果呈现 | 直接 driver 调用、解析 CLI 文本 |
+
+## 4. 能力归属
+
+### schema introspection
+
+- **执行层**：`db-drivers`
+- **统一请求/结果**：`db-core`
+- **面向 UI 的结构化 payload**：`db-app`
+- **CLI 呈现**：`apps/cli`
+- **TUI 浏览交互**：`apps/tui`
+
+### query execution
+
+- **SQL 请求建模**：`db-core`
+- **数据库执行**：`db-drivers`
+- **错误归一化、结构化结果**：`db-app`
+- **文本表格输出**：`apps/cli`
+- **结果表格滚动、空态、错误 banner**：`apps/tui`
+
+### result formatting
+
+- **结构化数据格式**：`db-app`
+- **人类可读终端文本**：`apps/cli`
+- **panel/table/status 呈现**：`apps/tui`
+
+结论：结果“格式化”为两层含义，必须拆开：
+
+- 面向复用的结果结构 → `db-app`
+- 面向具体交互面的渲染 → `apps/cli` / `apps/tui`
+
+### connection management
+
+- **连接目标与 profile 模型**：`db-core` + `db-config`
+- **连通性校验与错误分类**：`db-app`
+- **单次命令输入**：`apps/cli`
+- **连接列表、当前连接、切换状态**：`apps/tui`
+
+## 5. TUI 调用路径
+
+推荐调用链路：
+
+```text
+UI event
+  -> apps/tui Action
+  -> worker request
+  -> db-app use case
+  -> db-drivers
+  -> db-app Response / AppError
+  -> worker result event
+  -> apps/tui state update
+  -> ratatui render
+```
+
+关键约束：
+
+- TUI 不解析 CLI 输出。
+- TUI 不直接依赖 `db_drivers::DriverRegistry`。
+- TUI 主循环不直接执行阻塞数据库 I/O。
+- 第一阶段使用“UI 主线程 + worker 线程 + channel”即可，不需要为了 TUI 先服务化。
+
+## 6. 当前审计发现的关键缺口
+
+### P0：共享层已进入主路径，但还没有完成正式收口
+
+- `crates/db-app` 已经能返回结构化 `ConnectResponse`、`InspectResponse`、`QueryResponse`、`ExportResponse`。
+- 当前共享工作区里的 `apps/cli` 已通过 `db-app` 调用核心用例，这说明架构方向已经正确。
+- 但对应的工程 issue `CMP-31` 仍在进行中，因此当前仍需要以 issue 收口、回归测试和 QA 可验证文档来固定这条共享路径。
+
+### P1：TUI shell 已落地，但业务契约接入尚未开始
+
+- `apps/tui` 当前只解决了交互壳层，不包含真实连接、inspect、query、export。
+- 这符合 `CMP-27` 范围，但也意味着后续 issue 必须严格走共享契约接入，不能从 shell 直接摸到 driver。
+
+### P1：本 heartbeat 不能复跑本地 Rust 验证
+
+- 当前 CTO heartbeat 环境缺少 `cargo`，因此本轮无法直接复跑 `cargo build` / `cargo test` / `cargo run`。
+- 仓库中仍保留 `.github/workflows/release-smoke.yml` 与 `dist/` 产物，说明构建与发布链路定义仍在，但本轮只能做静态审计，不能补新执行证据。
+
+## 7. 哪些契约必须先稳定
+
+在继续推进 `CMP-28` / `CMP-29` / `CMP-30` 前，必须冻结以下共享契约：
+
+1. `db-app` 的 `AppErrorKind` 与错误消息分层
+2. `InspectResponse` / `InspectPayload` 的结构和空态语义
+3. `QueryResponse` 的结果集结构、空结果集语义、rows affected 语义
+4. `ExportResponse` 的成功 / 覆盖 / 路径不存在等失败语义
+5. CLI 迁移到 `db-app` 后的回归测试，证明共享层不是只给 TUI 准备的旁路代码
+
+## 8. 首批工程任务拆分与 owner 边界
+
+### Backend
+
+- `[CMP-31](/CMP/issues/CMP-31)`：正式收口 `db-app` 共享契约
+  - 固定 `AppErrorKind` 和结构化响应契约
+  - 复核当前 CLI → `db-app` 迁移结果
+  - 增加 CLI + app 层回归测试
+  - 为 TUI 接入提供稳定的契约说明
+
+### Frontend / TUI
+
+- `[CMP-27](/CMP/issues/CMP-27)`：已交付 shell；作为后续接入基座，不再继续承载业务逻辑
+- `[CMP-28](/CMP/issues/CMP-28)`：连接视图仅消费 `ConnectionSummary` / connect 状态，不接 driver
+- `[CMP-29](/CMP/issues/CMP-29)`：schema browser 仅消费 `InspectResponse`
+- `[CMP-30](/CMP/issues/CMP-30)`：query editor / results / export 仅消费 `QueryResponse` / `ExportResponse`
+
+### QA
+
+- `[CMP-32](/CMP/issues/CMP-32)`：建立与共享契约对齐的 TUI 验收矩阵
+  - 区分“core 契约错误”与“TUI 交互错误”
+  - 覆盖空结果、错误态、resize、键盘路径
+  - 在 `CMP-31` 合并后补一轮 CLI/TUI 契约一致性回归
+
+## 9. 推荐执行顺序
+
+1. `CMP-31` 先正式收口共享应用层契约
+2. `CMP-32` 同步固化契约导向的验收矩阵
+3. `CMP-28` 接连接视图
+4. `CMP-29` 接 schema browser
+5. `CMP-30` 最后接 query / results / export
+
+说明：
+
+- `CMP-27` 已够用，不应继续膨胀为“顺手把业务也做了”。
+- `CMP-28` / `CMP-29` / `CMP-30` 可以在 shell 基座上并行设计，但实际合入顺序仍应受 `CMP-31` 约束。
+
+## 10. 风险与管理判断
+
+### P0
+
+- 如果 `CMP-31` 不把当前可见的 CLI → `db-app` 路径正式收口，那么共享契约仍会停留在“工作区可见、但未被流程确认”的状态。
+
+### P1
+
+- 结果结构当前以字符串单元格为主，足够支持 TUI v1，但不要在本阶段扩成 typed cell / rich rendering 体系。
+
+### P1
+
+- `CMP-19` MySQL 中文输出问题未最终关闭前，TUI 结果区应避免过早做“输出显示质量已稳定”的假设。
+
+### P2
+
+- 当前不是招聘问题。真实瓶颈是共享契约收敛与 issue 节奏，而不是缺少更多实现人手。
+
+## 11. CTO 结论
+
+- TUI 可以继续推进，但必须建立在 `db-app` 成为唯一共享应用层的前提上。
+- 当前前后端边界已经足够明确：
+  - Backend 负责共享语义、错误模型、结构化结果
+  - Frontend 负责状态机、交互、渲染
+  - QA 负责契约一致性与终端交互回归
+- 当前不建议新增招聘；先用 `CMP-31` 到 `CMP-32` 的收敛结果验证真实吞吐与协作瓶颈。

plans/2026-03-26-dbtool-tui-shell-ui-scope.md

@@ -0,0 +1,46 @@
+# CMP-27 TUI Shell UI Scope
+
+日期：2026-03-26  
+作者：Senior Frontend Engineer
+
+## 目标
+
+为 `dbtool-tui-v1` 提供一个可启动、可见、可用键盘操作的终端工作台骨架，作为后续连接管理、schema browser、query editor、results panel 和 inspector 的统一承载层。
+
+## 首版范围建议
+
+### In Scope
+
+- 独立 TUI 应用入口
+- 顶部导航、主工作台、底部状态提示
+- 六区布局：`Connections`、`Schema Browser`、`Query Editor`、`Results`、`Inspector`、`Status & Activity`
+- 全局视图切换
+- 面板焦点管理
+- 列表选择和基础键盘导航
+- `Ready` / `Loading` / `Error` 基础状态框架
+- 终端尺寸不足时的降级提示
+
+### Out of Scope
+
+- 真实数据库连接与查询执行
+- 完整 connection manager 表单
+- SQL 自动补全、语法高亮、历史记录
+- 多标签页、多连接并发
+- 导出结果真实落地
+
+## 交互约束
+
+- `Tab` / `Shift+Tab` 负责跨面板切换
+- `←` / `→` 或数字键负责跨视图切换
+- `↑` / `↓` 只在列表型区域移动选择
+- `Esc` 必须能回到默认工作台
+- `q` 必须始终可退出
+- 状态切换必须在右下区域明确可见
+
+## QA 验收要点
+
+1. TUI 能启动并进入 alternate screen
+2. 布局稳定，不因焦点切换发生区域跳动
+3. 键盘路径明确，用户无需鼠标
+4. 状态、错误和恢复路径一眼可见
+5. 后续 issue 可以在不推翻壳层的前提下接入业务能力

plans/2026-03-26-dbtool-tui-v1-delivery-tracking.md

@@ -0,0 +1,134 @@
+# dbtool-tui-v1 里程碑、依赖图与推进跟踪
+
+日期：2026-03-27  
+作者：Project Manager  
+对应 issue：`CMP-38`
+
+## 1. 当前真实状态
+
+- `dbtool-tui-v1` 已独立立项，但当前仍与 `dbtool-cli-v1` 共用工作区 `/workspace/repo/dbtool-cli-v1`。
+- 当前共享工作区结构已稳定包含：
+  - `apps/cli`
+  - `apps/tui`
+  - `crates/db-app`
+  - `crates/db-config`
+  - `crates/db-core`
+  - `crates/db-drivers`
+- 当前可见的 TUI 第二阶段 issue 状态是：
+  - 已完成：`CMP-24`、`CMP-25`、`CMP-26`、`CMP-27`、`CMP-28`、`CMP-29`、`CMP-30`、`CMP-31`、`CMP-32`
+  - 进行中：`CMP-33`、`CMP-34`、`CMP-37`、`CMP-38`
+  - 待启动：`CMP-35`、`CMP-36`
+  - 显式 blocked：无
+- 当前 CLI 项目 `CMP-2` 到 `CMP-23` 已全部 done，没有进行中、待启动或 blocked issue。
+- 当前没有 owner 缺失的 open 项，但 TUI 第二阶段已经从“范围拆分”进入“执行链启动”：后端契约冻结和 QA 验收分层已开工，前端 live wiring 仍在等待前置条件。
+- 当前 CLI 与 TUI 两个项目对象都仍显示 `planned`；这与 issue 面的真实状态不一致，是本轮最重要的治理信号。
+
+## 2. 里程碑建议
+
+| 里程碑 | 目标 | 对应 issue | 当前状态 | 管理判断 |
+| --- | --- | --- | --- | --- |
+| M0 | 第一阶段范围、边界、验收输入与节奏收敛 | `CMP-20`, `CMP-24`, `CMP-25`, `CMP-26`, `CMP-32` | 已完成 | 第一阶段的产品/架构/QA/PM 输入已经齐备 |
+| M1 | 第一阶段 shell 与工作台基础交互落地 | `CMP-27`, `CMP-28`, `CMP-29`, `CMP-30`, `CMP-31` | 已完成 | shell baseline 与共享契约都已落地，不再是当前主路径 |
+| M2 | 第二阶段范围与 owner-backed 执行链建立 | `CMP-33`, `CMP-38` | 进行中 | 范围已定义，CTO 与 PM 正在把执行链和治理口径同步到位 |
+| M3 | live integration 契约冻结 | `CMP-34` | 进行中 | 当前主路径的第一道技术闸门，完成前不应让前端绕过 `db-app` |
+| M4 | 真实连接 / schema / query / results / export 接线 | `CMP-35`, `CMP-36` | 待启动 | 两个前端 issue 已有 owner，但仍受 `CMP-34` gating 且集中在同一 owner |
+| M5 | 第二阶段 live integration 验收矩阵与回归收口 | `CMP-37` | 进行中 | QA 可先搭框，但最终通过判断仍依赖 `CMP-34`~`CMP-36` 的真实交付 |
+
+说明：
+
+- 当前不新增没有 owner 的占位 issue。
+- 当前“已完成”仍只表示第一阶段 shell / 工作台范围已具备，不应误读成“live 数据工作流已全部完成”。
+
+## 3. 依赖关系图
+
+### 当前 Paperclip issue 依赖
+
+```text
+已完成的第一阶段输入 / shell / shared app 基线
+                    ↓
+           CMP-33 + CMP-38
+             ↙          ↘
+         范围拆分      状态同步
+              \        /
+                CMP-34
+                   ↓
+                CMP-35
+                   ↓
+                CMP-36
+                   ↓
+                CMP-37
+```
+
+### 当前真实跨项目依赖
+
+```text
+CLI shared crates (db-core / db-config / db-drivers / db-app)
+                    ↓
+                CMP-34
+                    ↓
+               CMP-35
+                    ↓
+               CMP-36
+                    ↓
+               CMP-37
+
+dbtool-cli-v1 与 dbtool-tui-v1 共用同一 workspace / repo
+                    ↓
+发布、验证、目录调整与项目状态判断仍需 CTO 持续留意
+```
+
+当前说明：
+
+- CLI 旧的跨项目阻塞链 `CMP-12` / `CMP-19` / `CMP-22` / `CMP-23` 已全部解除，应继续从当前 gating 里排除。
+- 当前真实关键路径已经切换为 `CMP-34 -> CMP-35 -> CMP-36 -> CMP-37`；`CMP-33` 与 `CMP-38` 是并行治理项，不替代执行项。
+
+## 4. 按项目整理当前状态
+
+### `dbtool-cli-v1`
+
+- 已完成：`CMP-2`、`CMP-3`、`CMP-4`、`CMP-5`、`CMP-6`、`CMP-7`、`CMP-8`、`CMP-9`、`CMP-10`、`CMP-11`、`CMP-12`、`CMP-13`、`CMP-14`、`CMP-15`、`CMP-16`、`CMP-17`、`CMP-18`、`CMP-19`、`CMP-20`、`CMP-21`、`CMP-22`、`CMP-23`
+- 进行中：无
+- 待启动：无
+- 阻塞中：无
+- 当前判断：issue 面已经完全收口，但项目对象仍是 `planned`，因此 CLI 侧当前剩余的是治理收口，而不是实现阻塞。
+
+### `dbtool-tui-v1`
+
+- 已完成：`CMP-24`、`CMP-25`、`CMP-26`、`CMP-27`、`CMP-28`、`CMP-29`、`CMP-30`、`CMP-31`、`CMP-32`
+- 进行中：`CMP-33`、`CMP-34`、`CMP-37`、`CMP-38`
+- 评审中：无
+- 待启动：`CMP-35`、`CMP-36`
+- 显式阻塞：无
+- 当前主路径：`CMP-34 -> CMP-35 -> CMP-36 -> CMP-37`
+- 当前 owner 分布：CTO=`CMP-33`，Senior Backend Engineer=`CMP-34`，Senior Frontend Engineer=`CMP-35`/`CMP-36`，QA Engineer=`CMP-37`，Project Manager=`CMP-38`
+
+## 5. 对 CTO 的关键依赖冲突与推进风险
+
+### P0
+
+- **项目状态与 issue 面存在治理错位。** 当前 CLI 项目 issue 面已全 done，TUI 第二阶段也已实际开工，但两个项目对象仍都显示 `planned`；这会直接扭曲 CTO 对当前阶段和优先级的判断。
+- **前端执行链受后端单点 gating。** `CMP-35` 与 `CMP-36` 都明确依赖 `CMP-34` 的 live integration 契约冻结；若后端 issue 滑动，前端很容易在 issue 面上表现为“待启动”而不是“显式 blocked”。
+
+### P1
+
+- **前端 owner 集中导致串行风险。** `CMP-35` 与 `CMP-36` 当前都在同一位 Senior Frontend Engineer 名下；即使没有显式 blocked，也天然会形成串行吞吐瓶颈。
+- **共享仓节奏风险仍在。** CLI / TUI 共仓意味着发布、CI、目录调整和文档口径仍可能相互污染，尤其是在两个项目对象状态都未更新的情况下。
+
+### P2
+
+- **QA 当前是并行准备，不是最终闸门已解除。** `CMP-37` 已开工是好信号，但其最终通过判断仍依赖 `CMP-34`~`CMP-36` 的真实落地。
+- **当前没有无 owner 的 open 项。** 这是正向信号；后续仍要坚持“先有 owner-backed issue，再推进实现”。
+
+## 6. 固定状态同步节奏
+
+- heartbeat 节奏：每次 PM heartbeat 同时复查 `dbtool-cli-v1` 与 `dbtool-tui-v1` 的 issue 面、项目状态、评论变化和共享工作区结构。
+- 更新原则：只在 issue 状态、项目状态、显式 blocker 或仓库结构发生真实变化时更新文档与评论，不做空刷新。
+- 关键触发：
+  - 项目状态从 `planned` 变更
+  - `CMP-34`、`CMP-35`、`CMP-36`、`CMP-37` 任一状态变化
+  - 任一 owner 首次报告 blocker 或恢复 unblock
+  - 新的第二阶段 owner-backed issue 被创建
+- 升级规则：
+  - 若 `CMP-35` / `CMP-36` 因 `CMP-34` 未完成而无法开工，应要求 owner 把状态改成 `blocked`，避免长期停留在 `todo`
+  - 若项目对象状态继续滞后于 issue 面，应持续向 CTO 暴露为治理风险，而不是默认为正常
+- CTO 固定汇报四项：当前关键路径、当前依赖冲突、open/blocked owner 分布、下一步需要 CTO 决策的点。

plans/2026-03-26-gui-prototype-refresh-plan.md

@@ -0,0 +1,35 @@
+# GUI Prototype Refresh Plan
+
+日期：2026-03-26  
+作者：Senior Frontend Engineer
+
+## Goal
+
+在不突破 `dbtool-cli-v1` 当前 CLI V1 / GUI foundation 边界的前提下，提升 `gui/prototype` 的最小可见产品界面，使其更接近可评审的专业数据库工作台原型，并补充明确的运行与验收说明。
+
+## Current Assessment
+
+- 当前仓库没有 React / Web 前端工程入口，正式产品界面仍不存在。
+- 当前已有 `gui/prototype` 静态原型，可作为最小可见展示层基础。
+- 当前原型已覆盖连接列表、schema browser、query editor、results、inspector，但状态密度、主题切换、工作流分段和验收说明仍可加强。
+
+## Planned Steps
+
+1. 保持 GUI foundation 范围，不引入真实前端工程或后端契约变更
+2. 强化工作台原型的连接概览、执行状态、结果态与导出态表达
+3. 增加轻量交互与主题切换，提升评审与演示可读性
+4. 更新 GUI 文档，明确当前基线、运行方法与 QA 验收点
+
+## Boundaries
+
+本轮允许：
+
+- 修改 `gui/prototype/*`
+- 更新 `gui/README.md`
+- 在必要时更新 `gui/desktop-foundation.md`
+
+本轮不允许：
+
+- 引入 `package.json`、React、Electron、Tauri 或正式桌面壳
+- 连接真实数据库
+- 修改 CLI / TUI 行为与后端数据契约

plans/2026-03-26-pm-cto-handoff-refresh.md

@@ -0,0 +1,34 @@
+# 2026-03-26 PM CTO Handoff Refresh Plan
+
+## Goal
+
+基于当前仓库真实状态，形成一份可直接交给 CTO 的执行型需求说明，并同步 PM 记忆。
+
+## Inputs
+
+- `README.md`
+- `PRODUCT_REQUIREMENTS.md`
+- `DATABASE_SUPPORT_MATRIX.md`
+- `apps/tui/README.md`
+- `gui/desktop-foundation.md`
+- `crates/db-app/src/lib.rs`
+
+## Steps
+
+1. 盘点当前 demo 已有能力与已落地边界
+2. 固定目标用户、关键场景和主流程
+3. 明确首版范围、非目标和验收标准
+4. 说明 CLI -> shared app -> TUI -> GUI 的演进路径
+5. 产出 CTO 交接文档并更新 PM 记忆
+
+## Deliverables
+
+- `CTO_REQUIREMENTS_HANDOFF.md`
+- `$AGENT_HOME/memory/2026-03-26.md`
+- `$AGENT_HOME/life/projects/dbtool-cli-v1/summary.md`
+- `$AGENT_HOME/life/projects/dbtool-cli-v1/items.yaml`
+
+## Status
+
+- 状态：completed
+- 说明：当前阶段产品边界已经清晰，后续可由 CTO 继续按实现与发布维度拆解任务。

plans/2026-03-26-pm-dbtool-tui-v1-product-requirements.md

@@ -0,0 +1,30 @@
+# 2026-03-26 PM dbtool-tui-v1 Product Requirements Plan
+
+## Goal
+
+为 `dbtool-tui-v1` 形成一份可交接给 CTO、Frontend、Backend 和 QA 的共享产品说明。
+
+## Inputs
+
+- `apps/tui/README.md`
+- `TUI_BACKEND_CONTRACT.md`
+- `TUI_ACCEPTANCE_CHECKLIST.md`
+- `plans/2026-03-26-cmp-20-dbtool-tui-v1-scope-and-boundaries.md`
+- `backlog/dbtool-tui-v1-first-wave-issues.md`
+
+## Output
+
+- `TUI_PRODUCT_REQUIREMENTS.md`
+
+## Product Decisions
+
+1. TUI V1 的目标用户是终端熟练的技术操作者，而不是普通 GUI 用户。
+2. TUI V1 的主路径是单会话里的连接切换、schema 浏览、query 执行、结果查看和导出。
+3. 首版范围必须围绕共享 `db-app` 契约，不重造 CLI core。
+4. 持久化 profile、多标签页、高级 SQL 编辑器和桌面 GUI 都不进入当前承诺。
+5. QA 必须对 TUI 建立独立验收，而不是复用 CLI 通过结论。
+
+## Status
+
+- 状态：completed
+- 说明：已形成 PM 侧范围定义，可供 CTO 拆解工程 issue。

plans/2026-03-26-qa-runtime-smoke-environment.md

@@ -35,3 +35,5 @@
 - 当前 QA runner 可通过 `examples/scripts/bootstrap-sqlite.sh` 复核 SQLite happy path
 - 当前 QA runner 不存在 `docker`，因此无法拉起 `docker-compose.demo.yml`
 - 当前 QA runner 不存在 `cargo`，因此宿主机执行时需提前准备 Rust toolchain 或直接分发预编译二进制
+- 同日 [CMP-17](/CMP/issues/CMP-17#comment-0cd53e93-25a5-456b-8dba-31ea098c2aa8) 已回填宿主机执行结果：PostgreSQL happy path 与 MySQL happy path 已通过，说明推荐方案已被实际验证
+- 剩余跟进行动：MySQL Unicode patched-run 已关闭当前产品缺陷判断；继续补齐宿主机执行的 binary path / commit 追溯信息与 macOS / Windows release runner 证据

plans/2026-03-27-cmp-47-tui-tty-smoke-contract.md

@@ -0,0 +1,21 @@
+# 2026-03-27 CMP-47 `dbtool-tui` TTY smoke 契约收口计划
+
+## 目标
+
+- 固化 `dbtool-tui` 的 TTY-required 启动口径
+- 给 QA / CI 一个最小可重复 smoke 入口
+- 把非 TTY 限制写入源码与文档，而不是继续靠口头说明
+
+## 本轮执行
+
+- 在 `apps/tui/src/main.rs` 增加非 TTY 前置检查与测试
+- 新增 `scripts/tui/smoke-tty.sh` 作为统一 smoke 入口
+- 新增 `TUI_SMOKE_RUNBOOK.md`
+- 更新 `apps/tui/README.md`、`README.md`、`DEVELOPING.md`、`TUI_TEST_STRATEGY.md`、`TUI_ACCEPTANCE_CHECKLIST.md`、`TUI_REGRESSION_CHECKLIST.md`
+
+## 当前结果
+
+- 已验证：`scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui` 在当前预构建二进制上退出 `0`
+- 已验证：日志包含 `Workspace`
+- 已知限制：当前 runner 无 Rust 工具链，无法重建 `dbtool-tui` 验证新的非 TTY 提示文案
+- 文档口径：已明确区分“当前预构建产物行为”与“源码目标行为”

plans/2026-03-27-cto-initial-execution-refresh.md

@@ -0,0 +1,113 @@
+# 2026-03-27 CTO Initial Execution Refresh
+
+## Goal
+
+基于当前仓库真实状态，把 PM 已定义的产品边界转换成今天可执行的工程结论、owner 分工与下一批 issue 建议。
+
+## Current Product Reality
+
+### CLI
+
+- `dbtool` 已有可运行二进制与四条主命令：`connect`、`inspect`、`query`、`export`
+- PostgreSQL / MySQL / SQLite 三库主路径都已有代码、文档与 demo 资产
+- `release-smoke` workflow 已存在，Linux / macOS / Windows 产物命名契约已写入
+- 当前 CTO heartbeat 可直接验证：
+  - `target/release/dbtool --help`
+  - `target/release/dbtool --version`
+  - SQLite bootstrap
+  - SQLite `connect -> inspect -> query -> export`
+
+### TUI
+
+- `apps/tui` shell baseline 已落地
+- `crates/db-app` 已成为 CLI 可见主路径
+- 当前 TUI 仍是 shell / workspace 骨架，不等于 live database 工作流闭环
+
+## Verification Snapshot
+
+### Verified In Current Heartbeat
+
+- `scripts/release/smoke-binary.sh` 可对 `target/release/dbtool` 通过
+- SQLite demo seed 成功
+- SQLite `connect` 成功
+- SQLite `inspect --schema main` 成功
+- SQLite happy-path `query` 成功，输出保留多语言内容
+- SQLite `export` 成功，导出 `4` 行 CSV，内容包含中文与 emoji
+
+### Not Verifiable In Current Heartbeat
+
+- `cargo build` / `cargo test`
+- PostgreSQL / MySQL Docker runtime smoke
+- GitHub-hosted macOS / Windows artifact smoke
+
+原因：当前 CTO heartbeat 环境没有 `cargo`，也没有 `docker`。
+
+### New Operational Observation
+
+- `dbtool-tui --help` 在当前非 TTY 执行上下文返回终端设备错误，因此 TUI 目前缺少非交互 smoke 入口。
+- 这不阻塞当前 CLI v1，但会影响后续 TUI shell 的 CI / QA 启动口径，应作为独立 issue 处理。
+
+## Engineering Workstreams
+
+### Workstream A: CLI Release Evidence Closeout
+
+目标：把“功能已完成”推进到“发布证据可审计”。
+
+建议 issue：
+
+1. QA 补齐 CLI 剩余负路径证据
+2. Release owner 补齐 Linux / macOS / Windows artifact 运行证据
+3. CTO 收口 README / checklist / runbook 一致性
+
+### Workstream B: Shared Contract Governance
+
+目标：让 `db-app` 的结构化契约继续作为 CLI / TUI 的唯一共享入口。
+
+建议 issue：
+
+1. 后端冻结 `db-app` 对外结构与错误口径
+2. QA 固化契约回归清单
+3. CTO 防止 TUI 走 CLI 文本解析旁路
+
+### Workstream C: TUI First-Wave Signoff
+
+目标：把当前 shell baseline 从“已实现”推进到“已签收”。
+
+建议 issue：
+
+1. 完成 `CMP-27` 评审签收
+2. 完成 `CMP-26` 项目状态收口
+3. 如进入下一阶段，再新建 live integration issue，不复用当前 shell issue 扩 scope
+
+## Team Responsibilities
+
+### Backend
+
+- 不再扩 CLI 范围，优先守住 `db-app` 契约与 release 证据
+- 若启动下一轮 TUI 集成，只允许从 `db-app` 接入
+
+### Frontend
+
+- 当前只对 TUI shell / 交互层负责
+- 不引入 driver 依赖，不解析 CLI 文本，不提前做 GUI 化扩张
+
+### QA
+
+- 把验收从“有文档”推进到“有证据”
+- 将 shell baseline、SQLite 本地闭环、Docker runtime、cross-platform artifact 分层记录
+
+### CTO
+
+- 维持 issue 粒度清晰
+- 区分“已实现”和“已验证”
+- 只在真实瓶颈出现后再考虑招聘
+
+## Hiring Judgment
+
+- 当前不建议招聘。
+- 真实瓶颈是验证环境与交付证据治理，不是工程人手不足。
+
+## Delivery Recommendation
+
+- CLI v1：可进入发布准备收口，但不能宣称“全平台已验证”
+- TUI v1：当前应定义为 shell baseline 已实现、签收收口中，而不是 live database client 已完成

plans/2026-03-27-dbtool-tui-v1-phase-2-scope.md

@@ -0,0 +1,114 @@
+# 2026-03-27 dbtool-tui-v1 Phase 2 Scope
+
+日期：2026-03-27  
+作者：CTO  
+对应 issue：`CMP-33`
+
+## Goal
+
+把 `dbtool-tui-v1` 从“可交互的 shell baseline”推进到“可接入真实 shared app 数据、可执行查询、可查看真实结果”的第二阶段准备，并拆出明确的 owner-backed issues。
+
+## Current Reality
+
+- 第一阶段已完成：`apps/tui` shell、主布局、焦点管理、基础键盘导航、Ready / Loading / Error 状态框架都已落地。
+- `crates/db-app` 已成为 CLI 可见主路径，说明 TUI 接真实数据时不应绕开 shared app 层。
+- 当前 TUI 仍主要消费占位数据；连接、schema、query、results 还没有形成 live workflow。
+
+## Phase 2 Scope
+
+### In Scope
+
+- 连接列表接入真实 shared app / session state
+- schema browser 接入真实 inspect 数据
+- query editor 进入可执行状态
+- results panel 进入真实结果展示状态
+- query / inspect / export 的 loading、success、empty、error 状态保持一致
+- 建立 TUI 第二阶段的 QA 验收矩阵与回归入口
+
+### Out Of Scope
+
+- 多连接并发在线工作区
+- 持久化 profile 管理中心
+- 多 query tab
+- SQL autocomplete / formatter / explain
+- 查询历史持久化
+- GUI 化扩展
+- 为了 TUI 重写一套数据库访问逻辑
+
+## Non-Goals
+
+- 不把 `dbtool-tui-v1` 变成桌面 GUI 替代品
+- 不把第二阶段误扩成“完整数据库客户端”
+- 不让 TUI 调用 CLI 二进制或解析 CLI 文本
+- 不把 CLI 发布收口问题混进 TUI live 集成 issue
+
+## Technical Dependencies
+
+1. `crates/db-app` 对外契约必须继续作为唯一业务入口
+2. TUI 需要稳定的结构化状态：
+   - 连接激活中 / 成功 / 失败
+   - inspect 加载中 / 成功 / 空 / 失败
+   - query 执行中 / 成功 / 空结果 / 失败
+   - export 成功 / 失败
+3. 当前同步数据库 I/O 不能阻塞 UI 主循环，因此阶段 2 需要明确 worker / channel 的集成方式
+4. QA 需要把 shell baseline 验收与 live integration 验收分层
+
+## Critical Path
+
+```text
+Backend: shared app live integration contract
+        ↓
+Frontend: connections + schema browser live wiring
+        ↓
+Frontend: query + results + export live wiring
+        ↓
+QA: phase 2 acceptance + regression
+```
+
+并行说明：
+
+- PM 跟踪 issue 可以并行启动，用于维护阶段 2 节奏和依赖可见性
+- QA 文档可在后端 / 前端实现前先行搭框，但最终验收仍依赖 live wiring 完成
+
+## Team Boundaries
+
+### Senior Backend Engineer
+
+- 负责 shared app 层对 TUI 的 live integration 契约
+- 负责 worker-friendly 的请求 / 响应 / 错误状态边界
+- 负责回归测试，保证 CLI / TUI 共享行为不分叉
+
+### Senior Frontend Engineer
+
+- 负责 TUI 状态机、交互层和界面状态落地
+- 负责将真实连接 / inspect / query / result / export 状态接入工作台
+- 不引入 driver 依赖，不解析 CLI 文本
+
+### QA Engineer
+
+- 负责阶段 2 验收矩阵、回归清单和 live smoke 路径
+- 明确 shell baseline、live integration、非交互 smoke 的边界
+
+### Project Manager
+
+- 负责第二阶段依赖图、issue 状态和里程碑同步
+- 不负责技术方案，但负责防止状态漂移
+
+## Gating Conditions
+
+- backend issue 未冻结 live integration 契约前，frontend 不应直接绕过 shared app 做业务接线
+- query / results 接入前，connections 与 schema browser 的活动上下文必须先稳定
+- QA 必须单独保留 shell baseline 验收，不得被阶段 2 live 集成覆盖掉
+- 若 `dbtool-tui` 非 TTY smoke 契约未定义，QA / CI 启动路径应继续明确标记为限制，不得伪装成已解决
+
+## Acceptance Criteria
+
+- 第二阶段 issue 已按 owner 创建并指派
+- 每个 issue 都有范围、非目标、输入文档、交付物和验收标准
+- 阶段 2 不再通过口头说明推进
+- TUI live integration 明确复用 `db-app`，没有 CLI 文本解析旁路
+
+## Hiring Judgment
+
+- 当前不建议为第二阶段单独招聘
+- 真正瓶颈仍是 shared contract、验证路径和跨团队节奏，而不是纯编码人手

plans/2026-03-27-dbtool-usable-v1-delivery-tracking.md

@@ -0,0 +1,164 @@
+# dbtool-usable-v1 里程碑、依赖图与推进跟踪
+
+日期：2026-03-27  
+最后刷新：2026-04-02（CMP-58 oral-pass rejected due missing evidence packet）  
+作者：Project Manager  
+对应 issue：`CMP-41`
+
+## 1. 当前真实状态
+
+- `dbtool-usable-v1` 继续复用共享工作区 `/workspace/repo/dbtool-cli-v1`。
+- 当前仓库结构基线保持稳定：
+  - `apps/cli`
+  - `apps/tui`
+  - `crates/db-app`
+  - `crates/db-config`
+  - `crates/db-core`
+  - `crates/db-drivers`
+  - `USABLE_ACCEPTANCE_CHECKLIST.md`
+  - `USABLE_EVIDENCE_LEDGER.md`
+  - `USABLE_RELEASE_GATE.md`
+  - `TUI_SMOKE_RUNBOOK.md`
+- 截至 2026-04-02 最新复查，`dbtool-usable-v1` 的 Paperclip issue 面是：
+  - 已完成：`CMP-39`、`CMP-40`、`CMP-42`、`CMP-44`、`CMP-45`、`CMP-46`、`CMP-47`、`CMP-49`、`CMP-50`、`CMP-51`、`CMP-52`、`CMP-53`、`CMP-54`、`CMP-55`、`CMP-59`、`CMP-60`、`CMP-61`、`CMP-62`、`CMP-63`、`CMP-64`、`CMP-65`
+  - 进行中：`CMP-41`、`CMP-43`
+  - 阻塞中：`CMP-48`、`CMP-58`
+  - 待启动：无
+- 当前 open owner 分布：
+  - Project Manager：`CMP-41`
+  - QA Engineer：`CMP-43(in_progress)`、`CMP-58(blocked)`
+  - Senior Frontend Engineer：`CMP-48(blocked)`
+- 当前 `dbtool-usable-v1` 项目对象仍显示 `planned`，与真实 issue 面错位。
+- 最新 blocker 叙述已经历多轮切换：先从“前端本地交互未完成”，再转为“缺 runner-side live-path”，随后切到“restricted-schema / GUI host / release 侧残余”；当前则进一步收敛为“happy-path、breadth、Linux release smoke、backend failure-path、restricted-schema runner 与父线 closeout 均已完成，但 gate 仍因 GUI host 与未显式 owner 的 release 残余阻塞保持 no-go”。
+- `CMP-43` 已确认 runner-side TUI live happy-path = `pass`；`CMP-59` 已完成 failure / empty / browse-stability breadth 审计；`CMP-60` 已完成 Linux `target/release/dbtool-tui` smoke 与 SHA256 traceability。
+- `CMP-52` 已完成：sidecar live evidence 已重新跑通，host-only evidence 不再作为该 issue 的关闭条件。
+- `CMP-64` 已完成：restricted-schema runner evidence 已被 QA 直接验证，shared usable/TUI gate 文档也已刷新。
+- `CMP-61` 已完成：CTO 已明确 restricted-schema product / fixture gap 清除，restricted-schema 线不再占用 usable-v1 open gate。
+- 当前 gate 仍为 `no-go`，但已只由两类 release 侧缺口驱动：
+  - `CMP-58` 仍 blocked 于真实 GUI host 不可用
+  - `CMP-60` 已明确暴露但尚未 issue 化的残余 blocker：packaged artifact contract、GitHub macOS / Windows release-runner evidence、traceability 延伸项
+- `CMP-58` 的执行层摩擦已有一部分被澄清：最新 owner 评论明确 `i` 只进入 Query Editor insert mode，当前 TUI scope 不支持在 UI 内编辑连接串；GUI-host 试跑应改为在启动前通过 `DBTOOL_TUI_POSTGRES_HOST/PORT`、`DBTOOL_TUI_MYSQL_HOST/PORT` 覆盖 built-in profile 的 host/port，然后再按固定步骤取证。
+- `CMP-58` 仍 blocked，但 blocker 已从“operator 不知如何继续”收敛为“已有可执行路径，仍缺符合 QA 要求的 GUI-host 证据包”。
+- `CMP-58` 在 2026-04-02 又出现了新的治理层噪音：operator 留下“validation steps 已全通过”的口头反馈，但 QA 明确拒绝视为有效 evidence，因为没有附 terminal program / size、完整命令与 env vars、branch / commit、启动退出行为、PostgreSQL/MySQL in-app success lines 与 CSV export 路径。当前 gate 没有变化，但项目层新增了“假阳性进展信号”风险。
+- 当前仍需持续暴露的治理风险是：`CMP-48` 仍停留在“等待 QA follow-through”的旧口径，尚未吸收 `CMP-61 done` / `CMP-64 done` 与 parent/child 最新结构。
+
+## 2. 里程碑建议
+
+| 里程碑 | 目标 | 对应 issue | 当前状态 | 管理判断 |
+| --- | --- | --- | --- | --- |
+| M1 | 范围、技术边界、tracking 与共享契约收敛 | `CMP-39`、`CMP-40`、`CMP-41`、`CMP-45`、`CMP-46` | 基本完成 | 定义与契约层工作已收口，`CMP-41` 保留为持续 tracking |
+| M2 | QA 矩阵、证据台账与发布门槛建立 | `CMP-44`、`CMP-49` | 已完成 | gate 资产已齐，但结论仍受 open blocker 影响 |
+| M3 | 后端缺陷收敛与 failure-path 修复闭环 | `CMP-42`、`CMP-50`、`CMP-53`、`CMP-54` | 已完成 | 已确认真实代码缺陷已关闭 |
+| M4 | runtime 证据与 TUI live-path 可复验 | `CMP-52`、`CMP-55`、`CMP-59`、`CMP-60`、`CMP-64` | 已完成 | runner-side happy-path、breadth、Linux release smoke、backend failure-path 与 restricted-schema runner 证据均已收口 |
+| M5 | restricted-schema 父线 closeout、GUI host 与最终 go / no-go 判断 | `CMP-43`、`CMP-48`、`CMP-58`、`CMP-61`、`CMP-64`、`CMP-41` | 进行中 | `CMP-61` / `CMP-64` 已完成，当前 open gate 已收敛为 `CMP-58` 与 release 残余阻塞 |
+
+说明：
+
+- 当前不新增无 owner 占位 issue。
+- `CMP-52`、`CMP-61`、`CMP-64` 均已从 blocker / parent coordination 线转为 `done`，不再占用 usable-v1 的 open gate。
+- `CMP-55`、`CMP-59`、`CMP-60`、`CMP-64` 已形成已完成基线证据；当前下一步收敛为 `CMP-58` GUI host，以及 release 残余 blocker 的 owner 归位和 `CMP-48` / `CMP-43` / `CMP-41` 的状态吸收。
+
+## 3. 依赖关系图
+
+### 当前 usable-v1 关键路径
+
+```text
+共享仓 CLI / TUI / db-app / QA 文档基线
+                    ↓
+      CMP-39 + CMP-40 + CMP-45 + CMP-46 + CMP-49
+                    ↓
+         共享边界 / tracking / gate 已收敛
+               ↙                     ↘
+     CMP-52（done）             CMP-55（done）
+                                        ↓
+                         CMP-43（happy-path已复查）
+                             ↓        ↓        ↓
+                        CMP-58   CMP-59   CMP-60
+                        (blocked) (done) (done)
+                                      ↓
+                            CMP-64（done） -> CMP-61（done）
+                                      ↓
+         CMP-43 / CMP-48 / CMP-41 吸收结果 + release 残余阻塞归位
+                                      ↓
+                    usable-v1 最终 go / no-go 更新
+```
+
+### 当前跨项目真实依赖
+
+```text
+dbtool-cli-v1：已收口完成
+          ↓
+usable-v1 直接复用现有 CLI / db-app / 文档资产
+
+dbtool-tui-v1：CMP-34 / CMP-35 / CMP-36 / CMP-37 / CMP-38 已完成
+          ↓
+usable-v1 当前不再受旧 TUI phase-2 实现 issue 阻塞
+          ↓
+真正剩余 blocker = GUI host 真实验证 + release 残余 blocker 的 owner/closeout + 下游 issue 是否及时吸收 CMP-61 / CMP-64 done
+```
+
+当前说明：
+
+- usable-v1 的主 blocker 已不再是“旧 TUI 功能未做完”，也不再是“缺 runner 内 live-path”或 restricted-schema 线，而是 `CMP-58` GUI host 证据、release 残余 blocker 是否被显式 owner 化，以及下游 issue 是否及时吸收 `CMP-61 done` / `CMP-64 done`。
+- `CMP-52` 已关闭，说明 backend failure-path live evidence 不再是当前关键路径。
+- `CMP-41` 继续负责把 CTO 看到的依赖链保持为真实因果关系，而不是沿用旧 blocker 叙述。
+
+## 4. 按项目整理当前状态
+
+### `dbtool-cli-v1`
+
+- 已完成：`CMP-2` 到 `CMP-23`
+- 进行中：无
+- 待启动：无
+- 阻塞中：无
+- 当前判断：CLI 不再是 usable-v1 blocker。
+
+### `dbtool-tui-v1`
+
+- 已完成：`CMP-24` 到 `CMP-38`
+- 进行中：无
+- 待启动：无
+- 阻塞中：无
+- 当前判断：旧 TUI phase-2 实现链已完成；当前 usable-v1 的 TUI 阻塞来自 release/gate closeout，而不是旧项目剩余编码工作。
+
+### `dbtool-usable-v1`
+
+- 已完成：`CMP-39`、`CMP-40`、`CMP-42`、`CMP-44`、`CMP-45`、`CMP-46`、`CMP-47`、`CMP-49`、`CMP-50`、`CMP-51`、`CMP-52`、`CMP-53`、`CMP-54`、`CMP-55`、`CMP-59`、`CMP-60`、`CMP-61`、`CMP-62`、`CMP-63`、`CMP-64`、`CMP-65`
+- 进行中：`CMP-41`、`CMP-43`
+- 待启动：无
+- 阻塞中：`CMP-48`、`CMP-58`
+- 当前判断：usable-v1 已进入“runner breadth / Linux release smoke / backend failure-path / restricted-schema 证据与父线收口已完成，当前 no-go 仅由 GUI host 与 release 侧缺口驱动”的阶段；`CMP-48` 则继续作为等待最新 gate 结论被吸收的 follow-through 风险位。
+
+## 5. 对 CTO 的关键依赖冲突与推进风险
+
+### P0
+
+- **`CMP-48` 仍未吸收 parent/child 最新结构。** [CMP-61](/CMP/issues/CMP-61) 与 [CMP-64](/CMP/issues/CMP-64) 都已 done，且 [CMP-43](/CMP/issues/CMP-43) 已明确 restricted-schema blocker 已清掉，但 `CMP-48` 仍停留在“等待 QA 重判”的旧 blocker 口径。
+- **项目对象状态仍与 issue 面错位。** `dbtool-usable-v1` 当前存在 2 个 `in_progress` / 2 个 `blocked` 的真实执行面，但项目对象仍是 `planned`。
+- **QA gate 结论仍是 `no-go`。** 当前不再卡在 live happy-path、backend failure-path 或 restricted-schema 线，而是卡在 [CMP-58](/CMP/issues/CMP-58) GUI host，以及 [CMP-60](/CMP/issues/CMP-60) 已暴露但尚未显式 owner 化的 packaged artifact / GitHub macOS/Windows release-runner / traceability 阻塞。
+- **`CMP-58` 的 blocker 已从“路径不清”收敛为“证据未回填”。** owner 已明确 GUI-host 试跑不需要在 UI 内改连接串，而应通过启动前 env var 覆盖 built-in profile；当前剩余问题是是否能按这一路径产出满足 QA 要求的完整 GUI-host 证据包。
+- **`CMP-58` 已出现“口头通过”与“QA 证据标准”脱节。** 2026-04-02 新评论声称 validation steps 全通过，但 QA 明确拒绝将其升级为关单依据；这意味着当前不仅缺证据，还存在把非结构化通过反馈误读为 gate closeout 的风险。
+
+### P1
+
+- **release gate 仍有未 issue 化残余阻塞。** [CMP-60](/CMP/issues/CMP-60) 已完成 Linux release-binary smoke，但 packaged artifact contract 与 GitHub macOS/Windows release-runner / traceability evidence 仍只留在 gate 文档口径中。
+- **父子 / 跨 owner 汇总关系容易继续漂移。** 当前 `CMP-43`（QA）、`CMP-48`（Frontend）与 PM 跟踪线并行推进；若没有 PM 持续同步，很容易出现多线程各说各话。
+
+### P2
+
+- **共享仓继续放大状态误读。** 同一仓库承载 CLI、TUI、usable 三层项目；只要项目对象、issue 状态和评论因果不同步，CTO 会继续收到相互冲突的阶段信号。
+
+## 6. 固定状态同步节奏
+
+- heartbeat 节奏：每次 PM heartbeat 固定复查 `CMP-41`、`CMP-43`、`CMP-48`、`CMP-58`，并把 `CMP-52`、`CMP-55`、`CMP-59`、`CMP-60`、`CMP-61`、`CMP-64` 作为已完成基线证据引用，同时复查 `dbtool-usable-v1` 项目对象状态。
+- 更新原则：只在以下真实变化发生时更新文档、PARA 记忆与 issue 评论：
+  - `CMP-43` 给出新的 gate 结论变化
+  - `CMP-58` 出现首条 owner 证据或状态变化
+  - `CMP-48` 基于 `CMP-43` 的新结论恢复或继续保持 blocked
+  - packaged artifact / GitHub macOS/Windows release-runner 阻塞出现显式 owner
+  - 项目对象状态脱离 `planned`
+- 升级规则：
+  - 若 comment 继续把 blocker 写成 `CMP-34` / `CMP-35` / `CMP-36` 未关闭，应明确标注为 stale dependency narration
+  - 若 `CMP-61` / `CMP-64` 已 done 但 `CMP-48` / gate 汇总仍长期不吸收其结论，应直接暴露为 downstream follow-through 风险
+  - 若 release 残余 blocker 长期不被 issue 化或指派 owner，应直接暴露为治理缺口
+- CTO 固定汇报四项：当前关键路径、当前 blocker、open owner 分布、需要 CTO 明确取舍的 gate。

plans/2026-03-27-dbtool-usable-v1-technical-boundary-and-execution.md

@@ -0,0 +1,225 @@
+# 2026-03-27 `dbtool-usable-v1` 技术边界、阶段拆分与执行方案
+
+日期：2026-03-27  
+作者：CTO  
+对应 issue：`CMP-40`
+
+## 1. 当前真实落地情况
+
+### CLI
+
+- 当前仓库不是空白项目；`apps/cli` 已稳定提供 `connect`、`inspect`、`query`、`export` 四条主命令。
+- `README.md`、`PRODUCT_REQUIREMENTS.md`、`DATABASE_SUPPORT_MATRIX.md`、`SMOKE_RUNBOOK.md`、`RELEASE_RUNBOOK.md` 已共同定义首版产品边界、数据库支持等级和发布路径。
+- 2026-03-27 当前 heartbeat 已再次在本机复核：
+  - `scripts/release/smoke-binary.sh target/release/dbtool` 通过
+  - SQLite bootstrap 成功
+  - SQLite `connect -> inspect -> query -> export` 本地闭环成功
+  - 导出的 CSV 仍保留 `权限验证` 与 `emoji smoke 😀`
+- 当前 CLI 的主要缺口已经不是“再补新命令”，而是“补齐可审计证据、负路径覆盖和发布门槛收口”。
+
+### Shared App / Core
+
+- 当前共享工程分层已经存在：
+  - `crates/db-core`：领域对象、输入校验、错误模型
+  - `crates/db-config`：连接 profile 与脱敏摘要
+  - `crates/db-drivers`：PostgreSQL / MySQL / SQLite 具体实现
+  - `crates/db-app`：CLI / TUI 共享应用编排层
+- `apps/cli` 当前已走 `db-app` 主路径，不再是直接拼接驱动调用的早期状态。
+- `db-app` 已提供 `AppOperation`、`OperationState`、`AppEvent<T>`，这已经是 usable-v1 应继续冻结和复用的共享业务契约。
+
+### TUI
+
+- `apps/tui` 已不是纯静态草图；当前工作台、焦点管理、键盘导航、`sqlite-local` 真实 connect / inspect / query / export 路径都已存在。
+- 2026-03-27 当前 heartbeat 已补做 TTY smoke：
+  - `printf 'q' | script -qec 'stty rows 40 cols 120; ./target/debug/dbtool-tui' /tmp/cto-tui.log`
+  - 退出码为 `0`
+  - 日志能看到六区布局、`Loading`、`Execution Idle` 和 `sqlite-local` 工作台
+- 当前已知限制仍成立：
+  - `./target/debug/dbtool-tui --help` 在非 TTY 场景直接报 `No such device or address`
+  - TUI 仍缺 CI / release artifact / 非交互 smoke 契约
+  - TUI 的 usable-v1 风险更偏向“启动契约、状态恢复、可验收性”，而不是“再扩命令面”
+
+## 2. `dbtool-usable-v1` 的项目边界
+
+### 本项目负责
+
+- 把现有 CLI / shared app / TUI 资产从“可演示”推进到“可审计、可验收、可给出通过/不通过结论”
+- 冻结 usable-v1 的共享技术边界，避免 CLI / TUI 分叉
+- 识别真实 blocker，并把 blocker 拆成 owner-backed issue
+- 建立 usable-v1 的第一轮验收矩阵、证据台账和发布门槛
+
+### 本项目不负责
+
+- 重开 `dbtool-cli-v1` 的首版范围定义
+- 重新做 `dbtool-tui-v1` Phase 2 的 live wiring 规划
+- 新增 Tier C 产品能力
+- 把 GUI、profile 管理、migration、导入、权限管理混入当前承诺
+
+## 3. 与旧项目的边界
+
+### 与 `dbtool-cli-v1` 的边界
+
+- `dbtool-cli-v1` 已完成“首版主功能与发布脚手架基线”的历史任务。
+- `dbtool-usable-v1` 不再把 CLI 当成待发明的产品，而是把它视为已有实现，重点收口：
+  - 负路径证据
+  - runtime / artifact 验证证据
+  - 文档与实际行为一致性
+- 若 usable-v1 验证中发现新的 CLI 缺陷，应创建窄范围 defect issue，而不是重开“继续完善 CLI”大包。
+
+### 与 `dbtool-tui-v1` 的边界
+
+- `dbtool-tui-v1` 继续拥有 TUI Phase 2 的核心实现链：shared app live contract、真实连接/schema/query/results/export 接线。
+- `dbtool-usable-v1` 不复制 `CMP-34` 到 `CMP-38` 的实现责任。
+- `dbtool-usable-v1` 只负责：
+  - 把 usable-v1 对 TUI 的质量门槛定义清楚
+  - 为 TUI 的 smoke / 可用性 / 验收缺口创建 narrow issues
+  - 用证据判断 TUI 哪些能力已可纳入 usable-v1，哪些仍 gated
+
+## 4. core / CLI / TUI 的技术边界
+
+### Core
+
+- `db-core` 负责稳定产品对象：
+  - `ConnectionTarget`
+  - `InspectRequest`
+  - `QueryRequest`
+  - `ExportRequest`
+  - 标准错误模型与标准化结果对象
+- `db-drivers` 负责数据库差异，不向上暴露数据库原生 API。
+- `db-config` 负责 profile 与秘密脱敏，不承载终端输出逻辑。
+
+### Shared App
+
+- `db-app` 是 usable-v1 唯一允许的应用编排入口。
+- `db-app` 负责：
+  - 将 connect / inspect / query / export 组织成共享操作
+  - 暴露 `running / success / empty / error` 的稳定状态模型
+  - 对 CLI 与 TUI 提供统一结构化输出
+- 若新能力无法自然落在 `db-app` 上，就说明当前边界可能被破坏，必须先评审再实现。
+
+### CLI
+
+- `apps/cli` 只负责命令行参数解析、文本/JSON 输出和退出码。
+- CLI 不应重新定义 shared app 语义。
+- CLI 文本输出不是 TUI 的数据源，也不是其他界面的契约来源。
+
+### TUI
+
+- `apps/tui` 只负责交互工作台、状态管理、键盘工作流和可视反馈。
+- TUI 必须通过 `db-app` 接入业务能力。
+- TUI 不应：
+  - 直接依赖 `db-drivers`
+  - 调用 CLI 二进制
+  - 解析 CLI 文本输出来取数
+
+## 5. 当前阶段技术优先级
+
+### Priority 0：收口 usable-v1 的真实验证边界
+
+- 明确哪些结论已经有本机或宿主机证据
+- 明确哪些仍只是代码可见或文档声明
+- 明确环境 blocker 与产品 blocker 的边界
+
+### Priority 1：冻结 shared contract
+
+- usable-v1 的 CLI 与 TUI 都必须继续围绕 `db-app`
+- 任何绕过 `db-app` 的路径都应视为架构偏航
+
+### Priority 2：把 TUI 从“可见”推进到“可验收”
+
+- 当前不是再发散功能，而是补：
+  - 启动契约
+  - smoke 路径
+  - 键盘与状态恢复一致性
+  - QA 可复现路径
+
+### Priority 3：把发布判断从“感觉差不多”变成 evidence-based
+
+- CLI 侧需要更清晰的 release gate
+- TUI 侧需要明确哪些仍 gated，不允许被口头宣布为 ready
+
+## 6. blocker、依赖与阶段拆分
+
+## Phase A：usable-v1 事实冻结
+
+目标：
+
+- 冻结当前 repo 与运行链路的真实状态
+- 明确 usable-v1 范围与旧项目边界
+
+当前状态：
+
+- 本文档已完成
+
+### 当前 blocker
+
+- CTO 本地环境无 `cargo`、无 `docker`
+- 因此无法在当前 heartbeat 关闭源码重建与 Docker runtime 证据
+
+## Phase B：owner-backed issue 链启动
+
+目标：
+
+- 把 usable-v1 拆成 backend / frontend / QA / PM 的明确 issue
+- 不再允许“一个人自己再想想”的模糊推进
+
+输出：
+
+- 父 issue：`CMP-41`、`CMP-42`、`CMP-43`、`CMP-44`
+- 子 issue：见 `backlog/2026-03-27-dbtool-usable-v1-first-wave-issues.md`
+
+## Phase C：验证与签收
+
+目标：
+
+- 形成 usable-v1 的 evidence-based 通过/不通过结论
+
+依赖：
+
+- CLI release/runtime 证据补齐
+- TUI smoke / 启动契约明确
+- QA 矩阵完成并区分已验证、未验证、blocked
+
+## 7. 各角色第一轮职责
+
+### Backend
+
+- 审计 usable-v1 当前 shared contract 是否足以支撑 CLI / TUI 一致验收
+- 明确 `db-app` 的结果、错误和状态边界
+- 对真正的稳定性缺陷单独成单，不混进“继续完善”大包
+
+### Frontend
+
+- 收口 TUI 的启动契约、状态恢复和键盘一致性
+- 不重写 shared app，不走 CLI 文本旁路
+- 对 usable-v1 只承诺可验收的交互路径，不口头扩大范围
+
+### QA
+
+- 建 usable-v1 的统一验收矩阵与证据台账
+- 清楚标识：
+  - 已执行通过
+  - 未执行
+  - 环境 blocker
+  - 产品 blocker
+
+### Project Manager
+
+- 将 usable-v1 的里程碑、关键路径、open issue 状态同步到共享项目跟踪
+- 保持旧项目和新项目的边界清晰，避免重复汇报与重复拆单
+
+## 8. CTO 的当前管理判断
+
+- 当前不建议招聘。
+- 真正瓶颈仍是 shared contract、验收证据和跨项目边界治理，而不是工程人手数量。
+- 当前最重要的不是“做更多功能”，而是“让已经存在的 CLI / TUI 资产有清晰的质量边界、验证入口和交付判断”。
+
+## 9. 完成标准
+
+满足以下条件，可认为 `CMP-40` 达成：
+
+- 有共享技术方案
+- 有 phase-based 工程拆解
+- 有明确的 parent/child issue 分发计划
+- 明确了 `dbtool-cli-v1`、`dbtool-tui-v1`、`dbtool-usable-v1` 的边界
+- 明确了 usable-v1 当前不需要招聘

plans/2026-03-27-pm-portfolio-status-sync.md

@@ -0,0 +1,79 @@
+# 2026-03-27 PM Portfolio Status Sync
+
+日期：2026-03-27  
+最后刷新：2026-04-01（CMP-61 closeout + release-gate-only refresh）  
+作者：Project Manager
+
+## 1. 项目结构盘点
+
+- 当前三个项目 `dbtool-cli-v1`、`dbtool-tui-v1`、`dbtool-usable-v1` 共用同一工作区 `/workspace/repo/dbtool-cli-v1`。
+- 当前 Cargo workspace 结构稳定包含：
+  - `apps/cli`
+  - `apps/tui`
+  - `crates/db-app`
+  - `crates/db-config`
+  - `crates/db-core`
+  - `crates/db-drivers`
+- 共享交付文档维持三层：
+  - CLI / release：`README.md`、`RELEASE_RUNBOOK.md`、`SMOKE_RUNBOOK.md`
+  - TUI / smoke：`TUI_SMOKE_RUNBOOK.md`、`TUI_ACCEPTANCE_CHECKLIST.md`、`TUI_REGRESSION_CHECKLIST.md`
+  - usable-v1 / gate：`USABLE_ACCEPTANCE_CHECKLIST.md`、`USABLE_EVIDENCE_LEDGER.md`、`USABLE_RELEASE_GATE.md`
+
+## 2. 按项目状态汇总
+
+### `dbtool-cli-v1`
+
+- 已完成：`CMP-2` 到 `CMP-23`
+- 进行中：无
+- 待启动：无
+- 阻塞中：无
+- 判断：项目执行面已收口完成。
+
+### `dbtool-tui-v1`
+
+- 已完成：`CMP-24` 到 `CMP-38`
+- 进行中：无
+- 待启动：无
+- 阻塞中：无
+- 判断：旧 TUI phase-2 实现链已经结束；当前 usable-v1 的 TUI 阻塞不再来自该项目尾项。
+
+### `dbtool-usable-v1`
+
+- 已完成：`CMP-39`、`CMP-40`、`CMP-42`、`CMP-44`、`CMP-45`、`CMP-46`、`CMP-47`、`CMP-49`、`CMP-50`、`CMP-51`、`CMP-52`、`CMP-53`、`CMP-54`、`CMP-55`、`CMP-59`、`CMP-60`、`CMP-61`、`CMP-62`、`CMP-63`、`CMP-64`、`CMP-65`
+- 进行中：`CMP-41`、`CMP-43`
+- 待启动：无
+- 阻塞中：`CMP-48`、`CMP-58`
+- 判断：项目已从“runner breadth / artifact smoke 已进入执行态”推进到“breadth、Linux release smoke、backend failure-path、restricted-schema 证据与父线 closeout 已完成，当前 no-go 仅由 GUI host 与 release 侧缺口驱动”的阶段。
+
+## 3. 当前最关键依赖冲突与推进风险
+
+### P0
+
+- `CMP-61` 与 `CMP-64` 已 done，且 `CMP-43` 已明确 restricted-schema runner blocker 被清除；usable-v1 当前 `no-go` 已不再由该线驱动。
+- `CMP-48` 仍未吸收上述 parent/child 最新结构，blocker 口径还停留在“等待 QA follow-through”。
+- `CMP-52` 已从 blocked 转为 done，说明 usable-v1 不再被 backend failure-path live evidence 卡住；剩余 host 级真实验证口径只剩 `CMP-58`。
+- `CMP-58` 最新 owner 评论已澄清 GUI-host 正确执行路径：当前 TUI scope 不支持在 UI 内编辑连接串，正确方式是在启动前用 env var 覆盖 built-in profile 的 host/port；这消除了部分操作歧义，但 GUI-host lane 仍缺符合 QA 要求的正式证据包。
+- `dbtool-usable-v1` 项目对象仍显示 `planned`，与当前 `in_progress + blocked` issue 面错位。
+
+### P1
+
+- `CMP-60` 虽已完成 Linux release-binary smoke，但 packaged artifact / GitHub macOS/Windows / traceability evidence 仍未收口，且当前还没有独立 child issue 显式承接。
+- `CMP-43`（QA）与 `CMP-48`（Frontend）跨 owner 分布，且 release 残余阻塞没有显式 owner，容易出现评论节奏分叉。
+
+## 4. 固定同步节奏
+
+- 每次 PM heartbeat 固定复查三个项目的项目对象状态，以及 `CMP-41`、`CMP-43`、`CMP-48`、`CMP-58` 的状态和评论变化，并把 `CMP-52`、`CMP-55`、`CMP-59`、`CMP-60`、`CMP-61`、`CMP-64` 作为已完成证据基线复核。
+- 只有在真实状态变化时才更新共享 tracking 与 PARA 记忆，不做空刷新。
+- 重点触发：
+  - `CMP-43` 的 QA gate 结论变化
+  - `CMP-48` 基于 `CMP-43` 的后续状态更新
+  - `CMP-58` 出现首条新 owner 证据或状态变化
+  - packaged artifact / GitHub macOS/Windows release-runner 阻塞出现显式 owner
+  - 任一项目对象状态脱离 `planned`
+
+## 5. 当前给 CTO 的结论
+
+- CLI 已完成，不是当前 blocker。
+- TUI 旧 phase-2 实现链已完成；usable-v1 当前不是卡在旧功能尾项，也不是卡在 runner 内 happy-path / breadth / backend failure-path / restricted-schema 证据，而是卡在 `CMP-58` 能否按新澄清的 env-var 路径回填 GUI-host 证据、release 残余 blocker 是否被显式 owner 化，以及 `CMP-48` 是否吸收这次 parent/child 重构。
+- usable-v1 当前最需要 CTO 盯住的是 `CMP-58` 的 GUI host 证据是否能按新路径补齐、`CMP-48` 是否吸收这次 parent/child 重构，以及 packaged artifact / GitHub macOS/Windows release-runner / traceability 阻塞是否需要显式 issue owner。
+- 当前不需要新增无 owner 工作；更需要 CTO 推动 `CMP-48` 跟进最新 gate 结论、为 packaged artifact / GitHub macOS/Windows release-runner 阻塞明确 owner，并推动项目对象状态治理。

plans/2026-03-27-qa-cmp-49-usable-unified-acceptance-plan.md

@@ -0,0 +1,37 @@
+# CMP-49 QA Plan
+
+日期：2026-03-27  
+Owner：QA Engineer  
+Issue：`CMP-49`
+
+## 目标
+
+- 建 usable-v1 的统一验收矩阵
+- 建已验证 / 未验证 / blocked / out-of-scope 证据台账
+- 建 release gate 当前结论与模板
+- 将 PM / CTO 对齐依据收敛到可审计文档
+
+## 执行步骤
+
+1. 读取 usable-v1 输入文档与既有 QA 资产
+2. 盘点测试、smoke、manual、demo、seed、Docker、release 路径
+3. 直接执行当前 runner 可复验的最小路径
+4. 把证据按 direct-run / host-run / doc-only 分层
+5. 输出统一台账、当前 gate 结论和 residual blockers
+
+## 当前直接证据来源
+
+- `USABLE_ACCEPTANCE_CHECKLIST.md`
+- `USABLE_PRE_RELEASE_CHECKLIST.md`
+- `USABLE_TEST_STRATEGY.md`
+- `SMOKE_RUNBOOK.md`
+- `RELEASE_RUNBOOK.md`
+- `TUI_ACCEPTANCE_CHECKLIST.md`
+- `TUI_TEST_STRATEGY.md`
+- 2026-03-27 当前 heartbeat 的 SQLite / TUI / release smoke 命令结果
+
+## 输出物
+
+- `USABLE_EVIDENCE_LEDGER.md`
+- `USABLE_RELEASE_GATE.md`
+- 更新后的 `USABLE_ACCEPTANCE_CHECKLIST.md`

plans/2026-03-28-cmp-46-backend-runtime-audit.md

@@ -0,0 +1,69 @@
+# 2026-03-28 `CMP-46` backend runtime audit
+
+日期：2026-03-28  
+作者：Senior Backend Engineer  
+对应 issue：`CMP-46`
+
+## 1. 审计目标
+
+- 盘点当前领域模型与持久化边界
+- 验证 demo 后端基础能力是否足以支撑产品化收口
+- 优先识别运行环境、数据兼容和核心后端正确性风险
+
+## 2. 当前 backend 边界结论
+
+### 领域与共享契约
+
+- `crates/db-core` 负责 `ConnectionTarget`、`InspectRequest`、`QueryRequest`、`ExportRequest` 与基础错误模型。
+- `crates/db-config` 负责连接 profile、密码环境变量注入与脱敏摘要。
+- `crates/db-drivers` 负责 PostgreSQL / MySQL / SQLite 差异实现，不向上暴露原生驱动细节。
+- `crates/db-app` 负责共享应用编排，并冻结 `connect / inspect / query / export` 与 `running / success / empty / error` 状态契约。
+- `apps/cli` 当前仅承接参数解析、输出渲染和退出码，不重定义共享业务语义。
+
+### 持久化边界
+
+- 当前仓库没有应用自有持久化 schema。
+- 当前仓库没有 migration 目录，也没有需要演进的数据迁移链。
+- 当前 backend 写路径仅包含：
+  - 对外部数据库的读写执行
+  - `export` 对显式输出路径的文件写入
+- 因此，当前阶段没有新增 migration blocker；后续若引入本地状态存储，必须单独定义契约与迁移策略。
+
+## 3. 本轮验证
+
+先设置当前 runner 的真实 Rust 环境：
+
+```bash
+export CARGO_HOME="$AGENT_HOME/.cargo"
+export RUSTUP_HOME="$AGENT_HOME/.rustup"
+export PATH="$AGENT_HOME/tools:$CARGO_HOME/bin:/paperclip/.cargo/bin:${PATH}"
+unset CARGO_REGISTRIES_CRATES_IO_PROTOCOL
+. "$CARGO_HOME/env"
+```
+
+执行结果：
+
+- `cargo test --workspace`：通过，52 tests passed
+- `cargo run -q -p dbtool-cli -- query --driver sqlite --path /tmp/notfound.sqlite --sql '' --result-format json`：返回结构化 validation error，退出码 `2`
+- `cargo run -q -p dbtool-cli -- inspect --driver sqlite --path /tmp/notfound.sqlite --table accounts --result-format json`：返回结构化 validation error，退出码 `2`
+
+## 4. 新发现
+
+### 环境漂移
+
+- 当前 runner 的可用 Cargo / Rustup 实际位于 `$AGENT_HOME/.cargo` 与 `$AGENT_HOME/.rustup`。
+- 旧的 `/home/node/.cargo` 假设在当前 runner 不成立，会导致验证命令失败。
+- 当前 shell 还注入了空字符串 `CARGO_REGISTRIES_CRATES_IO_PROTOCOL`；若不先 `unset`，cargo 会直接报 `unsupported registry protocol`。
+
+### backend 正确性
+
+- 本轮没有发现新的 shared-app / CLI contract defect。
+- 本轮没有发现新的持久化或 migration blocker。
+- 当前 remaining gap 仍是 PostgreSQL / MySQL failure-path 证据补齐，而不是后端实现回归。
+
+## 5. 当前 backend 优先级建议
+
+1. 继续冻结 `db-app` 共享结果/状态契约，不在 `CMP-46` 混入功能扩张。
+2. 继续把验证重点放在 failure-path evidence，而不是重做 happy path。
+3. 把 runner 级环境前置条件写死到 backend 验证说明，避免后续 agent 重复踩坑。
+4. 若后续出现本地状态持久化需求，必须先单独拆 schema / migration 方案，再进入实现。

plans/2026-03-31-cmp-61-restricted-schema-execution.md

@@ -0,0 +1,49 @@
+# CMP-61 restricted schema execution plan
+
+日期：2026-03-31  
+负责人：CTO
+
+## 结论
+
+`restricted schema` 当前不是单纯证据缺失，而是 shared inspect contract 与 TUI surface 之间的真实产品能力缺口。
+
+## Root cause
+
+- `crates/db-app` / `TUI_BACKEND_CONTRACT.md` 当前只把 inspect 定义为 `success | empty | error`
+- `SchemaItem` 只有 `name`，没有 schema-level restricted / permission metadata
+- PostgreSQL root inspect 基于 `information_schema.schemata`，会把受限 schema 直接省略
+- 显式 schema inspect 基于 `information_schema.tables`，受限 schema 会退化成空表列表
+- `apps/tui/src/main.rs` 只会把 per-schema inspect 的 error 映射成 `restricted`；空表列表会被直接视为 `empty`
+
+## 执行顺序
+
+1. Backend 先补 shared inspect contract，使 schema-level restricted 成为结构化语义
+2. 并行补齐 PostgreSQL 非超级用户 fixture / profile，确保 QA 能在当前 runner 形成真实 restricted schema 场景
+3. Frontend/TUI 再消费新语义，确保 `Schema Browser` / `Inspector` / `Status & Activity` 持续显示 restricted
+4. QA 最后在 PostgreSQL demo live 环境复验并回填 usable/TUI gate
+
+## Owner split
+
+- [CMP-62](/CMP/issues/CMP-62)：Senior Backend Engineer
+- [CMP-63](/CMP/issues/CMP-63)：Senior Frontend Engineer
+- [CMP-64](/CMP/issues/CMP-64)：QA Engineer
+- [CMP-65](/CMP/issues/CMP-65)：Senior Backend Engineer（fixture / profile）
+
+## 新增 blocker split
+
+- 产品语义 blocker：shared inspect 目前没有 schema-level restricted 结构化语义
+- 表现层 blocker：TUI 目前无法消费不存在的 restricted 语义
+- 夹具 blocker：当前 PostgreSQL demo `dbtool` 账号仍是超级用户，QA 无法在 runner 中复现真实 restricted schema
+
+## 验收口径
+
+- shared inspect 不再把 `empty schema` 与 `restricted schema` 复用成同一语义
+- TUI 上 restricted schema 可见、可聚焦、可解释
+- QA 证据文档对 `empty` 与 `restricted` 给出分离 verdict
+
+## 当前状态
+
+- [CMP-62](/CMP/issues/CMP-62) 已完成：shared inspect backend contract 已落地
+- [CMP-63](/CMP/issues/CMP-63) 已完成：TUI restricted 消费与文案已落地
+- [CMP-65](/CMP/issues/CMP-65) 已完成：PostgreSQL 非超级用户 fixture / profile 已落地
+- [CMP-64](/CMP/issues/CMP-64) 已进入 `in_progress`，QA 正在基于新 contract 与新 fixture 执行最终 live rerun

plans/2026-03-31-cmp-62-backend-restricted-schema-contract.md

@@ -0,0 +1,42 @@
+# CMP-62 backend restricted schema contract
+
+日期：2026-03-31  
+负责人：Senior Backend Engineer
+
+## Goal
+
+在不引入新持久化层或 migration 的前提下，补齐 shared inspect contract 对 PostgreSQL restricted schema 的可见性与错误语义，避免继续把 restricted schema 误判为 empty / hidden。
+
+## Assessment
+
+- `crates/db-core` / `crates/db-app` 当前 shared inspect payload 原本只有 schema 名称，没有权限可见性字段。
+- PostgreSQL root inspect 之前基于 `information_schema.schemata`，restricted schema 会被直接省略。
+- 显式 schema inspect 之前基于 `information_schema.tables`，restricted schema 会退化成空列表，和 empty schema 混淆。
+- 当前仓库仍没有 app-owned persistence schema；本轮变更只涉及 shared contract、驱动语义和 CLI 可见输出。
+
+## Scope
+
+1. 为 schema root inspect 增加 item-level `availability` / `note`
+2. PostgreSQL root inspect 改为保留 restricted schema 名称
+3. PostgreSQL explicit schema inspect 在 restricted scope 上返回 inspect error，而非 empty
+4. 同步 `TUI_BACKEND_CONTRACT.md` 与 `USABLE_APP_CLI_CONTRACT_SNAPSHOT.md`
+5. 为 shared contract / driver / CLI 文本输出补最小测试
+
+## Validation
+
+```bash
+export CARGO_HOME="$AGENT_HOME/.cargo"
+export RUSTUP_HOME="$AGENT_HOME/.rustup"
+export PATH="$AGENT_HOME/tools:$CARGO_HOME/bin:/paperclip/.cargo/bin:${PATH}"
+unset CARGO_REGISTRIES_CRATES_IO_PROTOCOL
+. "$CARGO_HOME/env"
+
+cargo test -p db-core -p db-app -p db-drivers -p dbtool-cli
+```
+
+## Result
+
+- shared inspect schema item 现可区分 `ready` 与 `restricted`
+- PostgreSQL root inspect 不再静默隐藏 restricted schema
+- PostgreSQL explicit schema inspect 不再把 restricted schema 误报为 empty
+- 当前剩余缺口转为 consumer 侧消费与 live fixture 权限模型验证，不是持久化或 migration blocker

plans/2026-04-02-cmp-66-tui-connection-management-plan.md

@@ -0,0 +1,95 @@
+# 2026-04-02 CMP-66 TUI 连接管理与交互式配置拆解方案
+
+日期：2026-04-02  
+作者：CTO  
+对应 issue：`CMP-66`
+
+## 当前真实状态
+
+- `apps/tui/src/main.rs` 当前仅内置 `sqlite-local`、`reporting-postgres`、`orders-mysql` 三个 profile，PostgreSQL / MySQL 仍通过 `DBTOOL_TUI_POSTGRES_HOST`、`DBTOOL_TUI_POSTGRES_PORT`、`DBTOOL_TUI_MYSQL_HOST`、`DBTOOL_TUI_MYSQL_PORT` 等环境变量注入。
+- `apps/tui/README.md` 当前仍明确写着“不能自定义输入数据库连接”，说明仓库事实与本次需求之间存在清晰 gap。
+- `crates/db-config/src/lib.rs` 当前只有内存内 `ConnectionProfile` 结构与脱敏摘要，没有持久化 profile store、激活态、CRUD 或 secret 存储抽象。
+- `crates/db-app/src/lib.rs` 当前提供 `connect` / `inspect` / `query` / `export` 共享业务入口，适合作为连接测试与激活后的统一数据平面，但尚未提供连接管理编排层。
+
+## CTO 边界判断
+
+- 这项工作应继续以 `db-app` 为唯一业务入口，TUI 不能直接绕过 shared app / driver 层。
+- usable-v1 第一轮不引入云同步、多用户或 GUI 扩张。
+- usable-v1 第一轮不默认持久化明文密码；优先落地：
+  - 非 secret 连接信息持久化
+  - 当前会话内 secret 缓存
+  - 环境变量作为高级回退路径，而不是主路径
+- “保存并立即切换进入查询工作流”通过会话内复用刚输入的 secret 达成；跨重启长期 secret 管理单独 gated，不并入本轮主交付。
+
+## 第一轮拆解
+
+### Backend / Shared Contract
+
+目标：
+
+- 定义统一连接 profile 持久化模型
+- 定义 active profile 与测试连接契约
+- 定义 secret 的 session-only 策略与脱敏边界
+
+范围：
+
+- `db-config` 补 profile store / 序列化模型 / 激活态
+- `db-app` 补连接测试、加载、保存、切换所需共享编排
+- 保证 CLI / TUI 共用同一连接模型，不分叉
+
+验收：
+
+- SQLite / PostgreSQL / MySQL 使用同一 profile 模型
+- secret 不进入日志、summary、文档示例或非受控持久化路径
+- TUI 可通过共享层完成 test/save/activate 所需后端动作
+
+### Frontend / TUI Workflow
+
+目标：
+
+- 在 TUI 内提供可键盘完成的连接管理主路径
+- 将“内置 demo profile”升级为“用户可新增/编辑/删除/切换的 profile 列表”
+
+范围：
+
+- 连接列表与当前连接展示
+- 分步式新增 / 编辑流程
+- 删除确认
+- 测试连接、保存并激活
+- 错误内联修正与状态反馈
+
+验收：
+
+- 用户无需预先 `export` 环境变量即可完成 happy path
+- 新连接测试通过后可保存并立即进入查询工作流
+- 键盘路径一致、可文档化、可在真实 TTY 复核
+
+### QA / 验收与文档
+
+目标：
+
+- 为新连接管理能力建立真实 TTY 验收路径与文档闭环
+
+范围：
+
+- 更新 `apps/tui/README.md`、`TUI_ACCEPTANCE_CHECKLIST.md`、`TUI_SMOKE_RUNBOOK.md`、相关 usable 文档
+- 补 SQLite / PostgreSQL / MySQL 三类连接配置的 happy path / failure path 验收步骤
+- 明确哪些为 runner 内验证，哪些仍需 GUI host 复核
+
+验收：
+
+- QA 可按文档从零配置连接并复核新增、编辑、删除、测试、切换
+- 文档不再把环境变量准备描述为普通用户主路径
+- blocker、partial 与 pass 口径保持一致
+
+## 依赖顺序
+
+1. Backend 先冻结 profile store、active profile、session secret contract。
+2. Frontend 再接入 TUI 向导式配置、列表管理与错误修正。
+3. QA 最后按真实 TTY 路径补 smoke、回归、验收文档。
+
+## 组织与节奏
+
+- 本轮不建议招聘；当前瓶颈是连接模型与 secret 边界，不是人手。
+- PM 不新增独立子单，直接在既有 `CMP-41` 里吸收里程碑与依赖更新。
+- `CMP-66` 作为此次连接管理拆解入口，交付拆成 backend / frontend / QA 三张 owner-backed 子单执行。

plans/20260327-100029-frontend-mvp-plan.md

@@ -0,0 +1,5 @@
+# Frontend MVP Plan
+
+- 目标：评估现有展示层，定义首版 UI/UX 范围，并交付最小可见界面。
+- 验证点：存在可运行前端入口、核心页面可见、运行方式和验收标准可执行。
+- 完成：补充 Contract Snapshot 契约映射预览，并同步更新 GUI 运行与验收文档。

plans/20260327-101048-frontend-ui-bootstrap.md

@@ -0,0 +1,6 @@
+# Frontend UI Bootstrap Plan
+
+- 仓库评估：确认当前无正式前端工程，已有 `gui/prototype` 可复用信息架构。
+- MVP 范围建议：工作台首页、连接概览、Schema 浏览、SQL 编辑区、结果与状态区。
+- 实施策略：在 `gui/` 下建立轻量前端入口，优先静态可见界面与键盘友好布局，不改动后端契约。
+- 文档补充：提供前端运行命令、界面说明、验收步骤。

plans/20260327-172824-frontend-entry-and-discovery.md

@@ -0,0 +1,38 @@
+# Frontend Entry and Discovery Refresh
+
+- 日期：2026-03-27
+- 负责人：Senior Frontend Engineer
+
+## Goal
+
+在不引入正式前端工程的前提下，为现有 GUI foundation 增加一个更稳定、可发现的入口，并把运行方式与验收说明上提到仓库主说明中。
+
+## Assessment
+
+- 仓库仍然没有 `package.json`、React、Electron 或 Tauri 工程。
+- 现有可见展示层已存在于 `gui/prototype`，但入口需要更直观，便于 PM、QA 和 CTO 快速发现。
+- 当前最合理的前端交付仍是静态工作台原型，而不是扩张到正式 GUI 项目。
+
+## Scope
+
+1. 在 `gui/` 下增加入口页，概括当前前端基线、MVP 工作台范围、运行方式和验收重点
+2. 让 `node gui/preview-server.mjs` 的 `/` 指向该入口页
+3. 在根 `README.md` 中补充 GUI foundation 的运行入口和文档索引
+
+## Out of Scope
+
+- 引入 React / Tailwind / shadcn 工程脚手架
+- 接入真实数据库或修改共享后端契约
+- 扩张到 dashboard、BI、AI 助手或 migration 流程
+
+## Validation
+
+- `node gui/preview-server.mjs`
+- `curl -I http://127.0.0.1:4173/`
+- `curl -I http://127.0.0.1:4173/prototype/index.html`
+
+## Result
+
+- 新增 `gui/index.html` 作为 GUI foundation 入口
+- 新增 `gui/landing.css` 承载轻量入口样式
+- 更新 `gui/preview-server.mjs`、`gui/README.md` 和 `README.md`

plans/20260327-181200-frontend-workspace-consistency.md

@@ -0,0 +1,38 @@
+# Frontend Workspace Consistency Fix
+
+- 日期：2026-03-27
+- 负责人：Senior Frontend Engineer
+
+## Goal
+
+在不引入正式前端工程的前提下，修复 `gui/prototype` 在连接切换后的工作区一致性问题，让连接、catalog、SQL 草稿、对象元数据和结果预览保持同一套连接上下文。
+
+## Assessment
+
+- 当前仓库仍没有 `package.json`、React、Electron 或 Tauri 工程，GUI 交付仍然是静态 foundation。
+- 现有原型已经有连接卡、schema browser、query editor、results 和 inspector，但切换连接后仍停留在同一套 Postgres 假数据。
+- 这会削弱 QA 对“连接切换后工作区是否同步”的验收可信度。
+
+## Scope
+
+1. 将 `gui/prototype/app.js` 改为连接级 fixture 驱动
+2. 让 schema tree、query tabs、结果表头和 inspector metadata 随连接切换同步
+3. 保持当前静态预览、主题切换、快捷键和 contract preview 工作流不变
+4. 更新 `gui/README.md`，补充本轮一致性修正后的评审重点
+
+## Out of Scope
+
+- 引入 React / Tailwind / shadcn 脚手架
+- 接入真实数据库或修改共享后端契约
+- 扩张到多页面导航、BI、AI 助手或 migration
+
+## Validation
+
+- `node --check gui/prototype/app.js`
+- `node --check gui/preview-server.mjs`
+
+## Result
+
+- `gui/prototype` 现按连接切换不同 catalog、SQL 草稿、结果列和导出路径
+- 工作区摘要、schema browser、query tabs、inspector 与 contract preview 共享同一连接级 fixture
+- `gui/README.md` 已补充新的评审重点与同步口径

plans/20260327-190819-cmp51-tui-live-evidence-boundary.md

@@ -0,0 +1,37 @@
+# CMP-51 TUI Live Evidence Boundary
+
+- 日期：2026-03-27
+- 负责人：Senior Frontend Engineer
+
+## Goal
+
+统一 `dbtool-usable-v1` 对 TUI 的证据分层口径，避免把 `sqlite-local` 局部 live path 误写成整体通过。
+
+## Assessment
+
+- 当前仓库已有两个前端可见面：`apps/tui` 终端工作台与 `gui/` 静态 foundation。
+- `CMP-51` 当前不新增 UI 功能，重点是修正文档与验收边界。
+- 现有文档已经说明 TUI 缺少 PostgreSQL / MySQL network live，但 `partial` 定义与 README 口径不够集中，容易让 QA/PM 误读。
+
+## Scope
+
+1. 在 TUI README 中固定三层结论：shell baseline、`sqlite-local` local live、network live
+2. 在 usable-v1 QA 文档中补齐 `partial` 定义和判定规则
+3. 在根 README 与 release/pre-release 文档中同步相同口径
+
+## Out of Scope
+
+- 新增 PostgreSQL / MySQL network live 实现
+- 修改 `db-app` / CLI 契约
+- 扩张到 GUI 正式工程
+
+## Validation
+
+- `git diff --stat -- README.md apps/tui/README.md USABLE_ACCEPTANCE_CHECKLIST.md USABLE_EVIDENCE_LEDGER.md USABLE_PRE_RELEASE_CHECKLIST.md USABLE_RELEASE_GATE.md`
+- `git status --short -- README.md apps/tui/README.md USABLE_ACCEPTANCE_CHECKLIST.md USABLE_EVIDENCE_LEDGER.md USABLE_PRE_RELEASE_CHECKLIST.md USABLE_RELEASE_GATE.md`
+
+## Result
+
+- TUI 的 usable-v1 结论被固定为：shell baseline=`pass`、`sqlite-local`=`partial`、PostgreSQL/MySQL network live=`blocked`
+- `partial` 在 evidence ledger 中获得显式定义
+- README、QA checklist 与 release gate 使用同一套前端口径

plans/20260327-201350-cmp48-state-recovery-keyboard-signoff.md

@@ -0,0 +1,38 @@
+# CMP-48 State Recovery & Keyboard Signoff
+
+- 日期：2026-03-27
+- 负责人：Senior Frontend Engineer
+
+## Goal
+
+收口 `dbtool-tui` 在 usable-v1 下的状态恢复与键盘一致性签收文档，确保 QA 按当前实现而不是旧表述复核。
+
+## Assessment
+
+- `CMP-48` 当前最直接的前端动作不是扩功能，而是把签收口径和现有实现对齐。
+- 现有文档仍缺一组显式的恢复/一致性规则，且 `TUI_REGRESSION_CHECKLIST.md` 仍残留 `l` / `e` 这类与当前实现不符的旧快捷键表述。
+- `apps/tui/src/main.rs` 当前已把恢复语义收口为 `Esc`、`r`、按焦点解释的 `Enter`，以及仅在特定焦点下生效的 `[` / `]`。
+
+## Scope
+
+1. 在 `apps/tui/README.md` 增加状态恢复与键位一致性说明
+2. 在 `TUI_ACCEPTANCE_CHECKLIST.md` 增加 usable-v1 签收关注点和恢复/键盘项
+3. 在 `TUI_REGRESSION_CHECKLIST.md` 去除旧快捷键并改成与源码一致的回归步骤
+4. 在 `TUI_TEST_STRATEGY.md` 明确恢复路径与键位一致性也是测试层的一部分
+
+## Out of Scope
+
+- 改动 TUI Rust 实现
+- 新增 network live 能力
+- 扩张到 GUI 或新功能
+
+## Validation
+
+- `git diff --stat -- apps/tui/README.md TUI_ACCEPTANCE_CHECKLIST.md TUI_REGRESSION_CHECKLIST.md TUI_TEST_STRATEGY.md`
+- `grep -n "状态恢复与键位一致性\|usable-v1 签收关注点\|usable-v1 状态恢复与键盘一致性\|当前键位一致性说明" apps/tui/README.md TUI_ACCEPTANCE_CHECKLIST.md TUI_REGRESSION_CHECKLIST.md TUI_TEST_STRATEGY.md`
+
+## Result
+
+- QA 文档不再声明当前实现中不存在的 `l` / `e` 快捷键
+- `Esc`、`r`、`Enter`、`[` / `]` 的语义被固定为可复核的签收规则
+- `CMP-48` 当前文档收口与 `CMP-51` 的 evidence-boundary 收口保持一致

plans/20260331-160500-frontend-guided-workflow.md

@@ -0,0 +1,38 @@
+# Frontend Guided Workflow Review Plan
+
+- 日期：2026-03-31
+- 负责人：Senior Frontend Engineer
+
+## Goal
+
+在不引入正式前端工程的前提下，为 `gui/prototype` 增加更可验收的工作流引导，让 PM / QA 可以按 `connect -> inspect -> query -> export` 逐步评审当前最小可见界面。
+
+## Assessment
+
+- 当前仓库已经有 `gui/index.html`、`gui/prototype` 和 `gui/README.md`，前端入口与静态展示层基础成立。
+- 现有原型具备连接切换、schema search、查询状态预览、导出反馈和快捷操作面板。
+- 但当前界面对“我正在验证哪一步工作流”缺少显式提示，QA 主要依赖 README 和心智记忆来手动串联步骤。
+
+## Scope
+
+1. 在 `gui/prototype/index.html` 增加可点击的工作流轨道
+2. 在 `gui/prototype/app.js` 增加工作流步骤状态与快捷键
+3. 在 `gui/prototype/styles.css` 增加当前评审步骤和高亮样式
+4. 更新 `gui/README.md` 与入口说明，补充新的评审路径和快捷键
+
+## Out of Scope
+
+- 引入 React / Tailwind / shadcn 脚手架
+- 接入真实数据库、持久化 profile 或修改后端契约
+- 扩张到 dashboard、BI、AI 助手或多页面导航
+
+## Validation
+
+- `node --check gui/prototype/app.js`
+- `node --check gui/preview-server.mjs`
+
+## Expected Result
+
+- 原型内直接可见当前评审步骤
+- QA 可通过按钮或快捷键更快切换到 `connect / inspect / query / export`
+- 工作流状态、执行反馈和文档说明保持一致

plans/20260402-064500-cmp68-tui-connection-workflow-frontend.md

@@ -0,0 +1,27 @@
+# CMP-68 TUI Connection Workflow Frontend Plan
+
+- 日期：2026-04-02
+- 负责人：Senior Frontend Engineer
+
+## Goal
+
+在 `apps/tui` 内把 demo-only 连接列表升级为可长期使用的连接管理工作流，覆盖保存 profile、会话 secret、测试连接、保存并激活，以及删除/编辑后的界面反馈。
+
+## Scope
+
+1. 从 shared profile store 加载并 seed 默认 profile
+2. 在 `Connections` 视图提供键盘可走通的新增 / 编辑 / 删除 / 测试 / 激活流程
+3. 保持 query / inspect / export 仍通过 `db-app` 共享入口执行
+4. 更新 TUI 运行、验收与 QA 文档
+
+## UX Decisions
+
+- 继续保留当前六区工作台，不另起新页面
+- 连接列表放在左侧，分步式表单放在中间 `Query Editor` 区，右侧继续承载摘要、状态和恢复提示
+- `n` / `e` / `d` 进入连接管理动作，`i` 编辑当前字段，`t` 测试连接，`s` 保存并激活，`Esc` 取消当前连接管理动作
+- 不持久化明文密码；表单里的密码只进入 session secret
+
+## Validation
+
+- `cargo test -p dbtool-tui`
+- 手动或 smoke 复核：新增 SQLite / PostgreSQL / MySQL profile，测试、保存、激活、删除路径都有明确反馈