将 vigiles spec 中 guidance()…

当需要强化 vigiles spec 的 guidance() 规则，使其可由已启用或可配置的 linter 规则强制执行时使用。

适用场景

解决思路

1. 原则：区分成本而非严格度；对已存在且已启用的 linter 规则的 guidance()->enforce() 直接替换（Tier 1），这是纯收益、可逆、无假阳性风险，应直接应用。
2. 原则：任何有成本的变更（编辑 linter 配置、安装插件，或可能让干净 CI 失败）都由用户决定：说明权衡并让用户选择（Tier 2-4）。
3. 原则：绝不静默编辑配置、安装依赖，或把仓库升级为严格门禁；这是把 init 的执行模型（结构性默认开启，工作流/严格需选择加入）应用到编辑时。
4. Step 0：询问用户选择模式：Auto 或 interactive？Auto：应用所有安全变更（规则已启用时的直接替换），提交并展示 diff；有风险的变更（需要配置编辑或插件安装）放入摘要供 review。Interactive：逐条展示建议，由用户选择应用哪些。若用户未指定，默认 interactive。
5. Step 1：运行 `npx vigiles generate types` 获取项目中已启用 linter 规则的完整列表。
6. Step 1：读取 `.vigiles/generated.d.ts`，查看所有检测到的 linter 中可用的每条规则。
7. Step 1：记录生成的类型中出现了哪些 linter 前缀（例如 `EslintRule`、`RuffRule`）；只需要为检测到的 linter 查阅参考文档。
8. Step 2：在项目中查找所有 `.spec.ts` 文件（`**/*.md.spec.ts`）。对每个文件，识别每一条 `guidance()` 规则。
9. Step 3：对每条 guidance 规则，检查 `.vigiles/generated.d.ts` 中是否有已启用的规则直接匹配。这是快速、确定性的路径，无需读文档。
10. Step 3：匹配时查找：文本中的精确规则名（例如 guidance 说 `no-console`，`no-console` 在 `EslintRule` 中）；语义匹配（例如 guidance 说 `don't use console.log`，`no-console` 可用）；规则描述匹配（例如 guidance 说 `unused variables`，`no-unused-vars` 或 `@typescript-eslint/no-unused-vars` 可用）。
11. Step 3：如果找到匹配且规则在生成的类型中（即已启用），这是直接替换——无需配置变更。
12. Step 4：对 Step 3 未匹配的 guidance 规则，读取项目已检测 linter 的 linter 参考文档：ESLint → `../linter-docs/eslint.md`；Stylelint → `../linter-docs/stylelint.md`；Ruff → `../linter-docs/ruff.md`；Pylint → `../linter-docs/pylint.md`；RuboCop → `../linter-docs/rubocop.md`；Clippy → `../linter-docs/clippy.md`。
13. Step 4：只读取项目实际使用的 linter 的文档；跳过在生成类型中没有规则的 linter 的文档。
14. Step 4：检查插件表和决策矩阵。guidance 文本可能描述的模式由以下覆盖：已安装但未启用的插件规则；尚未安装的插件；`no-restricted-*` 配置模式（见 Step 4b）。
15. Step 4b：许多 guidance 规则可以通过内置 linter 配置强制执行，而无需自定义规则；这是最常见的 strengthen 模式——「不要做 X」映射到限制配置。
16. Step 4b：ESLint 示例：用 `no-restricted-imports` 的 `patterns` 配置禁止从内部模块导入；用 `no-restricted-syntax` 的 `selector` 配置禁止调用 `console.log`；用 `no-restricted-imports` 的 `paths` 配置禁止使用 `moment.js`。
17. Step 4b：Ruff 示例：在 `[tool.ruff.lint.flake8-tidy-imports.banned-api]` 中配置禁用 `os.system` 的消息。
18. Step 4b：RuboCop 示例：如果 `Rails/Output` 不合适，可配置 `Custom/NoPuts` 启用。
19. Step 4b：建议 `no-restricted-*` 变更时：1) 展示所需的确切配置编辑（哪个文件、哪个部分）；2) 展示引用它的 `enforce()` 规则；3) 说明这会改变 linter 配置，而不仅仅是 spec。
20. Step 5：将输出分组为层级：Tier 1 直接替换（规则已启用，零风险），示例：before `no-console: guidance(Use structured logger instead of console.log)`，after `no-console: enforce(eslint/no-console, Use structured logger instead of console.log)`。
21. Step 5：Tier 2 配置支持（规则存在但需要配置选项），示例：spec 改为 `no-moment: enforce(eslint/no-restricted-imports, Use dayjs instead of moment.)`，并需要在 `eslint.config.mjs` 中配置 `no-restricted-imports` 的 paths。
22. Step 5：Tier 3 需要安装插件，示例：`cognitive-complexity: guidance(Keep functions simple)` → 安装 `eslint-plugin-sonarjs`，启用 `sonarjs/cognitive-complexity` → `enforce(eslint/sonarjs/cognitive-complexity, Keep functions simple)`。
23. Step 5：Tier 4 无匹配（保持为 guidance——未来规则合成技能的候选），示例：`research-first: guidance(Google unfamiliar APIs first.)` → 没有 linter 规则可强制执行，目前保持 guidance；自定义规则合成已计划但尚未发布。
24. Step 6 Auto mode：1) 应用所有 Tier 1 变更（编辑 spec 文件，把 `guidance()` 替换为 `enforce()`）；2) 运行 `npm run build && npx vigiles compile` 验证每个变更可编译；3) 如果任何编译失败，回滚该特定变更并报告错误；4) 提交所有成功变更；5) 将 Tier 2-4 作为摘要呈现给用户 review。
25. Step 6 Interactive mode：1) 呈现所有 tiers；2) 询问用户要应用哪些建议；3) 对批准的 Tier 2 变更：先编辑 linter 配置，再编辑 spec；4) 运行 `npm run build && npx vigiles compile` 验证；5) 如果编译失败，报告错误并回滚。
26. Step 6：对于 Tier 4（无匹配）：告诉用户这些规则保持为 guidance——自定义规则合成是已计划技能，尚不可用。

适用边界 · 注意事项

• 不适用于一般性 lint 或修复 lint 错误。
• 不适用于没有 vigiles spec、`.spec.ts` 文件或 `guidance()` 规则的项目。
• 不适用于无法映射为现有或可配置 linter 规则的 guidance 规则；这些应保持 guidance，不要强行 enforce。