跳转至

知识契约与决策

{
  "scope": "global",
  "triggers": {
    "specification": [
      "INV9",
      "INV11",
      "INV14",
      "INV16",
      "INV18",
      "INV20",
      "INV21",
      "INV25",
      "INV26",
      "DEC-9",
      "INV27",
      "DEC-10",
      "DEC-12",
      "DEC-13",
      "DEC-15",
      "INV28",
      "INV31"
    ]
  }
}
{
  "paths": ["apps/docsite/**"]
}

目的

评审者应当能够在不重新阅读旧拉取请求的情况下回答两个问题:

  1. 哪些行为已由人类做出决策?
  2. 本次拉取请求是否正在做出需要人类介入的新决策?

系统模型

Astryx 将不同的事实存放在不同的位置:

  • 组件契约描述某个组件承诺的聚合行为。
  • 模块契约描述由某一组件拥有的、可独立契约化的公共钩子、插件、工具或子系统。私有实现辅助函数不需要记录。一个新的内部模块或钩子,如果可被其他组件导入——例如包的 internal/ 导出,或在所属组件之外使用的钩子——则不属于私有辅助函数:在记录对其进行定义之前,它需要所有者决策(见升级步骤 5 之前的契约,DEC-22)。
  • 组件或模块契约内部可选的 设计决策 表格记录该所有者本地范围内的持久视觉意图。它不保存精确像素调优或跨组件共享的规则。
  • 族契约描述兄弟组件共享的行为。
  • 设计规范记录由人类拥有的视觉与交互决策,包括用于判断 token/颜色配对的跨主题可访问性与对比度方法论。
  • 主题规范记录单个包主题的意图、继承的基础、选定的 token 与调色板映射、必需的配对/状态、主题特定例外、测量结果、已知差距、兼容性与产物。
  • 系统规范记录跨组件或跨主题的决策,或改变架构的决策。
  • 消费者文档解释 props、示例与用法。
  • 审计记录保存当前证据与发现。操作存储是自动化 wiki component-scores.json,它为沙箱提供当前修复后得分与未解决发现。引导阶段预留了同址共存的 <PublicName>.audit.json 文件,但没有任何 schema 或记录激活该路径;它既不是审计数据存储,也不是当前迁移目标。

评审者从已更改的代码和最近的当前组件或模块契约开始。他们只跟踪回答问题所需的链接:

changed code or theme source
  → nearest current component, module, or theme contract
  → relevant family or design requirement
  → architecture or system decision only when referenced
  → mapped tests and audit evidence

查找也可以从任何仓库路径开始。pnpm specs:for <path> 列出链接到该路径的每一条当前记录、决定这些记录的系统规范,以及该路径组件触发路由的全局声明;使用 --diff 时,变更所涉及的声明所路由到的声明会优先列出(INV20)。它只跟踪记录与文件声明的链接:

  • 放置位置:记录本身,或其规范位置包含该路径的组件、模块或主题记录(组件或模块记录的位置是其文件夹在 docs/specs/components/ 下镜像的源目录);
  • 路径字段:applies_to、verified_by 与 path-applicability:v1 模式;
  • 名称:指向该路径组件或消费者文档主题的族 members、设计 components 与 affects_consumer_docs id;
  • 引用:写在文件正文(如 Markdown 文档)中的系统规范编号(如 AST-030)或声明(如 AST-108 FR4)。查找也会读取源代码注释中的此类链接,但 INV29 会在注释移除前将每个此类链接移入记录,因此移除注释绝不会丢弃文件与记录之间的唯一链接;
  • 继承:某条链接记录所依赖的引用。

当前记录可以引用先前的人类决策。当新案例处于该决策所声明的范围内时,评审者直接应用该决策,无需再次询问。

主题记录位于共享主题架构与下游记录之间。跨主题的 API、词汇、继承、验证、编译器行为与产物策略保留在架构或系统规范中。跨主题的人类视觉与可访问性对比度方法论属于当前设计记录;共享的测量/工具实现属于架构或工具。单个主题选定的 token/调色板映射、必需的配对与状态、例外、测量结果、已知差距、迁移与产物属于其包本地主题记录。组件与族继续拥有可观察行为;消费者文档继续拥有受支持的语法与示例。

每条记录要么是:

  • draft(草稿):对评审有用,但不是规则;
  • current(当前):已明确批准且可安全依赖;
  • archived(已归档):为历史而保留,并在存在替代记录时链接到该替代记录。

边界与不变量

  • INV1 — 当前意味着已批准。 只有 current 记录指导实现与评审。
  • INV2 — 一个事实只有一个所有者。 组件或主题记录不复制族、设计、系统、消费者、审计或工具内容。跨主题 API 与编译器行为保留在架构/系统记录中;人类对比度方法论保留在设计记录中;共享测量实现保留在架构/工具中;主题特定映射、状态、例外、收据与差距保留在包本地主题记录中;聚合可观察组件行为保留在组件/族记录中;可独立契约化的公共组件模块行为保留在模块记录中;消费者语法保留在消费者文档中。
  • INV3 — 现有决策可复用。 评审者引用适用决策并继续推进,无需再次询问人类。
  • INV4 — 新判断需显式化。 当没有当前决策适用、现有决策冲突,或该选择被刻意归为人类所有时,评审者会询问人类。
  • INV5 — 空白表单不是策略。 模板只创建草稿。搜索与评审绝不会将模板文本呈现为已批准的 Astryx 决策。
  • INV6 — 必需结构按种类变化。 模板措辞可以在不接触现有记录的情况下更改。新增种类不会迁移不相关的种类。为现有种类添加或移除必填字段或章节时,会为该种类创建后续 schema 定义,并在同一拉取请求中迁移该种类的所有活动记录。
  • INV7 — 只有纯规范更改使用轻量 CI。 每个已更改文件都必须是组件、模块、族、设计、主题或系统规范。对代码、架构、指南、模板、schema、审计或任何未知路径的更改运行常规 CI。
  • INV8 — 私有操作保持私有。 公共记录绝不指名或链接私有发布或自动化系统。
  • INV9 — 当前记录没有隐式优先级。 较新、较窄或更局部的当前记录不会静默覆盖另一条当前记录。
  • INV10 — 记录描述理想行为,而非拉取请求裁决。 当前记录独立于任何单个实现更改,陈述持久的要求、禁止、兼容性、所有权与证据。它绝不为批准某个拉取请求而存在,也绝不批准、拒绝、分类、指定或授权某个特定拉取请求。拉取请求与 issue 不是常设内容:记录陈述的是更改所确立的事实,而非更改本身,并且在不再引用任何曾引用的拉取请求或 issue 时依然完整。支持决策的研究——调查、选项比较、基准测试、测试设计或得分——是链接自拉取请求的产物,而非记录内容;记录将结论保留在依赖该结论的决策内部。由他处拥有的事实通过链接拥有该事实的记录来委托。评审者拥有每个更改相对于当前权威的处理结果。
  • INV11 — 每个公共增量都有权威结果。 每个公共 API 更新与每个公共行为更改在验收前都必须与当前已提交的权威匹配。包导出形状并非唯一触发条件:可达的支持类型、上下文成员、钩子返回值、默认值与可观察行为也参与其中。
  • INV12 — 审计状态只有一个自动化数据存储。 Wiki component-scores.json 是当前得分与未解决发现的操作来源。未激活的 <PublicName>.audit.json 约定已退役。未来的存储更改需要显式系统决策、版本化数据契约、自动化迁移与对账、沙箱读取器切换以及回滚证据;它 MUST NOT 按约定创建按组件划分的影子账本。
  • INV13 — 作者在创建权威之前先搜索。 在创建或实质性扩展记录之前,按拟议的规范所有者/id、受影响路径与导出符号以及语义行为术语搜索当前记录与打开的拉取请求。默认扩展或将现有规范所有者投射到该记录上。新记录需要清晰的事实边界,并显式解释为何现有所有者无法容纳它。打开的拉取请求用于协调重叠工作;它们仍然只是非权威证据。
  • INV14 — 当前权威按声明限定范围。 authority: current 批准记录声明的所有权边界内的显式声明。它不承诺指定组件、模块、族或代码路径的每个行为都已被规范化。评审 MUST NOT 将一个狭窄决策扩展到相邻的未签约行为,除非拉取请求的确切增量依赖于该行为。
  • INV15 — 评审契约朝向单一可落地意图。 作者确定一个主要意图,评审者分别分类每个可观察增量。违反当前权威或需要新人类决策的可分离增量会在评审要求主要更改承载新权威之前被移除或拆分。规范是有意持久决策的路径,而非对评审期间发现的无关范围的默认补救措施。未被任何当前记录决定的新增或更改公共 API 行是例外:它将交由人类评审以做出所有者决策(见更改耦合步骤 6)。
  • INV16 — 规范主导;生成的评审上下文仅供参考。 已提交的当前组件、模块、族、设计、主题、架构与系统记录拥有预期的产品行为。评审者生成的摘要、章节、清单、测试、截图、测量与建议仅为上下文或证据。它们可以证明符合性、矛盾或实现缺陷;它们 MUST NOT 发明方向、授权增量、撤销人类保留或升级权威结果。
  • INV17 — 缺失的评审上下文保持问题绑定。 评审首先阅读拉取请求与当前权威,然后仅填补缺失的上下文。它追溯问题为何发生、为何损害受影响任务、以及为何该损害重要;将提议的解决方案以及每个主要或支持性增量映射回该问题;并识别可独立移除的附带更改。产品影响仍由适用的产品记录拥有。评审可以解释谁受影响、在何种受支持状态下、以及更改启用或阻止了什么,但该生成解释在被当前规范所有者记录行为之前仍属上下文。
  • INV18 — 产品契约保留实现自由。 组件、模块、族、设计、主题与系统规范拥有可观察的输入、输出、状态、保证、失败、兼容性与调用者可见的所有权。一个新的

或作出重大修订的需求 MUST NOT 规定内部模块、文件、函数名称、算法、数据结构、存储布局、清单、日志、锁、事务协议或 CI 作业/工作流拓扑,除非该确切机制本身就是有意的公共契约。内部所有权、接缝和机制属于架构记录。验证映射指明足以证明某一声明的证据;它并不授权产生该证据的实现或 CI 结构。现有当前记录继续管辖其明确声明,直到其人类所有者有意迁移它们;此不变量不会静默失效或重新解释这些记录。

  • INV19 — 自动化规范审查为人类决策提供信息。 主要意图是创建、修订、采纳或取代产品契约的拉取请求,在指定的人类所有者裁决之前,必须收到书面咨询分析。分析应识别权威知识所有者、适用的当前声明、重叠的当前和进行中的工作、所有权冲突或缺失所有者、声明范围缺口、行为与架构之间的泄漏,以及需要保留、移除、移动或澄清的精确声明。自动化可以报告矛盾、证据缺口和提议的编辑;它 MUST NOT 批准、采纳、认可或将契约变为当前状态。即使咨询分析未发现任何缺陷,仍需人类批准。
  • INV20 — 全局审查路由是显式的且以声明为范围。 跨领域基线只有在没有组件反向链接的情况下参与,当且仅当它的 review-applicability:v1 块声明 scope: "global",并将语义触发器或关注点映射到同一记录中的精确声明 ID。审查会先加载匹配的当前全局声明,再加载较窄的记录;当直接组件、模块或系列所有者管辖该变更时,优先解析该所有者。该标记绝不会让整个记录、相邻声明、草稿或拟议 HEAD 的权威来管辖。每次路由匹配都会记录基础权威提交、记录摘要、记录 ID、路径、触发器或关注点、声明 ID、声明标题和确定性匹配原因。拥有共享关注点的记录 MAY 将其列在该块的 concerns 映射中:共享工具的名称、重新实现它的代码模式,以及它路由的声明。如果变更的已发布源代码新增行与某个关注点匹配,则无论组件记录的 review_triggers 列表如何,该变更都会路由这些声明,并且每次匹配都会指明匹配的行。
  • INV21 — 组件本地的视觉意图保持本地且持久。 ## Design relationships 下的可选 ### Design decisions 表仅用于组件或模块本地的外观意图,未来的重新设计必须重新考虑这些意图。作者在新增一行之前,应引用、重用或修订稳定的 DD1、DD2 … 行。精确的像素调整通常保留在代码和视觉证据中;共享或跨组件的规则保留在 docs/design/ 中。团队设计负责人可以在一个原子性的、仅涉及外观的拉取请求中提交一行像素和证据。外部贡献者遵循正常的贡献流程,MUST NOT 被要求编写规范;维护者拥有任何缺失的权威。人类请求提供意图,但只有通过所有者对当前规范内容(DEC-14)的批准,才会成为已提交的当前权威。

审查证据放置

  • INV22 — 一次性证据随变更保留。 临时截图、录屏、测量数据、传感器凭证和运行日志附加或链接到使用它们的拉取请求中,而不是作为一次性资产提交到 main 下的 docs/pr-assets/ 或另一个源目录。公开 GitHub 附件是手动发布的一次性证据的首选位置。常设记录保留持久的结论和验证关系,而不是单个运行的清单。已接受的视觉基线、可复用的用户故事和测试夹具、随版本发布的文档媒体,以及由当前所有者明确允许的仓库自有凭证,仍与代码一起进行版本管理。
  • INV23 — 清理保留历史证据。 从当前树中移除一次性资产 MUST NOT 重写历史或破坏现有固定在提交上的证据链接。在删除之前,每个被移除的文件都有一份经过验证的公开保留副本。保留的 main 历史之外的链接提交需要在该确切提交处有一个持久保留锚点;仅凭提交哈希或临时分支是不够的。当附件发布不可用时,不可变的、非发布用途的 evidence/ 标签可以保留历史 Git 托管的证据。其名称不遵循发布标签约定,也不受自动清理影响;只要证据仍被引用,它 MUST NOT 被移动或移除。在移除源文件之前,清理会验证远程锚点、确切字节和现有链接。
  • INV24 — 存储不改变证明或权威。 拉取请求的文本说明声明、已测试构建、相关状态、观察到的结果和证据链接;图像或即将过期的工件不是结论的唯一记录。附件在 INV16 下仍然是证据,而不是权威。特定于所有者的凭证要求、运维审计存储和 CI 工件生命周期仍归其当前所有者管理。AST-009 拥有 real-AT 凭证;INV12 拥有运维审计数据存储。AST-029 的 FR5 和 FR10 拥有审计拉取请求的证据凭证和精确头部资格报告。AST-030 的 FR12 拥有共享视觉回归执行和基线采用。此放置规则不新增捕获所有者,也不要求永久归档每次 CI 运行。

路径发现

  • INV25 — 每条当前记录都可以通过路径访问。 每条当前记录都通过放置、路径字段、名称、引用、继承或决定链接,从至少一个本身不是知识记录的仓库路径链接而来。优先按路径查找时,如果没有链接记录,则将该路径报告为未路由。它绝不根据文件名称、扩展名或目录名称推断链接。
  • INV26 — 路径适用性定位记录;声明仍然起决定作用。 如果记录的规则适用于其他链接无法到达的路径,则该记录在一个 path-applicability:v1 块中声明这些路径。匹配的路径会列出该记录。匹配不会扩大任何声明的范围(INV14),不会让该记录优先于范围更窄的所有者(INV9),也不要求行为必须位于指定的文件中(INV18)。每个模式至少匹配一个受跟踪的文件。

记录覆盖

  • INV27 — 仓库中的每条规范都是一条知识记录。 规范是指述明系统任何部分必须做什么的文件,与解释如何使用它的用户文档、指南和 README 相对;它是本记录所命名的某一种类的一条记录,存在于今天已有或以后添加的任何包中。它带有该种类的前置元数据(frontmatter),遵循 docs/templates/knowledge/ 中该种类的模板,并位于该种类的标准位置(属主代码)。任何包都不得定义自己的规范格式、模板或位置。Discovery 将每个受跟踪的名为 *.spec.md 的 Markdown 文件,以及 specs 目录下每个受跟踪的 Markdown 文件都视为记录候选;不是有效记录的候选会使 pnpm check:knowledge 失败。README.md 索引文件、plan.md 实施计划以及 Discovery 已忽略的路径不视为候选。

用户文档

  • INV28 — 每个公开 hook 都有一个最小的、可运行的示例来展示它。 公开 hook 是从已发布入口点导出的、由已发布包公开的 hook,正如构建后的 API 表面所列出的一样(architecture:public-component-api INV24)。它的文档至少包含一个真实、可运行的示例:一个实时模板块,将该 hook 命名为示例目标(exampleFor;当该块也服务于另一个页面时用 alsoExampleFor)。 该示例:
  • 在解决其文档所述用例的组件中展示该 hook;
  • 仅通过其公开入口点导入包自身的代码;
  • 覆盖该 hook 的主要参数和返回值;
  • 通过文档构建;
  • 其可见行为来自 hook 本身,因此移除 hook 会破坏示例所展示的内容;并且
  • 是最小的:只包含展示用例所需的代码,没有无关的 UI 或样式。
    文档页面如何选择示例块并对其排序,属于 `architecture:template-authoring`。没有符合要求的示例的公开 hook 是文档缺口,会在仓库的问题队列中作为 issue 跟踪(DEC-16)。
    

源代码注释

  • INV29 — 源代码注释只解释不显而易见的工作。 名称、结构和控制流让源代码自我解释。重述代码所做之事的注释是缺陷:修复方式是更清晰的代码,而不是注释。源代码注释只解释读者在代码中看不到的东西:原因、约束、不变量或浏览器/平台怪癖。它绝不叙述代码、重述名称或类型、提及拉取请求、issue 或日期,也不引用或援引知识记录。记录链接到代码,因此 pnpm specs:for <path> 能找到管辖记录,而组件的 {Name}.spec.md 保存其记录 ID。当注释的引用是文件与某条记录或主张之间的唯一链接时,先由记录链接该文件,然后才移除注释,因此 pnpm specs:for <path> 在前后列出相同的记录和被引用主张。整条记录的引用(如 AST-108)会变成被引用记录中的 applies_to、verified_by 或 path-applicability:v1 链接。这些链接到达整条记录,因此它们无法保留被引用的主张(如 AST-108 FR4)。文件自身组件、模块或主题记录中限定到主张的引用会保留它,方法是在被引用记录所属种类的引用字段中注明,例如 Spinner 记录中针对 Spinner.tsx 的 system_specs: [spec:AST-108/FR4]。pnpm check:knowledge 只解析主题或模块记录 references 中的 /DEC-N 主张,所以主题或模块文件中的主张引用(例如 butterTheme.ts 中的 AST-079 FR2)会一直保留到该检查解析任何主张后缀为止。在记录持有这些链接之一之前,引用会一直保留。注释遵循 ASD-STE100 Simplified Technical English 风格:指令最多 20 个单词,描述最多 25 个单词,每句话一个主题,使用主动语态、现在时、语义单一的简单词汇,且没有习语或填充词。以下注释可以保留:
  • 版权行;
  • 文件头:@input、@output、@position 和 SYNC: 提醒,最多约 12 行,没有重复主 JSDoc 的文字;
  • 导出组件、props、hooks 和工具函数上的 JSDoc,带有未标记的 @example 围栏;
  • 每个 Effect 上指明其同步的外部系统的注释(architecture:react-component-runtime INV3);
  • 工具读取的指令:lint 和 TypeScript 指令、浏览器无障碍规范文件头部注释中 spec:AST-030 FR12 读取的 @pr-a11y 路由行,以及仓库工具解析的任何其他注释行。

示例。下面这条注释违反了 INV29。它引用了记录,把多个主题塞进长句,并重述了它下方的 finalFocusRef 行:

// The returned focus shows the focus-visible ring only after keyboard
// input (`architecture:interaction-modality` INV1). The native close
// may already have restored focus to the target with a ring; the helper
// clears it first.
//
// With a sheet still open beneath this one, focus returns into that
// sheet: to the opener when it is there, else to the sheet's panel.
//
// An explicit `finalFocusRef` always receives focus, as released. The
// recorded opener of a non-modal sheet does so only if the person was
// still in the sheet when it closed (`hidePopover()` never moves
// focus, and the page behind it was live, so focus the person took
// elsewhere stays there).

这条注释遵循 INV29。每句话陈述一个事实,其余由代码陈述:

// The native close can show a focus ring on the target. Clear it. The ring
// shows only after keyboard input.
//
// If a sheet is open below, focus goes to this sheet's opener when it is in
// that sheet, else to that sheet's panel.
//
// A non-modal sheet returns focus to its opener only if focus was still in
// the sheet. The page behind it stays live, so the person can move focus
// away first.
  • INV30 — 来自团队之外的新外部链接需要一个人工所有者。 由不在团队中的作者发起的、向文档站或包文档添加外部 URL(指向本仓库和 Astryx 自有站点以外的站点)的 pull request,绝不会由自动化批准或合并。人工所有者会批准它,审查者会检查每个新链接是否属于该归属范围。团队作者发起的链接遵循常规门禁(DEC-17)。在此规则中:
    • 团队 是指 main 分支上 .github/ENGOWNERS 或 .github/DESIGNOWNERS 中列出的账户。机器人账户永远不属于团队。
    • Astryx 自有站点 是指 GitHub 上的本仓库、Astryx 文档站、Astryx 预览部署,以及 npm 上的 @astryxdesign 包。指向 Web 标准和平台参考(W3C、WHATWG、MDN、TC39)以及保留示例域名的链接,在此规则中不视为外部链接。
    • 人工所有者 是 cixzhang 或 DESIGNOWNER,在确切的 head 上给予批准。

审批行

  • INV31 — 记录的审批行仅可追加。 更改或删除现有决策的 Decider 行,或者用不同账户替换记录的 approved_by 的 pull request,需要原决策者在其确切的 head 上给予批准;cixzhang 自己的 pull request 可视为她本人的批准。添加决策或审批者不需要额外操作(DEC-18)。在此规则中:
    • 原决策者 是现有行中指名的账户。
    • 批准 是来自该账户的、在确切 head 上的批准审查,或 /approve-spec <完整 head SHA> 注释。除 cixzhang 之外的任何决策者,也会在其自己的 pull request 上批准确切的 head。
    • 更改 是指对该行的编辑或删除,包括被删除的决策。仅移动位置的行、在未更改的 Decider 行之后添加的文本,以及由真实决策者替换的占位决策者,都不属于更改。

记录状态

  • INV32 — 记录表述的是行为和决策,而非项目状态。 记录表述预期行为、边界、所有者、证据和决策。它不表述其背后的工作已进展到哪一步,也不表述这些工作发生的顺序(DEC-20)。这一点适用于每个部分,包括缺口或当前状态部分。在此规则中:
    • 构建状态 指对目前已编写、已构建或已发布内容的陈述:“构建尚未开始”、“还没有代码”、“尚不存在模块”、“未构建”、“尚未实现”、“后续工作”。
    • 排序 指对工作顺序的陈述:“首个消费者”、“首个采用者”、“采用顺序”、“Table 率先采用”、“早于 ... 落地”、“阶段 1”。系统自身遵循的顺序,例如先发布弃用再移除的发布规则,属于行为,而非排序。
    • 需求缺口 允许采用 <FR 或 INV id> gap: <可观察的不一致> 的形式。它指出系统目前做了哪些需求所禁止的事情,且不陈述任何构建状态或排序。
    • 状态行 是允许的:最多一行,例如 Status: in progress,只说明该记录仍在进行中。
    • 生命周期字段 是允许的:知识模板要求的字段,例如系统规格中的 phase 或 Released default preserved 行,说明的是记录自身的生命周期,而非构建进度,并予以保留。
    • 实施计划(plan.md)跟踪工作进度,不受此规则约束。

公共 API 作用范围

  • INV33 — pull request 添加或更改的每个公共 API 行都会在其作用范围中被指名。 pull request 指名其更改的组件和模块,并按组件列出其公共 API 行。不在该指名范围内、且当前没有任何获所有者批准的记录对其作出决策的行,会被发送给所有者并在列表中列出该行;在行被指名并获得所有者批准,或拆分为独立 pull request 之前,该 pull request 不会合并。若该范围之外的行已由当前记录作出决策,则无需进一步步骤(INV25),但状态仍会将其列为范围之外,以便审查者看到。在范围之外添加的行为处理程序(一个公共事件或回调 prop,例如 onClick,它使组件对输入作出反应)会发出警告。

路径适用性

当记录所管辖的路径无法通过其位置、路径字段、名称和继承链接覆盖时,可使用此可选块。已经能覆盖它所管辖的每条路径的记录无需标记。

{
  "paths": ["apps/docsite/**", "packages/**/*.doc.mjs"]
}

在选用该块的记录中,将示例标记替换为 path-applicability:v1。模式是相对于仓库的,且区分大小写。** 是一个完整段,可跨任意多个段;* 匹配单个段内的内容;? 匹配单个段内的一个字符。模式只能使用字母、数字、_ . @ - / 以及这些通配符。单独的 ** 会被拒绝。已检入的验证器会拒绝格式错误的块、不安全或重复的模式,以及不匹配任何受跟踪文件的模式。

全局审查适用性

仅当具名的声明适用于在其他方面互不相关的组件所有者时,才可使用此可选块。普通组件、模块、系列、设计、架构、主题和系统记录保持不标记。

{
  "scope": "global",
  "triggers": {
    "public-api": ["FR1", "DEC-2"],
    "accessibility": ["AR1"]
  }
}

在选用该块的记录中,将示例标记替换为 review-applicability:v1。触发器名称使用以下封闭词汇表:accessibility、behavior、compatibility、component-slots、docsite、interaction、layering、layout、motion、navigation、platform、public-api、react-runtime、responsive、scrolling、specification、styling、testing、theming、tokens 和 visual。每条触发器都有一个非空的唯一声明 ID 列表,且每个 ID 都解析为该记录中的一条显式编号声明。一个块可以添加 concerns 映射(INV20),也可以携带它来代替 triggers。每个采用小写短横线命名(lower-kebab)的 concern 都会列出 claims,以及 names(共享工具或实用程序的标识符)和 patterns(针对重新实现该工具或实用程序的代码的正则表达式)中的至少一项。

{
  "scope": "global",
  "concerns": {
    "slot-presence": {
      "names": ["isRenderable"],
      "patterns": ["typeof [\\w.]+ !== 'boolean'"],
      "claims": ["INV16"]
    }
  }
}

一个关注点存于拥有其声明的记录中,因此每条声明都从单一来源路由。已检入的验证器拒绝不受支持的触发器、格式错误的块、缺失或重复的声明、无效模式以及空路由。scripts/review-global-baselines.mjs 既要求精确审阅的 head,也要求其完整的基础权威提交,验证该提交是 head 的 origin/main 合并基,输出确定性排序的匹配行,并在 concernMatches 中列出 head 新增行所匹配的关注点对应的声明。因此,它不能将提议的 head 视为自身的权威来源。使用方在窄查询之前加载这些行,在审查回执中保留其出处,并在直接所有者被解析后仅应用所引用的声明。

编写规格说明与契约

这些规则在把读者最需要的决策置于首位的同时,保留语义保真度。它们是编写指导,而非关于人类可读性的量化声明。它们前瞻性地适用于新建或实质性修订的架构、组件和模块规格说明;不要求改写历史内容。

编写之前:

  1. 在当前记录中搜索相关行为、公共符号、受影响的路径,以及提议的规范所有者/ID。
  2. 在开放的拉取请求中搜索相同的所有者路径、符号和语义术语。
  3. 更新规范所有者,或与重叠的工作进行协调。仅当该事实具有不同的所有者时才创建新记录,并在拉取请求摘要中说明这一边界。

在每个组件或模块契约的标题之后,以这个读者优先的投影表开头:

领域 契约
公共契约 说明精确的公共 API、概念或语法差异;当无变化时写 None。
行为 说明可观察的治理行为,包括决定性的默认值、边界或优先级规则。
终端用户影响 指出谁在什么状态下受到影响,以及什么改进了、变差了或保持不变。
构建者影响 指出迁移工作及每个新的调用方选择;当没有新增负担时写 None。
兼容性/就绪度 说明默认兼容性、增量/破坏性状态、权威、需求缺口(INV32),以及仍待补充的实质性证据。
审查检查 列出使实现或提案在该契约下可被拒绝的少数具体条件。
治理规则 链接规范所有者以及为支持该投影所需的最新条款。

架构记录使用相同的位置和页脚,但行内容为架构专用:

领域 契约
治理契约 指出该架构所服务的可观察的现有决策;当没有产品契约变化时写 None。
系统行为 说明已交付的系统行为,包括决定性的不变量、边界或优先级规则。
终端用户影响 指出谁在什么状态下受到影响,以及什么改进了、变差了或保持不变。
构建者影响 指出该架构移除或添加的实现决策、协调工作或变通方案。
兼容性/就绪度 说明兼容性影响、权威、需求缺口(INV32),以及仍待补充的实质性证据。
审查检查 列出使变更可被拒绝的边界违规、产品 API 机制泄漏,或丢失的不变量/证据区分。
治理规则 链接具有决定性的规格说明以及为支持该投影所需的最新条款。

该表是一个审查投影;正文仍然具有权威性。投影本身并不会让记录变短。只有当作者在不丢弃契约语义的前提下从正文中移除真正的重复内容时,篇幅才会缩小。Review checks 从正文中投射出已确定的需求和边界;它们不会发明政策,也不会重新开启已作出的决策。当引用诸如 AST-002 FR 这样的列表项条款时,请使用其精确的可见标签和规范文件链接。不要为没有稳定标题或显式锚点的条款编造片段 URL。

然后编写权威正文:

  • 以现在时描述系统,而不是描述产生它的项目。docs/contributing/spec-writing.md 将这条规则和 INV10 转化为一份评分标准;创建或更改记录的拉取请求会在审查前于其描述中报告该评分标准的结果。
  • 说明预期的行为和决策,而非项目状态:不写构建状态,也不写工作指令(INV32)。需求缺口写成 <FR or INV id> gap: <observable mismatch>;像 Status: in progress 这样的单行文本可以表明记录仍在进行中,模板要求的生命周期字段予以保留。
  • 使用熟悉的词汇和简短直接的句子。
  • 将每条规则及其控制条件和例外完整陈述一次。后续章节引用其 ID 或规范所有者,而不是重述原文。
  • 只对正在决策的语义切片订立契约。将相邻行为命名为非目标或未订立契约的缺口;不要仅仅为了让记录显得 current 而填补它。
  • 不要复制使用方 prop 表、用法示例、共享系统机制、当前审计转储或实现步骤。链接它们的规范所有者。
  • 当可读的表能改善浏览时,用它们来表示分支或状态矩阵。绝不要仅仅为了缩短记录而移除契约内容。

对于例行的局部外观意图,组件或模块记录可在 Design relationships 下包含可选的带版本号的 Design decisions 表。每行使用稳定的、唯一的 DD id,并说明该决策、其意图或理由、适用范围以及允许的变体。仅当该意图足够持久、未来的重新设计必须重新考虑它时,才添加一行。首先重用或修改现有行。不要从代码/证据中复制精确的像素调优内容,也不要从 docs/design/ 中复制共享规则。模板中仅含表头的表是有效的;已编写的块至少包含一个完整行。

平实语言必须保留规范效力、谓词、基数、默认值、兼容性、权威、所有者、ID、证据状态和决策状态。不得删除、削弱、合并或隐藏不同的规范内容。仅当此记录的归属规则将该事实指派给另一个规范所有者时,才用链接替换本地事实。

限定词和权威动词是契约语义,而非润色。诸如 only、every、consistently、current、records、owns、delegates 和 inherits 等词语在重写过程中不得被删除、泛化、弱化或升级。重塑规则时,应将其动作、激活条件、例外或非目标、所有者以及证据状态,与它们所限定的声明放在同一行或同一列表项中。

不要以行数、词数、字节数或百分比缩减为目标进行优化。首先去除真正的重复,在不改变含义的前提下精简散文,使用易读的表格或列表,并按照 INV2 的要求链接真正共享的权威。保留每一个仍然承重的条件、限定词、边界、决策和证据区分。人类可扫描性和语义保真度优先于篇幅。

同一规则,更平实的形式

密集:

当 items 恰好包含一个可见项时,组件 MUST 恰好宣告那个项一次;当 items 包含零个或多于一个可见项时,它 MUST NOT 宣告任何项,且省略 items 的使用者 MUST 保持现有的静默行为。

平实:

条件 必需行为
省略 items MUST 保持现有的静默行为。
恰好存在一个可见项 MUST 恰好宣告那个项一次。
存在零个或多于一个项 MUST NOT 宣告任何项。

平实版本改变了形式,而非含义。

评审前

  • [ ] 将编辑后的文本与其来源进行比较,并确认上述每一项契约属性仍然明确。
  • [ ] 确认每条规则的动作、条件、限定词、例外或非目标、所有者、权威动词和证据状态仍然明确,并且与它们所限定的声明相邻。
  • [ ] 确认投影说明了公共增量、行为、最终用户和构建者影响、兼容性/就绪性、拒绝检查以及治理规则,且未替换或抵触权威主体。
  • [ ] 确认表格和列表在不隐藏内容的前提下提高了可扫描性,且没有仅仅为了达到篇幅目标而删除内容。

当当前记录不一致时

  1. 草稿仅供参考,不能与现行政策冲突。
  2. 从事实的范围识别规范所有者:聚合组件行为、独立公共模块行为、系列行为、设计表示、某个主题的语义/映射、跨主题架构、消费者用法或审计证据。
  3. 如果两条当前记录做出不同声明,则评审停止。不要根据新旧程度、路径相近性或具体性来选择;记录一个 novel-human 差距。
  4. 通过更改规范所有者并移除被复制的声明来解决该差距。有意例外由该所有者记录;受影响的记录链接到它,而不是重述它。
  5. 系统规范决策可以授权该更改,但在评审人员依赖它之前,当前所属契约必须在同一拉取请求中更改。

变更耦合

一份文档不会仅凭约定就保持现行有效。

在任何组件、模块、系列、设计、主题或架构记录成为 current 之前,仓库必须支持以下流程:

  1. 记录指明可能影响它的代码表面,以及验证它的检查。
  2. 触及该表面的拉取请求会触发一次聚焦的契约评审。
  3. 评审从拉取请求声明的首要意图出发,并将每个公共增量独立分类为五种结果之一:
    • preserves:该确切增量恢复或保留当前权威,且未在其之外添加公共 API 或行为;
    • settled:现有的当前人工决策覆盖该确切增量并被引用;
    • violates:该确切增量与当前权威相矛盾;
    • novel-human:没有当前权威解决该确切的公共 API、行为、所有权、兼容性或设计增量;或
    • out-of-scope:由另一个组件、模块、系列、系统或产品拥有。
  4. preserves 和 settled 进入正常正确性评审。只有当实现和证据也通过时,它们才有资格获得批准。
  5. violates 会收到请求变更,并附带最小的合规补救措施:更改或移除违规增量。评审不会仅仅为了挽救矛盾的实现而推荐规范;所有者可以单独选择提出策略变更。
  6. 可分离的 novel-human 附带变更会从首要意图中移除或拆分出来。评审可以要求进行该收缩,而无需决定附带变更的语义,然后继续评审其余变更。只有当 novel-human 增量是首要意图、与其不可分离,或作者或所有者明确选择推进它时,它才进入人工持有阶段。拉取请求的公共 API 增量(architecture:public-component-api INV24)中新增或更改的一行如果是 novel-human,则无论是否可分离,都会将该拉取请求连同该行一起发送至人工评审;该记录的所有者会接受、拆分或移除该行,且评审绝不会仅针对该行请求变更。
  7. 错误修复仅在恢复现有当前权威且未超出该契约更改公共 API 或公共行为时才属于 preserves。任何可分离的 API、视觉、布局或交互附带变更遵循第 5 或 6 步,而不是让恢复等待更广泛的规范。
  8. 当当前组件、系列、设计、主题或客观可访问性权威覆盖其确切结果时,视觉修正可以是 preserves 或 settled。真实的渲染证据必须证明受影响的状态和具有代表性的未更改状态。新的视觉表示仍是 novel-human;称其为改进并不能使其成为 settled。
  9. 审计新鲜度根据相同的代码和测试关系计算,因此相关的代码更改不能使审计看起来仍然是当前的。

Audit-storage(审计存储)迁移是一个独立的契约变更。它需要版本化的数据契约、对现有 wiki 行的自动化转换与对账、过渡期间命名的唯一事实来源、sandbox-reader 切换,以及回滚证据。仅仓库本地的逐组件文件本身并不构成迁移计划。

在升级处理之前先收敛契约

审查与构建应当收敛到能够落地的最小理想变更:

  1. 说明 Pull Request 的主要意图,并划分其可观察的差异(delta)。
  2. 将当前权威(current authority)应用于每个差异。即使组件记录没有列举其精确绘制细节,现有设计与客观标准也可以解决视觉修正问题。
  3. 对于矛盾之处,使其符合规范或将其移除。除非改变策略本身就是一个有意的、需要单独审查的目标,否则不要提议修改规范。
  4. 对于尚未确定但可分离的差异,将其移除或拆分。继续主要变更,不要要求贡献者解决相邻的系统设计。未声明的公共 API 行是例外:它将进入人工审查,由负责人接受、拆分或移除(变更耦合步骤 6)。
  5. 只有幸存下来的、有意的 novel-human 差异、未声明的公共 API 行,或记录未定义的新内部模块或钩子,才应升级处理(System model,DEC-22)。只记录该差异所需的确切决策;相邻模块行为可以保持未签约(uncontracted)状态。

可执行的审查结果应指明该可落地收缩(landing-ready contraction)的验收标准。它不应仅仅报告缺少权威。

记录新的人工决策

  1. 贡献者以普通的 Pull Request 语言解释预期行为与主要意图,并回应审查。外部贡献者保持正常的贡献流程:永远不会要求他们撰写或更新规范。
  2. 审查者或代理应用上述收缩路径。只有幸存下来的、有意的 novel-human 问题才会继续推进;贡献者不会自行发明答案,也不会规范无关的相邻行为。未声明的公共 API 行也会继续推进,如变更耦合步骤 6 所述,而不是由审查移除或拆分。
  3. 经授权的负责人(owner)在 Pull Request 审查中作答。
  4. 维护者或代理将该裁定记录到规范的属主记录(canonical owning record)中。
    • 当维护者可以更新分支时,优先在同一个 Pull Request 中提交。
    • 如果他们无法更新贡献者分支,则在该 PR 下方打开一个小的、关联的规范 Pull Request,并在该决策落地后对实现进行变基(rebase)。
    • 如果方向被接受,贡献者按需更新代码。
    • 如果方向被拒绝,则移除或更改被拒绝的实现。仅当边界影响重大且很可能再次出现时,才记录被拒绝的替代方案。
  5. 最终提交会使先前的批准失效。在记录与实现一致之后,负责人批准确切的最新提交(heads)。

如果没有实现方向被接受,则关闭贡献者的 Pull Request。仅当裁定本身独立有用时,维护者拥有的规范 Pull Request 才保留。

审查评论是对话的证据;已检入的记录才是规范的决策。

记录持久的结果,而不是审查记录。当以下至少一项成立时,裁定应属于规范记录:

  • 它改变或澄清了某个属主组件、模块、族(family)或系统边界;
  • 它确立了未来工作必须保留的需求或禁令;或
  • 它拒绝了一个影响重大且很可能再次出现的替代方案。

被放弃的 Pull Request 中的属性名、实现机制或失败的视觉实验应保留在审查历史中,除非该细节本身通过上述测试。

仅当裁定改变了超出贡献者变更范围的共享契约、且应当独立落地或复用时,才使用单独的较低层规范 Pull Request。实现 Pull Request 随后基于该决策进行变基。

示例:

  • NumberInput 更改了其步进(stepping)数学逻辑。其当前契约规定最终操作会钳制到 min/max,且映射的测试仍然通过。结果:preserves;无需人工提问,继续正常的正确性审查。
  • 一个新的 NumberInput 路径使用了之前已批准的相同转换顺序。结果:settled;引用该 DEC,继续正常的正确性审查。
  • 一个包导出的上下文更改了某个必需函数参数,而其当前契约保留了较早的操作形态。结果:violates;请求最小的符合性变更。新的兼容性策略是一个单独的提案,而不是默认的修复方式。
  • 一个滚动溢出修复还引入了新的悬停披露(hover disclosure)。溢出恢复在其现有布局权威下继续进行。如果披露缺乏权威,则移除或拆分这个可分离的视觉附带变更;不要要求该缺陷修复来规范整个交互模块。
  • Selector 的主要意图是移除空指示器空间,但当前没有决策说明选项标签是否必须保持对齐。结果:novel-human;在负责人决定确切对齐契约期间,将其私下保留。
  • 一个产品请求为族属(family-owned)输入布局规则添加一次性宽度属性。结果:out-of-scope;将该变更路由到族契约,而不是创建组件特定的 API。

草稿记录无法消除审查缺口。只有经过验证的 current 契约或适用的决策才能产生 preserves 或 settled。

在流程通过历史审查基准并在 Pull Request 上强制执行之前,引导(bootstrap)不会将任何组件、模块或族记录标记为 current。

属主代码

  • AGENTS.md 将审查者指向最窄的相关记录。
  • docs/templates/knowledge/ 包含唯一的编写表单;软件包不保留自己的模板(INV27)。
  • 组件记录位于 docs/specs/components/<ComponentRoot>/ 中,每个组件根目录一个文件夹,作为直接的 <PublicName>.spec.md 子项(DEC-15)。文件夹树镜像组件的源代码树:组件根目录是 Core(packages/core/src/)或 Lab(packages/lab/src/)的组件目录,或者是 scripts/component-packages.cjs 注册的扁平组件包(Charts、RichText 和 Vega)的顶级模块,其记录为 docs/specs/components/<PublicName>/<PublicName>.spec.md。拥有记录的包是其源代码树包含该组件根的包;当两个包具有同名的根时,则是持有记录代码的那个包。平台实现的记录位于同一文件夹中,文件名为 <PublicName>.<language>.spec.md(例如 docs/specs/components/Button/Button.swift.spec.md),其 id 为 component:<language>/<PublicName>(例如 component:swift/Button),在其 platform_of 中命名其核心组件(component:<PublicName>),并且只说明该平台新增或必须不同处理的内容;核心记录保有共享契约(INV2)。在核心组件拥有自己的记录之前,其公共源代码和文档可充当该契约。公共名称通常与根目录匹配;父子/成员例外要求在该根目录中有精确的顶级或完整的内联消费者文档条目。公共语义模块记录嵌套在同一文件夹下至少一层目录中,通常位于 modules/,或位于插件自己的文件夹中,例如 Table/plugins/rowStatus/。子目录不必与模块代码所在位置匹配:查找通过代码的文件名或其 verified_by 证据到达记录。父组件的 modules 列表与模块的 parent_component 字段必须一致。组件包的源代码树和 packages/native/apple/Sources/ 都不包含 *.spec.md。隐藏路径、fixture、测试、生成、构建输出、覆盖率、依赖以及 *.generated.spec.md 路径在发现和 PR 路由中会被一致地忽略。
  • Wiki 中的 component-scores.json 是当前的操作性审计数据存储。历史性的 <PublicName>.audit.json 保留从未获得模式或活动记录,并已被 INV12 退役。
  • 管理某个软件包跨组件规则的记录位于该包的 specs/ 目录下,文件名为 <slug>.spec.md,kind(种类)为 architecture,id 为 architecture: 后跟包名、specs/ 与文件之间的每个目录以及 slug,用连字符连接。例如,packages/native/specs/swift/accessibility.spec.md 为 architecture:native-swift-accessibility。仓库级架构位于 docs/architecture/ 中。
  • packages/themes/<theme>/<theme>.spec.md 包含该包主题的规范记录;docs/themes/README.md 只是指南和索引。
  • docs/schemas/knowledge/ 定义了所需结构。
  • scripts/check-knowledge.mjs 验证模板、记录、批准元数据、可选的组件/模块设计决策表、path-applicability:v1 块以及 INV25 可达性。
  • scripts/specs-for-file.mjs(pnpm specs:for)解析与路径相关联的记录。--unrouted 列出没有关联 current 记录的已跟踪路径;--unreached 列出没有任何路径可达的 current 记录。
  • .github/scripts/component-design-decisions.cjs 根据可信的 base 和 head 字节,将当前的组件/模块变更分类为无 DD 变更、仅 DD 或混合变更。仅 DD 要求路径、kind、权威不变,且有效可选块之外的每一个字节都不变。
  • .github/scripts/knowledge-paths.cjs 保存着唯一的记录路径列表。它命名了 check:knowledge 发现的记录以及受属主门禁(owner-gated)的路径:每一条记录;docs/specs/ 或软件包的 specs/ 或 docs/architecture/ 下的每一个 Markdown 文件(包括 README);族、设计、架构和主题文档文件夹中的每一个 Markdown 文件(每个文件夹的 README.md 索引除外);主题包中的每一个 *.spec.md;以及规范性设计资产。被忽略的位置保持被忽略。
  • .github/scripts/change-scope.cjs 识别纯规范记录变更以及变更所触及的受属主门禁路径,并为工作流之外的调用者分类路径(--classify-paths)。
  • .github/workflows/review-signal.yml 发布唯一的审查门禁 review-required,它也承载规范属主批准(DEC-14)。一个属主批准涵盖 Pull Request 中的每一个知识记录变更,并约束批准的具体规范内容,而不是某个提交。每种记录类型的批准均源自 .github/ENGOWNERS;当前的设计和主题记录、规范性设计资产以及仅 DD 的当前组件/模块变更还额外接受 .github/DESIGNOWNERS,但设计属主的批准(审查或 /approve-spec)不能单独批准可访问性要求或弃用(即使位于当前设计或主题记录内部也是如此)(DEC-14)。混合的 DD 加上其他组件/模块编辑需要两个组都批准。没有自身权威的受属主门禁 Markdown 文件(例如规范旁边的生成表)需要工程属主批准。记录元数据永远不会自我授权。该门禁只决定批准;它从不启用自动合并。该门禁不会检测来自团队外的新外部链接(INV30);请参见“验证”下的执行缺口。
  • .github/workflows/review-signal.yml 允许 DESIGNOWNER 作者绕过工程门禁,但前提是可信的 base 代码验证了已更改的每一行 Core 都是根据获取的 base/head 源字节、在真实的 stylex.create 调用中作为保守声明而存在,并且没有其他代码原因适用。分类器还会拒绝任一 diff 侧上的直接交互、可操作性(operability)和滚动控制声明——包括命中测试、触摸行为、选择、调整大小、光标、可见性、溢出、吸附(snapping)和滚动条提示(scrollbar affordance)。贡献者以及混合或行为性变更仍然受到门禁限制。

安全空间分类同时考虑当前路径和先前路径:只有当变更的每个路径都是安全的时,该变更才会被排除;任何跨越该边界的重命名都是一个工程理由。工程审查和设计审查仅在它们的 commit_id 等于当前拉取请求头部时才会被计入。直接协调器只清除已由 review-signal 拥有的当前头部门禁;有效的 ENGOWNER CHANGES_REQUESTED 或 DISMISSED 状态会先将硬性状态门禁恢复为 pending,再恢复其建议性标签。状态写入失败时不会执行任何前置标签变更。批准、撤回和驳回都会在变更前立即重新检查头部;未设门禁的头部绝不会仅凭审查状态获得门禁。对于实时仓库权限为 write 或 admin 的作者,REVIEW_APP 仓库变量中指定的审查应用在 DEC-11 下也满足工程门禁。只有该应用最新的、且 commit_id 等于当前头部的 APPROVED、CHANGES_REQUESTED 或 DISMISSED 审查才会计入。两个工作流在每次评估时都会读取作者权限,并使用各自的 Actions 令牌发布状态。

决策规范

DEC-1 — 当前记录冲突不按优先级解决

引用: architecture:knowledge-contracts/DEC-1 决策者: cixzhang, 2026-08-30

一条当前记录不会因为更新、更窄或更接近代码而覆盖另一条记录。审查会停下来,识别规范所有者,并在该处解决冲突。其他记录链接到所属决策,而不是复制它。

已拒绝:静默选择最新或最具体的记录,因为这会把文档顺序变成未经审查的系统策略。

DEC-2 — 新裁定通常留在贡献者的拉取请求中

引用: architecture:knowledge-contracts/DEC-2 决策者: cixzhang, 2026-08-30

人工裁定通常会在暴露该空白的拉取请求中讨论。贡献者负责解释意图并修改其代码;维护者和审查代理负责规范体系。他们尽可能在同一个分支中记录该裁定;当贡献者分支无法更新时,则记录在一个小的、关联的下层规范 PR 中。被拒绝的实现会被移除或修改;被拒绝的替代方案仅在它能保护某个重要边界免于再次被争论时才被记录。当前规范内容的最终所有者批准,证明决策与实现是一致的。

已拒绝:要求所有者针对每个裁定都开启第二个拉取请求,因为这会把答案与变更分开,并增加不必要的审查工作。

DEC-3 — 写入前搜索重叠的权威范围

引用: architecture:knowledge-contracts/DEC-3 决策者: cixzhang, 2026-09-07

在起草新记录或实质性扩大现有记录之前,应使用比拟定标题更多的条件搜索当前记录和开放的拉取请求:规范所有者/ID、受影响路径、导出的符号以及语义行为术语。当事实已属于该规范所有者时,扩展该所有者或将事实归入其中。只有针对一个不同的事实边界才创建新记录,并解释为什么现有所有者无法容纳它。

已拒绝:仅搜索文件名或已落地的记录。语义重叠可能使用不同的标题,开放的工作也可能在落地之前就已经在改变同一所有者。开放的拉取请求用于协调工作并提供证据;它们不会成为权威。

DEC-4 — 收窄先于新权威

引用: architecture:knowledge-contracts/DEC-4 决策者: cixzhang, 2026-09-11

当一个原本可审查的变更带有可分离的矛盾或未决决策时,移除或拆分该增量,并让主要意图继续推进。只有在存留的增量被有意作为持久行为追求时才推荐规范,而不是因为审查发现了相邻的不完整性。未声明的公共 API 行是例外:变更耦合步骤 6 会将其发送给人工审查以做出所有者决策,审查不会移除或拆分它。

已拒绝:将每个未被收窄的附带项都变成规范项目,因为这会让一个窄小的修复吸收无关的设计工作,并让贡献者没有可落地的路径。

DEC-5 — 当前批准以主张为范围

引用: architecture:knowledge-contracts/DEC-5 决策者: cixzhang, 2026-09-11

一条当前记录只在其所述所有权边界内授权其明确主张。它可以有意让相邻行为保持未收窄状态。审查者不应将 current 视为整个组件或公共模块已被完全规范的认证,也不应在应用一项范围窄小的已批准决策之前要求无关的覆盖。

已拒绝:要求一个范围窄小的视觉或行为决策去收窄所命名模块的每个 API、组合、可访问性和实现事实。

DEC-6 — 产品规范为准;生成的审查上下文仅供参考

引用: architecture:knowledge-contracts/DEC-6 决策者: cixzhang, 2026-09-12

已提交的当前产品记录决定预期行为。审查从这些主张开始,仅使用生成的上下文、清单、测试、截图、测量和建议来证明符合性、矛盾性或具体缺陷。生成的完整性和绿色检查永远不会创造权威,也不会升级权威结果。

当拉取请求或当前记录使上下文保持隐含时,审查可以通过三个“为什么”问题追溯问题、将解决方案映射回该问题、并指出附带项来填补空白。它还可以解释受影响的用户、支持的状态、启用或阻止的行为,以及调用方的负担。这些解释仍是上下文,除非规范产品所有者将其记录为当前行为。

已拒绝:将完整的审查表单、有说服力的影响叙述或通过的验证矩阵视为产品方向的替代来源。

DEC-7 — 产品规范将行为契约化,而非内部架构

参考: architecture:knowledge-contracts/DEC-7 决策者: cixzhang, 2026-09-12

新的或经实质性修订的产品规范应规定符合性实现必须满足的可观察契约,并让等价的外部实现保持自由。仅当调用方或互操作系统的确有意识地依赖某机制作为公共行为时,规范才指明该确切机制。否则,内部所有权与接缝归属架构记录,验证仍作为证据,而非规定的 CI 或测试拓扑。

此编写规则具有前瞻性。在指定的人类所有者迁移之前,现有现行记录保留其明确权威;添加此规则不能静默地使诸如遗留实现约束之类的要求失效。当修正涉及此类要求时,所有者要么证明该机制是公开可观察的,要么将其移至适用的架构记录。

已拒绝:仅因为某实现提供了决策证据,就将成功原型的模块图、算法、清单、日志、锁、事务设计、文件系统布局或 CI 任务提升为产品要求。

DEC-8 — 规范审查是针对人类所有者的咨询性分析

参考: architecture:knowledge-contracts/DEC-8 决策者: cixzhang, 2026-09-12

对规范的自动化审查不止于将变更路由给人类。它首先会就规范所有者、现有及重叠声明、所有权冲突、声明范围、错置的架构以及确切契约编辑,生成书面且有证据支撑的反馈。该分析帮助人类所有者检查决策;它绝不替代所有者的批准,也不成为权威。

已拒绝:因为检查通过就自动批准规范,或只返回“需要人类”而不向所有者提供审查者已经掌握的契约与所有权分析。

DEC-9 — 全局适用性路由精确声明,而非整份记录

参考: architecture:knowledge-contracts/DEC-9 决策者: cixzhang, 2026-09-19

跨领域规则仅在通过经过验证的 review-applicability:v1 块时,才能在没有组件反向链接的情况下被发现。每个语义触发器都指明确切的本地声明 ID。审查者在加载更具体的记录之前,先从基础权威提交加载匹配的当前声明,保留匹配来源,然后在该直接所有者管辖变更时优先解析直接所有者。

已拒绝:将 global 标记视为文件中每一条声明的权威,因为那会抹除声明边界,并让无关或草稿材料静默地支配变更。

DEC-10 — 常规视觉意图位于其组件或模块中

参考: architecture:knowledge-contracts/DEC-10 决策者: cixzhang, 2026-09-23

拥有组件或模块规范中的小型结构化 Design decisions 表仅记录持久的本地视觉意图。一行可涵盖一条连贯的本地方向;微小的视觉调整不会为每次微调创建一条决策记录。在添加新行之前,现有行会被引用、复用或修改。精确像素保留在代码和证据中,而共享和跨组件的方向保留在 docs/design/ 中。

团队 DESIGNOWNER 可以将本地决策、实现和证据包含在一个原子的仅外观拉取请求中。仅 DD 的现行记录变更路由至设计审批;将 DD 编辑与另一个组件/模块契约编辑混合需要设计和工程两者。DESIGNOWNER 与所有其他所有者一样,使用 /approve-spec <sha> 进行批准。仅当可信基础分类证明现有文件是仅声明外观差异且没有其他代码原因适用时,Core 代码门才被绕过。任何不确定性、贡献者编写的变更、行为、JSX、API、包、barrel 文件、新组件或未知运行时路径都会失败关闭至工程审查。

外部贡献者解释意图并提供常规证据;维护者拥有规范工作,并且绝不要求贡献者编写规范。请求或对话是决策输入,而非已提交的权威。编辑后的现行记录仅在所有者批准其内容后才可复用(DEC-14)。

已拒绝:sidecar 记录或每次像素微调一条设计记录,因为这会将该常规意图与其所有者拆分;在设计请求得到所有者批准之前就将其视为权威,因为可审查的意图尚未成为已提交的策略。

DEC-11 — 审查应用的批准可为拥有写权限的作者清除代码门

参考: architecture:knowledge-contracts/DEC-11 决策者: cixzhang, 2026-10-15

拥有仓库写权限或管理员权限的作者是内部贡献者,无论他们是否是工程或设计所有者;拥有写权限的设计师和合作伙伴也包含在内。对于这些作者,已配置审查应用的最新精确头部裁决决定工程门禁:批准会清除门禁,而之后的变更请求、撤销或新提交会使其重新变为待处理。有效的 ENGOWNER 对精确头部提出变更请求会使得门禁在应用批准之上仍保持待处理,而 ENGOWNER 的批准仍可为每位作者清除门禁。

没有写权限的作者,包括只读成员和 fork 贡献者,只能通过 ENGOWNER 批准来清除门禁。权限来自评估时仓库的协作者权限,而非所有者列表、组织成员身份或作者关联。未设置的 REVIEW_APP、不可读的权限或任何较低权限都会使应用的审查不产生效果。该状态由工作流自身的身份发布,绝不由个人账户发布。

已拒绝:统计拉取请求上的任何应用批准,因为对较早头部的批准或在之后有变更请求的批准都会让门禁保持清除。

DEC-12 — 记录在可选覆盖层中声明其管辖的路径

参考: architecture:knowledge-contracts/DEC-12 决策者: cixzhang,2026-10-21

一份用于管辖其他链接无法到达路径的记录,在可选的 path-applicability:v1 块中声明 glob 模式,与 review-applicability:v1 并列。该叠加层独立版本化,因此选择加入不会改变某个记录种类的必需形态,也不会迁移其他记录。路径优先的查找会列出一条匹配的记录;声明范围、优先级和实现自由度均保持不变。

已否决:要求每种记录都带 applies_to 字段,因为这会迁移每一条活动记录,让它们声明大多已通过放置或继承覆盖到的路径。已否决:正则表达式,因为评审者无法一眼看出其覆盖范围,而且它们会静默过度匹配。

DEC-13 —— 每个规范都是知识记录,无论它位于何处

参考: architecture:knowledge-contracts/DEC-13 决策者: cixzhang,2026-10-23

任何包中的规范记录(包括以后新增的包)都使用本记录定义的记录种类、frontmatter、模板和放置方式;对于具备规范形态、但并非有效记录的文件,发现机制会判定其失败。平台实现的组件记录是一个语言限定 id 的 component 记录,其 id 指向核心组件,因此核心记录保留共享契约,平台记录只承载平台自身的部分。在核心组件拥有自己的记录之前,其公共源码和文档暂时充当该契约。

已否决:包内自有的规范格式,因为其记录会跳过结构检查、所有者门禁和路径路由。

DEC-14 —— 一次所有者批准即对拉取请求的规范内容产生约束

参考: architecture:knowledge-contracts/DEC-14 决策者: cixzhang,2026-10-28

规范所有者会整体审阅一个拉取请求的知识记录改动,并整体批准或要求返工。该批准约束的是规范内容:一个指纹覆盖所有被所有者门禁的已更改路径,每条路径都在某个提交处读取。在 Markdown 记录中,指纹会省略 frontmatter 中的 authority、approved_by 和 approved_at 值,因此记录一次批准以及将记录从 draft 移到 current 都不会改变指纹。工作流完全根据拉取请求的文件计算每个指纹;没有任何注释、标签或状态参与提供指纹。

  • 批准行为。 以下每种行为,由符合条件的所有者执行时,都会批准其指定的提交内容,并且只要该提交的指纹等于当前 head 的指纹,该批准就持续有效:

    • 一条 /approve-spec <sha> 注释,指定完整的提交 SHA;该 SHA 表明所有者审阅的是哪个内容;
    • 一个针对其提交的 GitHub 批准式评审(approving review)。

      /revoke-spec(带或不带 SHA)以及针对其他规范内容提出的修改请求,都会撤销该所有者的批准,直到其再次批准为止。针对当前规范内容提出的修改请求会卡住门禁,直到该所有者再次批准。表情反应不算批准。 资格遵循上述所有者分组。ENGOWNER 作者可以用 /approve-spec 批准自己的拉取请求;作者本人的批准式评审永远不计入。列在 .github/DESIGNOWNERS 中的设计所有者批准设计记录和主题记录(设计规则与决策:视觉与交互外观),包括在他们自己的拉取请求上用 /approve-spec 批准。公共 API、行为规则、无障碍需求和弃用(deprecation)需要工程所有者(.github/ENGOWNERS):设计所有者的批准(评审或 /approve-spec)不能单独批准一项无障碍需求或弃用,即使是在当前的设计记录或主题记录之内。当前缺口:门禁仅按记录种类路由批准,因此设计所有者的单独批准即可放行当前设计记录或主题记录,即使其改动带有无障碍需求或弃用——无论是他们自己在自己拉取请求上的 /approve-spec,还是他们对贡献者拉取请求的批准式评审,都是如此。.github/scripts/spec-owner-decision.cjs 只按记录种类选择所有者分组,并没有对无障碍需求或弃用的检查。

  • 什么会保持批准。 只更改其他路径的提交、来自基础分支的合并、变基以及批准记账操作都不会改变指纹,因此它们会保持所有批准有效。

  • 什么会重置它。 已批准规范文本发生变化、出现新的已更改规范路径,或者 head 丢弃了某项已批准的规范改动;先前的批准停止计数,直到有所有者批准一个携带当前内容的提交。
  • 单一评审门禁。 review-required 同时承载代码评审和规范批准。在代码评审缺失时,由它先行;一旦代码评审满足,缺失的规范批准会在同一个状态上显示;成功需要两者都满足。缺失的批准是 pending,绝不是失败。该状态会指明谁可以批准:

    仍缺失的规范分组 review-required 文本
    工程(单独或与设计/主题一起) ⏳ Waiting for human spec approval: an eng owner can reply /approve-spec <sha>
    仅设计或主题 ⏳ Waiting for human spec approval: a design or eng owner can reply /approve-spec <sha>

当修改请求卡住门禁时,它会改而点名其所有者:…: @owner requested changes and can reply /approve-spec <sha>。已批准的规范改动在代码评审结果旁边显示为 ✅ Spec approved by @owner。ENGOWNER 的批准可满足所有分组。

  • 详情。 门禁的详情会给出可供复制的 head 命令,列出已更改的记录(id、标题、authority 变更,以及每条记录所需的分组)、已更改路径和指纹,并说明为什么先前的某个行为不再计数:规范在批准后发生了变化、该批准被撤销,或者命令格式错误。
  • 决策记录。 spec-owner-approval 用最小化描述上报规范半边,review-required 的其他写入方会从它读取规范半边。它并非必需检查,也不会决定 review-required 尚未展示的任何事项。
  • 事件覆盖。 每个拉取请求事件、同仓库评审以及所有者命令都会重新评估门禁,每次评估都会为其读取的 head 发布一个终态。来自 fork 的评审携带只读令牌,会被跳过,因此所有者通过命令来批准 fork 的拉取请求。不是所有者命令的评论不会启动 runner。如果某次运行会超出 spec-owner 任务的请求预算,门禁会保持 pending,因为变更过大而无法自动协调;此时由维护者触发的运行来决定(spec:AST-030 FR15)。

已拒绝:精确头部绑定(记录批准后,每次基础合并 都会强制重新批准未更改的文本);按记录或按章节批准 (规范审查是全有或全无);没有 SHA 的命令(就在它之前的一次推送 会在未经查看的情况下被批准);单独的规范状态(一个门禁,一条消息); 表情回应批准(没有事件,因此需要一个轮询任务);工作流推送的 draft-到-current 变更(它不会触发检查,也无法写入 fork)。

DEC-15 — 一个组件的记录位于 docs 下的一个文件夹中,适用于每个平台

参考: architecture:knowledge-contracts/DEC-15 决策者: cixzhang,2026-10-28

每个组件记录和模块记录都位于 docs/specs/components/<ComponentRoot>/ 中,结构按照组件的源代码树组织, 因此在任何平台上处理某个组件的人都能在一个文件夹中看到其核心契约和每个平台的记录。 查找仍然是路径优先:发现过程读取该树,放置过程将每条记录映射到其文件夹所镜像的源目录。 记录 ID 和内容不会因移动而改变。

已拒绝:将记录放在每个包的代码旁边,因为这样组件的核心记录和平台记录会位于不同的包中, 而且每个平台包都需要自己的规范位置。

DEC-16 — Hook 示例受规范约束,缺口即问题

参考: architecture:knowledge-contracts/DEC-16 决策者: cixzhang,2026-11-01

Hook 文档受本记录约束,每个公开 hook 的文档都包含一个最小、可运行的示例来演示该 hook(INV28)。 缺失或不符合规范的示例是仓库问题队列中的一个 issue,其规模适合贡献者首次上手。 所有者的指示是:“应由规范约束,任何缺口都应是 astryx 问题队列中的 issue。它们很适合贡献者首次参与”,以及“对于任何示例,确保它确实演示了该 hook。理想情况下,它应该相当精简”。

示例覆盖率报告检查 hook 示例的方式与检查组件文档示例的方式相同:它报告缺失和不符合规范的示例, 并且绝不会阻止合并或发布(所有者决定,2026-09-30)。

已拒绝:一个渲染了内部调用 hook 的组件的示例,因为读者永远看不到 hook 的接线方式。

参考: architecture:knowledge-contracts/DEC-17 决策者: cixzhang,2026-11-08

来自团队外部作者的拉取请求,如果向文档站点或包文档添加外部 URL,必须由人工负责人批准, 绝不能由自动化批准(INV30)。自动化批准不得发布外部贡献者在未经人工检查的情况下添加的链接。 团队撰写的链接遵循正常门禁。

DEC-18 — 记录的批准行是仅追加的

参考: architecture:knowledge-contracts/DEC-18 决策者: cixzhang,2026-11-08

现有决定的 Decider 行和记录的 approved_by 只有在精确头部获得原始决策者批准时才能更改(INV31)。 批准行记录的是谁做的决定,因此没有那个人的重写会署上并未做出决定的人的名字。 只有 cixzhang 自己的拉取请求才算是对她自己行的批准;其他每位决策者都批准精确头部。 新决定和新增批准者遵循正常门禁。

DEC-19 — 仅涉及 Lab 的拉取请求无需所有者决定

参考: architecture:knowledge-contracts/DEC-19 决策者: cixzhang,2026-11-04

所有者说过:“任何仅涉及 Lab 的内容都会得到同意”。按照 spec:AST-030 FR26 的定义, 仅涉及 Lab 的拉取请求,其 Lab 行为或 Lab API 无需所有者决定(INV4)。 它更改的 Lab 记录仍然需要工程负责人在拉取请求头部进行 /approve-spec(DEC-14)。 根据 FR26 不算是仅涉及 Lab 的拉取请求,对其更改的每个部分都遵循正常的所有者规则; 拆分出非 Lab 部分后,其余部分就变成了仅涉及 Lab。

已拒绝:将同时更改 Core 或其他包的拉取请求视为仅涉及 Lab。

DEC-20 — 记录陈述行为和决定,而非项目状态

参考: architecture:knowledge-contracts/DEC-20 决策者: cixzhang,2026-11-09

所有者说过:“我们也应该书面规定,规范应避免包含项目的临时状态,比如已经写了什么或什么优先。 但它可以包含类似‘仍在进行中’的陈述”。记录陈述的是预期行为和决定(INV32)。 构建状态和工作顺序会随着工作的推进而变得过时,后来的读者无法区分过时的状态行和需求。 需求缺口以 <FR or INV id> gap: <observable mismatch> 的形式保留,因为它指出了系统必须更改的行为。 Status: in progress 这样的单行状态可以说明记录仍在进行中。实施计划和拉取请求承载工作的进度和顺序。

已拒绝:一个对状态短语报错的检查,因为同样的词语也描述行为(“焦点落定”,“在 Action 待处理期间”)。

DEC-21 — 拉取请求范围之外的公共 API 行需要决定

参考: architecture:knowledge-contracts/DEC-21 决策者: cixzhang,2026-11-09

所有者说过:“我认为对于像 3280 这样的大型 PR,我们需要更好的护栏来防止捎带更改(tag-along)”。 一次大型导入曾经在没有记录任何决定的情况下,带来了 Item 的 onClick 行和容器点击。 上述规则使得这种捎带更改在合并之前可见。已拒绝:依赖审查来捕获大型拉取请求中的捎带更改。

DEC-22 — 未定义的内部模块或 hook 需要所有者决定

决策者: cixzhang,2026-11-10

所有者说过:“基本上,我们不应该批准任何 API 模糊且未被规范定义的内容。那些内容需要人工审查”。 未声明的公共 API 行已经进入所有者审查。其他组件可以导入的新的内部模块或 hook 同样是组件之间的 API, 因此,对于某个没有记录定义的模块或 hook,审查会要求修改,直到所有者做出决定, 并显示增量:用法、为什么需要它,以及为什么现有模块不够用。

已拒绝:将每个内部模块或 Hook 视为私有辅助工具。

验证

不变量 证据 失败信号
INV1, INV6 scripts/check-knowledge.test.mjs 未经批准的当前记录或未迁移的活动记录通过检查
INV5, INV7 .github/scripts/change-scope.test.mjs 模板、模式、指南、架构、代码变更、不安全的重命名或截断列表被认定为仅规范变更
批准遵循规范内容 .github/scripts/spec-owner-decision.test.mjs 对其他规范内容的批准通过了门禁,自封所有者成为审批者,或错误的所有者组批准了当前记录
INV3, INV4, INV11 盲审历史回顾基准 评审者重新提出已决决策、发明新决策、批准未定的公开变更,或将矛盾视为保持不变
INV10 记录内容和评审处置的测试夹具 规范对 PR 给出判定,或评审者将 PR 链接视为权威依据
INV13 盲化规范编写测试夹具及重叠搜索凭证 作者创建并行权威,仅搜索已合入记录或文件名,遗漏正式所有者上的未完成工作,或将开放的 PR 视为权威
INV14, INV15 窄决策与混合意图审查测试夹具 当前的可视化切片被迫收缩其整个模块;可分离的伴生变更阻断了修复;或审查报告缺口但未给出可合入的补救措施
INV16, INV17 规范优先审查与缺失上下文测试夹具 生成的清单完整性凌驾于权威之上;审查臆造产品方向、复述已提供的上下文,或未能识别无关的伴生变更或受影响的调用方状态
INV18 规范审查机制分析及所有者迁移凭证 新增/修订的产品规范要求私有机制却未证明其公开性、静默使既有当前记录失效,或在产品契约中留下被改动的架构措辞
INV19 规范审查所有权冲突凭证与人工决策 自动审查批准产品契约,却遗漏当前/开放所有者重叠、错过冲突或架构泄漏,或仅返回人工挂起而无可操作的文字分析
INV20, DEC-9 scripts/check-knowledge.test.mjs 和 scripts/review-global-baselines.mjs 匹配的评审遗漏了当前全局声明、加载了草稿/不匹配的声明、丢失了 base commit 溯源,或将路由记录的其余部分视为权威来源。
INV21, DEC-10 .github/scripts/component-design-decisions.test.mjs、.github/scripts/review-signal-decision.test.mjs、.github/scripts/spec-owner-decision.test.mjs 和 .github/scripts/lib/classify-visual.test.mjs 格式错误/本地的 DD 逃过了验证,过期的批准使新的 head 通过门禁,所有者路由漏掉了混合变更门禁,或将可执行/API/未知运行时代码错误分类为仅外观改动。
DEC-14 .github/scripts/spec-owner-reconcile.test.mjs、.github/scripts/spec-owner-decision.test.mjs、.github/scripts/spec-owner-workflow.test.mjs 和 .github/scripts/knowledge-paths.test.mjs 非 spec 提交、基础合并、rebase 或状态翻转会重置批准;更改 spec 文本或新增 spec 路径时保留批准;指定其他 spec 内容的命令、表情回应、非所有者操作或作者评审会触发批准;review-required 在 spec 批准缺失或 spec 决策发布之前仍然成功;指定其他 spec 内容的撤销或变更请求被忽略;缺少批准时报告失败;评估结束时其 head 未处于终止状态;或者当前记录 check:knowledge 发现变化,或一个自身没有权威来源、受所有者门控的 Markdown 文件在没有所有者的情况下发生变更。
DEC-14(设计所有者的自己的 PR) .github/scripts/spec-owner-reconcile.test.mjs “接受 DESIGNOWNER 作者自己在其设计记录上执行 /approve-spec”;无障碍要求和弃用限制没有门禁检查(DEC-14 中的当前缺口) DESIGNOWNER 作者自己的 /approve-spec 未能在他们自己的拉取请求上批准当前设计记录;无障碍要求和弃用限制没有失败信号,因为门禁不检查它(当前缺口)
DEC-11 .github/scripts/review-signal-decision.test.mjs、.github/scripts/review-clear-workflow.test.mjs 和 .github/scripts/review-signal-workflow.test.mjs 应用批准使只读作者或 fork 作者或较早的 head 通过门禁;之后应用的变更请求或驳回使门禁保持通过状态;应用批准覆盖 ENGOWNER 的变更请求;或者未设置的应用或不可读的权限使门禁通过。
不变式 证据 失败信号
INV22–INV24 贡献者/审查者证据清单;公共链接和字节验证;保留的远程 refs;未更改的 fixture/基线/媒体路径 一次性捕获内容进入源代码树,清理过程丢失了被引用的图像,临时分支被视为持久分支,或存储变更覆盖了所有者的证明或保留契约
INV25, INV26, DEC-12 scripts/specs-for-file.test.mjs、scripts/check-knowledge.test.mjs 和 pnpm check:knowledge 当前记录无法通过任何受跟踪的非记录路径到达,查找操作仅凭名称推断链接,模式匹配不到任何内容或匹配到整个仓库,或模式匹配扩大了声明范围、压过了范围更窄的所有者
INV27, DEC-13 scripts/check-knowledge.test.mjs、.github/scripts/change-scope.test.mjs 和 pnpm check:knowledge 一个 *.spec.md 文件或 specs 目录下的 Markdown 文件,若没有有效的记录 frontmatter、位于其类型应有的位置之外、或遵循包本地模板,却通过了检查
INV28、DEC-16 针对构建后界面中的钩子行运行 apps/docsite/src/lib/exampleCoverage.mjs,并运行 apps/docsite/src/__tests__/example-coverage.test.ts(仅供参考:报告只会打印输出,不会拦截),同时根据 INV28 的标准审查每个钩子示例 报告遗漏了某个没有钩子文档或没有合规示例块的公共钩子,或者某个缺失或不合规的钩子示例导致合并或发布失败
INV29 对包源代码(而非构建产物)中的注释进行基线化 lint:新注释中若包含记录 id、拉取请求编号、issue 编号、日期戳或长引用块则失败,已有位置则保留为基线。审查将叙述性文字和超过约 12 行的文件头报告为非阻塞性发现。清理工作以按领域划分的拉取请求形式落地,不改变行为,每个请求都附有 pnpm specs:for 对比,涵盖每个被修改文件在清理前后的差异 新注释引用了记录、拉取请求、issue 或日期,引述了某条记录,或对代码进行叙述;文件头增长超过约 12 行却没有 lint 失败或审查发现;删除某条注释导致某条记录或被引用的声明从文件的 pnpm specs:for 结果中消失,因为该注释是文件与它的唯一关联;或者清理操作删除或改写了工具会读取的指令,例如 @pr-a11y 行
INV30、DEC-17 对团队外部作者提交的拉取请求中每个新的外部 URL 进行人工所有者审查,由存储库之外的审查与合并工具强制执行;存储库内没有 CI 检查(见下方 INV30 执行缺口) 团队外部的拉取请求在包文档或 docsite 下添加外部 URL,但未经人工所有者的 exact-head 批准即被批准或合并,或者团队内部的拉取请求添加了 URL 却被搁置等待人工所有者处理
INV31、DEC-18 scripts/check-knowledge.test.mjs 中的“批准行历史”;pnpm check:knowledge --base <base> 列出每条被更改的批准行及其原始决策者;存储库之外的审查与合并工具要求该决策者给出 exact-head 批准(见下方 INV31 执行缺口) 更改或移除现有 Decider 或 approved_by 行的拉取请求,未经原始决策者的 exact-head 批准即被批准或合并,或者仅添加决策或批准者的拉取请求被搁置
INV32、DEC-20 scripts/lib/knowledge-status-phrases.test.mjs;pnpm check:knowledge 会对规范或架构记录中的每条构建状态或排序短语发出警告但不会失败(DEC-20);根据 docs/contributing/spec-writing.md 中的评分标准项 R7 审查每条被更改的记录,并在 ## Writing rubric results 下报告 被更改的记录在需求缺口或单条状态行之外陈述了构建状态或工作顺序,却没有产生 R7 发现;或者以 <FR or INV id> gap: 形式出现的需求缺口、单条状态行或模板要求的生命周期字段被报告为 R7 发现
INV33, DEC-21 .github/scripts/api-tagalong.test.mjs 新增或更改的行,其组件位于标题范围和 Components: 行之外,未在行内代码中或 ## Scope 下的 Components: 行中被命名,且未由当前记录决策,却未列为附带项;范围内的、已命名的、已移除的或已决策的行被列为附带项;范围外已决策的行未出现在摘要中;某行匹配另一个包的组件;或不可读的 API changes 文件以退出码 0 退出
DEC-15 .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs, 和 pnpm check:knowledge 组件或模块记录位于 docs/specs/components/<ComponentRoot>/ 之外;*.spec.md 留在组件包的源码树中或 Swift 视图旁边;两个包共享某个根时记录匹配到错误的包;记录的组件根不在任何已注册包的源码树中;平台记录的 id 或 platform_of 与其路径不匹配;或平台记录变更跳过了 spec-owner 门禁

证据的位置由贡献者和审查者共同强制约束。本地的 docs/pr-assets/ 忽略规则可防止意外暂存;它不是阻断性 CI 检查,也不阻止通过强制添加将证据放在其他位置。

Discovery 会读取每个包的架构记录(packages/<package>/specs/…/<slug>.spec.md):pnpm check:knowledge 会像检查任何架构记录一样检查它们,并额外检查其种类、由路径得到的 id;spec-owner 门禁也将其与 docs/architecture/ 中的记录同等对待。

当前执行差距:discovery 尚不读取 docs/、themes 和包 specs/ 之外的其他记录候选项,例如不在 <slug>.spec.md 形式下的 specs 目录中的 Markdown;组件记录在下个 schema 版本之前没有 platform_of 字段;组件 id 模式也尚不接受如 component:swift/Button 这样的语言限定 id。在这三项全部落地之前,这些其他候选项仅由人工审查检查。pnpm check:knowledge 会像检查核心组件记录(其文件夹和公共名称、schema 规则、适用性块和 id)一样检查平台记录(docs/specs/components/<ComponentRoot>/<PublicName>.<language>.spec.md),接受其语言限定 id,并检查 platform_of 是否指向其核心组件、verified_by 路径是否存在。它的主题目标块没有可对照检查的核心主题化契约。spec-owner 门禁和 pnpm specs:for 将平台记录与其旁边的核心记录同等对待。

Review 强制实施开放 PR 搜索(INV13):PR 摘要记录搜索词、规范所有者/路径,以及已检查的重叠开放工作。

当前执行差距:示例覆盖率报告会列出每个没有 hook 文档或没有命名它的示例块的公共 hook,但它无法判断示例是否演示了该 hook,因此 review 负责检查 INV28 的这一部分。每个没有符合要求示例的公共 hook 都是 INV28 下的一个开放文档缺口,会记录在仓库的 issue 队列中。

当前执行差距:仓库中没有 CI 检查可以检测团队外部作者在 PR 中新增的外部 URL(INV30)。仓库之外的 review 和合并工具强制执行此项。

当前执行差距:没有仓库检查读取审批(INV31)。pnpm check:knowledge --base <base> 会将每条变更的审批行报告为警告而不会失败。仓库之外的 review 和合并工具要求原始决策者批准。

当前执行缺口:.github/scripts/api-tagalong.mjs 会列出拉取请求命名范围之外的每个新增或已更改的公共 API 行(INV33);当调用方提供这些行时,该脚本还会列出当前记录判定为范围之外的行,但不将其计为附带变更。目前尚无 CI 作业运行该脚本,因此审阅会将未决定的行发送给所有者。该脚本只读取 API 行:审阅会检查所有者对具名行的批准,以及范围之外且不添加 API 行的行为处理器变更。

当前执行缺口:pnpm check:knowledge 会针对规范或架构记录中的每个构建状态或时序短语发出警告(INV32),但不会导致失败(DEC-20)。对照审查标准项 R7 的审阅会逐行做出裁定。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx