strengthen

扫描 spec 文件中的 guidance() 规则，并提出由真实 lint 规则支持的 enforce() 替换方案。

原则：免费收益自动处理，有代价的改动先征求意见

划分界线在于代价，而非严格程度。如果某条 lint 规则已存在且已启用，那么将 guidance() 替换为 enforce() 就是纯收益——免费、可撤销，且没有误报风险，因此应直接应用（下文的第 1 层）。任何需要付出代价的改动——修改 lint 配置、安装插件，或可能导致 CI 检查失败的改动——都由用户决定：明确说明其中的权衡，让用户选择（第 2 至 4 层）。绝不暗中修改配置、安装依赖，或将仓库升级为严格门禁模式。这是在编辑时应用 init 强制策略模型（默认启用结构规则，工作流／严格规则则选择启用）。

操作说明

第 0 步：选择模式

询问用户：

自动处理还是交互处理？

• 自动处理——我会应用所有安全的改动（直接替换已启用规则的情况）、提交改动，并展示差异。存在风险的改动（需要修改配置或安装插件）会汇总起来供你审核。
• 交互处理——我会逐项提出建议，由你选择要应用哪些。

如果用户未指定，默认采用交互处理。

第 1 步：检查已安装的内容

运行 npx vigiles generate types，获取项目中已启用 lint 规则的完整列表。阅读 .vigiles/generated.d.ts，查看所有已检测到的 linter 中可用的规则。

记录生成类型中出现的 linter 前缀（例如 EslintRule、RuffRule）。你只需要查阅已检测到的 linter 的参考文档。

第 2 步：查找所有 guidance 规则

查找项目中所有 .spec.ts 文件（**/*.md.spec.ts）。对每个文件，找出所有 guidance() 规则。

第 3 步：与生成的类型匹配（快速路径）

对每条 guidance 规则，检查 .vigiles/generated.d.ts 中是否有已启用的规则与之直接匹配。这是快速且确定的路径，无需阅读文档。

查找以下匹配：

• 文本中出现完全相同的规则名——guidance 写着“no-console”，而 EslintRule 中包含 no-console
• 语义匹配——guidance 写着“不要使用 console.log”，而 no-console 可用
• 规则描述匹配——guidance 写着“未使用的变量”，而 no-unused-vars 或 @typescript-eslint/no-unused-vars 可用

如果找到匹配，且该规则存在于生成的类型中（意味着它已启用），那么这就是直接替换——无需更改配置。

第 4 步：阅读 linter 文档（慢速路径）

对于第 3 步中未匹配的 guidance 规则，阅读项目中已检测到的 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

**只阅读项目实际使用的 linter 的文档。**如果某个 linter 在生成的类型中没有规则，则跳过其文档。

查看插件表和决策矩阵。guidance 文本描述的模式可能由以下规则覆盖：

• 已安装但未启用的插件规则
• 尚未安装的插件
• no-restricted-* 配置模式（见第 4b 步）

第 4b 步：no-restricted-* 模式

许多 guidance 规则可以通过内置的 linter 配置强制执行，无需自定义规则。这是最常见的强化模式——“不要做 X”可以映射为限制配置。

ESLint：

// "Don't import from internal modules"
"no-restricted-imports": ["error", {
  patterns: [{ group: ["src/internal/*"], message: "Use the public API." }]
}],

// "Don't call console.log"
"no-restricted-syntax": ["error", {
  selector: 'CallExpression[callee.object.name="console"]',
  message: "Use the project logger."
}],

// "Don't use moment.js"
"no-restricted-imports": ["error", {
  paths: [{ name: "moment", message: "Use dayjs instead." }]
}],

Ruff：

# "Don't use os.system"
[tool.ruff.lint.flake8-tidy-imports.banned-api]
"os.system".msg = "Use subprocess.run instead."

RuboCop：

# "Don't use puts in production" — if Rails/Output doesn't fit
Custom/NoPuts:
  Enabled: true

提出 no-restricted-* 改动时：

1. 展示所需的准确配置改动（具体文件和对应区块）
2. 展示引用该配置的 enforce() 规则
3. 说明这会更改 linter 配置，而不只是 spec

步骤 5：展示建议

按层级分组输出：

第 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"),

第 2 层：由配置支持（规则已存在，但需要配置选项）

// Spec change:
"no-moment": enforce("eslint/no-restricted-imports", "Use dayjs instead of moment."),

// Config change needed (eslint.config.mjs):
"no-restricted-imports": ["error", {
  paths: [{ name: "moment", message: "Use dayjs instead." }]
}],

第 3 层：需要安装插件

"cognitive-complexity": guidance("Keep functions simple")
→ Install eslint-plugin-sonarjs, enable sonarjs/cognitive-complexity
→ enforce("eslint/sonarjs/cognitive-complexity", "Keep functions simple")

第 4 层：无匹配项（保留为指导——可作为未来规则合成技能的候选项）

"research-first": guidance("Google unfamiliar APIs first.")
→ No linter rule can enforce this. Stays as guidance for now.
→ (Custom-rule synthesis is planned but not yet shipped.)

步骤 6：应用更改

在自动模式下：

1. 应用所有第 1 层更改（编辑规范文件，将 guidance() 替换为 enforce()）
2. 运行 npm run build && npx vigiles compile，验证每项更改均可编译
3. 如果任何编译失败，撤销相应更改并报告错误
4. 提交所有成功的更改
5. 将第 2 至第 4 层的内容汇总后交由用户审核

在交互模式下：

1. 展示所有层级
2. 询问用户要应用哪些建议
3. 对于已批准的第 2 层更改：编辑 Linter 配置，然后编辑规范
4. 运行 npm run build && npx vigiles compile 进行验证
5. 如果编译失败，报告错误并撤销更改

**对于第 4 层（无匹配项）：**告知用户这些规则将保留为指导——自定义规则合成是一项计划中的技能，目前尚不可用。