【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文以 gsd-core 的架构决策记录 ADR-1820 为主体剖析其引入的三大架构表面spec-section检测模块Module seam、workflow.specless_probe_fallback配置开关fallback toggle以及 SPEC 供给谓词与 probe 推导谓词之间的优先级/authoring 契约precedence contract。文章结合仓库源码与测试用例说明阶段未编写 SPEC.md 时验证谓词如何自动兜底生成并写入 PLAN.md的完整原理与实战配置方法读完你将掌握该兜底链路的触发条件、逐节优先级规则、开关用法及其与验证器的 fail-closed 交互。一、问题背景verifier reach spec reach 的静默覆盖漏洞gsd-core 的验证体系建立在谓词predicate之上验证器verifier从PLAN.md 的 frontmatter读取must_haves目标回溯验证所需的正向/负向断言而不是直接读取 SPEC.md。SPEC.md 只是plan-phase阶段可选抬升lift的源头。在 ADR-1820 之前edge-probe边界完整性探针与 prohibition-probe禁止项完整性探针两个探针家族只在spec-phaseStep 5.5 / 5.6运行。这带来一个结构性漏洞若某阶段编写了 SPEC.md探针在 spec-phase 生成的谓词经由 plan-phase 抬升进入 PLAN.md验证器可见若某阶段没有编写 SPEC.md或 SPEC 省略了相关章节plan-phase 无从抬升谓词集为空探针的覆盖面随之丢失——而 SPEC 越薄恰恰越需要探针兜底。这正是 ADR-1820 所称的载荷关键前提verifier reach spec reach验证器可达性等于 SPEC 可达性被破坏的静默覆盖空洞silent coverage hole。二、决策总览三条架构表面ADR-1820 在既有地基ADR-857 谓词生成属核心基座、ADR-550 的 spec-phase 探针契约与must_haves.prohibitions投影、ADR-1606 的验证期强制缝之上新增了三块架构表面src/spec-section.cts模块Module seam——SPEC 是否供给章节 X的唯一判定权威workflow.specless_probe_fallback配置开关——默认开启、可显式禁用的策略开关SPEC 供给 ↔ 探针推导的优先级与 authoring 契约——谁赢SPEC 还是探针的文档化裁决。这三者共同构成spec-optional predicate railSPEC 可选的谓词轨道没有 SPEC 时探针直接在 plan-phase 的must_havesauthoring 阶段兜底生成谓词。三、决策一spec-section模块——SPEC 章节检测的唯一权威3.1 为什么需要一个独立模块而不是内联 awk在 #1820 之前判定SPEC 是否供给## Edge Coverage/## Prohibitions章节的逻辑是内联在 workflow 主体里的临时awk它在调用点硬编码章节标题字符串并手工实现 markdown 表格行计数。这种脆弱性直接导致了两个真实 bug标题锚点 bug精确锚定^## Prohibitions$漏掉了规范的## Prohibitions (must-NOT)标题——一个已供给的章节被误判为缺失导致人类编写的 SPEC 禁止项被探针覆盖单表格假设 bug假设每个章节只有一个表格多表格章节会错计行数。将检测逻辑集中到模块后知识既可测试又可在多个消费者间共享——而引入其他代码将依赖的 Module seam正是触发 ADR 的判定标准见 docs/contributing/contributor-standards.md 中引入 Module seam 必须写 ADR的约定。3.2 锁定导出的表面locked exported surface按 ADR-457 的构建缝约定源码src/spec-section.ctsTypeScript经tsc -p tsconfig.build.json编译为 gitignored 的运行时产物gsd-core/bin/lib/spec-section.cjs测试通过require()该产物进行断言。模块纯净、无依赖pure and dependency-free锁定导出导出类型/签名含义SpecSectionKeyedges \| prohibitions兜底逻辑关心的逻辑章节SECTION_HEADERSRecordSpecSectionKey, RegExp规范、后缀容忍的标题匹配器SectionStatus{ key, present, dataRows, supplied }章节状态形状countSectionDataRowsspecText → { present, dataRows }纯函数多表格稳健的计数specSectionStatusspecFile → SectionStatus磁盘读取包装器3.3 源码实现要点SECTION_HEADERS的核心设计是后缀容忍suffix-tolerantsrc/spec-section.ctsexport const SECTION_HEADERS: RecordSpecSectionKey, RegExp { edges: /^##[ \t]Edge Coverage([ \t]|\(|$)/, prohibitions: /^##[ \t]Prohibitions([ \t]|\(|$)/, };prohibitions同时匹配## Prohibitions与## Prohibitions (must-NOT)edges匹配## Edge Coverage及任何未来的括号后缀——这正是对标题锚点 bug 的根治。行计数算法src/spec-section.cts逐行扫描并维护三段状态机遇到任意##标题行时判断是否进入目标章节并重置afterSeparator在章节内|…|行先检查是否匹配分隔符|---|SEPARATOR /^\|[ \t]*:?-{2,}/是则置afterSeparatortrue后续|…|行即数据行否则在afterSeparator为真时计数 1——分隔符之前的|…|行是表头行永不计数空白或散文行重置当前表格状态因此一个章节包含多个表格或表格间夹杂散文时每个表格的数据行都被正确累计——这就是对单表格假设 bug 的根治。3.4 三个被钉死的不变量供给规则Supply rulesupplied present AND dataRows 0。章节存在但为空有标题、有表头、有分隔符、无数据行不算供给触发兜底后缀容忍标题契约若 spec-phase 重命名标题必须同步更新SECTION_HEADERS与 gsd-core/templates/spec.md 中的标题该契约由tests/spec-section.test.cjs钉死故障安全Fail-safeSPEC 文件缺失/不可读时解析为present:false/supplied:false兜底触发而不是抛异常src/spec-section.cts。3.5 回归测试历史 bug 被钉死tests/spec-section.test.cjs 断言编译产物gsd-core/bin/lib/spec-section.cjs的锁定行为两个历史回归均有专门用例后缀容忍回归## Prohibitions (must-NOT)章节 2 行数据 →present:true, dataRows:2同时验证不会把后续## Ambiguity Report表格的行误计入 prohibitions多表格回归## Edge Coverage下两个表格1 行 2 行数据中间夹散文→dataRows:3另覆盖## Edge Coverage正常计数、present-but-empty 章节 →supplied:false、章节缺席 →supplied:false、文件缺失 → 不抛异常且supplied:false、以及 CLI 双用例合法 key 输出 JSON 退出 0、非法 key 退出 2。3.6 CLI 接口模块自带可直接执行的 CLIsrc/spec-section.ctsnode spec-section.cjs specFile edges|prohibitions # 输出 SectionStatus JSON成功含文件缺席——那是合法的未供给答案退出 0仅用法错误缺参/非法 key退出 2require.main module守卫保证仅在直接执行编译产物时运行 CLI被测试require()时不会误触发。四、决策二workflow.specless_probe_fallback——默认开启的可禁用开关4.1 配置参数配置键类型默认值取值说明workflow.specless_probe_fallbackbooleantruetrue、false门控 plan-phase 的 SPEC-less 探针兜底该键注册于gsd-core/bin/shared/config-schema.manifest.json的validKeys并在 gsd-core/references/planning-config.md 中正式文档化。启用时默认未供给## Edge Coverage/## Prohibitions章节标题缺席或 present-but-empty的阶段会运行既有探针协议——edges 用确定性的edge-probe.cjsprohibitions 用 planner 内的 LLM 召回通道——并将结果谓词写入 PLAN.mdmust_haves章节级优先级SPEC 已供给的章节绝不重跑或覆盖。4.2 开关的 Gate 读取逻辑兜底协议文档 gsd-core/references/specless-probe-fallback.md 的 §0 给出了 gate 的标准读取方式除字面量false外的任何值均视为开启任何旧配置缺失都安全回落为默认开启SPECLESS_CFG$(gsd_run query config-get workflow.specless_probe_fallback 2/dev/null || echo true) SPECLESS_FALLBACKtrue; [[ $SPECLESS_CFG false ]] SPECLESS_FALLBACKfalse随后通过共享的spec-section助手计算EDGE_ABSENT/PROHIB_ABSENT并记录可见跳过visible skip当开关禁用或阶段无 requirement ID 时向 stderr 打印 WARNING/INFO 并把SPECLESS_FALLBACK_DISABLED说明串注入 planner 提示Step 8使计划明确记录本次未生成探针谓词——从不静默跳过也从不硬失败。4.3 为什么需要开关Chestertons Fenceprohibition 召回是有真实单次调用成本的 LLM 通道。开关是成本闸门cost-gate项目可以在不触碰验证器↔谓词契约的前提下把兜底调用路径整体关掉——契约仍然完整只是不再从 SPEC-less 兜底产出谓词。4.4 为什么默认开启探针家族是核心验证基座ADR-857 确立的 predicate boundary。若兜底默认关闭就会在更高一层复刻可跳过闸门skippable-gate的失败模式。默认开启保证基座默认触达验证器而可见跳过标记则让禁用状态保持诚实、绝不静默。4.5 与 ADR-857:66 的边界已裁定未重开ADR-857:66 裁定探针生成器默认开启且不可移除。本开关管辖的是SPEC-less 兜底调用路径而非生成器或验证器↔谓词契约后者仍是不可开关的核心基座。维护者在 #1820 上裁定857:66 管辖 spec-phase不管辖 SPEC-less 兜底——因此对兜底路径施加默认开启但可禁用的开关在边界之内。ADR-1820 记录该裁定不修正 857:66。五、决策三SPEC 供给 ↔ 探针推导的优先级与 authoring 契约5.1 章节级优先级SPEC 供给的章节永不重跑兜底是**逐章节per section**触发的仅对缺席或为空supplied false的章节运行探针。人类在 SPEC 中编写的章节原样抬升永不被探针覆盖。这是章节级而非文件级粒度一个部分 SPECedges 已供给、prohibitions 省略只对 prohibitions 运行兜底。5.2 单一序列化器无第二生产者Hyrum兜底产出的 prohibitions 通过与 SPEC 抬升路径相同的projectProhibitions序列化器写入must_haves.prohibitions兄弟块绝非truths——ADR-550 D3不存在并行 authoring 路径因此验证器↔谓词往返契约保持不变。任何未来的禁止项消费者复用它而非重新解析 markdown。5.3 兜底谓词无描述符 → 标记为 flagged绝不绿、绝不自动消除探针召回、且未接入check_*描述符的 prohibition在验证期按 ADR-550 D4/D5 的 fail-closed 默认处置为flagged/unverified诚实验证器弃权#1154——它浮出水面供人工裁决绝不静默通过。未解析的 edges 被显式呈现为假设绝不静默丢弃。No-silent-drop 等式在 SPEC 抬升路径与兜底路径间成立每个章节的探针浮现条目数写入must_haves的条数 以 flagged 假设浮出的条数。六、协议实现从 Gate 到 Authoring 的完整链路兜底协议存放于 gsd-core/references/specless-probe-fallback.md懒加载避免撑爆受预算约束的 plan-phase.md#717/#1074由 gsd-core/workflows/plan-phase.md 的 Step 7.95gate与specless_probe_fallbackplanner 块消费。6.1 Gate§0开关 逐节缺席判定如上文 §4.2gate 先读开关再用spec-section计算两个缺席标志。其中有一个无可探测内容守卫兜底谓词源自需求文本所以零 requirement ID 无可探测 可见跳过非硬失败防止无 SPEC 无需求的阶段在默认开启的兜底下中止整个流程。6.2 确定性 Edge 探针§A仅在SPECLESS_FALLBACKtrue AND EDGE_ABSENT1时运行Edge 探针与 spec-phase Step 5.5 逐字镜像**唯一分歧D-02**是$REQS_JSON的数据源从阶段需求 ID{phase_req_ids}而非 SPEC 访谈构造逐条从 REQUIREMENTS.md 拉取需求文本。协议对edge-probe.cjs的调用做了四层防护解析防护按 GSD 安装目录RUNTIME_DIR起解析编译产物找不到且位于源码检出树内才npm --prefix ... run build:lib否则响亮失败RR-04绝不静默跳过输入防护REQS_JSON 为空/非法数组/仍含replace:占位符 → 退出 1退出码防护探针引擎 fail-closed 退出 2坏形状时裸的COVERAGE$(node …)会吞掉它——协议用if ! COVERAGE$(...)显式捕获并退出 1绝不带着空 coverage 继续输出防护报告必须可解析为{ items[], coverage{} }且coverage.applicable 0时打印 WARNING大概率是分类遗漏而非真正零边界的阶段绝不静默写入空 Edge Coverage。6.3 禁止项召回§B无编译引擎的 LLM 通道prohibition 无编译引擎、无node调用ADR-550 D7b——gsd-planner在提示内执行完整两阶段协议Stage 1 — 对抗式召回逐需求问这个特性可能静默变成什么作者不想要的、而 spec 未禁止的东西过度产出约 10 条原始 must-NOT 候选Stage 2 — 精炼丢弃常规工程项普通正确性/卫生——归 edge probe 或 code review 所有保留价值/安全/伦理项约 2–3 条存活Canon 转介丢弃ADR-550 D6存活的候选若属 canon 安全/合规OWASP / 原型污染 / 路径遍历 / 注入 / GDPR / 通用公平性不铸造——输出一行面包屑后丢弃由/gsd:secure-phase/ eslint 拥有。兜底--auto分歧D-06 / RAIL-04 / PROH-1每条存活的 prohibition 以无 wired-check 描述符的 flagged-unverified形态 authoring。绝不写check_kind/check_target/check_rule/check_violation_fixture/check_clean_fixture——没有人类去接线/验证 check而无描述符正是保持 fail-closed 的关键经复用的dispositionForProhibition下游处置为{status:unverified, flagged:true}。绝不自动消除、绝不伪造 check 路径未解析的 prohibition 以 flagged 假设浮出绝不静默丢弃。6.4 Authoring§Cdownstream_consumer的 else 分支Edges →每条 resolvedverification: explicitedge 的验收标准 →must_haves.truths纯字符串每条 resolvedverification: backstopedge →must_haves.truths结构化扁平标量标记{ statement, verification: backstop }非散文#1110/#1278 脆弱性验证器确定性地分支于verification: backstop字段括号注记不可解析——验证器无法以显式证据确认的 backstop truth 弃权 →human_neededreasoninsufficient_spec#1154绝不静默通过每条 unresolved/unclassified 行 → 显式 flagged 假设Prohibitions →每条存活的 prohibition →must_haves.prohibitions:兄弟块非truthsADR-550 D3经唯一projectProhibitions序列化器Hyrum——无第二序列化器authoring 为无描述符无check_*标量以处置为 flagged-unverified章节级优先级SPEC 供给的章节绝不重跑或覆盖——每章节恰好一个生产者No-silent-drop 等式每章节探针浮现条目数写入must_haves数 flagged 假设数。七、后果与代价正向收益探针的覆盖面不再依赖阶段是否编写 SPECSPEC 章节检测可测试、可共享替代内联重解析开关为项目提供成本闸门而无须能力表面优先级契约把谁赢SPEC 还是探针从调用点行为提升为文档化决策。代价 / Hyrum默认开启是可观测行为变更无 SPEC 阶段现在会产出此前没有的谓词——但诚实验证器的 fail-closed 弃权使其不构成回归无描述符的兜底谓词 flag/弃权绝不把此前为绿的阶段翻红。SECTION_HEADERS成为被依赖表面重命名必须与templates/spec.md同步移动由测试钉死。延后Galls Law构建过程中浮出_gsd_lib()运行时目录解析惯用法在探针 shim 步骤间重复进一步集中化延后未做。ADR-1820 将spec-section缝命名为先例使下一个探针兜底消费者扩展既有缝而非重新内联检测——这是文档化缝要预防的失败模式。八、交叉引用与进一步阅读ADR-857 —Verification substrate vs. plug-in tier谓词生成是核心、不可开关的基座Phase 6 将探针家族接入核心轨道857:138。ADR-1820 是该迁移的 plan 侧落地。ADR-550 — spec-phase 探针契约must_haves.prohibitions投影projectProhibitions与本轨道复用的 fail-closed 处置。ADR-1606 — 消费已 authoring 谓词的验证期强制缝。ADR-457 —src/*.cts→ gitignoredbin/lib/*.cjs构建缝。CONTEXT.md —Spec-Section Helper Module可 grep 的模块谓词。代码/提示src/spec-section.cts、gsd-core/workflows/plan-phase.mdStep 7.95 downstream_consumerOtherwise 分支、gsd-core/references/specless-probe-fallback.md协议、gsd-core/references/planning-config.md开关、gsd-core/bin/shared/config-schema.manifest.jsonvalidKeys 注册测试tests/spec-section.test.cjsIssue#1820。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐GSD 规划文档分类引擎 gsd-doc-classifier 深度解析从 ADR/PRD/SPEC/DOC 到结构化智能档案GSD 规划文档分类引擎 gsd doc classifier 深度解析从 ADR/PRD/SPEC/DOC 到结构化智能档案 导读 get shit don人工智能AI 应用提示工程开发工具工作流自动化AI AgentVespa predicate-search-core 深度解析布尔谓词解析、AST 表示与表达式优化Vespa predicate search core 深度解析布尔谓词解析、AST 表示与表达式优化 本文围绕 Vespa 仓库中 predicate se后端搜索引擎人工智能大数据Milvus 分片委派端主键谓词段剪枝Segment Filter via PK Predicate Hints机制深度解析Milvus 分片委派端主键谓词段剪枝Segment Filter via PK Predicate Hints机制深度解析 本文基于 Milvus 官方设数据库向量数据库分布式数据库后端上一篇从 CHANGELOG 读懂 artifacts-viewerCloudflare Artifacts 只读仓库浏览器的版本演进与架构实现下一篇Zcash 1.0.13-rc1 发布说明深度解读libsnark 构建整合、z_shieldcoinbase 转正与测试体系重构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考