Astryx 组件审计回填与自动合并系统规范spec:AST-029实战指南【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读spec:AST-029Component audit contract backfill and auto-merge system spec是 Astryx 设计系统中负责全组件审计安全运行的系统级规范它精确规定了哪些组件参与审计、组件契约缺失或不完整时审计如何继续、哪些修复可以随审计一起落地以及 Night Watch 审计在何种条件下可以自动合并。本文以该规范为骨架结合仓库中的知识契约架构docs/architecture/knowledge-contracts.md、组件规范模板docs/templates/knowledge/component-spec.md、公开 API 准入规范docs/specs/AST-002/spec.md、组件测试充分性架构docs/architecture/component-test-sufficiency.md以及分数账本工具scripts/score-ledger.mjs逐一展开。读完本文你将理解 Astryx 如何让观察性回填 客观修复 精确 head 机器报告在审计 PR 中共存掌握审计模式N/O/P/R、FR5 证据收据、FR10 精确 head 资格报告与 fail-closed 自动合并的完整落地形态。背景为什么需要一份审计专用的系统规范Astryx 的知识体系由多种记录构成组件契约描述单个组件承诺的聚合行为模块契约描述由组件拥有的独立可契约公共钩子/插件/工具家庭契约描述兄弟组件共享的行为设计规范记录人类拥有的视觉与交互决策系统规范记录跨组件、跨主题或改变架构的决策见 knowledge-contracts.md 的 System model。整组件审计whole-component audit之前遇到的核心矛盾是当某个组件的契约缺失或不完整时审计应该如何进行过去可能的选择是为了审计而先造一套并行契约格式或者等契约补齐再审计。spec:AST-029明确否定了这两条路只定义让整组件审计安全运行所必需的增量行为组件契约的形状、权威authority、所有权、审批、冲突处理和语义 API 规则继续由 docs/templates/knowledge/component-spec.md 与配套的版本化知识 schema、architecture:knowledge-contracts、spec:AST-002 以及每个组件既有的Name.spec.md拥有审计不得创建第二套组件规范格式、编写指南、schema 或审批路径观察性回填不得新增、改进、移除或重新解释组件行为不得用审计数据替换分级grading、晋升promotion或 review 模式的 issue 与账本规则。从实现现状看这条边界是真实落地而非纸面声明审计分数账本scripts/score-ledger.mjs只存储分数审计提示词AUDIT_PROMPT中明确写着 Component and module specs store durable product behavior only; do not put audit scores, run inventories, screenshots, findings, or eligibility data in them.组件与模块规范只存持久产品行为不得放入审计分数、运行清单、截图、发现或资格数据。FR1–FR4审计名册、契约权威与观察性回填FR1 — 单一审计名册审计队列和 Component Audits 沙箱表必须使用同一份已检入checked-in的公共组件名册目标名册覆盖 Core、Lab、Charts、Rich Text 和 Vega 五个包。一个包只有在既有权威知识系统认可其组件记录位置并完成校验后才能进入活跃审计名册审计不得发明仅审计使用的 spec 路径。仓库中这份唯一注册表正是 scripts/component-packages.cjs包名源码根布局Storybook 前缀corepackages/core/srcnestedcore-labpackages/lab/srcnestedlab-chartspackages/charts/srcflatcharts-richtextpackages/richtext/srcflatlab-vegapackages/vega/srcflatvega-其头部注释明确写到Single registry used by audit rosters and component knowledge paths.审计名册与组件知识路径共用的单一注册表。nested 布局下一个目录即一个组件单元flat 布局下公共组件模块直接位于src/之下、由src/index.ts的命名导出识别。而 scripts/score-ledger.mjs 中的唯一组件谓词isComponentDirectory/flatPackageComponents从包结构推导名册而非维护一份易过期的名字列表——The roster is the packages名册就是包本身这从实现层面印证了 FR1 的one audit roster要求。FR2 — 既有组件契约保持权威审计必须从最近的当前组件或模块契约开始沿其链接跟进到当前的家庭、设计、架构和系统权威使用既有的组件模板与 schema而不是创建并行契约形状。这条原则在 knowledge-contracts.md 的 System model 中被形式化为一条检索链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 evidenceFR3 — 缺失契约走既有规范流程当组件契约缺失或不完整时审计者可以使用既有模板、schema、权威规则和 exact-head 所有者审批流程准备或补全一份Name.spec.md草稿但缺失草稿不得阻塞基于当前权威与可核验证据的评级。FR4 — 回填仅限观察审计撰写的组件契约必须描述已核实的发布行为不得新增、改进、移除或重新解释行为拟议含义属于待解答问题或独立的所有者决策草稿不能把审计发现当作已定案政策清除。审计提示词AUDIT_PROMPT把这条写成了可直接执行的操作纪律A backfill is observational only: it may describe verified shipped behavior, but it must not add, improve, remove, reinterpret, or otherwise change product meaning.回填仅限观察可描述已核实的发布行为但不得新增、改进、移除、重新解释或以其他方式改变产品含义。这也呼应了知识契约架构中 INV5 — Blank forms are not policy空白模板不是政策与 INV10 — Records describe ideal behavior, not pull-request verdicts记录描述理想行为而非 PR 判决。FR5–FR6审计完整性的证据收据与冲突路由FR5 — 审计完整性记录在组件契约之外审计 PR 必须携带一份封闭的证据收据closed evidence receipt其有限清单finite inventory来自公共导出与类型public exports and types文档化的概念与变体documented concepts and variants通过公共 API 可达的状态与转换states and transitions reachable through the public API从这些表面可达的实现分支implementation branches reachable from those surfaces。只有当证据显示相同可观察契约时等价输入才可共享一行每一行必须指名相关源码、既有测试、消费者文档、渲染证据、适用的当前权威或客观标准以及任何冲突或缺口。这份收据是审计证据不为组件规范 schema 增加必需小节。FR6 — 既有权威解决冲突审计者必须应用architecture:knowledge-contracts与spec:AST-002当前共享权威与客观标准在其范围内管辖。当当前记录之间发生冲突或问题需要新的 API、兼容性、所有权或设计判断时客观修复立即停止并路由给所有者。这与 knowledge-contracts.md 的冲突处理流程一致两个当前记录作出不同主张时审查停止不得按新旧、路径远近或具体程度挑选而是记录一个novel-human缺口交由规范所有者本仓库为cixzhang裁定。FR7–FR10修复捆绑、模式隔离与精确 head 资格报告FR7 — 客观修复可与审计 PR 同行一份 Night Watch PR可以把以下内容组合在一起观察性组件契约编辑缺失的行为测试稳定的视觉回归覆盖消费者文档漂移修复结果已被既有权威定案的实现缺陷修复。但基线证据与每项修复的前后对比证明必须保持彼此独立。审计提示词把可批处理范围限定为 tests, stable visual coverage, doc-drift fixes, and implementation fixes whose required outcome is already settled by current authority or an objective standard测试、稳定视觉覆盖、文档漂移修复、以及结果已被当前权威或客观标准定案的实现修复。FR8 — 人工边界失败关闭fail closed以下内容必须保持人工审查、不得自动合并公共 API 的含义或形状默认值兼容性或迁移承诺所有权边界或冲突主观的表征、比例、密度或交互感受决策。FR9 — 审计模式保持区分Night WatchN不为普通逐条发现建档 issue只记录修复后的账本结果分级O与晋升P保留既有的逐 BLOCK issue 与记录流程审查R把发现放到 PR 或 review 上不套用整组件账本生命周期。共享审计提示词必须保留所选模式。这一区分在 scripts/score-ledger.mjs 的AUDIT_MODES常量中有精确的机器可读实现模式码标签别名是否提交 BLOCK issueNNight Watchn/nightly/night-watch/night watch否Ogradingo/grading/on-demand/on demand是Ppromotionp/promotion是Rreviewr/review否auditModePolicy()负责把 scorecard 或旧账本里的模式别名解析到对应生命周期策略--file-issues子命令明确拒绝 N 与 R 模式Night Watch and review modes are refused。FR10 — 自动合并要求精确 head 资格报告Night Watch 审计者必须输出一份版本化、机器可读的报告包含组件与包、审计模式与评分规则版本rubric version被审计仓库与组件契约的 headFR5 清单封闭状态未决的客观与人工缺口修复及其前后证据所需审批状态、所需检查状态带理由的失败关闭资格结论fail-closed eligibility verdict。一份**受信任的检查trusted check**必须对照当前 PR 与 head 校验该报告把每一项未满足条件发布到其摘要中并投影所需的audit-eligibility状态。报告可以存在于受信任的 PR/check 元数据中不得要求第二份已检入的审计记录任何缺失、过期、不一致或不合格的报告都让 PR 保持开放等待人工审查。审计提示词已经内置了这份报告的 JSON 骨架schemaVersion 1其顶层字段为component、package、auditMode、rubricVersion、heads.repository、heads.componentContract、inventory、unresolvedGaps、remediations、approvals、checks、eligibility。并明确 Fail closed: missing, stale, inconsistent, or unresolved evidence keepseligibility.eligiblefalse and the PR open for human review.——这就是 FR8人工边界失败关闭与 FR10报告驱动自动合并在可执行提示词层面的接合点。FR11 与激活条件自动合并的显式、分离、原子化开关spec:AST-029对自动合并保持极度谨慎直到本记录同时满足authority: current且phase: shipped自动合并保持不可用激活变更必须一次性落地审计提示词、wiki 流程、权威包/spec 覆盖、名册消费者、资格检查与聚焦测试一起落地仅有审批而未完成完整激活不改变运行时行为——每个审计 PR 仍然仅人工审查由于 FR5 把审计专用证据放在组件契约之外本规范不要求组件模板或 schema 迁移。审计提示词中的 N 模式生命周期同样写明Every Night Watch PR remains manual-review-only untilspec:AST-029isphase: shippedand a trusted exact-head eligibility check is active. Do not enable auto-merge.在spec:AST-029达到phase: shipped且受信任的精确 head 资格检查激活之前每个 Night Watch PR 保持仅人工审查不要启用自动合并。结合 docs/specs/README.md 中 Only records withauthority: currentare authoritative只有authority: current的记录才具权威性可以推断本规范当前处于phase: accepted审批通过待实施状态即文章撰写时自动合并尚未激活这与规范 Current-state impact 一节本已接受规范不改变任何审计自动化或组件契约 schema的声明互相印证。FR13–FR15审计数据归属与分数新鲜度FR13 — 审计数据遵循既有存储权威持久产品行为保留在组件.spec.md自动化的 wikicomponent-scores.json是当前修复后分数与未决发现的运营数据存储未激活的按组件审计文件不是迁移目标审计 PR 存储可审查的运行证据受信任的 Check Run 存储 FR10 精确 head 机器报告任何未来数据存储变更都需要单独自动迁移与切换cutover契约。实现侧scripts/score-ledger.mjs 的头部注释与常量把它说得很透LEDGER_FILENAME component-scores.json——The one stored form of the ledger账本的唯一存储形式分数放在 wiki 仓库WIKI_REMOTE因为recording a score must not require a pull request记录分数不应要求 PR没有生成的 Markdown 表格副本——a second copy of the same numbers goes stale the moment the JSON changes同一组数字的第二个副本在 JSON 变化的瞬间就会过期沙箱页在运行时拉取该 JSON--push子命令把审计未记录 审计未发生做成一条命令完成浅克隆缓存 wiki、应用变更、提交并推送。FR14 — 评分使用组装后的适用契约每个审计小节必须对以下来源中适用的需求评分当前全局权威与客观标准、当前家庭契约、当前组件/模块契约。每条需求映射到一个评分小节与一个证据结果一个缺陷不重复计分N/A需求被排除证据不可用走评分规则既有的not_measured行为既有严重度、权重、等级区间与 BLOCK 上限保持不变除非评分规则显式对评分变更做版本化。FR15 — 权威变更使受影响分数失效而非全局标尺当前组件/模块契约变更 → 使该组件审计失效当前家庭或全局权威变更 → 使每个链接的适用组件失效评分规则版本仅在评分方法论、权重、严重度或证据处理变化时才变更单纯权威变更触发同一标尺上的定向重审。这条权威失效机制在账本里有对应实现compareEntry()的第三条规则是rubricVersion不一致即判incomparable——The two numbers came off different scales, so the delta is meaningless两个数字来自不同标尺差值无意义此时不判失败而是要求按 head 版本重审而新增 BLOCK 或分数下降则直接判failratchet 棘轮机制。测试文件 scripts/score-ledger.test.mjs 覆盖了这些判定路径。验证矩阵每条需求如何被证明spec:AST-029的 Verification 表为每条需求给出了验证方式、代表状态与变异/失败预期是理解规范如何被机器证明的关键契约验证代表状态变异或失败预期FR1权威知识路径覆盖 名册与沙箱一致性测试五个目标包不支持包新组件私有助手组件记录尚未权威化就被审计、队列与沙箱分叉、合格组件消失FR2–FR6使用既有组件记录的审计夹具当前草稿缺失有限公共状态清单等价输入本地漂移冲突审计发明第二套契约形状、遗漏可达公共状态、草稿变成政策、冲突被奉为权威FR7–FR10模式、报告 schema、信任校验与资格测试安全客观修复API/默认值/所有权/设计边界带缺口的收据过期 head缺审批不安全或不完整的工作自动合并、过期报告清除了状态、一种模式收到另一种模式的生命周期FR11权威/阶段与激活测试草稿current/proposedcurrent/accepted带部分接线的 current/shipped完全激活在显式状态与全部所需表面落地之前自动合并被激活FR12TDD 追踪与行为测试审查已定案接缝未定案接缝红色失败最小绿色切片实现耦合测试生产变更先于红色出现、发明未定案接缝、测试未观察契约却通过FR13存储边界测试wiki 账本PR 证据Check Run 报告尝试按组件记录日志审计数据被复制、写在错误所有者名下、或从未经批准的存储读取FR14–FR15评分与新鲜度测试全局/家庭/组件需求N/Anot measured本地与共享权威变更缺陷被计两次、需求被遗漏、受影响分数被错误地保持当前FR12 引出的 TDD 义务正是决策日志中的 DEC-4见下节并被 docs/architecture/component-test-sufficiency.md 的 INV9 承接Audit-authored behavior-test remediation followsspec:AST-029/DEC-4: establish the current or established public seam, demonstrate the new case red before production changes, and implement one minimal observable vertical slice.审计撰写的行为测试修复遵循spec:AST-029/DEC-4确立当前或既有公共接缝在生产变更前演示新用例变红并实现一个最小的可观察垂直切片。决策日志六个关键取舍DEC-1 — 审计复用既有组件规范体系审计回填使用既有组件模板、schema、权威模型与组件记录审计专用完整性证据保留在审计收据中。否决创建第二套组件规范指南或给每个组件契约添加审计工作流字段。DEC-2 — 回填与已定案修复可同行一份审计 PR 可以描述已核实的发布行为并修复带前后证明的客观缺陷新判断留在该自动路径之外。否决仅因为同一次审计发现了缺失契约就把安全修复拆开。DEC-3 — 自动合并使用结构化报告而非重复的已检入记录Night Watch 输出 FR10 的版本化资格格式受信任检查把它绑定到精确 PR head、对照仓库状态校验并发布所需状态与理由。报告放在受信任的 PR/check 元数据中而不是第二份已检入审计文件。否决以非结构化散文作为自动合并输入、第二份仓库审计记录、或仅凭 CI 全绿判定资格。DEC-4 — 审计撰写的行为测试使用 Matt Pocock 的 TDD 技能Night Watch 使用固定的公共tdd技能进行行为测试修复接缝由当前契约或既有公共接口决定审计者不得自造每个周期先证明红色再改生产代码并通过可观察行为实现一个最小垂直切片。否决先实现后写测试、测试内部实现、或未从第一个垂直切片学习就一次性生成全部测试。DEC-5 — 审计数据按所有权拆分自动 wiki 账本仍是当前组件审计状态的运营存储审计 PR 存一次运行的、可供人审查的证据受信任 Check Run 存精确 head 的机器决策组件契约只存持久产品行为。任何未来数据存储变更都需要显式的自动迁移与切换契约。否决按组件影子账本、把截图或运行矩阵塞进组件规范、把瞬态 CI 工件当作唯一审查记录。DEC-6 — 评分保持稳定适用权威动态组装评分规则保留既有小节、权重、严重度、等级区间与未测量处理每次审计从适用的当前全局、家庭、组件与模块需求填充各小节权威变更使链接组件审计失效只有评分方法变更才版本化评分标尺。否决把每条局部需求复制进 wiki 评分规则、组件需求变多时悄悄改权重、或把 spec 编辑当作全局评分版本变更。平台支持边界spec:AST-029同时界定了支持的运行底线支持的特性/引擎下限仓库支持的 Node、浏览器与 CI不支持的行为无法解析的组件或缺失证据必须作为显式审计缺口存在而不是消失或放行浏览器证据可见性与交互主张使用审计评分规则与适用当前记录所要求的真实浏览器证据。结语从审计到自动合并的完整闭环spec:AST-029的价值不在于发明新的契约语言而在于把安全地做整组件审计这一系统工程问题拆成一组可验证、可组合、可审计的规则单一名册FR1、既有权威优先FR2/FR6、观察性回填FR3/FR4、契约外证据收据FR5、带前后证明的客观修复捆绑FR7、人工边界失败关闭FR8、模式隔离FR9、精确 head 机器报告驱动的自动合并FR10、显式原子激活FR11与稳定的数据归属FR13–FR15。仓库中 scripts/component-packages.cjs、scripts/score-ledger.mjs、scripts/score-ledger.test.mjs 以及审计提示词AUDIT_PROMPT共同构成了这条规范的可执行侧写——读者若想深入验证某条 FR 的实现细节可从这些路径入手追踪。若你的项目也在建设AI/Agent 辅助的大规模组件审计流程本规范中最值得直接借鉴的三点是让名册与 schema 保持唯一来源杜绝双份配置漂移、把观察与决策严格分离回填只描述已发布行为新判断必须路由给人、以及用版本化机器报告 fail-closed 校验来为自动合并设闸任何缺失、过期或不一致的证据都退回人工审查。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Astryx 组件审计回填与自动合并系统规范（spec:AST-029）实战指南
Astryx 组件审计回填与自动合并系统规范spec:AST-029实战指南【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读spec:AST-029Component audit contract backfill and auto-merge system spec是 Astryx 设计系统中负责全组件审计安全运行的系统级规范它精确规定了哪些组件参与审计、组件契约缺失或不完整时审计如何继续、哪些修复可以随审计一起落地以及 Night Watch 审计在何种条件下可以自动合并。本文以该规范为骨架结合仓库中的知识契约架构docs/architecture/knowledge-contracts.md、组件规范模板docs/templates/knowledge/component-spec.md、公开 API 准入规范docs/specs/AST-002/spec.md、组件测试充分性架构docs/architecture/component-test-sufficiency.md以及分数账本工具scripts/score-ledger.mjs逐一展开。读完本文你将理解 Astryx 如何让观察性回填 客观修复 精确 head 机器报告在审计 PR 中共存掌握审计模式N/O/P/R、FR5 证据收据、FR10 精确 head 资格报告与 fail-closed 自动合并的完整落地形态。背景为什么需要一份审计专用的系统规范Astryx 的知识体系由多种记录构成组件契约描述单个组件承诺的聚合行为模块契约描述由组件拥有的独立可契约公共钩子/插件/工具家庭契约描述兄弟组件共享的行为设计规范记录人类拥有的视觉与交互决策系统规范记录跨组件、跨主题或改变架构的决策见 knowledge-contracts.md 的 System model。整组件审计whole-component audit之前遇到的核心矛盾是当某个组件的契约缺失或不完整时审计应该如何进行过去可能的选择是为了审计而先造一套并行契约格式或者等契约补齐再审计。spec:AST-029明确否定了这两条路只定义让整组件审计安全运行所必需的增量行为组件契约的形状、权威authority、所有权、审批、冲突处理和语义 API 规则继续由 docs/templates/knowledge/component-spec.md 与配套的版本化知识 schema、architecture:knowledge-contracts、spec:AST-002 以及每个组件既有的Name.spec.md拥有审计不得创建第二套组件规范格式、编写指南、schema 或审批路径观察性回填不得新增、改进、移除或重新解释组件行为不得用审计数据替换分级grading、晋升promotion或 review 模式的 issue 与账本规则。从实现现状看这条边界是真实落地而非纸面声明审计分数账本scripts/score-ledger.mjs只存储分数审计提示词AUDIT_PROMPT中明确写着 Component and module specs store durable product behavior only; do not put audit scores, run inventories, screenshots, findings, or eligibility data in them.组件与模块规范只存持久产品行为不得放入审计分数、运行清单、截图、发现或资格数据。FR1–FR4审计名册、契约权威与观察性回填FR1 — 单一审计名册审计队列和 Component Audits 沙箱表必须使用同一份已检入checked-in的公共组件名册目标名册覆盖 Core、Lab、Charts、Rich Text 和 Vega 五个包。一个包只有在既有权威知识系统认可其组件记录位置并完成校验后才能进入活跃审计名册审计不得发明仅审计使用的 spec 路径。仓库中这份唯一注册表正是 scripts/component-packages.cjs包名源码根布局Storybook 前缀corepackages/core/srcnestedcore-labpackages/lab/srcnestedlab-chartspackages/charts/srcflatcharts-richtextpackages/richtext/srcflatlab-vegapackages/vega/srcflatvega-其头部注释明确写到Single registry used by audit rosters and component knowledge paths.审计名册与组件知识路径共用的单一注册表。nested 布局下一个目录即一个组件单元flat 布局下公共组件模块直接位于src/之下、由src/index.ts的命名导出识别。而 scripts/score-ledger.mjs 中的唯一组件谓词isComponentDirectory/flatPackageComponents从包结构推导名册而非维护一份易过期的名字列表——The roster is the packages名册就是包本身这从实现层面印证了 FR1 的one audit roster要求。FR2 — 既有组件契约保持权威审计必须从最近的当前组件或模块契约开始沿其链接跟进到当前的家庭、设计、架构和系统权威使用既有的组件模板与 schema而不是创建并行契约形状。这条原则在 knowledge-contracts.md 的 System model 中被形式化为一条检索链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 evidenceFR3 — 缺失契约走既有规范流程当组件契约缺失或不完整时审计者可以使用既有模板、schema、权威规则和 exact-head 所有者审批流程准备或补全一份Name.spec.md草稿但缺失草稿不得阻塞基于当前权威与可核验证据的评级。FR4 — 回填仅限观察审计撰写的组件契约必须描述已核实的发布行为不得新增、改进、移除或重新解释行为拟议含义属于待解答问题或独立的所有者决策草稿不能把审计发现当作已定案政策清除。审计提示词AUDIT_PROMPT把这条写成了可直接执行的操作纪律A backfill is observational only: it may describe verified shipped behavior, but it must not add, improve, remove, reinterpret, or otherwise change product meaning.回填仅限观察可描述已核实的发布行为但不得新增、改进、移除、重新解释或以其他方式改变产品含义。这也呼应了知识契约架构中 INV5 — Blank forms are not policy空白模板不是政策与 INV10 — Records describe ideal behavior, not pull-request verdicts记录描述理想行为而非 PR 判决。FR5–FR6审计完整性的证据收据与冲突路由FR5 — 审计完整性记录在组件契约之外审计 PR 必须携带一份封闭的证据收据closed evidence receipt其有限清单finite inventory来自公共导出与类型public exports and types文档化的概念与变体documented concepts and variants通过公共 API 可达的状态与转换states and transitions reachable through the public API从这些表面可达的实现分支implementation branches reachable from those surfaces。只有当证据显示相同可观察契约时等价输入才可共享一行每一行必须指名相关源码、既有测试、消费者文档、渲染证据、适用的当前权威或客观标准以及任何冲突或缺口。这份收据是审计证据不为组件规范 schema 增加必需小节。FR6 — 既有权威解决冲突审计者必须应用architecture:knowledge-contracts与spec:AST-002当前共享权威与客观标准在其范围内管辖。当当前记录之间发生冲突或问题需要新的 API、兼容性、所有权或设计判断时客观修复立即停止并路由给所有者。这与 knowledge-contracts.md 的冲突处理流程一致两个当前记录作出不同主张时审查停止不得按新旧、路径远近或具体程度挑选而是记录一个novel-human缺口交由规范所有者本仓库为cixzhang裁定。FR7–FR10修复捆绑、模式隔离与精确 head 资格报告FR7 — 客观修复可与审计 PR 同行一份 Night Watch PR可以把以下内容组合在一起观察性组件契约编辑缺失的行为测试稳定的视觉回归覆盖消费者文档漂移修复结果已被既有权威定案的实现缺陷修复。但基线证据与每项修复的前后对比证明必须保持彼此独立。审计提示词把可批处理范围限定为 tests, stable visual coverage, doc-drift fixes, and implementation fixes whose required outcome is already settled by current authority or an objective standard测试、稳定视觉覆盖、文档漂移修复、以及结果已被当前权威或客观标准定案的实现修复。FR8 — 人工边界失败关闭fail closed以下内容必须保持人工审查、不得自动合并公共 API 的含义或形状默认值兼容性或迁移承诺所有权边界或冲突主观的表征、比例、密度或交互感受决策。FR9 — 审计模式保持区分Night WatchN不为普通逐条发现建档 issue只记录修复后的账本结果分级O与晋升P保留既有的逐 BLOCK issue 与记录流程审查R把发现放到 PR 或 review 上不套用整组件账本生命周期。共享审计提示词必须保留所选模式。这一区分在 scripts/score-ledger.mjs 的AUDIT_MODES常量中有精确的机器可读实现模式码标签别名是否提交 BLOCK issueNNight Watchn/nightly/night-watch/night watch否Ogradingo/grading/on-demand/on demand是Ppromotionp/promotion是Rreviewr/review否auditModePolicy()负责把 scorecard 或旧账本里的模式别名解析到对应生命周期策略--file-issues子命令明确拒绝 N 与 R 模式Night Watch and review modes are refused。FR10 — 自动合并要求精确 head 资格报告Night Watch 审计者必须输出一份版本化、机器可读的报告包含组件与包、审计模式与评分规则版本rubric version被审计仓库与组件契约的 headFR5 清单封闭状态未决的客观与人工缺口修复及其前后证据所需审批状态、所需检查状态带理由的失败关闭资格结论fail-closed eligibility verdict。一份**受信任的检查trusted check**必须对照当前 PR 与 head 校验该报告把每一项未满足条件发布到其摘要中并投影所需的audit-eligibility状态。报告可以存在于受信任的 PR/check 元数据中不得要求第二份已检入的审计记录任何缺失、过期、不一致或不合格的报告都让 PR 保持开放等待人工审查。审计提示词已经内置了这份报告的 JSON 骨架schemaVersion 1其顶层字段为component、package、auditMode、rubricVersion、heads.repository、heads.componentContract、inventory、unresolvedGaps、remediations、approvals、checks、eligibility。并明确 Fail closed: missing, stale, inconsistent, or unresolved evidence keepseligibility.eligiblefalse and the PR open for human review.——这就是 FR8人工边界失败关闭与 FR10报告驱动自动合并在可执行提示词层面的接合点。FR11 与激活条件自动合并的显式、分离、原子化开关spec:AST-029对自动合并保持极度谨慎直到本记录同时满足authority: current且phase: shipped自动合并保持不可用激活变更必须一次性落地审计提示词、wiki 流程、权威包/spec 覆盖、名册消费者、资格检查与聚焦测试一起落地仅有审批而未完成完整激活不改变运行时行为——每个审计 PR 仍然仅人工审查由于 FR5 把审计专用证据放在组件契约之外本规范不要求组件模板或 schema 迁移。审计提示词中的 N 模式生命周期同样写明Every Night Watch PR remains manual-review-only untilspec:AST-029isphase: shippedand a trusted exact-head eligibility check is active. Do not enable auto-merge.在spec:AST-029达到phase: shipped且受信任的精确 head 资格检查激活之前每个 Night Watch PR 保持仅人工审查不要启用自动合并。结合 docs/specs/README.md 中 Only records withauthority: currentare authoritative只有authority: current的记录才具权威性可以推断本规范当前处于phase: accepted审批通过待实施状态即文章撰写时自动合并尚未激活这与规范 Current-state impact 一节本已接受规范不改变任何审计自动化或组件契约 schema的声明互相印证。FR13–FR15审计数据归属与分数新鲜度FR13 — 审计数据遵循既有存储权威持久产品行为保留在组件.spec.md自动化的 wikicomponent-scores.json是当前修复后分数与未决发现的运营数据存储未激活的按组件审计文件不是迁移目标审计 PR 存储可审查的运行证据受信任的 Check Run 存储 FR10 精确 head 机器报告任何未来数据存储变更都需要单独自动迁移与切换cutover契约。实现侧scripts/score-ledger.mjs 的头部注释与常量把它说得很透LEDGER_FILENAME component-scores.json——The one stored form of the ledger账本的唯一存储形式分数放在 wiki 仓库WIKI_REMOTE因为recording a score must not require a pull request记录分数不应要求 PR没有生成的 Markdown 表格副本——a second copy of the same numbers goes stale the moment the JSON changes同一组数字的第二个副本在 JSON 变化的瞬间就会过期沙箱页在运行时拉取该 JSON--push子命令把审计未记录 审计未发生做成一条命令完成浅克隆缓存 wiki、应用变更、提交并推送。FR14 — 评分使用组装后的适用契约每个审计小节必须对以下来源中适用的需求评分当前全局权威与客观标准、当前家庭契约、当前组件/模块契约。每条需求映射到一个评分小节与一个证据结果一个缺陷不重复计分N/A需求被排除证据不可用走评分规则既有的not_measured行为既有严重度、权重、等级区间与 BLOCK 上限保持不变除非评分规则显式对评分变更做版本化。FR15 — 权威变更使受影响分数失效而非全局标尺当前组件/模块契约变更 → 使该组件审计失效当前家庭或全局权威变更 → 使每个链接的适用组件失效评分规则版本仅在评分方法论、权重、严重度或证据处理变化时才变更单纯权威变更触发同一标尺上的定向重审。这条权威失效机制在账本里有对应实现compareEntry()的第三条规则是rubricVersion不一致即判incomparable——The two numbers came off different scales, so the delta is meaningless两个数字来自不同标尺差值无意义此时不判失败而是要求按 head 版本重审而新增 BLOCK 或分数下降则直接判failratchet 棘轮机制。测试文件 scripts/score-ledger.test.mjs 覆盖了这些判定路径。验证矩阵每条需求如何被证明spec:AST-029的 Verification 表为每条需求给出了验证方式、代表状态与变异/失败预期是理解规范如何被机器证明的关键契约验证代表状态变异或失败预期FR1权威知识路径覆盖 名册与沙箱一致性测试五个目标包不支持包新组件私有助手组件记录尚未权威化就被审计、队列与沙箱分叉、合格组件消失FR2–FR6使用既有组件记录的审计夹具当前草稿缺失有限公共状态清单等价输入本地漂移冲突审计发明第二套契约形状、遗漏可达公共状态、草稿变成政策、冲突被奉为权威FR7–FR10模式、报告 schema、信任校验与资格测试安全客观修复API/默认值/所有权/设计边界带缺口的收据过期 head缺审批不安全或不完整的工作自动合并、过期报告清除了状态、一种模式收到另一种模式的生命周期FR11权威/阶段与激活测试草稿current/proposedcurrent/accepted带部分接线的 current/shipped完全激活在显式状态与全部所需表面落地之前自动合并被激活FR12TDD 追踪与行为测试审查已定案接缝未定案接缝红色失败最小绿色切片实现耦合测试生产变更先于红色出现、发明未定案接缝、测试未观察契约却通过FR13存储边界测试wiki 账本PR 证据Check Run 报告尝试按组件记录日志审计数据被复制、写在错误所有者名下、或从未经批准的存储读取FR14–FR15评分与新鲜度测试全局/家庭/组件需求N/Anot measured本地与共享权威变更缺陷被计两次、需求被遗漏、受影响分数被错误地保持当前FR12 引出的 TDD 义务正是决策日志中的 DEC-4见下节并被 docs/architecture/component-test-sufficiency.md 的 INV9 承接Audit-authored behavior-test remediation followsspec:AST-029/DEC-4: establish the current or established public seam, demonstrate the new case red before production changes, and implement one minimal observable vertical slice.审计撰写的行为测试修复遵循spec:AST-029/DEC-4确立当前或既有公共接缝在生产变更前演示新用例变红并实现一个最小的可观察垂直切片。决策日志六个关键取舍DEC-1 — 审计复用既有组件规范体系审计回填使用既有组件模板、schema、权威模型与组件记录审计专用完整性证据保留在审计收据中。否决创建第二套组件规范指南或给每个组件契约添加审计工作流字段。DEC-2 — 回填与已定案修复可同行一份审计 PR 可以描述已核实的发布行为并修复带前后证明的客观缺陷新判断留在该自动路径之外。否决仅因为同一次审计发现了缺失契约就把安全修复拆开。DEC-3 — 自动合并使用结构化报告而非重复的已检入记录Night Watch 输出 FR10 的版本化资格格式受信任检查把它绑定到精确 PR head、对照仓库状态校验并发布所需状态与理由。报告放在受信任的 PR/check 元数据中而不是第二份已检入审计文件。否决以非结构化散文作为自动合并输入、第二份仓库审计记录、或仅凭 CI 全绿判定资格。DEC-4 — 审计撰写的行为测试使用 Matt Pocock 的 TDD 技能Night Watch 使用固定的公共tdd技能进行行为测试修复接缝由当前契约或既有公共接口决定审计者不得自造每个周期先证明红色再改生产代码并通过可观察行为实现一个最小垂直切片。否决先实现后写测试、测试内部实现、或未从第一个垂直切片学习就一次性生成全部测试。DEC-5 — 审计数据按所有权拆分自动 wiki 账本仍是当前组件审计状态的运营存储审计 PR 存一次运行的、可供人审查的证据受信任 Check Run 存精确 head 的机器决策组件契约只存持久产品行为。任何未来数据存储变更都需要显式的自动迁移与切换契约。否决按组件影子账本、把截图或运行矩阵塞进组件规范、把瞬态 CI 工件当作唯一审查记录。DEC-6 — 评分保持稳定适用权威动态组装评分规则保留既有小节、权重、严重度、等级区间与未测量处理每次审计从适用的当前全局、家庭、组件与模块需求填充各小节权威变更使链接组件审计失效只有评分方法变更才版本化评分标尺。否决把每条局部需求复制进 wiki 评分规则、组件需求变多时悄悄改权重、或把 spec 编辑当作全局评分版本变更。平台支持边界spec:AST-029同时界定了支持的运行底线支持的特性/引擎下限仓库支持的 Node、浏览器与 CI不支持的行为无法解析的组件或缺失证据必须作为显式审计缺口存在而不是消失或放行浏览器证据可见性与交互主张使用审计评分规则与适用当前记录所要求的真实浏览器证据。结语从审计到自动合并的完整闭环spec:AST-029的价值不在于发明新的契约语言而在于把安全地做整组件审计这一系统工程问题拆成一组可验证、可组合、可审计的规则单一名册FR1、既有权威优先FR2/FR6、观察性回填FR3/FR4、契约外证据收据FR5、带前后证明的客观修复捆绑FR7、人工边界失败关闭FR8、模式隔离FR9、精确 head 机器报告驱动的自动合并FR10、显式原子激活FR11与稳定的数据归属FR13–FR15。仓库中 scripts/component-packages.cjs、scripts/score-ledger.mjs、scripts/score-ledger.test.mjs 以及审计提示词AUDIT_PROMPT共同构成了这条规范的可执行侧写——读者若想深入验证某条 FR 的实现细节可从这些路径入手追踪。若你的项目也在建设AI/Agent 辅助的大规模组件审计流程本规范中最值得直接借鉴的三点是让名册与 schema 保持唯一来源杜绝双份配置漂移、把观察与决策严格分离回填只描述已发布行为新判断必须路由给人、以及用版本化机器报告 fail-closed 校验来为自动合并设闸任何缺失、过期或不一致的证据都退回人工审查。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
