模块化治理工作流（机械量化版）

目标：让 Agent 在分治开发中遵循固定闭环：

1. •先把框架（层级与边界）定义正确。
2. •每轮改动都得到机械 review 反馈。
3. •按反馈修复后继续分治，直到 PASS。

Workflow（必须按顺序执行）

Step 1：先定义框架契约（Framework Contract）

做什么：

1. •创建/复制策略文件：references/modularity-policy.template.json。
2. •明确目标模块层级顺序（layerOrder）与入口文件（entryFiles）。
3. •设定阈值（文件行数、扇出、循环依赖、反向依赖等）。

产出：

1. •机械策略文件（JSON）。

Step 2：执行基线检查（脚本）

做什么：

1. •运行模块化检查脚本：

node .agents/skills/modularization-governance/scripts/check-modularity.mjs \
  --target web/src/features/knowledge \
  --policy .agents/skills/modularization-governance/references/modularity-policy.template.json \
  --output .agents/skills/modularization-governance/artifacts/knowledge.modularity-report.json

1. •读取输出报告中的 summary 与 findings。

产出：

1. •结构化报告（JSON）。
2. •当前状态：PASS | REFINE | BLOCK。

Step 3：按机械反馈分治修复

做什么：

1. •优先修复 BLOCK 项（如 CIRCULAR_DEPENDENCY、REVERSE_LAYER_IMPORT）。
2. •每次只处理一个问题簇（一个 cycle 或一组反向依赖）。
3. •修复后立即回到 Step 2 重新跑脚本。

判定：

1. •任何时刻若仍有 BLOCK，不得进入收尾阶段。

Step 4：收敛优化项（REFINE）

做什么：

1. •对 REFINE 项按收益排序处理（大文件、高扇出、深层相对路径等）。
2. •无法当轮处理的项，必须记录为明确技术债（含文件与原因）。

判定：

1. •允许存在 REFINE 结束当轮，但必须可追踪。

Step 5：执行最终门禁

做什么：

1. •再跑一次模块化脚本，确认无 BLOCK。
2. •跑仓库质量门禁：

bash scripts/check_errors.sh

Step 6：输出可机读交付

做什么：

1. •交付 modularity-report.json（脚本产物）和修复清单。
2. •在日志中记录：本轮 BLOCK 清零情况、剩余 REFINE、下一轮入口。

交付模板

## 模块化结论
- 目标模块: `<path>`
- 结论: `PASS | REFINE | BLOCK`
- 报告: `<report-path>`

## 关键风险
1. ...
2. ...

## 已执行动作
1. ...
2. ...

## 下一步（如需）
1. ...

机械规则说明

脚本输出字段与规则定义见：

• •references/scorecard.md（机械规则与状态机，不含人工主观评分）
• •references/refactor-playbook.md（问题码到修复动作映射）