chore: governance - tighten repo hygiene

scripts/lib/AGENTS.md

@@ -0,0 +1,9 @@
+# scripts/lib/ Agent 指南
+
+本目录是 `scripts/` 下质量门禁脚本的共享库。
+
+## 约束
+
+- 公共函数必须保持小而稳定，避免把具体业务规则塞进通用库。
+- 不允许在 import 阶段执行文件写入、网络访问或命令调用。
+- 变更后至少运行 `make test`，确认所有脚本入口仍可直接执行。

scripts/lib/README.md

@@ -0,0 +1,13 @@
+# scripts/lib
+
+共享脚本库，放置多个质量门禁共同使用的解析与校验辅助函数。
+
+## 当前模块
+
+- `taxonomy.py` - 读取 `metadata/taxonomy.yml`，输出目录分区和文档路径。
+
+## 约束
+
+- 只放无副作用的纯辅助逻辑。
+- 不在导入时读写仓库文件。
+- 修改公共函数后必须运行 `make test`。

scripts/lib/__init__.py

@@ -0,0 +1 @@
+"""Shared helpers for repository quality gate scripts."""

scripts/lib/taxonomy.py

@@ -0,0 +1,81 @@
+"""Helpers for reading the repository taxonomy file.
+
+The project intentionally keeps metadata in a small YAML subset so the quality
+gate scripts can run without extra Python dependencies.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+TAXONOMY = ROOT / "metadata/taxonomy.yml"
+
+
+def strip_quotes(value: str) -> str:
+    """Remove simple surrounding quotes from a taxonomy scalar."""
+    return value.strip().strip("\"'")
+
+
+def taxonomy_sections() -> dict[str, dict[str, str]]:
+    """Return top-level taxonomy sections keyed by section id."""
+    sections: dict[str, dict[str, str]] = {}
+    current: str | None = None
+    in_sections = False
+
+    for line in TAXONOMY.read_text(encoding="utf-8").splitlines():
+        if line == "sections:":
+            in_sections = True
+            continue
+        if in_sections and line and not line.startswith(" "):
+            break
+        if not in_sections:
+            continue
+
+        section_match = re.match(r"^  ([A-Za-z0-9_-]+):\s*$", line)
+        if section_match:
+            current = section_match.group(1)
+            sections[current] = {}
+            continue
+        field_match = re.match(r"^    (path|entry|agent_guide):\s*(.+?)\s*$", line)
+        if current and field_match:
+            sections[current][field_match.group(1)] = strip_quotes(field_match.group(2))
+
+    return sections
+
+
+def taxonomy_document_paths() -> list[str]:
+    """Return document path entries from metadata/taxonomy.yml."""
+    paths: list[str] = []
+    in_documents = False
+
+    for line in TAXONOMY.read_text(encoding="utf-8").splitlines():
+        if line == "documents:":
+            in_documents = True
+            continue
+        if in_documents and line and not line.startswith(" "):
+            break
+        if not in_documents:
+            continue
+
+        stripped = line.strip()
+        if stripped.startswith("- path:"):
+            _, value = stripped.split(":", 1)
+            paths.append(strip_quotes(value))
+
+    return paths
+
+
+def doc_readmes_from_taxonomy() -> dict[Path, list[str]]:
+    """Return docs README files and required main anchors from taxonomy."""
+    readmes: dict[Path, list[str]] = {}
+
+    for target in taxonomy_document_paths():
+        path_part, _, anchor = target.partition("#")
+        if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"):
+            continue
+        readmes.setdefault(Path(path_part), []).append(anchor)
+
+    return readmes