integration-contract

集成契约

将规范中的跨仓库衔接点写入磁盘，作为 契约 文件，并通过 冒烟门禁 检查。名义上仅涉及单个项目的规范仍需执行下方的消费者扫描。

输入

<SPEC-ID> — 规范（PRD）／父级议题标识符；从上下文中获取，或询问一次。用户不在，且无法推断标识符 → 停止并注明需要用户提供；绝不猜测规范标识符。

规则

• 不添加任何署名。 任何输出中都不得添加或保留共同作者、AI 或工具署名；在契约中纳入此规则。
• 环境权限。 默认使用本地测试环境。绝不访问生产环境。使用暂存环境需要获得明确批准并由用户提供访问权限；每项变更都需要单独批准。主机未知或缺少权限时，相关流程标记为 pending。
• 单项目也要扫描，不可盲信。 规范仅涉及一个 PROJECT-CODE → 扫描 Project Matrix 中的其他仓库，查找变更表面的调用点（仅限下方所述的窄范围检索）。若扫描完整且未发现外部调用点，包括任何位置都没有找到消费者 → 报告 single project — no contract needed 并 停止；不要创建文件。保留并报告任何历史契约；不要删除其门禁日志。若发现任何外部调用点 → 尽管规范如此描述，衔接点仍属跨项目；创建契约，并将每个此类消费者列为风险项。
• 仅限窄范围检索。 按照 references/consumer-sweep.md，在每个 Project Matrix 仓库中搜索每个变更表面；绝不批量读取仓库或其 specs/ 目录树。将消费者引用为 file:symbol。仓库不可用会导致扫描不完整：记录风险，不得得出无需契约的结论。
• 区分意图与实现。 阅读 GLOSSARY.md（旧名称为 CONTEXT.md）和相关 ADR，了解已记录的决策；追踪当前代码以确定实际行为。将与规范或当前用户决策冲突的情况记录为风险项。本地 CLI 记忆只能作为线索，必须核实。
• 决策必须留存为记录。 聊天报告只说明已写入的内容以及阶段更新。
• 在所有位置使用 Project Matrix 中的完整 PROJECT-CODE；绝不将一个项目的约定、令牌或组件混入另一个项目。
• 未找到消费者是风险，不是通过。 在跨项目契约中，若变更表面在矩阵的任何位置都没有消费者调用点，或消费者不在规范涉及的切片中，则添加 RISK 项；绝不能默默假设该表面未被使用。
• 流程只有在环境已核实的情况下才计入。 缺少证据的通过状态保持为 pending，而不是 pass。
• 只建议，不自动串联。 build 不自动运行 gate；gate 不自动运行 /commit-push-*。建议下一步，然后停止。
• build 阶段只读。 只写入契约文件；绝不修改产品代码、配置、议题或 ADR。
• 子 Agent：对于相互独立的工作，自动派发本地工作流；绝不使用云端 Agent。派发时告知工作流数量，并在每个工作流完成时报告。

契约产物

每个规范对应一个文件，位于 <artifacts-root>/specs/integration/<SPEC-ID>-contract.md。解析 <artifacts-root>：如果存在 *.code-workspace 文件，则使用其所在目录；否则使用上下文对应的根目录（仓库根目录下的 GLOSSARY-MAP.md；旧名称为 CONTEXT-MAP.md）；再否则使用仓库根目录。

重新运行时，读取现有契约，保留用户编辑内容和门禁日志；如果实现或环境发生变化，将受影响的流程重置为 pending。验证 <SPEC-ID> 是单个文件名组件，不包含路径分隔符或 ..。

在 build 模式下，填写 references/build-contract.md。在 gate 模式下，使用现有契约；只有在结构或冒烟测试覆盖需要修复时才加载架构定义。不确定时，可选读一份已填写的示例：references/contract-example.md。

模式

build（默认）

1. 阅读规范及其子问题。
2. 检测受影响的 PROJECT-CODE；恰好一个 → 单项目检查（Rules），不需要契约时停止。
3. 确定生产者切片及其使用者；填写第 1–3 节。超出规范范围的使用者 → 还要通过 /to-tickets 建议一个切片。
4. 编写第 4 节流程（Driver、空的 Evidence、Status: pending），写入文件，并输出 build 更新。

gate

完整 gate 会约束规范级交付和 PM 交接。跨越尚未实现切片的流程不会阻塞逐切片的 /commit-push-*：先运行跨越部分已实现的流程，其余流程保留为 pending。

1. 执行任何操作前先验证环境（第 1 节）：确认主机权限、服务可访问性、所需测试数据，以及变更的界面已包含在运行中的构建产物中。仅在上述权限范围内重新构建或准备数据；否则，将受影响的流程保留为 pending。对照实现检查第 2–3 节，并在运行流程前更新已变更的界面。
2. 按各流程的 Driver 执行；记录 Evidence（截图路径、引用的响应、观察到的文本）；标记为 pass/fail。浏览器流程遵循 references/consumer-sweep.md。
3. **任何 fail 都会重新开启契约：**记录并指出该问题，阻止当前步骤——不得提交推送，不得交给 PM，也绝不可悄悄丢弃失败项。将失败的衔接点转交 /to-tickets；若是缺陷而非缺失的切片，则转交 /diagnosing-bugs。
4. Driver 不可用（未安装 agent-browser；当前无法执行手动步骤）：说明情况，将这些流程列为用户的手动步骤，并保留为 pending——绝不可凭假设将流程标记为 pass。
5. 附加 gate 日志行，包含待处理数量及原因。全部为 pass → 建议执行 /code-review，然后执行 /commit-push-close / /commit-push-pr，或交接给 PM；任何 fail → 执行 /to-tickets 或 /diagnosing-bugs。任何 pending 都会阻止规范级交付和 PM 交接；报告缺失的证明。停止——绝不自动串联后续操作。

输出

每次阶段转换时输出 Stage / Found / Next / Needs user——每个字段单独一行。

build 更新：

Stage: build — wrote specs/integration/<SPEC-ID>-contract.md. [or: single project — no contract needed (matrix swept; no external call-sites)]
Found: producer <PROJECT-CODE>; consumers <PROJECT-CODE>, <PROJECT-CODE>; <K> changed surfaces; <R> risk row(s). [or: matrix swept for <K> changed surfaces; no external call-sites]
Next: implement the slices, then integration-contract gate mode before spec-level ship and PM handoff. [or: proceed per-slice — no integration gate needed]
Needs user: <risk rows to confirm, environment facts, or "none">.

gate 报告——填写 Status 的第 4 节表格（不含 Evidence），置于以下两行之间：

Environment: <verified service(s) and artifact evidence, or unverified service(s) and reason>.
<table>
Reopened by failures (blocking, not shipped): <#s or "none">.

Suggested next skills (optional):
- /to-tickets: slice the failing seam (<#s>).
- /code-review then /commit-push-*: once every flow is pass.

完成标准

• 契约以四个章节和 gate 日志重新开启；或者 build 更新写明 single project — no contract needed，未写入新文件，且保留并指出任何历史契约
• gate：已附加新的 gate 日志行；每个流程的 Status 均为 pass/fail 且填写了 Evidence，或为 pending
• 输出的更新符合本次运行模式对应的 Output 模板