doc-bdd-fixer

doc-bdd-fixer

用途

读取最新的审计报告并修复 BDD 套件，衔接 ../doc-bdd-audit/SKILL.md 与通过审计的 BDD，使审计↔修复周期 能够收敛。

层级：4（BDD 质量改进）。 上游：BDD 文档 + .aidoc/audit/04_BDD-audit.md。 下游：修复后的 BDD + BDD-NN.F_fix_report_vNNN.md。

使用时机

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

输入约定

使用 .aidoc/audit/04_BDD-audit.md 报告。编辑前备份 BDD（tmp/backup/BDD-NN_<ts>/）；出错时恢复。元素 ID 标准来自 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md；结构和 YAML 场景架构来自 ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml 和 README.md。

修复模式

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

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

1. 读取审计报告 .aidoc/audit/04_BDD-audit.md，并在存在时读取 .aidoc/review/04_BDD/<BDD-id>/ 下按角色划分的槽位（其中 <BDD-id> 是简短的产物 ID，例如 BDD-01）。

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

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

   • 单视角发现项（1 个 persona）：分派该视角。
   • 多视角发现项（2 个或更多 personas）：并行分派所有列出的视角。每个视角都写入自己的 <persona>.fix_<N>.json 槽位。只有在所有已分派视角均未发现新的 P0/P1 时，修复才算通过（任一视角发现回归都会导致补丁回滚）。
   • 没有 persona／孤立发现项（personas 为空或缺失）：根据 REVIEW_CREWS.yaml，分派 BDD 团队的作者视角（BDD 中为 qa_lead）作为默认负责审查者。

   BDD 的视角 → Agent 映射：

   视角	Agent
   qa_lead	aidoc-flow:test-architect
   tech_lead	aidoc-flow:solutions-architect
   chaos_engineer	aidoc-flow:chaos-engineer
   security_engineer	aidoc-flow:security-engineer
   operator	aidoc-flow:devops-release-engineer
   auditor	aidoc-flow:traceability-auditor

   BDD 团队权重：{qa_lead: 35, tech_lead: 25, chaos_engineer: 14, security_engineer: 6, operator: 10, auditor: 10}。

   P2/P3 为建议项——直接按确定性规则处理，无需视角验证。

3. 针对每条阻断性发现项提出并应用补丁。 下方的修复阶段 0–7 描述了补丁的形式；两种模式使用相同的目录。先根据现有输入约定进行备份。

4. 验证是否存在回归。 对于步骤 2 中确定的每个负责视角，以补丁验证模式分派一个 Task 子 Agent：subagent_type=<mapped agent>；简报 = 已修补区域 + 原始发现项 + 补丁差异；该视角在生成 lens_score 时不得读取、引用或权衡任何作者自我评估分数（*_ready_score/*_score/readiness_score/audit_score）（REVIEW_TEAM.md GD-05）；输出 = 一条新的 persona 输出记录（已修补区域的 lens_score + 任何新发现项）。 将每个视角的输出保存为 .aidoc/review/04_BDD/<BDD-id>/<persona>.fix_<N>.json（<N> = 从 1 开始递增的修复迭代计数）。多视角发现项在同一个 <N> 下为每个负责视角生成一个槽位文件。

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

6. 分派综合器一次 （subagent_type=aidoc-flow:synthesizer），在所有补丁完成验证后生成统一的修复报告。保存为 BDD-NN.F_fix_report_vNNN.md，其中既包含 Fixes Applied 表，也包含 Validation Slots 索引。

single_pass 模式（回退方案）

直接单独应用阶段 0–7，不进行视角验证。沿用未变的旧行为——当配置文件要求如此、无法分派 Task 子 Agent，或不存在槽位时，必须采用此模式。

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

Saga 交互

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

进入时

进入时，写入修复器的起始时间戳（epoch）：

Bash: mkdir -p .aidoc/review/04_BDD/<BDD-id>/ && date +%s > .aidoc/review/04_BDD/<BDD-id>/.skill-start.fixer

如果 .aidoc/review/04_BDD/<BDD-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 子代理返回后：
   • 如果补丁验证通过（无回归）：转换回 BRANCH_COMPLETED。更新 compensation_actions[] 中的最后一条记录，写入验证结果。
   • 如果补丁导致回归（透镜在已修补区域标记出新的 P0/P1）： 转换为 BRANCH_FAILED。将 compensation_actions[] 中最后一条记录的 action 设为 "escalate"。 该问题变为 manual_required。

分派 synthesizer 之前

根据 REVIEW_SAGA.md §“Break-circuit policy”，修复器的检查点边界位于多透镜验证分派之间 （每个阻塞问题的逐透镜验证构成一个边界）。 分派下一次验证之前：

Bash: echo $(( $(date +%s) - $(cat .aidoc/review/04_BDD/<BDD-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-bdd-autopilot §3.4 的恢复逻辑，在下次调用时继续。

synthesizer reduce 之后

• 追加状态转换：{"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/04_BDD/<BDD-id>/saga.json 不存在（用户在 autopilot 循环之外直接运行 /aidoc-flow:doc-bdd-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 §“断路策略”，此技能会在一个检查点边界检查已流逝的实际时间：所有针对各项发现的补丁返回后、调用合成器之前。SOFT_DEADLINE 为 1500s （ORCHESTRATOR_TIMEOUT=1800s，减去 300s 缓冲时间）。

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

修复阶段

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

阶段	范围	代表性操作
0 — 结构	文件夹/索引规则	将 BDD 移至 docs/04_BDD/BDD-NN_{slug}/；将文件夹重命名为与 ID 匹配；确保索引存在；移动后修复相对链接
1 — 缺失文件	被引用但不存在	根据模板创建术语表 / 索引占位文件
2 — 链接	失效/绝对路径	重新计算相对路径；将绝对路径转换为相对路径
3 — 元素 ID	旧版/无效 ID	重新推导 BDD.NN.SS.xxxx（章节 + 内容哈希）；移除旧版 BDD.NN.xxxx、数字类型代码、SCEN-XXX/STEP-XXX 前缀
4 — 内容	占位内容、字段、阈值	填写模板日期；添加缺失的场景字段（type/priority/ears/id）；添加内联 WITHIN @threshold:；标记 [TODO]/[TBD] 以及缺失的 given/when/then 阶段列表（BDD-SCHEMA-001），以便手动补全
5 — 引用	可追溯性	确保每个场景都包含元素级 ears: 列表（根据 LAYER_REGISTRY.yaml 中必要上游约定，BDD 的 required_tags）；修复跨文档路径；添加/修复 spec_trace；更新可追溯性矩阵
6 — 上游	元数据 + 漂移	修复 deliverable_type/document_type/upstream_mode；上游 EARS 发生漂移时，应用分级漂移合并策略（见下文）
7 — 风格	STY01 禁用短语、STY02/03 过长的散文、FM01 frontmatter 不匹配	替换填充内容；替换标记出的最高级表述；将段落（同一章节中有 ≥ 3 个禁用短语）改为项目符号列表；协调 frontmatter ↔ Document Control 行；STY02/03 — 在类别边界处拆分过大的场景块，或标记为 manual_required。依据：${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

元素 ID 重新推导： BDD.{doc_id}.{section_id}.{hash} — 分配一个 稳定的 4 位十六进制字符标识符，在其所属章节中不得重复（HASH01）；发生冲突时扩展为 8 位。此处不要计算 SHA-256：哈希形式是由确定性工具处理生成的规范化目标值，且字节级精确字段提取仅针对 BRD §7 定义（BDD 的第 2 阶段及之后）。保留现有的有效 ID — 重新推导会破坏所有下游引用。 依据：framework/governance/ID_NAMING_STANDARDS.md。文档级引用（SPEC-NN、ADR-NN、IPLAN-NN）保持连字符形式；场景位于章节 03。

**内容保留：**绝不修改场景步骤文本（given/when/then）或 examples 数据；只添加缺失字段/元数据，并将硬编码值替换为内联 @threshold: 引用。缺失的字段/结构应标记出来，不得自行编造。从 Gherkin 迁移时，将每个 @scenario-id 原样复制到场景的 id: 中 — 绝不要重新计算哈希（以保持下游 @bdd: 稳定）。

分级上游漂移（EARS 自 BDD 创建后发生变化）：变化 <5% → 第 1 级，自动合并新场景（补丁版本递增）；变化为 5–15% → 第 2 级，自动合并并添加详细变更日志，将修改过的源场景标记为待审核（次版本递增）；变化 >15% → 第 3 级，归档当前版本并通过 autopilot 重新生成（主版本递增）。绝不删除上游已移除的场景 — 标记为 @deprecated 并保留以供追溯。 将结果记录在 .drift_cache.json 中。

置信度分类

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

置信度	含义
auto-safe	确定性高、语义风险低（链接/路径、标签移位、ID 转换、阈值替换）
auto-assisted	基于部分假设插入模板（搭建场景/章节、默认优先级标签）
manual-required	无法推断领域内容（未解决的 TODO/TBD、缺少 Given-When-Then、步骤语义）

内容保留规则

• 绝不删除现有场景内容；仅在章节或场景缺失或未达到最低结构要求时插入模板区块。
• 将场景上游追踪信息作为 ears: 列表字段保留（而非 @ 标签）；绝不重复。
• 仅在同一文档内重新编号/调整结构；如果交叉引用锚点可能失效，则予以标记。

修复报告格式

表格管道符转义（MD056）

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

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

应用于每一条在表格单元格中输出 shell 管道符代码段的报告行。触发 MD056 的级联输出属于 SKILL 缺陷，而非 markdownlint 过于严格 — 应在此修复，而非忽略 lint 错误。

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

项目适配

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

相关资源

• 审计（输入）：../doc-bdd-audit/SKILL.md · 创建：../doc-bdd/SKILL.md
• 编排：../doc-bdd-autopilot/SKILL.md · ID：../doc-naming/SKILL.md
• 权威依据：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml， ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md