From af6088737f489ab33abbd18ae3a59fff375d6839 Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Sun, 25 Oct 2026 14:26:05 +0800
Subject: [PATCH 1/2] =?UTF-8?q?fix(checks):=20=E7=BB=9F=E4=B8=80=E6=A0=BC?=
 =?UTF-8?q?=E5=BC=8F=E4=B8=8E=20lint=20=E5=85=A5=E5=8F=A3=E5=92=8C?=
 =?UTF-8?q?=E7=BB=B4=E6=8A=A4=E8=8C=83=E5=9B=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 复用 PDM 检查并补齐本地 hook 安装要求
---
 .pre-commit-config.yaml                       | 11 +++++++++--
 CONTRIBUTING.md                               |  5 +++++
 docs/40-deployment/development-environment.md |  2 ++
 ruff.toml                                     |  3 ++-
 4 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e5e0ba04..ff5ed50e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -11,10 +11,17 @@ repos:
     hooks:
       - id: check-format
         name: Check Ruff formatting
-        entry: ruff format --check .
+        entry: pdm run format:check
         language: system
         files: ^(.*\.py|pyproject\.toml|ruff\.toml)$
-        exclude: ^(cli/|\.agents/)
+        exclude: ^(cli/|\.agents/|tasks/)
+        pass_filenames: false
+      - id: check-lint
+        name: Check Ruff lint
+        entry: pdm run lint
+        language: system
+        files: ^(.*\.py|pyproject\.toml|ruff\.toml|\.pre-commit-config\.yaml)$
+        exclude: ^(cli/|\.agents/|tasks/)
         pass_filenames: false
       - id: typecheck
         name: Check Pyrefly types
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index feae76bc..1578d011 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,7 @@ bugs that do not cross a security boundary.
 ```bash
 git submodule update --init --recursive
 pdm install -G dev --frozen-lockfile
+pdm run pre-commit install
 pdm run doctor
 pdm run check
 ```
@@ -23,6 +24,10 @@ pdm run check
 `.python-version` is the shared Python runtime anchor. CI installs PDM 2.28.0, and
 `doctor` reports a mismatch when the local toolchain does not match that contract.
 
+Git hook 需要在每个本地 checkout 安装；提交前会执行与 CI 相同的格式和 lint 入口。
+移动仓库目录后，需要重建含旧绝对路径的虚拟环境入口并重新安装 hook；CI 的完整
+`check` 仍是交付检查依据。
+
 `check` is the same hermetic repository gate used by CI. It verifies the lock and
 requirements export, migration configuration and append-only baseline, Ruff formatting,
 repository lint, and static types. Use narrower commands while iterating:
diff --git a/docs/40-deployment/development-environment.md b/docs/40-deployment/development-environment.md
index fda0d527..42dcbd34 100644
--- a/docs/40-deployment/development-environment.md
+++ b/docs/40-deployment/development-environment.md
@@ -103,6 +103,8 @@ pdm run dev
 repository contract checks tool versions, lock/export consistency, migration integrity,
 formatting, lint, settings isolation, and the complete unit-test suite.
 
+格式与 lint 的范围由 `ruff.toml` 拥有，覆盖正式源码、测试与脚本。`tasks/` 是临时实验材料，`.agents/` 是独立维护的技能；二者不参与产品门禁。成为正式验证步骤的实验应迁入 `scripts/` 或 `tests/`。已发布迁移保持不可变；独立 CLI 使用 `pdm run --project cli check` 及自己的 CI。pre-commit 的格式与 lint 钩子复用 `pdm run format:check` 和 `pdm run lint`，CI 的完整入口仍为 `pdm run check`。
+
 Use narrower read-only checks while iterating:
 
 ```bash
diff --git a/ruff.toml b/ruff.toml
index 80297420..d1b4b67b 100644
--- a/ruff.toml
+++ b/ruff.toml
@@ -1,6 +1,7 @@
 line-length = 92
 indent-width = 2
-extend-exclude = ["migrations/versions", "*.md", "cli", ".agents"]
+# Task probes are disposable evidence; maintained checks belong in scripts/ or tests/.
+extend-exclude = ["migrations/versions", "*.md", "cli", ".agents", "tasks"]
 
 [format]
 indent-style = "space"

From a44a6b57cc338131073fe49b87300276cbc052a8 Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Sun, 25 Oct 2026 14:32:38 +0800
Subject: [PATCH 2/2] =?UTF-8?q?fix(ci):=20=E5=AF=B9=E9=BD=90=E5=8F=97?=
 =?UTF-8?q?=E4=BF=9D=E6=8A=A4=E5=88=86=E6=94=AF=E8=A6=81=E6=B1=82=E7=9A=84?=
 =?UTF-8?q?=E6=A3=80=E6=9F=A5=E5=90=8D=E7=A7=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 保留原有检查内容与分支保护约束
---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 12cbab67..daeea412 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,7 +30,7 @@ jobs:
         run: bash scripts/automation/cli_publication.sh check-build
 
   repository:
-    name: Hermetic repository contract
+    name: impl-py checks
     runs-on: ubuntu-latest
     services:
       postgres:
@@ -105,7 +105,7 @@ jobs:
         run: pdm run pre-commit run --all-files
 
   artifact:
-    name: Portable peer database runtime
+    name: impl-py e2e tests
     runs-on: ubuntu-latest
     services:
       postgres: