Agent-System/.doc/ops/lessons/2026-09-28-quality-heading-normalize.md

lesson_id, lesson_state, owner, reviewer, last_reviewed, reviewed_revision, source_issues, keywords

lesson_id	lesson_state	owner	reviewer	last_reviewed	reviewed_revision	source_issues	keywords
LESSON-20260928-quality-heading-normalize	candidate	Cursor	Cursor（自审，待 dev 重跑调研报告后升 validated）	2026-09-28	434d542c3c	ISSUE-20260928-quality-heading-drift	quality_gate 缺少必填章节 State-of-the-Art H3 AutoRepair

章节门禁比对标题，不比对空格和层级

• 触发条件：交付正文章节都在，质量报告仍写「缺少必填章节」，评分往往停在 85。
• 机制与来源：模板 H2 与模型常写的 H3、多一个或少一个空格、全角字母，在精确字符串比较下会被当成整章缺失。缺章会短路受控投影。见 ISSUE-20260928-quality-heading-drift。
• 开发检查：标题比对先去空白、折全角、忽略大小写，并允许 H2–H4。只在归一化后确实没有该标题时判缺失。层级不一致记软警告，不扣分。不要把「待确认」或材料不足算进这道门禁。
• 验证方式：TestQualityGate_Validate_HeadingLevelAndSpaceDrift 同时覆盖漂移通过和真实缺章失败。聊天触发须带 AutoRepair。
• 适用边界：只覆盖 ATX 标题存在性。近义改名、章节被写进代码块、内容空洞仍不在本条范围内。
• 防护落实：internal/squad/quality_gate.go 与 quality_gate_test.go。
• 修订与失效：若产品要求章节层级必须与模板一致才可交付，应把软警告改回硬失败，并同步改回归用例。