📚 docs(governance): 强化 Issue/PR 元数据编码与证据规范

[ZhaoXingPeng]

关联 Issue

Closes #149

本 PR 建立 Issue、PR 和提交元数据的可执行规范，修复历史正文不可审计的问题。

背景（Situation）

历史 PR/Issue 出现章节缺失、字面量转义、控制字符和连续问号，导致 GitHub 展示不可读，验证结果与实验边界难以追溯。旧 metadata job 只检查少量标题和章节信号，空章节或模板内容仍可能进入审查。

任务（Task）

统一 Gitmoji + Conventional Commits 标题、PR 七段正文、Issue bug/feature 正文和阶段性回帖粒度；提供 UTF-8、章节顺序、非空内容和关联 Issue 的自动校验，不改变运行时 API。

行动（Action）

• 扩展 scripts/validate_commit_title.py，检查替代字符、连续问号、控制字符、字面量换行转义和模板内容。
• 新增 Issue 正文校验与 issues event 入口，检查章节顺序和非空内容。
• 更新 PR/Issue 模板、CONTRIBUTING.md 和工程规范，固定验证、证据、风险和回滚章节。
• 增加历史元数据审计记录与阶段性回帖模板。
• 没有做：未重写已合并 commit hash，未改变运行时 MCP、数据库、依赖或发布物。

验证（Verification）

环境：Windows；Python 3.10.1；pytest 9.0.3；Ruff。

• 单元测试：687 passed in 7.91s。
• Ruff check：All checks passed。
• 修改文件格式检查：2 files already formatted。
• git diff --check：无输出。
• 标题校验与远端 PR/Issue 正文审计返回 OK。

实验与证据（Evidence）

校验输入覆盖合法 UTF-8、替代字符、连续问号、字面量转义、控制字符和模板内容。章节解析按 Markdown heading 定位并截取到下一个 heading，HTML 注释不会伪造正文；空章节、乱序章节和缺少 Closes/Refs 会明确失败。Issue 表单与手工 Markdown 的章节形式均有回归。

兼容性、风险与回滚

校验器是开发门禁，不改变运行时公共 API；严格门禁可能拒绝历史简短正文，应编辑正文修复而非绕过。Issue event workflow 只提供校验入口。恢复提交 ea00722 可撤销本主题；后续清理历史开放 PR 正文并在合并前核验 required checks。

[ZhaoXingPeng]

实现完成（2026-09-09）

当前结论

治理提交 ea00722 已将标题、PR 正文和 Issue 正文的编码/结构规则固化为可复用的纯 Python 校验器，并同步模板、贡献指南和历史审计文档。运行时 MCP/API、数据库适配器和依赖没有改变。

变更与设计取舍

• 提交：ea00722
• validate_title() 保留现有 Gitmoji/type/scope 映射，增加 U+FFFD、连续问号、控制字符、字面量反斜杠转义、通用占位符、无上下文标题和句末标点检测。
• validate_pr_body() 使用 heading 顺序截取章节，先移除 HTML 注释，再拒绝缺失或无实质内容的七段；这样模板说明不会成为误报，空章节仍会失败。
• 新增 validate_issue_body() 和 --issue-event，同时兼容工程规范名称与当前 bug/feature 表单生成的 heading 层级和同义标题。
• 采用本地纯函数而非网络请求，避免把 GitHub token 或运行时依赖引入 CI metadata 门禁。

验证与证据

• python -m pytest tests/unit/test_commit_metadata.py -q：17 passed。
• python -m ruff check scripts/validate_commit_title.py tests/unit/test_commit_metadata.py：All checks passed。
• 输入覆盖合法标题、原生 Unicode Emoji、U+FFFD、连续问号、伪换行、控制字符、空章节和模板占位符；测试文件为 tests/unit/test_commit_metadata.py。

兼容性与下一步

• 严格正文门禁可能要求旧客户端补齐章节；不涉及运行时兼容性。
• Issue 事件尚未接入独立 workflow，当前提供 CLI 和本地审计入口；验证完成后再决定是否单独增加 workflow。

[ZhaoXingPeng]

验证完成（2026-09-09）

当前结论

本地完整 unit suite 和本次修改文件的 Ruff 检查均通过；PR #148 与 Issue #149 的远端正文经 API 拉取后分别通过 validate_pr_body() 与 validate_issue_body()。这些结果证明治理规则和现有运行时代码测试兼容，不代表 CI、性能或真实数据库实验已通过。

变更与设计取舍

• 提交：ea00722
• 保留单一治理提交，便于 squash merge 前审查和回滚；未纳入用户已有未跟踪的 uv.lock。
• 历史审计文档区分不可变 commit object 与可编辑 GitHub title/body，避免声称重写历史。

验证与证据

• $env:PYTHONPATH='src'; python -m pytest tests/unit/ -q：687 passed in 7.91s，Windows Python 3.10.1。
• python -m ruff check src/ tests/ scripts/：All checks passed。
• python -m ruff format --check scripts/validate_commit_title.py tests/unit/test_commit_metadata.py：2 files already formatted。
• git diff --check：无输出。
• python scripts/validate_commit_title.py --title ":books: docs(governance): 强化 Issue/PR 元数据编码与证据规范"：OK。
• 远端 API 正文审计：PR 🐛 fix(codegen): 统一真实生成的 DTO 包路径 #148 OK，Issue 📚 docs(governance): 强化 Issue/PR 元数据编码与证据规范 #149 OK。
• 全仓 format check 报告 64 个基线文件需重格式化；本 PR 未修改这些文件，也未把该检查写成通过。

兼容性与下一步

• 未运行 CI、真实 MySQL/PostgreSQL、Maven 或性能基准；没有对应证据就不做结论。
• 按约定提交后不轮询 CI；准备 squash merge 时只检查最新 HEAD 的全部 required checks。
• 如需撤回，恢复 ea00722；后续可另开 Issue 接入轻量 issues event workflow。