SuperAPI AI 工具集

bridge-contract

编程与开发

查看项目

更新于 10-16 00:03

技能介绍

用途:bridge-contract 是 spec-superflow 的定义层技能,把规划产物转换为单一执行握手文件 execution-contract.md,作为从规划进入实现的交接契约。当用户表示“现在实现”“准备开始构建”“把计划转成执行规则”“准备交接”“刷新契约”“规格变了,更新执行契约”时调用。

主要能力:读取 proposal.md、specs/、design.md、tasks.md、docs/artifact-contract.md,不依赖聊天记忆替代这些文件。可用结构化产物解析自动提取契约字段:从 proposal.md 提取意图锁(Why 压缩为“要解决的问题”、What Changes 压缩为“范围内”)、范围围栏(Out of Scope)、非目标;从 specs/ 提取已批准需求摘要(SHALL/MUST)、关键场景、验收检查(THEN 子句)、测试义务(可观察行为须先写失败测试);从 design.md 提取架构、接口、依赖、数据约束;从 tasks.md 按章节分组执行批次、完成定义与评审时机。解析引擎不可用时按映射规则手工提取,并逐字段与源产物交叉核对。

覆盖检查:列出 specs/ 中每条 SHALL/MUST 需求,检查是否反映在已批准行为、是否有对应测试义务、是否至少出现在一个执行批次或验收检查中;未覆盖的需求须在契约的升级规则中标记,不得静默丢弃。

使用方式:以 templates/execution-contract.md 为基线结构撰写,强调压缩与可操作性,而非重复规划细节。契约须清楚说明已批准行为、明确排除范围、实现须遵守的约束、执行批次划分、哪些测试须先失败、哪些条件强制回退规划。生成后运行 node scripts/spec-superflow.mjs state init <change-dir> 创建 .spec-superflow.yaml(含 artifacts_hash 与 contract_hash),用于后续快速检测过期。

审批与限制:本技能只准备实现就绪,不代替用户授权实现;须总结交接规则、指出仍模糊之处、标出无法映射到测试义务或批次的需求,并请求用户显式批准,批准后才可进入 execution-governor。若 proposal.md 范围、specs/ 已批准需求、design.md 架构或接口约束、tasks.md 执行批次发生实质变化,或契约与团队意图不符,须刷新契约。hotfix 模式下生成最小契约,仅含意图锁、任务清单与 DP-3 审批门,跳过范围围栏、构建规则、评审门与测试证据要求,但仍需用户显式批准。护栏:存在重大歧义不得继续实现;不得替用户批准契约;不得因规划文档看似完整而跳过 execution-contract.md;本技能内不写生产代码。输出应包含桥接创建或刷新说明、意图锁与范围围栏、最重要测试义务、主要评审或回退触发条件、覆盖缺口,以及直接请求用户批准。