release: v0.12.0 (#310)

发布日期：2026-06-18

Added

• 新增 opt-in 人工审查检查点 post_doc_freeze —— 只门禁冻结类文档转换（PRD 冻结的 Phase 1→2、ARCH 冻结的 Phase 2→3），作为「只门禁冻结文档」与 phase_transition「门禁每次转换」之间的中间档，适合 ARCH 返工成本高的大型项目。默认检查点 [pre_dev, post_sprint, pre_deploy] 不变。

Changed

• 安装文档明确 pip 的结构性限制 —— 上游 prefixcommons 把测试期工具 pytest-logging 误声明为运行时依赖、新版 setuptools 下构建失败；该问题仅能由 uv 的 override-dependencies 中和，pip 无等价机制。installation.md 标注推荐 uv 并加告警。
• ui-spec 组件前缀 C- → UC-（不兼容变更） —— standard / lite / 分卷模板、dev-plan 跨文档引用、ui-design / task-decomp / change-guard / penpot-implement / penpot-review / tech-lead 的组件引用、组件分卷文件名范围标签（-c{start}-c{end} → -uc{start}-uc{end}）统一迁移到 UC-。doc-review 新增 convention 守卫：ui-spec 用 ### C-NNN 组件 heading 时报错并引导改用 UC-。已有下游 ui-spec 文档须将组件 C-NNN 改写为 UC-NNN 并重新 ingest（arch 的 C-/Component 不受影响）。
• context finalize 在 authoring=md 模式下返回 DocIndexResult —— md→KG 回灌 + 索引重建，不再返回导出用的 CompileResult；CLI 显示 indexed N doc(s) 而非 exported N file(s)。authoring=graph 模式不变。
• reviewer 三态判定加反向自检 —— 「verdict 由严重等级唯一决定」的双向判据：结论为 needs_revision 但无 CRITICAL/HIGH 时必须回落 approved_with_notes，且报告 frontmatter status 与正文 Verdict 同源一致。

Fixed

• kg reconcile 不再漏判悬空目标关系 —— 目标实体被重命名/删除后残留的 traceability 边原先因 object 无 cf:entity_id 被丢弃，使 reconcile 报 divergence=0。新增 orphan_relations 分类计入 divergence，kg repair 自动清理，并加 doctor KG xref target integrity 门禁。
• framework.json#context 的项目级 override 升级后不再丢失 —— upgrade / --force-scaffold 重写时只保留 kg_active_doc_types、会静默覆盖 kg_definition_authority / strategy / authoring。改为 context 块 existing-wins 深合并。
• ui-spec 组件现在能被抽取进知识图谱 —— 此前 ### C-NNN 映射到 arch 专属 Component 类被 authority 层整体丢弃。现统一改用 UC- 前缀（UIComponent，authority ui-spec），与 arch 的 C-/Component 彻底分开。
• context finalize 不再静默覆盖人工编辑的 Markdown —— authoring=md 下手工编辑导出 md 再 finalize 时修订被图谱重生成 reset。现 finalize 顶层按 authoring 模式分流：md 模式只回灌 md→KG + 重建索引、绝不导出覆盖；graph 模式才导出派生视图。
• context read 拆分卷整节读取不再被 git 分支操作打断 —— 新鲜度此前按文件 mtime 判定，checkout/merge/pull 刷新 mtime 即误判过期、对拆分卷 id（如 prd-keel）报「未知 doc_id」。改用逐文档 content_hash 比对（对 mtime 抖动免疫），真过期时按 file_path 重扫 heading。
• 子代理在外部工作目录运行 Layer 1 不再报 no executable scripts —— SkillRunner 构造改为优先读 CATAFORGE_PROJECT_ROOT，再退回 cwd 上溯，避免绑定错误根。
• arch / ui-spec 阶段 doc-review L1 KG 覆盖检查不再结构性必失败 —— 原对所有 doc_type 要求 has_impl AND has_test，但 has_test 在 Feature 粒度恒 False（TestCase 验证 AC，AC 经 cf:part_of 挂到 Feature），架构阶段也无 TestCase。现按 _CoverageRule.require_test 声明，arch / ui-spec / dev-plan 只验 has_impl。
• doc-consistency 的 PRD→ARCH AC 溯源改为传递式覆盖 —— 原要求 ARCH 直接引用每个 AC-NNN，但 arch 溯源语义是 arch→Feature（cf:implements），AC 经 cf:part_of 归属 Feature。现 KG 与 regex 两路一致认可 arch→Feature→AC 传递覆盖。