feat: harden contribution and map validation

[tommywutong]

背景

仓库已经有源码地图、版本清单、教学提示词和 Shell 更新脚本，但贡献入口较短，地图与提示词的静态结构没有 CI 保护。此 PR 补齐贡献者需要的执行规则，并增加不依赖上游下载的完整性检查，降低地图入口漂移和教学路由失效的风险。

改动

1. 扩展 CONTRIBUTING.md

补充以下可执行规则：

• 本地准备和 bootstrap.sh --check 用法；
• 全量源码下载约 2–3 GB，以及只下载单个 target 的建议；
• 源码目录是只读的独立上游仓库，不应提交到本仓库；
• 地图正文必须写在 maps/**/AGENTS.md，不要直接在源码目录创建游离文件；
• 地图允许/禁止的内容、200 行约束、版本与行号维护要求；
• 新增源码只能更新 sources.sh 和 .gitignore 相关配置，不应复制清单到三个脚本；
• 教学方法、表达风格和 Skill 的贡献边界；
• 提交前的 Shell、地图和提示词验证要求；
• PR 正文应记录模块、源码版本、行号影响、验证结果和未决取舍。

2. 增加 tests/maps-integrity.test.sh

新增静态地图完整性检查，故意不下载上游源码，因此可以在全新 clone 上运行。检查内容包括：

• 每个受版本控制的地图正文不超过 200 行；
• 每个 AGENTS.md 都有对应的 CLAUDE.md；
• CLAUDE.md 保持三行指针并指向 AGENTS.md；
• 所有教学提示词路由目标存在；
• sources.sh 的 11 个 target 都有对应的地图根目录；
• 地图正文与 Claude 入口数量一致，不把地图数量硬编码为固定值。

3. 增加 tests/prompts-integrity.test.sh

新增教学提示词路由检查，验证：

• 默认教学方法唯一；
• 默认表达风格唯一；
• 索引登记的默认、可选方法和默认风格文件都存在；
• 渐进式方法的首轮限制、理解检查、等待和退出条件仍存在；
• 面试风格声明为局部覆盖，并保留追问数量、直接回答和真实性约束。

该测试只验证稳定的配置契约，不尝试对 LLM 的自然语言输出做脆弱的快照测试。

4. 接入 Shell CI

在 .github/workflows/shell-tests.yml 中加入：

./tests/maps-integrity.test.sh
./tests/prompts-integrity.test.sh

现有 Shell 回归测试保持不变。

5. 修正一处源码地图路径

maps/swift-foundation/AGENTS.md 中将 AsyncMessage.swift 修正为实际路径：

NotificationCenter/AsyncMessage.swift:117 / :125

该路径已对照本地准备好的 Swift Foundation 工作区验证，当前文件为 Sources/FoundationEssentials/NotificationCenter/AsyncMessage.swift。

有意不包含的内容

README 状态漂移原本属于候选改动，但现有 PR #13 已经专门负责 README 重构。为避免与维护者正在审阅的 PR 重复，本 PR 不修改 README.md；README 的数量、目录和视觉结构由 #13 统一处理。

本 PR 也不修改上游源码版本、生产配置、GitHub Actions 的第三方 workflow pin，避免扩大变更边界。

提交拆分

• 8b0f1c4 docs: expand contribution guide
• 68cd0e6 test: validate source map integrity
• 294d0f7 test: validate teaching prompt routes
• 681ba7b docs: fix async message map path
• a03e798 test: avoid hardcoded map count

验证

以下命令均已在本分支执行并通过：

bash -n bootstrap.sh check-updates.sh update-sources.sh progress.sh tests/*.sh
./tests/progress.test.sh
./tests/track-ref.test.sh
./tests/check-updates-status.test.sh
./tests/maps-integrity.test.sh
./tests/prompts-integrity.test.sh
git diff --check

源码证据检查：

• ./check-updates.sh objc4 在当前仓库因没有本地源码返回缺失提示；未静默下载源码；
• 已使用准备好的本地源码工作区核对 objc4，检查结果为 UPTODATE；
• 已核对 CFRunLoop.c 3955 行、objc-runtime-new.mm 9959 行、Apple queue.c 9085 行；
• 已核对 Swift Foundation AsyncMessage.swift 的 117/125 行路径。

审查重点

1. tests/maps-integrity.test.sh 是否符合维护者对地图目录和未来新增 target 的预期；
2. sources.sh target 到地图根目录的显式映射是否应在未来抽象成清单字段；
3. CONTRIBUTING.md 的规则是否需要进一步与合并策略、Issue 模板或许可证政策对齐。

[github-actions]

PR Review Swarm

⚠️ 本次审核未完整覆盖，结论可能不完整。

未完成的阶段/范围：

• any_required_stage_failed

Verdict: incomplete
Incomplete reasons: any_required_stage_failed

Findings (0):

• (none)

[tommywutong]

跟进：补齐贡献入口与地图链接校验

在上一次提交后继续盘点并追加两项低风险、可验证的改进：

1. 新增 .github/pull_request_template.md

   • 将贡献指南里的目标/版本、地图影响、验证命令、审查边界转为提单默认字段；
   • 明确禁止提交上游源码、缓存和凭据。

2. 新增 .github/ISSUE_TEMPLATE/

   • bug_report.md 要求最小复现、check-updates.sh -v <target> 版本输出和地图 文件:行号；
   • source-map.md 要求上游版本、权威性边界、行号校对和 --maps-only 挂载计划；
   • 保留自由 Issue 入口。

3. 扩展 tests/maps-integrity.test.sh

   • 校验每份地图正文中的受版本控制相对 AGENTS.md 链接；
   • 链接必须落在 maps/ 中且目标受 Git 追踪；
   • 不检查 bootstrap 后才存在的上游源码路径，因此干净 clone 下仍可运行。

新增提交：

• b1e5ef9 docs: add contribution templates
• e6f2e0d test: validate internal map links

完整回归已重新通过：

bash -n bootstrap.sh check-updates.sh update-sources.sh progress.sh tests/*.sh
./tests/progress.test.sh
./tests/track-ref.test.sh
./tests/check-updates-status.test.sh
./tests/maps-integrity.test.sh
./tests/prompts-integrity.test.sh
git diff --check

当前自动 Shell CI 为 pass。PR Review Swarm 的所有可见执行阶段均为 pass，但最终 verdict 仍是 incomplete（any_required_stage_failed，Findings: 0）；这没有产生代码级修改项，需要维护者检查审查工作流的 required-stage 配置或重新运行。