Organize tests and document GPLv3 licensing

Makefile

@@ -16,12 +16,14 @@
 EMACS ?= emacs
 LOAD_EXTRA ?=
 WERROR ?= nil
-LOADPATH = -L . $(LOAD_EXTRA)
+TEST_DIR = tests
+LOADPATH = -L . -L $(TEST_DIR) $(LOAD_EXTRA)
 
 SRC = tp-core.el tp-reactive.el tp-layer.el tp-ops.el tp-search.el \
       tp-render.el tp-stack.el tp-query.el tp-palette.el tp-builtins.el tp.el
-TESTS = $(wildcard *-tests.el)
+TESTS = $(wildcard $(TEST_DIR)/*-tests.el)
-DEV = tp-doctest.el tp-run-shuffled.el tp-benchmark.el
+TEST_SUPPORT = $(TEST_DIR)/tp-doctest.el $(TEST_DIR)/tp-run-shuffled.el
+DEV = $(TEST_SUPPORT) tp-benchmark.el
 
 .PHONY: test test-shuffled doctest benchmark compile compile-all clean
 
@@ -50,4 +52,4 @@ compile-all: clean
 	  -f batch-byte-compile $(SRC) $(TESTS) $(DEV)
 
 clean:
-	rm -f *.elc
+	rm -f *.elc $(TEST_DIR)/*.elc

README.md

@@ -439,8 +439,9 @@ The modules and their roles:
 | `tp-palette.el` | Light/dark color palette data |
 | `tp-builtins.el` | Built-in layers, palette gallery, display-buffer helpers |
 
-A `Makefile` is included: `make test` runs all ERT suites, `make doctest`
+A `Makefile` is included. Test sources live under `tests/`: `make test` runs
-executes the README examples against the code (`tp-doctest.el`),
+all ERT suites, `make doctest` executes the README examples against the code
+(`tests/tp-doctest.el`),
 `make compile` byte-compiles the modules, and `make clean` removes
 compiled files.
 
@@ -4353,7 +4354,8 @@ To clear all reactive dependencies and watchers:
 
 ## License
 
-GNU General Public License v3 or later. See the [LICENSE](LICENSE) file.
+This project is distributed under the GNU General Public License v3 or later
+(`GPL-3.0-or-later`). See [LICENSE](LICENSE) for the complete GPLv3 terms.
 
 ---
 

README_CN.md

@@ -435,8 +435,9 @@ OBJECT 总是位于最后（nil 表示当前缓冲区）。所有核心函数和
 | `tp-palette.el` | 亮色/暗色调色板数据 |
 | `tp-builtins.el` | 内置属性层、调色板画廊、display-buffer 辅助工具 |
 
-项目附带 `Makefile`：`make test` 运行所有 ERT 测试套件，`make doctest`
+项目附带 `Makefile`，测试源码统一位于 `tests/`：`make test` 运行所有 ERT
-将 README 示例作为可执行测试运行（`tp-doctest.el`），`make compile`
+测试套件，`make doctest` 将 README 示例作为可执行测试运行
+（`tests/tp-doctest.el`），`make compile`
 字节编译各模块，`make clean` 清除编译产物。
 
 ---
@@ -4285,7 +4286,8 @@ tp.el 提供调试模式来帮助理解响应式更新流程：
 
 ## 许可证
 
-GNU 通用公共许可证 v3 或更高版本。参见 [LICENSE](LICENSE) 文件。
+本项目采用 GNU 通用公共许可证 v3 或更高版本（`GPL-3.0-or-later`）发布。
+[LICENSE](LICENSE) 包含完整的 GPLv3 条款。
 
 ---
 

docs/CODE-ANALYSIS.md

@@ -61,7 +61,7 @@ tp.el 是一个 Emacs Lisp 文本属性操作库，拆分前的单文件版本
 
 ## 文件结构
 
-当前（0.2.0）文件结构：
+当前（0.3.0）文件结构：
 
 ```
 tp/
@@ -75,8 +75,11 @@ tp/
 ├── tp-stack.el        # 属性层栈操作（709 行）
 ├── tp-palette.el      # 明/暗主题调色板数据（351 行）
 ├── tp-builtins.el     # 内置层与辅助工具（193 行）
-├── tp-tests.el        # 综合 ERT 测试套件（4123 行，280 个测试）
+├── tests/
-├── tp-*-tests.el      # 各模块回归测试套件（7 个文件，159 个测试；全套共 439 个测试）
+│   ├── tp-tests.el          # 综合 ERT 测试套件
+│   ├── tp-*-tests.el        # 各模块回归测试套件
+│   ├── tp-doctest.el        # README 可执行示例
+│   └── tp-run-shuffled.el   # 乱序 ERT 运行器
 ├── Makefile           # test / compile / clean
 ├── docs/
 │   ├── ARCHITECTURE.md              # 架构文档
@@ -721,7 +724,7 @@ tp-layers -> [props1 props2 props3]
    - 遵循模块间调用规则（只调用前置模块的函数）
 
 2. **编写测试用例**
-   - 在对应模块的 `tp-*-tests.el`（或综合套件 `tp-tests.el`）中添加测试
+   - 在 `tests/` 下对应模块的 `tp-*-tests.el`（或综合套件 `tp-tests.el`）中添加测试
    - 覆盖正常流程和边界情况
 
 3. **实现功能**

docs/REPOSITORY-AUDIT.md

@@ -449,7 +449,7 @@ FINAL-TEXT:
 ([`tp-render.el`](../tp-render.el#L339-L427))。这说明当前同一功能的“初次应用”
 和“更新应用”使用了两套不完全一致的合并引擎。
 
-现有 [`tp-render-tests.el`](../tp-render-tests.el#L318-L334) 覆盖了后续响应式更新，
+现有 [`tp-render-tests.el`](../tests/tp-render-tests.el#L318-L334) 覆盖了后续响应式更新，
 没有覆盖初次应用的这个状态。
 
 **根因：**
@@ -872,7 +872,7 @@ show 后：
 - 主要交互命令的 `call-interactively` 路径；
 - 调色板/主题切换后的动态视觉验证。
 
-`tp-run-shuffled.el` 只是改变测试顺序，不会生成新的输入状态。它能发现全局状态
+`tests/tp-run-shuffled.el` 只是改变测试顺序，不会生成新的输入状态。它能发现全局状态
 泄漏，但不能替代属性状态空间测试。
 
 ---

postmortem/2026-07-28-test-directory-and-license.md

@@ -0,0 +1,28 @@
+# 独立测试目录与许可证边界
+
+## 决策
+
+所有 ERT 套件、README doctest 与乱序测试运行器统一放在 `tests/`。基准脚本仍在
+仓库根目录，因为它是独立的性能工具，不属于测试入口。Makefile 同时把源码根目录
+和 `tests/` 加入加载路径，继续提供原有的 `test`、`test-shuffled`、`doctest` 与
+`compile-all` 命令。
+
+项目继续采用 `GPL-3.0-or-later`。仓库根目录保留完整、未经修改的 GPLv3 正文，
+README 明确标注 SPDX 许可证表达式并链接到该正文。
+
+## 原因
+
+测试文件与可发布模块混放会模糊安装边界，也让根目录的模块清单难以快速阅读。
+按职责集中测试后，发布源码、测试支持代码和性能工具各有明确位置，同时无需新增
+测试框架或包装脚本。
+
+许可证不能只依赖源码头部的简写声明；分发仓库需要同时提供完整条款。保留标准
+GPLv3 正文并在用户文档中明确 `GPL-3.0-or-later`，可以让机器识别信息与法律文本
+保持一致。
+
+## 被放弃的方案
+
+- 只移动 `*-tests.el`、把 doctest 和乱序运行器留在根目录：测试边界仍然分散。
+- 把基准脚本也移入 `tests/`：会把性能测量与正确性测试混为一谈。
+- 为新目录增加额外 Elisp 加载器：Makefile 已经能直接枚举并加载测试文件，新增
+  包装层没有净收益。

tests/tp-builtins-tests.el

@@ -6,7 +6,7 @@
 ;; macros, and the palette module (tp-builtins.el / tp-palette.el).
 ;;
 ;; Run with:
-;;   emacs --batch -L . -l tp.el -l tp-builtins-tests.el \
+;;   emacs --batch -L . -L tests -l tp.el -l tp-builtins-tests.el \
 ;;     -f ert-run-tests-batch-and-exit
 
 ;;; Code:

tests/tp-run-shuffled.el

@@ -20,7 +20,8 @@
 ;; shuffled names and runs each test on its own.
 ;;
 ;; Usage (after loading tp and all *-tests.el files):
-;;   emacs -Q --batch -L . -l tp.el -l tp-tests.el ... -l tp-run-shuffled.el
+;;   emacs -Q --batch -L . -L tests -l tp.el -l tp-tests.el ... \
+;;     -l tp-run-shuffled.el
 ;; or: make test-shuffled
 ;;
 ;; The shuffle seed is printed; reproduce a failing order with

tests/tp-tests.el

@@ -5,18 +5,16 @@
 ;;; Commentary:
 
 ;; Comprehensive test suite for tp.el using ERT (Emacs Lisp Regression Testing).
-;; Run with: emacs --batch -L . -l tp.el -l tp-tests.el -f ert-run-tests-batch-and-exit
+;; Run with:
+;;   emacs --batch -L . -L tests -l tp.el -l tp-tests.el \
+;;     -f ert-run-tests-batch-and-exit
 
 ;;; Code:
 
 (require 'ert)
 (require 'cl-lib)
 (require 'tp-palette)
-
+(require 'tp)
-;; Load tp.el from the same directory
-(let ((tp-dir (file-name-directory (or load-file-name buffer-file-name))))
-  (add-to-list 'load-path tp-dir)
-  (require 'tp))
 
 ;;; ============================================================
 ;;; Test Utilities