refactor: adopt native evolution contract

- replace legacy comparison gates with public-contract pytest coverage

- isolate generated-project runtime and retain pairwise and deep-profile validation

- remove migration fixtures, shims, and redundant CI dependencies

Author: dlivxpr

.github/workflows/ci.yml

@@ -5,125 +5,17 @@ on:
   pull_request:
 
 jobs:
-  template-quality:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
       - uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
       - run: uv python install 3.14
       - run: uv sync --all-groups
-      - name: Template static checks
-        run: uv run python scripts/lint_template.py
-      - name: Migration goldens are append-only
-        if: github.event_name == 'pull_request'
-        run: uv run python scripts/check_migration_goldens.py ${{ github.event.pull_request.base.sha }}
-      - name: Migration goldens are append-only on push
-        if: github.event_name == 'push' && github.event.before != '0000000000000000000000000000000000000000'
-        run: uv run python scripts/check_migration_goldens.py ${{ github.event.before }}
+      - run: uv run python scripts/lint_template.py
       - run: uv run ruff check .
       - run: uv run ruff format --check .
       - run: uv run ty check
       - run: uv run pytest
-
-  generated-projects:
-    runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: postgres:17-alpine
-        env:
-          POSTGRES_DB: app
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready -U postgres -d app"
-          --health-interval 2s
-          --health-timeout 3s
-          --health-retries 15
-      redis:
-        image: redis:8-alpine
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 2s
-          --health-timeout 3s
-          --health-retries 15
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - name: default
-            data: '{}'
-            migrate: false
-          - name: postgresql-sqlalchemy-logfire
-            data: '{"database":"postgresql","orm_type":"sqlalchemy","enable_logfire":true,"include_example_crud":true}'
-            migrate: true
-          - name: postgresql-sqlmodel
-            data: '{"database":"postgresql","orm_type":"sqlmodel","enable_docker":false,"include_example_crud":true}'
-            migrate: true
-          - name: taskiq-redis-consumers
-            data: '{"background_tasks":"taskiq","enable_redis":true,"enable_caching":true,"enable_rate_limiting":true,"rate_limit_storage":"redis","rate_limit_requests":2,"rate_limit_period":1}'
-            migrate: false
-          - name: pydantic-ai-logfire
-            data: '{"ai_framework":"pydantic_ai","enable_logfire":true,"enable_docker":false}'
-            migrate: false
-          - name: full-nginx
-            data: '{"database":"postgresql","orm_type":"sqlalchemy","background_tasks":"taskiq","ai_framework":"pydantic_ai","enable_logfire":true,"enable_redis":true,"enable_caching":true,"enable_rate_limiting":true,"rate_limit_storage":"redis","rate_limit_requests":2,"rate_limit_period":1,"enable_docker":true,"reverse_proxy":"nginx_external"}'
-            migrate: true
-          - name: docker-ci-off
-            data: '{"enable_docker":false,"ci_type":"none","enable_rate_limiting":true,"rate_limit_storage":"memory","rate_limit_requests":2,"rate_limit_period":1}'
-            migrate: false
-    name: generated-${{ matrix.name }}
-    env:
-      POSTGRES_HOST: 127.0.0.1
-      POSTGRES_PORT: 5432
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: app
-      REDIS_HOST: 127.0.0.1
-      REDIS_PORT: 6379
-      LOGFIRE_SEND_TO_LOGFIRE: 'false'
-    steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v6
-        with:
-          enable-cache: true
-      - run: uv python install 3.14
-      - run: uv sync --all-groups
-      - name: Copier render
-        env:
-          COPIER_DATA: ${{ matrix.data }}
-        run: |
-          uv run python -c "import json, os, pathlib; pathlib.Path('.ci-data.json').write_text(json.dumps(json.loads(os.environ['COPIER_DATA'])), encoding='utf-8')"
-          uv run copier copy --defaults --data-file .ci-data.json . generated
-      - name: Generated project uv sync
-        working-directory: generated
-        run: uv sync --all-groups
-      - name: Apply database migrations
-        if: matrix.migrate
-        working-directory: generated
-        run: uv run alembic upgrade head
-      - name: Generated project quality
-        working-directory: generated
-        run: |
-          uv run ruff check .
-          uv run ruff format --check .
-          uv run ty check
-          uv run pytest
-      - name: Runtime smoke
-        working-directory: generated
-        run: |
-          uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 &
-          server_pid=$!
-          trap 'kill "$server_pid"' EXIT
-          for attempt in {1..30}; do
-            curl --fail --silent http://127.0.0.1:8000/health/live && exit 0
-            sleep 1
-          done
-          exit 1

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-本仓库提供唯一受支持的原生 Copier 模板，用于生成可组合的 FastAPI 后端服务。模板配置位于 `copier.yml`，模板树位于 `template/`；不再维护 Cookiecutter、自定义生成 CLI 或 legacy 生成器。
+本仓库提供唯一受支持的原生 Copier 模板，用于生成可组合的 FastAPI 后端服务。模板配置位于 `copier.yml`，模板树位于 `template/`；不维护 Cookiecutter 或自定义生成 CLI。当前公开承诺以 `docs/product-contract.md` 为准。
 
 保留能力：API Key、可选 PostgreSQL（SQLAlchemy/SQLModel）、Taskiq、Redis cache/rate limit、Pydantic AI、Logfire、Docker、外部 Nginx 配置和 GitHub Actions。不要重新引入 frontend、用户/JWT、teams、billing、消息渠道、文件存储、Webhooks、RAG、Kubernetes、Helm、Traefik 或替代队列/telemetry/provider SDK。
 
@@ -17,22 +17,24 @@ Copier 直接读取 `copier.yml`，再以原生条件路径和 Jinja 条件渲
 | 路径 | 用途 |
 |---|---|
 | `copier.yml` | Copier 问题、默认值、choices、when 与 validator 的事实来源 |
+| `docs/product-contract.md` | Copier 输入、生成边界和生成项目公开行为的规范 |
 | `template/` | 唯一生成项目模板；条件目录和文件名使用自定义 `[% ... %]` Jinja delimiters |
 | `template/app/` | 生成 FastAPI runtime、可选能力与生命周期组合 |
 | `template/tests/` | 生成项目的行为测试 |
 | `template/AGENTS.md.jinja` | 根据所选能力生成的根级 agent guidance |
-| `template/.omp/RULES.md.jinja` | 根据所选能力生成的 omp rules |
-| `tests/test_template.py` | Copier public interface、生成树和实际 runtime 验收 |
+| `template/.omp/` | 根据所选能力生成的 omp rules、skills 与 commands |
+| `tests/test_*_contract.py` | 按公开契约领域组织的生成与运行验收 |
+| `tests/support/` | 隔离生成环境、进程与真实服务的共享测试支持层 |
 | `scripts/lint_template.py` | 模板和条件路径的 Jinja 语法静态检查 |
-| `.github/workflows/ci.yml` | 根模板质量检查与代表性生成矩阵 |
+| `.github/workflows/ci.yml` | 根模板质量检查与 pytest 验收入口 |
 | `docs/adr/` | 已接受的产品和架构边界 |
 
 ## Development Commands
 
 ```bash
 uv sync --all-groups
 uv run python scripts/lint_template.py
-uv run pytest tests/test_template.py -q
+uv run pytest
 uv run ruff check .
 uv run ruff format --check .
 uv run ty check
@@ -58,19 +60,21 @@ uv run uvicorn app.main:app
 ## Code Conventions & Common Patterns
 
 - Python 使用 4 空格、双引号、100 字符行宽；Ruff 负责格式与 import 排序，类型检查使用 `ty`。
-- I/O、数据库、HTTP 和生命周期路径使用 `async`；测试使用 AnyIO、HTTPX `AsyncClient` + `ASGITransport`。
-- 依赖通过 FastAPI DI 或显式参数传递；每个测试结束后清理 `app.dependency_overrides`，禁止模块级请求状态。
+- I/O、数据库、HTTP 和生命周期路径使用 `async`；生成项目测试使用 AnyIO、HTTPX `AsyncClient` + `ASGITransport`。
+- 根 pytest 不把生成应用导入自身进程；运行行为必须在生成项目自己的 `uv` 环境或进程中验证。
 - 新增、修改或删除模板选项时，同步检查 `copier.yml`、条件路径、模板内容、依赖、环境变量、部署资产、guidance 和渲染测试。
 - Jinja 模板不是普通 Python。不要对整个 `template/` 自动修复；先渲染代表性项目，再在生成结果中运行 Ruff、ty 和 pytest。
 - 条件文件必须通过 Copier 原生路径条件消失，禁止恢复 cleanup hook、derived context 或兼容 alias。
-- Logfire 默认关闭；启用时先 `logfire.configure()`，再按实际能力 instrument FastAPI、SQLAlchemy engine、Redis、Taskiq 和 Pydantic AI，且默认不采集模型内容。
+- Logfire 仅在 Pydantic AI 启用时可用且默认启用；先 `logfire.configure()`，再只 instrument Pydantic AI，默认不采集模型或 binary content。
 - Docker 产物统一位于生成项目的 `deploy/`；Nginx 仅生成外部配置，不加入 compose service。
 
 ## Testing & QA
 
-公共测试 seam 是 Copier 渲染接口和生成项目公开开发/runtime 接口。测试应验证生成树、依赖、配置、HTTP 行为、后台任务和真实数据库/Redis 交互，不断言无意义的模板源码细节。
+公共测试 seam 是 Copier 渲染接口、文档化开发接口和生成项目公开 runtime。测试按契约领域组织，验证生成边界、依赖、配置、HTTP/CLI 行为、后台任务和真实数据库/Redis 交互；不按历史 issue 分组，也不断言模板源码文本。
+
+组合覆盖使用固定 pairwise answers 做快速边界检查，并对 minimal、default、两种 ORM、Agent+Logfire 和 Redis consumers+Taskiq 等代表剖面做深测。只允许 OpenAPI 等窄机器契约使用归一化快照，不保存完整生成树 golden。
 
-修改时先运行最窄的相关测试和 `uv run ty check`。涉及模板条件时必须运行 `uv run python scripts/lint_template.py`，并至少渲染一个受影响配置。交付前运行完整 `uv run pytest`、Ruff check、Ruff format check 和 ty。需要 PostgreSQL/Redis 的验收使用 Docker 随机映射端口，结束后必须清理容器。
+`uv run pytest` 是完整放行入口；开发时可用 marker 或测试路径筛选。涉及模板条件时还必须运行 `uv run python scripts/lint_template.py`。交付前运行完整 pytest、Ruff check、Ruff format check 和 ty。PostgreSQL、Redis、Docker 与 Nginx 验收使用随机端口并在 teardown 中清理。
 
 不要提交生成项目、虚拟环境、缓存、coverage 产物、`.env`、凭据或本地数据库。
 

CONTEXT.md

@@ -4,33 +4,25 @@
 
 ## Language
 
-**减法迁移（Subtractive Migration）**：
-以 `legacy/` 对应实现为规范性基线，仅减去 V1 删除能力及其引用，并叠加已封闭列举的必要迁移变换与批准差异；不包含借迁移进行的重构、重命名或重新设计。
-_Avoid_：参考实现、prior art、重新实现、现代化改造
+**原生演进基线（Native Evolution Baseline）**：
+以 Copier 公开问题与生成边界、生成项目公开 API 和运行行为共同定义的产品契约；模板实现、历史迁移来源和输出快照都不是规范。
+_Avoid_：历史实现基线、内容等价门禁、当前测试即规范
 
-**V1 能力边界（V1 Capability Boundary）**：
-V1 已确认的保留能力与删除能力集合；迁移实现不得以重新设计为由扩张或缩减该集合。
-_Avoid_：候选能力、待定范围、迁移建议
+**公开产品契约（Public Product Contract）**：
+调用方可观察并依赖的 Copier 输入与生成边界，以及生成项目的开发接口、HTTP API 和运行行为。
+_Avoid_：实现细节、文件内容快照、历史实现 contract
 
-**默认生成剖面（Default Generation Profile）**：
-调用方不覆盖任何答案时生成的能力组合；保留能力的默认启用状态属于 legacy 行为，不因迁移到 Copier 而改变。
-_Avoid_：lean default、推荐组合、新默认值
+**契约保持切换（Contract-preserving Cutover）**：
+在不改变现有公开产品契约的前提下，将规范来源和验收架构一次性切换到原生演进基线；产品行为变更必须另行决策。
+_Avoid_：顺带重设计、迁移即改版、自由清理
 
-**保留能力开关（Retained Capability Toggle）**：
-legacy 中用于启用或关闭某项 V1 保留能力的用户选择；迁移后继续表达同一选择，且默认值不变。
-_Avoid_：冗余选项、固定能力、实现细节
+**文档化开发接口（Documented Development Interface）**：
+生成项目文档明确承诺的文件、命令、环境变量、import 和扩展 seam；未文档化内部模块、符号及源码文本不属于兼容面。
+_Avoid_：全部生成实现、偶然可导入符号、源码快照
 
-**对应实现（Corresponding Implementation）**：
-`legacy/` 中承载同一保留能力、公开 contract 或运行行为的具体文件、符号与测试，是目标文件进入 V1 的可追溯来源。
-_Avoid_：灵感来源、相似示例、参考架构
-
-**批准差异（Approved Deviation）**：
-相对对应实现的显式例外，必须记录原因、最小影响范围和独立验收；未记录差异一律视为迁移回归。
-_Avoid_：顺手优化、合理调整、等价重构
-
-**迁移等价性（Migration Equivalence）**：
-目标生成树在扣除已声明的路径、条件、删除引用、兼容修改与批准差异后，与 legacy 对应实现的内容和行为一致。
-_Avoid_：大致一致、功能相似、测试能过
+**迁移兼容垫片（Migration Compatibility Shim）**：
+仅为复现迁移前实现或绕过迁移期依赖差异而存在的版本限制、workaround 或兼容分支；不包括公开产品契约或模型接口的协议兼容性。
+_Avoid_：所有 compatibility、公开兼容承诺、Chat Completions-compatible
 
 **后端服务（Backend Service）**：
 通过 API 对外提供算法、智能体或其他业务能力的统一服务类型。

README.md

@@ -0,0 +1,18 @@
+# Copier FastAPI Forge
+
+用于生成可组合 FastAPI 后端服务的原生 Copier 模板。公开 questions、能力生成边界和生成项目行为见 [`docs/product-contract.md`](docs/product-contract.md)。
+
+```bash
+uv sync --all-groups
+uv run copier copy --defaults . <output-dir>
+```
+
+模板维护者使用以下命令执行完整质量检查：
+
+```bash
+uv run python scripts/lint_template.py
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run pytest
+```

docs/adr/0012-use-subtractive-migration.md

@@ -1,5 +1,5 @@
 ---
-status: accepted
+status: superseded by ADR-0015
 ---
 
 # 以 legacy 对应实现执行减法迁移

docs/adr/0013-revise-v1-migration-boundary.md

@@ -1,5 +1,5 @@
 ---
-status: accepted
+status: superseded by ADR-0015
 ---
 
 # 修订 V1 迁移边界与批准差异

docs/adr/0014-require-migration-equivalence-acceptance.md

@@ -1,5 +1,5 @@
 ---
-status: accepted
+status: superseded by ADR-0015
 ---
 
 # 以迁移等价性逐项验收 V1

docs/adr/0015-adopt-native-evolution-baseline.md

@@ -0,0 +1,13 @@
+---
+status: accepted
+---
+
+# 采用原生演进基线
+
+V1 减法迁移已经完成，继续以历史模板文件、归一化 diff 和迁移内容摘要定义正确性会冻结实现细节，并使已经稳定的原生 Copier 模板无法独立演进。项目改以公开产品契约为唯一规范：Copier questions 与生成边界、文档化开发接口，以及生成项目的 HTTP、CLI 和运行行为共同定义正确性；源码文本、完整生成树快照、历史来源和当前测试实现都不是规范。
+
+本次切换保持现有公开产品契约不变。先让按契约领域组织的新 pytest 验收与旧迁移门禁同时通过，再在同一变更中删除历史模板 fixture、trace、comparison、内容摘要、兼容垫片及无用依赖。测试保留固定 pairwise 配置和代表性深测剖面，主要使用语义断言，仅对 OpenAPI 等完整机器契约使用窄范围归一化快照；生成应用必须在自己的依赖环境中运行，GitHub Actions 只调用 pytest 验收入口。
+
+未来可以显式修改公开产品契约，但必须在同一变更中更新产品契约文档和行为测试。breaking change 采用明确的 clean cutover；兼容期只有在单独说明范围、期限和删除条件时才能引入，不因历史行为默认保留 shim。`copier update` 不在本次契约内。
+
+本 ADR 取代 ADR-0012、ADR-0013 和 ADR-0014。旧 ADR 保留迁移历史，但不再约束当前实现。