文档与功能同步治理升级

1. 结论

本次不再增加一份手写功能目录，也不让脚本假装理解业务语义。治理核心是：

人声明文档影响，机器验证声明、路径、暂存状态和可重复生成结果。

先以 Google Maps 采集主流程建立一页用户视角产品文档，再让现有文档分类、索引、检查、提交和发布流程认识这层文档。历史文档不批量迁移。

2. 背景与问题

当前仓库已有 raw / specs / wiki / issues / rules / changelog，但各层回答的是来源、计划、实现知识、故障经验和工作流，缺少一份明确描述“用户现在能做什么”的当前产品行为文档。

现有 pnpm docs:check 能检查 frontmatter、INDEX 收录和 wikilink，但不能阻止这些漂移：

• 功能代码变化后，没有任何文档影响声明；
• README 版本和真实 package.json 版本可能不一致；
• README 可能引用已经移动的规则文件；
• 自动生成的 INDEX 可以长期未重建，检查仍通过；
• 提交门禁只要求 ISSUE / SPEC 关联，不验证受影响文档是否和代码一起暂存。

3. 目标与非目标

3.1 目标

1. 新增 docs/product/，只描述用户可见的当前产品行为，并先完成一个主流程试点。
2. 所有包含产品影响路径变更的提交都必须显式填写 Docs-Impact trailer。首期产品影响路径为 src/** 和 wxt.config.ts。
3. 非 none 的文档路径必须存在，且必须在同次提交中暂存。
4. none 必须带具体理由，不能只写裸 none。
5. 提供不写工作区的文档重建一致性检查。
6. 提供统一的日常验证命令和发布一致性检查。
7. 保持当前轻量 frontmatter parser，不引入新的 YAML 依赖。

3.2 非目标

• 不新增手写 docs/catalog/features.json 或其他重复事实源。
• 不做所谓“业务语义自动判断”。
• 不根据 diff glob 自动猜测具体应该更新哪篇文档。
• 不一次迁移现有全部历史文档。
• 不创建没有真实用例的空测试目录。
• 不在本期强制增加 GitHub Actions 或修改远端分支保护。
• 不要求每种改动同时创建 product / spec / wiki / issue / test 全套文档。

4. 文档职责边界

层	回答的问题	本期动作
product	用户现在如何使用、会看到什么、限制是什么	新增并试点
specs	接下来要做什么、如何验收	保留
wiki	当前技术实现和字段语义是什么	保留
issues	出过什么问题、如何修复	保留
rules	团队遇到某类工作时怎么做	补充治理规则
raw	原始输入和证据是什么	保留
changelog	每个版本发生了什么	保留

产品文档不得复制 Wiki 的实现细节，也不得复制 Issue 的故障复盘。它只保留用户完成任务所需的信息，并链接到相关工程文档。

5. Docs-Impact 提交契约

首期以一份明确、保守的路径列表判断“是否必须声明”，不判断“具体应该更新哪篇文档”：

• src/**：产品运行代码；
• wxt.config.ts：扩展名称、权限、host permissions、入口和 manifest 行为配置。

package.json 暂不作为 Docs-Impact 触发路径：依赖和开发脚本变动不必然改变产品行为；版本与发布一致性由 release:check 单独约束。若未来出现稳定的用户可见 package 字段，再通过评审扩展触发列表。

5.1 有文档影响

Docs-Impact: docs/product/google-maps-collection.md, docs/wiki/multi-stage-scrape-pipeline.md

机器只验证：

1. trailer 存在且只能有一条；
2. 路径位于 docs/ 且以 .md 结尾；
3. 路径在提交后的索引中存在；
4. 路径出现在本次 staged 变更中。

5.2 无文档影响

Docs-Impact: none — 删除未引用 JWT 辅助文件，不改变用户路径、接口或配置语义

none 后必须有非空、具体的理由。门禁不判断理由是否“业务上正确”，评审者负责判断。

5.3 兼容现有门禁

现有 ISSUE / SPEC 关联规则继续生效；Docs-Impact 是额外契约，不替代问题归档和规格关联。

6. 实施拆分与串行门禁

每一项均遵守“修改 → 验证 → 独立对抗审查 → PASS 后进入下一项”：

• 修复 README 版本与规则路径漂移。
• 新增 docs/product/INDEX.md 和 Google Maps 采集主流程产品文档。
• 扩展 docs_lib.py，让 product 成为正式文档层。
• 扩展 check-docs.py，检查 product INDEX 收录。
• 扩展 rebuild-docs.py，生成 product INDEX 与相关汇总。
• 更新 mkdocs.yml、docs/README.md、目录规范和治理规则。
• 实现 docs:rebuild:check，在临时目录比较生成结果，不写当前工作区。
• 扩展 commit-msg hook，执行 Docs-Impact 契约。
• 在隔离临时 Git 仓库验证 hook 的通过与拒绝路径。
• 新增无业务写入的统一 verify，并关闭 pnpm 11 的 script 前自动 install。
• 六个 diff 扫描器对缺失/损坏/非法 baseline fail closed，且合法空 baseline 可用。
• ISSUE audit grep 支持 expect: absent（默认）、expect: present、paths 与仅供 present 使用的 allow_paths；扫描 scope 内全部 UTF-8 普通文本文件并明确跳过含 NUL 或非法 UTF-8 的二进制；pattern / description / paths / allow_paths 必须加引号，expect 只允许加引号或精确、区分大小写的 plain absent / present；顶层只接受无缩进 plain audit_grep: 或 audit_grep: []，quoted key、冒号前空格、根级缩进、重复 key 均拒绝；显式 tag、inline comment、block scalar、无法识别的对象行、重复字段等未支持 YAML 形态与空字段、symlink 一律 fail closed；默认 scope 的全部后代普通文本均扫描，不按同名目录额外排除，任何后代目录不可枚举时退出 2；正确解码 YAML 双引号转义并可靠执行跨行/PCRE 风格历史 pattern；未知字段、非法路径/正则或 grep 执行失败返回退出码 2，不再伪装为通过。
• 新增只检查的发布专用 release:check。
• 运行最终编译、文档检查、扫描和独立总审查。

7. 验收标准

7.1 文档层

• docs/product/INDEX.md 被分类器识别为 product，不是 root。
• 产品试点页包含用户前提、入口、流程、采集范围、状态/错误、限制和可验证操作。
• pnpm docs:check 能发现 product 文档漏收录。
• MkDocs 导航能访问产品文档。

7.2 重建一致性

• pnpm docs:rebuild:check 在干净且已同步的文档树上退出 0。
• 人工制造 INDEX 漂移时退出非 0，并列出漂移文件。
• 命令结束后 git status --short 不新增变化。

7.3 Docs-Impact

隔离测试至少覆盖：

• src/ 变更但无 trailer：拒绝。
• wxt.config.ts 变更但无 trailer：拒绝。
• 写了不存在的文档路径：拒绝。
• 文档存在但未 staged：拒绝。
• Docs-Impact: none 无理由：拒绝。
• 合法路径且文档同时 staged：通过。
• 合法 none — 具体理由：通过。
• 没有产品影响路径变更：不强制 trailer。
• 仅修改 docs/** 或 scripts/**，且未修改 src/** / wxt.config.ts：不强制 trailer。

7.4 日常与发布门禁

• pnpm verify 串行执行类型检查、文档检查、治理脚本测试和现有静态扫描，不修改业务数据、版本号、changelog 或构建产物。
• pnpm-workspace.yaml 的 verifyDepsBeforeRun: false 在 script body 之前关闭 pnpm 自动安装；依赖未准备时前置脚本退出 2，提示人工运行 pnpm install，且不创建 node_modules、.wxt 或 postinstall sentinel。
• 六个 baseline diff 扫描器在基线缺失、损坏或 schema 非法时退出 2；合法 version: 1 + hits: [] 不误判；verify 通过 && 传播失败。
• scan:issue-coverage --strict 先解码 YAML scalar，以 grep -zE 做跨行预选排序，但 grep 的候选结果绝不缩小最终扫描集合；随后用原始完整 Python 正则精确扫描全部已枚举 UTF-8 文本，兼容 \\A / \\Z、[\\s\\S]、JS [^]、lazy quantifier、大上限和负向前瞻。仅 grep rc=1 视为有效 0 预选；非法正则、grep rc>1 或执行异常均报告 ISSUE、pattern、stderr/异常并退出 2。
• pnpm release:check 只检查、不构建、不生成 changelog。准备构建产物仍使用既有 pnpm build；生成根 changelog 仍使用既有 pnpm docs:changelog。
• release:check 的必需输入为 package.json、dist-v2/chrome-mv3/manifest.json、docs/changelog/development-log.md 和根 CHANGELOG.md；任一缺失都退出非 0。
• 精确解析 package.json.version 与 manifest JSON 的 version，两者必须字符串全等。
• docs/changelog/development-log.md 必须存在一条非模板 ## 标题，标题中包含当前 v<package version>。
• 根 CHANGELOG.md 必须存在精确标题前缀 ## [v<package version>]。
• manifest 缺失、manifest 版本不符、开发日志缺当前版本、根 changelog 缺当前版本四类负向用例均退出非 0，并报告具体文件和修复动作。
• 失败信息不得自动修改版本、重跑 build 或重生成 changelog。

8. 回滚策略

• 所有治理能力均落在文档、脚本、package scripts 和本地 hooks 中，不改变业务数据模型。
• 若新门禁误拦截，先回滚对应脚本和 hook 变更；不得用长期 --no-verify 代替修复。
• docs/product/ 是新增层，回滚时删除导航与分类支持后再删除试点页，不影响原五层知识库。

9. 已知边界

• 本地 hook 可被 --no-verify 绕过，因此它是默认工作流约束，不是不可绕过的安全边界。
• 当前没有 tracked 自动化业务测试；本期只对新增治理脚本建立可重复的命令级验证，不虚构业务测试覆盖。
• GitHub Actions 和分支保护需在确认远端 PR 工作流后另开 SPEC。

10. 决策记录

• 2026-08-23：否决手写 features.json，避免制造重复事实源。
• 2026-08-23：否决伪语义检查和 diff-glob 业务推断，改为显式 Docs-Impact 声明。
• 2026-08-23：产品文档只做 Google Maps 采集主流程试点，不批量迁移历史文档。
• 2026-08-23：自动测试暂不作为所有业务改动的统一硬门槛，允许记录明确的人工浏览器验证证据。