docs: add AnchorIR specification

[anteloper-c]

背景

AnchorIR 已具备双 Track 基础白名单、Forbidden 集合和两阶段验证能力，但项目中缺少集中、明确的规范文档，用于说明 IR 生产路径与 Backend 之间的交付契约及治理边界。

主要变更

• 新增 docs/anchor_ir_spec.md；
• 定义 AnchorIR 的职责边界和设计目标；
• 说明 Linalg Track 与 TritonGPU Track 的适用场景；
• 记录两个 Track 的基础方言白名单、Forbidden 集合和 Unknown 方言处理规则；
• 说明 pre-hook、Backend hook 和 post-hook 的两阶段验证流程；
• 明确 Track 基础白名单变更与 Backend 扩展方言的治理方式；
• 增加基础白名单变更日志。

影响范围

本 PR 仅新增规范文档，不修改现有代码、公共 API、基础白名单集合或运行时行为。

[github-actions]

Codex AI 自动审查

Codex AI 自动审查仅供参考且不阻塞合入；本地确定性 CI 检查结果才是合入门禁。

审查摘要

• Codex AI 审查结论：警告
• 本地确定性 CI 检查：已通过；Codex AI 自动审查只提供补充意见，不改变门禁结果。
• 合入建议：建议修正第 7 节两条变更日志的日期后合入。除该文档事实错误外，核心规范内容与现有实现、README 和既有测试契约一致；本地确定性 CI 检查已成功，且本次没有运行时代码改动。

本 PR 仅新增 AnchorIR 规范文档。双 Track 白名单、Forbidden/Unknown 规则、两阶段验证 API 和 Adapter→Backend hook 链路与现有实现一致；唯一确认的问题是变更日志将 eb9bd80 的日期写成 2026-05-08，而仓库 Git 历史显示为 2026-04-15。本地确定性 CI 检查在目标合并提交上成功完成构建及相关 smoke/序列化/性能阶段；文档本身未进行运行时测试。

贡献者目标与实现情况

• 判断：部分实现
• 贡献者目标：新增集中式 AnchorIR 规范，明确双 Track 的方言边界、两阶段验证流程和 Backend 扩展治理。
• 预期效果：仓库提供可供 Adapter、Backend 和维护者使用的 AnchorIR 双 Track 规范，准确描述现有验证 API、方言准入边界、扩展阶段和基础白名单变更历史；本 PR 不改变运行时行为。
• 当前实现情况：新增文档已实现主要规范内容，且核心集合、验证阶段和 API 描述与现有代码及 README 相符。但第 7 节两条初始白名单变更日志使用了与实际提交不一致的合入日期，导致历史记录不准确。
• 判断依据：
  • Git diff 仅新增 docs/anchor_ir_spec.md，未修改实现、公共 API、基础集合或运行时路径。
  • 文档列出的 Linalg 15 项、TritonGPU 8 项基础白名单及 7/3 项 Forbidden 集合与 python/triton_anchor/anchor_ir.py 定义一致。
  • 文档引用的 validate_pre_hook(ir_text) 和 validate_post_hook(ir_text, ext_allowed=...) 签名与现有实现一致。
  • 文档变更日志写入 2026-05-08，但对应提交 eb9bd80 的 Git 提交日期为 2026-04-15。

需要处理的问题

1. [低风险] 基础白名单变更日志日期与实际提交历史不一致

• 问题类型：正确性错误
• 代码定位：docs/anchor_ir_spec.md:340-341
• 这段代码负责：基础白名单变更日志的合入日期
• 核心证据：文档第 340-341 行将提交 eb9bd80 的合入日期记录为 2026-05-08；Git 中该提交的实际提交日期为 2026-04-15，且 v0.1 标签指向该提交。该日期差异会使规范历史与仓库事实不一致。
• 影响：维护者据此追踪基础白名单首次引入时间、版本发布和关联提交时会得到错误时间线；不影响当前运行时，但影响文档契约和变更审计。
• 建议：将两条日志的日期改为经仓库 Git 历史确认的实际日期；若项目定义的“合入日期”不是 Git 提交日期，应补充可验证的来源并保持该定义与日志说明一致。

可点击代码定位

链接固定到本次测试提交，便于提交者修复和审核者核对代码功能；已验证行号的问题链接到具体行，仅能确认文件的问题链接到文件并标注行号待核对。

• 问题 1：docs/anchor_ir_spec.md:L340-341

验证情况

• 验证内容与结果：
  • 完整 diff 确认本 PR 仅新增一个文档文件，没有生产代码、测试或配置变更。
  • AnchorIR 实现中的 Linalg/TritonGPU 白名单和 Forbidden 集合与文档数量及成员一致。
  • validate_pre_hook 和 validate_post_hook 的参数及阶段允许集合与文档描述一致。
  • 既有 README 和 Adapter 基类支持文档描述的 Adapter、hook 和两阶段验证链路。
  • 本地确定性 CI 检查目标提交为 1185cd4，构建、前端/后端 smoke、IR 序列化、pass profile、编译基准和 FlagGems 阶段均成功。
  • Git 历史核对确认 eb9bd80 的实际提交日期为 2026-04-15，与文档记录的 2026-05-08 不一致。
  • 获取受信变更范围执行成功。
  • Codex 执行的验证或诊断命令执行成功。
• 限制与未覆盖：
  • 本次未报告额外的验证限制或未覆盖项。

剩余风险

未报告剩余风险。

变更文件

查看变更文件

文件	类型	改动说明	影响
docs/anchor_ir_spec.md	新增	新增 AnchorIR 规范文档，覆盖双 Track 基础白名单、Forbidden/Unknown、pre-hook/backend hook/post-hook、扩展治理和基础白名单变更日志。	新增文档不改变运行时、公共 API 或 CI；其规范内容将作为后续生产路径和 Backend 扩展治理的维护依据。变更日志中的错误日期会降低契约变更的可追溯性，并可能误导版本/发布审计。

---

• 测试提交：1185cd46cd98
• Codex 自动审查状态：完成；结论：警告
• 查看完整 Codex AI 自动审查报告