Citadel 是 Capsem 的架构守卫套件,位于 tests/citadel/,用于把不应重复的架构错误固化下来。守卫均为源码级,在快速阶段运行,不需要制品、虚拟机或守护进程;每条失败信息都携带推理,让违规具有教学意义。它曾只能通过携带 require_artifacts 的 broad 套件根节点触达,导致 DB 边界违规在源码被读取约四十分钟后才暴露,现在改为与 Ruff 并行运行,且 tests/citadel 被列入 broad_ignores,test_guard_scheduling.py 会在其被移回时失败。
守卫覆盖多个方面:数据库边界、lint 覆盖率、形状边界、工作流强制、容器工作区、跨平台工具锁定、发布测试环境、技能上下文预算、热构建契约、包与机器架构边界、运行摘要、树复制边界、Rust 检查覆盖率、智能体契约、步骤属性、工作图不变量、工作流脚本检出等。核心思路是约束形状,使属性保持可证明。
新增守卫有三条规则:在具名 *_RATIONALE 中陈述理由并附加到断言,理由已有权威出处(如 config/gate.toml、AGENTS.md、技能)时引用而非重述;既写一致性用例也写对抗性用例;先让它红一次再修好,以确认它真的在断言。
新增 surface 通过 [[lint_surfaces]] 映射,每个条目对应一类第一方文件,并命名必须检查它的每个步骤。字段分 enforced_by(必须存在且在快速阶段响应)与 checked_by(可在任意阶段存在,用于合法地无法提前的检查)。test_lint_coverage.py 验证 surface 有文件、具名步骤存在、enforced_by 的检查提前运行。Shell 曾在 6,821 行无检查的情况下存在,Markdown 有 79,000 行无任何指向,两者都必须补上对应门禁。
lint 工具 harness 位于 build_system/scripts/audit/lint_harness.py,入口是 build_system/scripts/audit/check-surfaces.py,每次调用一个 surface。Sources 因形状不同而存在,例如 workflow run 体嵌于 YAML,Dockerfile RUN 体嵌于指令,.j2 模板需通过 render_dockerfile 渲染后再检查。capsem.gate.shellsurfaces 负责提取,与形状守卫共享。每个 surface 都失败关闭,无来源时抛出 EmptySurface。
运行摘要位于 cache/target/gate-runs/DIGEST.md,由 fast.digest 与 RunLog.close 依据 ledger.jsonl 重生成,用于捕捉仅跨运行可见的问题类别。比较持续时长需相同计划形状、argv 与主机类别;关键路径需同一命令;失败计数两者都不需要。空基线会明确说明。
债务清单是精确清单而非豁免列表,条目不允许增长,文件缩小需在同一次变更中更新或移除条目。上限来自树自身分布,是离群检测而非重写指令。相关技能:/dev-gate、/dev-testing、/ironbank。