symtest-cli 1.4.1__tar.gz → 1.5.1__tar.gz

{symtest_cli-1.4.1 → symtest_cli-1.5.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 CLI Test Framework Contributors
+Copyright (c) 2024 SymTest Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{symtest_cli-1.4.1 → symtest_cli-1.5.1}/MANIFEST.in

@@ -1,4 +1,5 @@
 include README.md
 include LICENSE
 recursive-include docs *
-recursive-include tests * 
+recursive-include skill *
+recursive-include tests *

{symtest_cli-1.4.1/src/symtest_cli.egg-info → symtest_cli-1.5.1}/PKG-INFO

@@ -1,20 +1,13 @@
 Metadata-Version: 2.4
 Name: symtest-cli
-Version: 1.4.1
+Version: 1.5.1
 Summary: Regression testing for CLI applications, with multi-step workflows and numerical file comparison.
-Home-page: https://github.com/ozil111/symtest-cli
-Author: Xiaotong Wang
-Author-email: xiaotongwang98@gmail.com
+Author-email: Xiaotong Wang <xiaotongwang98@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ozil111/symtest-cli
 Project-URL: Documentation, https://github.com/ozil111/symtest-cli/blob/main/docs/user_manual.md
 Project-URL: Source, https://github.com/ozil111/symtest-cli
 Project-URL: Tracker, https://github.com/ozil111/symtest-cli/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Testing
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -23,31 +16,16 @@ Requires-Dist: numpy>=1.21.0; python_version < "3.12"
 Requires-Dist: numpy>=1.26.0; python_version >= "3.12"
 Provides-Extra: yaml
 Requires-Dist: PyYAML>=6.0; extra == "yaml"
-Provides-Extra: tui
-Requires-Dist: textual>=0.40.0; extra == "tui"
 Provides-Extra: all
 Requires-Dist: PyYAML>=6.0; extra == "all"
-Requires-Dist: textual>=0.40.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: PyYAML>=6.0; extra == "dev"
-Requires-Dist: textual>=0.40.0; extra == "dev"
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
 Dynamic: license-file
-Dynamic: project-url
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
-# CLI Test Framework
+# SymTest
 
 [中文](README_cn.md) | English
 
@@ -60,10 +38,14 @@ Dynamic: summary
 > pip install symtest-cli
 > ```
 
-A feature-focused automated testing framework for command-line applications.
-It is built for regression suites that need more than an exit-code check:
-multi-step commands, numerical result comparison, large configuration sets,
-parallel execution, and CI-ready reports.
+Regression testing for numerical and scientific command-line workflows.
+
+Run solvers, compare HDF5/CSV outputs with tolerances, diagnose numerical
+regressions, and rerun only what failed.
+
+SymTest can also be used as a general-purpose CLI regression framework:
+multi-step commands, large configuration sets, parallel execution, and
+CI-ready reports.
 
 The project grew out of finite-element solver development, where a single test
 may run several programs, produce HDF5 or CSV results, compare them with
@@ -71,7 +53,7 @@ tolerances, and track execution time across revisions.
 
 ## What it solves
 
-CLI Test Framework keeps the execution workflow and its acceptance criteria in
+SymTest keeps the execution workflow and its acceptance criteria in
 one JSON or YAML configuration:
 
 - **Execute workflows** — single commands or fail-fast step sequences, with
@@ -79,8 +61,8 @@ one JSON or YAML configuration:
 - **Verify results** — return codes, output text and regular expressions, plus
   text, JSON, CSV, XML, HDF5, binary, and custom-script file comparisons.
 - **Manage large suites** — split configurations with `import`, reuse templates
-  with `extends`, filter by name or tag, and inspect cases across files in the
-  optional TUI.
+  with `extends`, filter by name or tag, and locate cases across files with
+  `symtest find`.
 - **Iterate and integrate** — parallel execution, `--last-failed`, step-level
   `--resume`, runtime history, structured reports, and JUnit XML output.
 
@@ -95,11 +77,10 @@ Python 3.9 or newer is required.
 pip install symtest-cli
 ```
 
-YAML and the TUI are optional:
+YAML support is optional:
 
 ```bash
 pip install "symtest-cli[yaml]"
-pip install "symtest-cli[tui]"
 pip install "symtest-cli[all]"
 ```
 
@@ -204,7 +185,7 @@ symtest run solver_tests.json -t long_case --resume
 `--resume` deliberately trusts that workspace artifacts have not changed
 between runs.
 
-## Large test suites and the optional TUI
+## Large test suites and cross-file search
 
 Large suites can be divided into sub-configurations:
 
@@ -217,12 +198,12 @@ Large suites can be divided into sub-configurations:
 }
 ```
 
-The optional TUI provides one searchable view across imported files. It is
-intended as an aid for locating cases and reviewing scenario coverage in large
-projects, rather than a requirement for normal test execution.
+`symtest find` auto-expands all `import` references and searches across the
+unified case set (substring / fuzzy / regex modes), making it easy to locate
+cases and review scenario coverage in large projects:
 
 ```bash
-symtest tui main_config.json
+symtest find main_config.json "login"
 ```
 
 ## Parallel execution and resources
@@ -298,9 +279,9 @@ requirement for using the framework.
 - [User manual](docs/user_manual_en.md)
 - [Design document](docs/design_en.md)
 - [Plugin examples](examples/plugins/README.md)
-- [AI Skill template](examples/skill/) — import framework knowledge into AI coding
-  assistants so they can author test cases, acceptance criteria,
-  and TDD workflows directly
+- [Official AI Skill](skill/) — install this skill into AI coding assistants
+  so they can author test cases, acceptance criteria, and TDD workflows
+  directly — the recommended entry point for new users
 
 ## Development
 

{symtest_cli-1.4.1 → symtest_cli-1.5.1}/README.md

@@ -1,4 +1,4 @@
-# CLI Test Framework
+# SymTest
 
 [中文](README_cn.md) | English
 
@@ -11,10 +11,14 @@
 > pip install symtest-cli
 > ```
 
-A feature-focused automated testing framework for command-line applications.
-It is built for regression suites that need more than an exit-code check:
-multi-step commands, numerical result comparison, large configuration sets,
-parallel execution, and CI-ready reports.
+Regression testing for numerical and scientific command-line workflows.
+
+Run solvers, compare HDF5/CSV outputs with tolerances, diagnose numerical
+regressions, and rerun only what failed.
+
+SymTest can also be used as a general-purpose CLI regression framework:
+multi-step commands, large configuration sets, parallel execution, and
+CI-ready reports.
 
 The project grew out of finite-element solver development, where a single test
 may run several programs, produce HDF5 or CSV results, compare them with
@@ -22,7 +26,7 @@ tolerances, and track execution time across revisions.
 
 ## What it solves
 
-CLI Test Framework keeps the execution workflow and its acceptance criteria in
+SymTest keeps the execution workflow and its acceptance criteria in
 one JSON or YAML configuration:
 
 - **Execute workflows** — single commands or fail-fast step sequences, with
@@ -30,8 +34,8 @@ one JSON or YAML configuration:
 - **Verify results** — return codes, output text and regular expressions, plus
   text, JSON, CSV, XML, HDF5, binary, and custom-script file comparisons.
 - **Manage large suites** — split configurations with `import`, reuse templates
-  with `extends`, filter by name or tag, and inspect cases across files in the
-  optional TUI.
+  with `extends`, filter by name or tag, and locate cases across files with
+  `symtest find`.
 - **Iterate and integrate** — parallel execution, `--last-failed`, step-level
   `--resume`, runtime history, structured reports, and JUnit XML output.
 
@@ -46,11 +50,10 @@ Python 3.9 or newer is required.
 pip install symtest-cli
 ```
 
-YAML and the TUI are optional:
+YAML support is optional:
 
 ```bash
 pip install "symtest-cli[yaml]"
-pip install "symtest-cli[tui]"
 pip install "symtest-cli[all]"
 ```
 
@@ -155,7 +158,7 @@ symtest run solver_tests.json -t long_case --resume
 `--resume` deliberately trusts that workspace artifacts have not changed
 between runs.
 
-## Large test suites and the optional TUI
+## Large test suites and cross-file search
 
 Large suites can be divided into sub-configurations:
 
@@ -168,12 +171,12 @@ Large suites can be divided into sub-configurations:
 }
 ```
 
-The optional TUI provides one searchable view across imported files. It is
-intended as an aid for locating cases and reviewing scenario coverage in large
-projects, rather than a requirement for normal test execution.
+`symtest find` auto-expands all `import` references and searches across the
+unified case set (substring / fuzzy / regex modes), making it easy to locate
+cases and review scenario coverage in large projects:
 
 ```bash
-symtest tui main_config.json
+symtest find main_config.json "login"
 ```
 
 ## Parallel execution and resources
@@ -249,9 +252,9 @@ requirement for using the framework.
 - [User manual](docs/user_manual_en.md)
 - [Design document](docs/design_en.md)
 - [Plugin examples](examples/plugins/README.md)
-- [AI Skill template](examples/skill/) — import framework knowledge into AI coding
-  assistants so they can author test cases, acceptance criteria,
-  and TDD workflows directly
+- [Official AI Skill](skill/) — install this skill into AI coding assistants
+  so they can author test cases, acceptance criteria, and TDD workflows
+  directly — the recommended entry point for new users
 
 ## Development
 

{symtest_cli-1.4.1 → symtest_cli-1.5.1}/docs/design.md

@@ -1,17 +1,17 @@
-# CLI Test Framework 设计文档
+# SymTest 设计文档
 
 > **维护原则（单一事实来源）**：本文档不镜像代码结构——不再维护目录树、类签名、
 > 函数清单、dataclass 字段定义等会随代码漂移的内容。目录结构与 API 以
 > `src/symtest/` 源码及其 docstring 为准，用法示例见 `examples/`。
 > 本文档只承载代码里读不出来的设计信息：架构分层、职责边界、关键流程语义、
-> 扩展契约、设计决策与核心架构宪法。
+> 扩展契约、设计决策与核心架构不变量。
 
 ## 1. 架构总览
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  CLI 入口层    symtest run / tui / validate / schema /       │
-│                compare-files（+ TUI 交互界面）                │
+│  CLI 入口层    symtest run / find / validate / schema /      │
+│                compare-files                                  │
 └───────────────────────────┬─────────────────────────────────┘
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
@@ -32,10 +32,10 @@
 └─────────────────────────────────────────────────────────────┘
 ```
 
-框架分为四层：**CLI 入口层**（含 TUI）、**Runner / Comparator 业务层**、**Config 管线层**、**Core 基础层**。
+框架分为四层：**CLI 入口层**、**Runner / Comparator 业务层**、**Config 管线层**、**Core 基础层**。
 
-层与层不是自由组合：跨层数据流与依赖方向受 §10「核心架构宪法」约束，
-新增 feature 请先对照宪法确定归属。
+层与层不是自由组合：跨层数据流与依赖方向受 §10「架构不变量」约束，
+新增 feature 请先对照不变量确定归属。
 
 ## 2. 模块地图
 
@@ -49,14 +49,13 @@
 | `runners/` | Config/JSON/YAML × 顺序/并行 的薄封装运行器 |
 | `file_comparator/` | 比较器家族 + 工厂 + workspace 插件发现（详见 §6） |
 | `utils/` | 路径解析、报告生成、JUnit XML 输出 |
-| `tui/` | Textual 交互式用例管理（详见 §7） |
 
 ### 2.1 入口点
 
 | 命令 | 映射 |
 |---|---|
 | `symtest run` | `symtest.cli:run_tests` |
-| `symtest tui` | `symtest.tui.app:run_tui` |
+| `symtest find` | `symtest.commands.find:run_find` |
 | `symtest validate` | `symtest.cli:run_validate` |
 | `symtest schema` | `symtest.cli:run_schema` |
 | `symtest compare` | `symtest.cli:run_compare` |
@@ -175,33 +174,68 @@ PathResolver 解析（系统命令直通、shell builtin 平台包装、复合
 
 ## 6. 文件比较子系统
 
-### 6.1 比较器分层
+### 6.1 三泳道比较器架构
 
-- 文本系比较器共享 difflib 行级基底，json / csv / xml 为其结构化特化（键对齐 / 列结构 / DOM 对齐）
-- h5 面向科学数据集；binary 流式分块 + LCS 相似度；script 委托外部脚本
-- 统一返回 ComparisonResult（identical / differences / error / script command_output），支持 text / json / html 渲染；支持行列窗口范围参数截取后比较
+所有比较器共享根契约 `ComparatorBase.compare(ctx) -> ComparisonResult`：
+框架构建 `CompareContext`（workspace / actual / baseline / params / error_analysis）；
+`actual`/`baseline` 以及插件 `path_params` 声明的构造参数在**比较器构造之前**
+按 workspace 统一解析，插件不得自行对 CWD resolve。配置单一事实源：
+比较器配置只存在于构造器捕获的实例状态，`ctx` 仅承载调用级上下文。
+三条泳道职责互斥：
 
-### 6.2 工厂与插件发现
+| 泳道 | 基类 | 契约 | verdict 归属 | 内置实例 |
+|---|---|---|---|---|
+| 文件泳道 | `FileComparator` | `read_content` + `compare_content`（两文件模型，行列窗口、line N 偏移、chunk_size、similarity 均属本泳道） | 插件 | text / json / csv / xml / h5 / binary |
+| 数据泳道 | `ExtractorComparator` | `extract(ctx) -> {channel: ChannelData}`；框架逐通道跑 `compare_numeric`，per-channel 容差（`channels` / `default_channel`），聚合 `ChannelResult` | **框架**（容差语义对 AI 消费端可预期） | script_extract、extractor 插件 |
+| 自主泳道 | 直接继承根 | `compare(ctx)` 全权判定 | 插件 | script、hourglass 式分析插件 |
 
-- `file_type` 取值：`text` / `json` / `csv` / `xml` / `h5` / `binary` / `script`；工厂按类型分发，支持动态注册与全局 reset（测试用）
-- 插件发现四处来源：内置 `*_comparator.py` 自动发现、`workspace/comparators/` 自动扫描、`--plugin-dir` CLI 参数、`CLITEST_PLUGIN_DIRS` 环境变量（供进程模式 worker 使用）
-- 命名约定：`*_comparator.py` + `*Comparator` 类名
+- 文本系共享 difflib 行级基底，json / csv / xml 为其结构化特化；h5 面向科学数据集；binary 流式分块 + LCS 相似度
+- 统一返回 `ComparisonResult`（identical / differences / error / error_stats / command_output / channels），支持 text / json / html 渲染
+- 数据泳道插件可通过 `ChannelData.extra_stats` 附带自定义误差指标，存放在独立命名空间（`ChannelResult.extra_stats`），不可覆盖框架规范指标；但 verdict 仍由框架容差持有——需要自定 verdict 的走自主泳道
 
-### 6.3 script 比较协议（对外契约）
+### 6.2 通道协议（数据泳道）
 
-- 子进程方式执行 `<interpreter> <script> <actual> <baseline>`
+- 通道判定：`identical = all(channels.passed)`；差异 position 带通道前缀（`channel S33`）；`error_stats` 按通道名嵌套
+- 内置 `script_extract` 类型：子进程执行用户脚本（零改动接入），脚本 stdout 输出约定 JSON：
+
+```json
+{"channels": {"S11": {"expected": [...], "actual": [...], "extra_stats": {...}}}}
+```
+
+  非零退出、超时、畸形 JSON 一律判为比较 error（绝不静默通过）；`actual`/`baseline` 按惯例以 baseline 在前的顺序追加为尾部 argv 槽位（可缺省）
+- 结果粒度：一条 compareSpec = 一条断言；`ComparisonResult.channels` 携带通道级子结果，报告逐通道展示 pass/fail + stats；JSON 输出中通道 differences 按 per-channel 配额截断
+
+### 6.3 工厂与插件发现
+
+- `file_type` 取值：`text` / `json` / `csv` / `xml` / `h5` / `binary` / `script` / `script_extract`；工厂按类型分发，支持动态注册与全局 reset（测试用）
+- 插件发现四处来源：内置 `*_comparator.py` 自动发现、`workspace/comparators/` 自动扫描、`--plugin-dir` CLI 参数、`CLITEST_PLUGIN_DIRS` 环境变量（用户声明的输入；框架只读，进程模式 worker 经进程池 initializer 显式接收插件目录，框架从不修改 `os.environ`）
+- 命名约定：`*_comparator.py` + `*Comparator` 类名；可用类属性 `comparator_type` 显式指定类型名（如 `script_extract`）；抽象基类自动跳过注册
+- 配置传递与严格校验：`actual`/`baseline`/`type`/`options` 之外的键转发给比较器构造函数（kwargs）；构造器参数是**严格**的——未声明的键（拼写错误）在构造时大声失败并给出支持参数清单。`options` 是框架持有的插件配置命名空间（并入构造参数，显式顶层键优先），核心 schema 不为单个插件增加专属字段；`channels`/`default_channel` 属数据泳道框架结构
+
+### 6.4 script 比较协议（自主泳道对外契约）
+
+- 子进程方式执行 `<interpreter> <script> <baseline> <actual>`（文件槽位可缺省）
 - 默认 exit code 0 → 通过；可选 `pass_pattern` / `fail_pattern` 正则匹配 stdout 细化判定
 - 超时可配
 
-## 7. TUI 子系统
+### 6.5 插件公共 API
+
+`symtest.file_comparator` 包导出：`ComparatorBase` / `CompareContext` /
+`FileComparator` / `ExtractorComparator` / `ChannelData` / `ChannelResult` /
+`compare_numeric` / `NumericComparisonStats` / `parse_data_filter`。
+数据泳道插件只需依赖 `ExtractorComparator` + `ChannelData`，数值判定全部复用框架核心。
 
-基于 Textual 的终端交互界面：App + Controller（load / create / update /
-delete / run_single / save 业务动作）+ 列表 / 编辑两屏 + 表格封装、多模式搜索条
-（名称 / 命令 / 标签）、expected 编辑器、steps 编辑器。
+## 7. 用例搜索命令（find）
 
-快捷键：`q` / Ctrl+Q 退出、`r` 刷新、`e` 编辑、`f` 单跑、`/` 搜索、`a` 新增、`d` 删除、`s` 保存。
+替代已移除的 TUI 搜索能力：`symtest find` 走与 runner 完全相同的加载路径
+（`load_config` 自动展开 import + 继承解析，`parse_test_cases` 全系统唯一
+解析器），在展开后的用例集上按三种模式匹配（子串 / 模糊 / 正则，字段覆盖
+name / command / args / tags / description），支持叠加标签过滤与 JSON 输出
+（供 AI / 脚本消费）。退出码沿用 grep 语义：有匹配 0、无匹配 1、错误 2。
 
-TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处理（§10 原则 6）。
+原 TUI 的另一职责（给不习惯写配置的同事提供图形化定义/修改用例）由官方
+skill（仓库根 `skill/`）承担：AI 编程助手按 skill 知识直接生成/修改
+JSON/YAML 配置，学习成本更低且无交互界面维护负担。
 
 ## 8. 扩展点
 
@@ -210,9 +244,8 @@ TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处
 | 新配置格式 | `BaseRunner` | 支持新的测试定义格式（如 XML、TOML） |
 | 自定义 Setup | `BaseSetup` | 数据库初始化、服务启停等 |
 | 自定义断言 | 扩展 `Assertions` | 特定业务校验逻辑 |
-| 新比较器 | `BaseComparator` | 支持新的文件格式比较，放入 `comparators/` 目录自动发现 |
+| 新比较器 | `FileComparator` / `ExtractorComparator` / `ComparatorBase` | 按泳道选择基类（文件格式 / 数据提取+通道 / 全权分析），放入 `comparators/` 目录自动发现 |
 | 新 Runner | `ParallelRunner` / `BaseRunner` | 自定义并行调度策略 |
-| TUI 扩展 | `CaseController` / Widgets | 扩展终端管理界面 |
 
 ## 9. 设计决策
 
@@ -238,17 +271,16 @@ TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处
 | DAG 依赖调度 | 基于 Kahn 拓扑 + 就绪队列，依赖满足后立即提交；依赖失败级联 skip 下游；无依赖时走 fast path 零开销 |
 | --update-baseline | 比较失败时自动将实际输出覆盖 baseline，适合批量更新基准 |
 | next_action_hint 结构化建议 | 失败结果附带下一步操作建议（update_baseline / update_expected / increase_timeout / investigate），便于 AI 消费 |
-| TUI 基于 Textual | 利用成熟的终端 UI 框架，提供交互式用例管理 |
+| 移除 TUI，由官方 skill + `symtest find` 替代 | TUI 的两大职责均有更轻替代：定义/修改用例由 AI 编程助手按官方 skill 完成，跨文件搜索由复用同一解析管线的 `find` 命令覆盖；移除后砍掉 textual 重依赖与交互界面维护负担 |
 | JUnit XML 输出 | 兼容 GitLab CI / Jenkins / CircleCI 等主流 CI 系统的测试报告格式 |
 | Logging 统一化 | 通过 `logging` 模块集中管理，CLI 入口激活控制台输出，库用户按需启用 |
 
 ---
 
-## 10. 核心架构宪法
+## 10. 架构不变量
 
-> **地位与效力**：本节自 Symtest 1.4 Phase 0 评审定稿，是本项目的核心架构契约，
-> 对所有后续 feature 具有最高约束力——任何功能需求先对照本宪法确定归属，再写代码。
-> 修订宪法必须在变更说明中显式指出所放宽/违反的条款及理由。
+> **定位**：本节自 Symtest 1.4 Phase 0 评审定稿。这些不变量定义了模块归属与依赖方向；
+> 新增 feature 应遵守它们，除非变更说明中显式记录了某条不变量为何需要演进。
 
 ### 10.1 数据流主线
 
@@ -326,10 +358,10 @@ Reporter 的合法输入只能是 Result 类型；`next_action_hint` 属于 resu
 
 #### 原则 6 — 核心模型不依赖表现层
 
-`core` 绝对不能 import：`cli` / `tui` / `reporter` / AI-specific adapter。
+`core` 绝对不能 import：`cli` / `reporter` / AI-specific adapter。
 
-解析器全系统唯一：TUI 与 runner 使用同一 parser，不允许存在 "TUI mode 后门"
-（如 workspace=None 时放宽校验）；宽松形态由 TUI 侧自行处理。
+解析器全系统唯一：不允许存在宽松解析后门（如 workspace=None 时放宽校验）；
+宽松形态由调用方先 normalize 再调用。
 
 ### 10.3 模块依赖方向
 
@@ -344,9 +376,9 @@ Reporter 的合法输入只能是 Result 类型；`next_action_hint` 属于 resu
 - `execution` 与 `validation` 互不 import；
 - `executor` 不得 import `assertions` / validation 侧模块；
 - `validator` 不得启动被测进程（见原则 3）；
-- `core` 不得 import `cli` / `tui` / `reporter`。
+- `core` 不得 import `cli` / `reporter`。
 
-### 10.4 违宪归属速查
+### 10.4 归属速查
 
 任何新需求先问归属：
 
@@ -358,14 +390,14 @@ Reporter 的合法输入只能是 Result 类型；`next_action_hint` 属于 resu
 | AI 告诉我下一步该干嘛？ | Result consumer / diagnosis |
 
 判据：若仍经常出现"这个功能到底放 execution、runner 还是 testcase？"的争论，
-说明宪法没有被正确适用，应回到 10.2 逐条对照。
+说明不变量没有被正确适用，应回到 10.2 逐条对照。
 
-### 10.5 宪法可执行化
+### 10.5 不变量可执行化
 
-宪法不是纯文档约定，配套 architecture guard 测试并由 CI 强制：
+这些不变量不只是文档约定，配套 architecture guard 测试并由 CI 强制：
 
 - 断言 import 图：如 `execution/executor.py` 的 import 不得出现
-  `assertions` / `validation`；`core/**` 不得 import `cli` / `tui` /
+  `assertions` / `validation`；`core/**` 不得 import `cli` /
   `reporter`；
 - guard 测试纳入常规回归套件（`python tests\run_all.py`），违规即失败；
 - 冲突裁决次序：guard 测试 > 本节文字 > 个人偏好。

{symtest_cli-1.4.1 → symtest_cli-1.5.1}/docs/design_en.md

@@ -1,4 +1,4 @@
-# CLI Test Framework Design Document
+# SymTest Design Document
 
 > **Maintenance principle (single source of truth)**: this document does not mirror
 > code structure — it no longer maintains directory trees, class signatures,
@@ -7,14 +7,14 @@
 > their docstrings; usage examples live in `examples/`.
 > This document only carries what cannot be read out of code: architecture
 > layering, responsibility boundaries, key flow semantics, extension contracts,
-> design decisions, and the architecture constitution.
+> design decisions, and the architecture invariants.
 
 ## 1. Architecture Overview
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  CLI Entry Layer    symtest run / tui / validate / schema /  │
-│                     compare-files (+ TUI interface)          │
+│  CLI Entry Layer    symtest run / find / validate / schema / │
+│                     compare-files                             │
 └───────────────────────────┬─────────────────────────────────┘
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
@@ -37,13 +37,13 @@
 └─────────────────────────────────────────────────────────────┘
 ```
 
-The framework is divided into four layers: **CLI Entry Layer** (including TUI),
+The framework is divided into four layers: **CLI Entry Layer**,
 **Runner / Comparator Business Layer**, **Config Pipeline Layer**, and
 **Core Foundation Layer**.
 
 Layers are not free-to-wire: cross-layer data flow and dependency directions are
-governed by the §10 Core Architecture Constitution. Resolve feature ownership
-against it first.
+governed by the §10 architecture invariants. Resolve feature ownership
+against them first.
 
 ## 2. Module Map
 
@@ -57,14 +57,13 @@ Responsibilities by package (file-level details and public APIs live in source):
 | `runners/` | Thin wrapper runners: Config/JSON/YAML × sequential/parallel |
 | `file_comparator/` | Comparator family + factory + workspace plugin discovery (see §6) |
 | `utils/` | Path resolution, report generation, JUnit XML output |
-| `tui/` | Interactive Textual case management (see §7) |
 
 ### 2.1 Entry Points
 
 | Command | Mapping |
 |---|---|
 | `symtest run` | `symtest.cli:run_tests` |
-| `symtest tui` | `symtest.tui.app:run_tui` |
+| `symtest find` | `symtest.commands.find:run_find` |
 | `symtest validate` | `symtest.cli:run_validate` |
 | `symtest schema` | `symtest.cli:run_schema` |
 | `symtest compare` | `symtest.cli:run_compare` |
@@ -204,17 +203,21 @@ guarantees they are unmodified.
 - Default exit code 0 → pass; optional `pass_pattern` / `fail_pattern` regexes refine the verdict on stdout
 - Timeout configurable
 
-## 7. TUI Subsystem
+## 7. Case Search Command (find)
 
-Textual-based terminal UI: App + Controller (load / create / update / delete /
-run_single / save actions) + list/edit screens + table wrapper, multi-mode
-search bar (name / command / tag), expected editor, steps editor.
+Replaces the search capability of the retired TUI: `symtest find` goes through
+exactly the same loading path as the runners (`load_config` auto-expands
+imports + resolves inheritance; `parse_test_cases` is the single system-wide
+parser), then matches cases in three modes (substring / fuzzy / regex, across
+name / command / args / tags / description) with optional tag filtering and
+JSON output (for AI / scripts). Exit codes follow grep semantics: 0 = match,
+1 = no match, 2 = error.
 
-Key bindings: `q` / Ctrl+Q quit, `r` refresh, `e` edit, `f` run single, `/`
-search, `a` add, `d` delete, `s` save.
-
-TUI and runners share the same parser; relaxed display shapes are handled on the
-TUI side itself (§10 Principle 6).
+The TUI's other responsibility (graphical case authoring/editing for people
+unfamiliar with writing configs) is now covered by the official skill
+(`skill/` at the repository root): AI coding assistants author/modify
+JSON/YAML configs directly from skill knowledge, with lower learning cost and
+no interactive UI maintenance burden.
 
 ## 8. Extension Points
 
@@ -225,7 +228,6 @@ TUI side itself (§10 Principle 6).
 | Custom assertions | Extend `Assertions` | Specific business validation logic |
 | New comparator | `BaseComparator` | Support new file formats; place in `comparators/` for auto-discovery |
 | New Runner | `ParallelRunner` / `BaseRunner` | Custom parallel scheduling strategies |
-| TUI extensions | `CaseController` / Widgets | Extend the terminal management interface |
 
 ## 9. Design Decisions
 
@@ -250,19 +252,17 @@ TUI side itself (§10 Principle 6).
 | DAG dependency scheduling | Kahn topology + ready queue; submits dependents immediately once deps are satisfied; cascade-skips downstream on dep failure; zero-overhead fast path when no deps declared |
 | --update-baseline | Automatically overwrites baseline files with actual output on comparison failure; ideal for batch baseline updates |
 | next_action_hint structured suggestions | Failed results include actionable suggestions (update_baseline / update_expected / increase_timeout / investigate), convenient for AI consumption |
-| TUI based on Textual | Leverages a mature terminal UI framework for interactive case management |
+| TUI removed; replaced by official skill + `symtest find` | Both TUI responsibilities have lighter replacements: case authoring/editing is done by AI assistants via the official skill; cross-file search is covered by the `find` command reusing the same parsing pipeline; removes the heavy textual dependency and interactive-UI maintenance burden |
 | JUnit XML output | Compatible with GitLab CI / Jenkins / CircleCI and other major CI system test report formats |
 | Centralized logging | All diagnostic messages go through Python's `logging` module; CLI entry activates console output; library users enable as needed |
 
 ---
 
-## 10. Core Architecture Constitution
+## 10. Architecture Invariants
 
-> **Status and force**: ratified at Symtest 1.4 Phase 0 review. This section is the
-> project's core architectural contract with supreme authority over all future
-> features — resolve ownership against this constitution before writing any code.
-> Amending it requires explicitly naming the clause being relaxed/waived and the
-> rationale in the change description.
+> **Status**: established at Symtest 1.4 Phase 0 review. These invariants define
+> module ownership and dependency direction. New features should preserve them
+> unless a change explicitly documents why an invariant must evolve.
 
 ### 10.1 Data Flow Spine
 
@@ -346,11 +346,11 @@ to result consumers (diagnosis) and must not exist in the execution layer.
 
 #### Principle 6 — The core model does not depend on presentation
 
-`core` must never import: `cli` / `tui` / `reporter` / AI-specific adapters.
+`core` must never import: `cli` / `reporter` / AI-specific adapters.
 
-One parser for the whole system: TUI and runners use the same parser; a "TUI
-mode back door" (e.g., relaxed validation when workspace=None) is forbidden;
-relaxed shapes are handled on the TUI side itself.
+One parser for the whole system: no relaxed-parsing back door is allowed
+(e.g., relaxed validation when workspace=None); relaxed shapes are normalized
+by the caller before invoking the parser.
 
 ### 10.3 Module Dependency Direction
 
@@ -365,7 +365,7 @@ Forbidden:
 - `execution` and `validation` must not import each other;
 - the `executor` must not import `assertions` / validation-side modules;
 - the `validator` must not launch the process under test (see Principle 3);
-- `core` must not import `cli` / `tui` / `reporter`.
+- `core` must not import `cli` / `reporter`.
 
 ### 10.4 Ownership Quick Reference
 
@@ -379,17 +379,17 @@ For any new requirement, ask ownership first:
 | AI tells me what to do next? | Result consumer / diagnosis |
 
 Litmus test: if arguments like "does this go into execution, the runner, or the
-testcase?" keep recurring, the constitution is not being applied correctly — go
+testcase?" keep recurring, the invariants are not being applied correctly — go
 back to 10.2 and check clause by clause.
 
-### 10.5 Making the Constitution Enforceable
+### 10.5 Making the Invariants Enforceable
 
-The constitution is not a documentation-only convention; it comes with
+These invariants are not documentation-only; they come with
 architecture guard tests enforced by CI:
 
 - Assert the import graph: e.g., imports of `execution/executor.py` must not
   contain `assertions` / `validation`; `core/**` must not import `cli` /
-  `tui` / `reporter`;
+  `reporter`;
 - Guard tests are part of the regular regression suite
   (`python tests\run_all.py`); violations fail the build;
 - Conflict resolution order: guard tests > this text > personal preference.