doc-spec-fixer

doc-spec-fixer

用途

读取最新的审计报告并修复 SPEC，衔接 ../doc-spec-audit/SKILL.md 与通过审计的 SPEC，以便审计↔修复循环能够 收敛。

层级：6（SPEC 质量改进）。 上游：SPEC 文档 + .aidoc/audit/06_SPEC-audit.md。 下游：修复后的 SPEC + SPEC-NN.F_fix_report_vNNN.md。

适用场景

在 doc-spec-audit 返回 FAIL 后，作为“审计 → 修复 → 审计”循环的一部分使用。 不要在没有审计报告时使用（请先运行审计），也不要用于创建新的 SPEC（请使用 ../doc-spec/SKILL.md / ../doc-spec-autopilot/SKILL.md）。

输入约定

读取 .aidoc/audit/06_SPEC-audit.md 报告。编辑前备份 SPEC（tmp/backup/SPEC-NN_<ts>/）；出错时恢复。ID 规范来自 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md；结构规则来自 ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml 和 README.md。

修复模式

从 .aidoc/profile.yaml 解析 review_mode；如果未设置，则根据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md 中的优先级链，回退到框架默认值 team。其他适配参数（section_toggles）也适用相同的 回退规则。

团队模式（依据 REVIEW_TEAM.md §Operations §Remediate）

1. 阅读审计报告 .aidoc/audit/06_SPEC-audit.md，并在存在时阅读 .aidoc/review/06_SPEC/<SPEC-id>/ 下按角色划分的插槽（其中 <SPEC-id> 是简短的 工件 ID，例如 SPEC-01）。

   • 对于结构化发现——稳定 ID、优先级、位置和建议——优先使用按角色划分的插槽。
   • 插槽为可选项——若不存在（例如，single_pass 运行未生成综合器输出），则直接解析审计报告的 Findings 部分。

2. 确定每项发现的负责审查视角。 每项阻断性发现（P0 + P1）在综合器的精简格式中都带有 personas 数组，或者可以根据各审查视角插槽的归属推断。分派规则：

   • 单一审查视角的发现（1 个 persona）：分派该审查视角。
   • 多个审查视角的发现（2 个或更多 personas）：并行分派所有列出的审查视角。每个审查视角都写入自己的 <persona>.fix_<N>.json 插槽。只有在所有被分派的审查视角都未返回新的 P0/P1 时，修复才会被接受（任何一个审查视角出现回归，都要还原补丁）。
   • 没有审查视角／孤立的发现（personas 为空或缺失）： 默认分派 SPEC 团队的作者审查视角（依据 REVIEW_CREWS.yaml：SPEC 的默认审查视角是 architect）。

   SPEC 的审查视角 → Agent 对应关系：

   审查视角	Agent
   architect	aidoc-flow:solutions-architect
   tech_lead	aidoc-flow:solutions-architect
   integration_lead	aidoc-flow:solutions-architect
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer

   对于绑定到 aidoc-flow:solutions-architect 的三个审查视角 （architect / tech_lead / integration_lead），验证说明必须在分派 Task 时明确指定要采用的审查视角，以便 Agent 将验证范围限定在该审查视角内。

   SPEC 团队权重：{architect: 30, tech_lead: 30, integration_lead: 20, chaos_engineer: 10, security_engineer: 10}。

   P2/P3 属于建议项——直接按确定性方式应用，无需审查视角验证。

3. 为每项阻断性发现提出并应用补丁。 下文的修复阶段 0–8 描述了补丁类型；两种模式使用相同的目录。按照现有输入约定，先备份。

4. 验证无回归。 对于步骤 2 中确定的每个负责审查视角，以补丁验证模式分派一个 Task 子 Agent： subagent_type=<mapped agent>；说明 = 已修补区域 + 原始发现 + 补丁差异；形成 lens_score 时，审查视角不得读取、引用或赋予任何作者自评得分权重（*_ready_score/*_score/ readiness_score/audit_score）（REVIEW_TEAM.md GD-05）；输出 = 一条新的角色输出记录（包含已修补区域的 lens_score 和任何新发现）。 将每个审查视角的输出保存至 .aidoc/review/06_SPEC/<SPEC-id>/<persona>.fix_<N>.json（<N> = 从 1 开始递增的修复迭代计数器）。多审查视角发现会针对同一 <N> 为每个负责的审查视角生成一个插槽文件。

5. 还原回归。 如果任何审查视角在补丁上发现新的 P0/P1，则还原该补丁，并将原始发现标记为 manual_required。绝不默默保留导致回归的修复。

6. 仅分派一次综合器 （subagent_type=aidoc-flow:synthesizer），在所有补丁都验证通过后分派，以生成统一的修复报告。保存为 SPEC-NN.F_fix_report_vNNN.md，其中同时包含 Fixes Applied 表格和 Validation Slots 索引。

single_pass 模式（回退方案）

直接单独应用阶段 0–8，不进行审查视角验证。沿用原有行为——当配置文件要求如此、无法分派 Task 子 Agent，或不存在任何插槽时，必须使用此模式。

两种模式下，P2/P3 建议项都无需审查视角验证即可应用；只有阻断性发现（P0/P1）会在团队模式下进入补丁验证循环。

Saga 交互

由 doc-spec-autopilot 调用（或直接调用）时，此技能会根据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md 读取并更新 saga 日志 .aidoc/review/06_SPEC/<SPEC-id>/saga.json。修复器作为 saga 的修复阶段运行：在补丁验证期间将 分支转换为 BRANCH_COMPENSATING，然后再转换回 BRANCH_COMPLETED（已验证）或 BRANCH_FAILED（检测到回归）。

进入时

进入时，写入修复器的开始 epoch：

Bash: mkdir -p .aidoc/review/06_SPEC/<SPEC-id>/ && date +%s > .aidoc/review/06_SPEC/<SPEC-id>/.skill-start.fixer

如果 .aidoc/review/06_SPEC/<SPEC-id>/saga.json 存在，则读取该文件。验证当前 saga 的 status 是否为 FANIN_REDUCED（审计后）或 BRANCH_FAILED（此前修复器回归后重新进入）。如果 状态不符合上述情况，记录警告并继续。

补丁验证期间（团队模式）

对于每个需要进行透镜验证的阻塞问题（P0/P1）：

1. 分派负责的透镜验证器之前：对问题 personas[] 列表中的每个透镜，追加一条状态转换： {"ts": "<now>", "from": "BRANCH_COMPLETED", "to": "BRANCH_COMPENSATING", "scope": "branch:<lens>"}。将 branches[<lens>].status 更新为 "BRANCH_COMPENSATING"。在 compensation_actions[] 中追加一条记录： {"ts": "<now>", "branch": "<lens>", "reason": "<finding_id>: <message>", "action": "retry"}。
2. 验证 Task 子 Agent 返回后：
   • 如果补丁通过验证（没有回归）：转换回 BRANCH_COMPLETED。用验证结果更新 compensation_actions[] 的最后一条记录。
   • 如果补丁出现回归（透镜在已打补丁区域标记出新的 P0/P1）： 转换为 BRANCH_FAILED。将 compensation_actions[] 最后一条记录中的 action 设为 "escalate"。 该问题将变为 manual_required。

分派综合器之前

根据 REVIEW_SAGA.md 的“熔断策略”一节，修复器的检查点边界位于多透镜验证分派之间 （每个阻塞问题的逐透镜验证都构成一个边界）。 分派下一项验证之前：

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/06_SPEC/<SPEC-id>/.skill-start.fixer) ))

如果已用时间 > SOFT_DEADLINE（1500s）：

• 追加状态转换：{"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "PARTIAL_TIMEOUT", "scope": "run"}。
• 将 saga 的 status 设为 "PARTIAL_TIMEOUT"。保留所有已完成的验证（其 fix_N.json 槽位保持持久化）。将 current_phase 设为 "fixer"，以便恢复调用能够 继续剩余验证。
• 更新 updated_at。写入 saga.json。正常退出。

剩余验证将在下次调用时，根据 doc-spec-autopilot 的 §3.4 恢复逻辑继续执行。

综合器归并后

• 追加状态转换：{"ts": "<now>", "from": "BRANCH_COMPENSATING", "to": "BRANCH_COMPLETED", "scope": "run"}（运行级：修复器阶段 已完成）。
• 将 saga 的 status 更新为 "BRANCH_COMPLETED"（autopilot 的下一阶段 将是 re-review）。
• 更新 updated_at。写入 saga.json。

独立调用时（进入时不存在 saga.json）

如果 .aidoc/review/06_SPEC/<SPEC-id>/saga.json 不存在（用户在 autopilot 循环之外直接运行 /aidoc-flow:doc-spec-fixer），不要初始化完整的 saga 架构。记录 saga.json not present; running fixer without saga journal (standalone mode)。照常运行 修复阶段；写入修复报告；跳过所有 saga.json 状态转换。保持与直接调用技能的向后兼容性。

在 single_pass 模式下调用时

如果 review_mode: single_pass 处于启用状态，修复器会确定性地应用补丁，不进行透镜验证，也不写入 saga.json。保留现有行为。

断路策略

根据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md §“断路策略”，此技能会在一个检查点边界检查已过的墙钟时间：所有逐条发现项的修补都返回后、调用综合器之前。软截止时间为 1500s （ORCHESTRATOR_TIMEOUT=1800s，减去 300s 缓冲时间）。

如果已超过软截止时间，则按照上文 §“综合器调度之前”的规定，正常退出，并将 saga status: "PARTIAL_TIMEOUT"。修复器的部分进度（已写入的 fix_N.json 槽位）会持久保存；恢复调用时会从断路触发处继续。

修复阶段

按顺序运行；后续阶段假定前面的阶段已成功。

阶段	范围	代表性操作
0 — 结构	嵌套文件夹规则	将 SPEC 移至 docs/06_SPEC/SPEC-NN_{slug}/；将文件夹重命名为与 ID 匹配；移动后修复相对链接
1 — YAML	格式错误的 YAML	修复缩进／引号，移除重复键，修正类型以使 SPEC 可解析
2 — 缺失文件	引用但不存在的文件	根据模板创建索引／引用占位文件
3 — 链接	失效／绝对路径	重新计算相对路径；将绝对路径转换为相对路径
4 — ID	无效／旧版 ID	在文档层级强制使用连字符形式的 SPEC-NN；将上游元素引用修正为 TYPE.NN.SS.xxxx；移除旧版 STEP-XXX／IF-XXX／DM-XXX、3 位数的 SPEC-NNN、数字类型代码
5 — 内容	占位内容、阈值	填写模板日期；将硬编码数字替换为 @threshold: 引用；标记 [TODO]／[TBD] 以供人工补全
6 — 引用	可追溯性	补上此层 required_tags 中缺失的标签（根据 LAYER_REGISTRY.yaml 的必要上游约定——SPEC 需要 @ears @bdd @adr）和下游的 @tdd: TDD-NN；修复上游路径；更新可追溯性矩阵
7 — 上游	元数据 + 漂移	修复 deliverable_type／document_type；根据上游 ADR／BDD 应用分级漂移合并（见下文）
8 — 风格	STY01 禁用短语、STY02/03 过长文本、FM01 前置信息不匹配	替换填充内容；替换标记出的最高级措辞；将段落（同一节中含 ≥ 3 个禁用短语）精简为项目符号；协调前置信息 ↔ Document Control 行；STY02/03 — 在下一个契约边界拆分过长的 Behavior／Interfaces 节，或标记为 manual_required。权威依据：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

ID 规则： SPEC 在文档层级以连字符形式 SPEC-NN 引用——绝不使用带点号的 SPEC 元素 ID。上游分层引用使用 4 段式元素形式 TYPE.NN.SS.xxxx（例如 BDD.01.03.8f4c）；文档层级使用 @adr: ADR-NN。

分级上游漂移（针对引用的 ADR／BDD）：变更 <5% → Tier 1 自动合并（补丁版本递增）；5–15% → Tier 2 自动合并 + 详细变更日志（次版本递增）；>15% → Tier 3 归档当前版本 + 通过自动驾驶重新生成（主版本递增）。 绝不删除上游已移除的内容——标记为 [DEPRECATED] 并保留以供追溯。将结果记录在 .drift_cache.json 中。

置信度分类

为每项已应用的修复标注，并在报告中列出数量：

置信度	含义
auto-safe	确定性高、语义风险低（链接／路径、YAML 重新缩进、ID 转换、阈值标注）
auto-assisted	基于部分假设插入模板（搭建章节骨架／接口存根）
manual-required	无法推断领域内容（接口签名、行为逻辑、尚未解决的 TODO/TBD）

内容保留规则

• 绝不删除现有接口定义、数据模型架构或行为逻辑；仅在章节缺失或未达到最低结构要求时插入模板块。
• 在原处规范化等效的 YAML 键／标题，而非重复创建章节；保留 YAML 注释。
• 仅在同一章节内重新编号；若交叉引用锚点会失效，则标记出来。

修复报告格式

表格管道符转义（MD056）

在输出包含带 shell 管道符的代码片段的 Markdown 表格单元格时（例如 `docker compose ps | grep 'Up'`），代码片段内未转义的 | 会被 markdownlint 解析为列分隔符，从而触发 MD056（列数不匹配）。有两种修复方法：

• **首选：**在代码片段中将管道符转义为 \| — 在 Markdown 查看器中仍会显示为 |，但不会破坏表格。 示例行：| OP-02 | ... | `docker compose ps \| grep 'Up'` | ... |
• **替代方案：**将代码片段移出表格单元格，并在表格下方通过脚注或段落引用。单元格中改用普通文本，例如“shell 就绪门控（见下文）”。

对每个在表格单元格内输出含 shell 管道符代码片段的报告行应用此修复。触发 MD056 的级联输出是 SKILL 缺陷，而不是 markdownlint 过于严格——应在此处修复，而非忽略 lint。

编写 SPEC-NN.F_fix_report_vNNN.md，包含：摘要（问题数／已修复／剩余；创建／修改的文件；修复的 YAML 代码块）· 已应用的修复（代码、问题、修复、文件、置信度）· 人工审核队列 · 上游偏差摘要 · 修复后验证（修复前→后的分数／错误／警告）· 清理摘要（删除已被取代的修复报告）· 后续步骤（重新运行 doc-spec-audit）。循环执行，直到分数 ≥ 阈值或达到最大迭代次数。

适配

应用修复前，请阅读项目适配配置文件 （.aidoc/profile.yaml）。遵循 section_toggles：不要重新引入项目已关闭的可选章节。忽略任何未知或超出适用范围的键。 权威文件：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

• 审计（输入）：../doc-spec-audit/SKILL.md · 创建：../doc-spec/SKILL.md
• 编排：../doc-spec-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 权威文件：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml， ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md