契约与质量门禁
Spec-First 的质量体系不是单一测试命令，而是一组轻量合同：入口声明能做什么，产物声明怎么交接，验证声明跑了什么，评审声明证据在哪里，安全边界声明哪些 raw evidence 不能进入持久化文档。
核心目标是防止 fake completion：不能只因为 LLM 判断“应该没问题”就声明完成。完成声明必须指向 source reads、diff、测试、构建、截图、日志、schema 或用户提供证据。
Workflow Contract Summary
公共 workflow 和关键 standalone skill 都应在入口附近声明紧凑合同：
| 字段 | 作用 |
|---|---|
| When To Use | 当前任务是否应该进入该入口 |
| When Not To Use | 哪些情况应停止、澄清或转到上游 |
| Inputs | 需要的计划、task pack、diff、setup facts 或用户目标 |
| Outputs | 产物、变更、报告或下一步 |
| Artifacts | durable 或 session-scoped evidence 在哪里 |
| Failure Modes | 何时不应继续自作主张 |
| Workflow | 入口内部的高层执行姿态 |
| Downstream Consumers | 谁会消费这次输出 |
这个 summary 是入口边界，不是完整说明书。它帮助 LLM 和人先判断路线，再决定是否读取更深的 source 或 artifact。
Artifact Summary 与 Handoff
artifact-summary.v1 解决跨 workflow 交接时的上下文膨胀问题：下游先读摘要、路径、限制和触发条件，只有必要时才展开完整 artifact。
| 字段组 | 典型内容 | 消费方式 |
|---|---|---|
| Identity | schema_version、artifact_type、source_path、producer | 定位 artifact 链路 |
| Decision surface | goal、scope、non_goals、key_conclusions | 判断是否可继续 |
| Risk surface | unresolved_risks、limitations | 形成 residual status |
| Evidence surface | evidence_paths、source_reads_required | 回到 source/test/log 确认 |
| Routing surface | recommended_next_action、full_artifact_read_triggers | 决定下一入口和是否展开全文 |
当 workflow 无法安全继续时，handoff 也应可执行：
Blocking reason: <why execution cannot continue safely>
Recommended entrypoint: <workflow or standalone skill>
Next action: <copy-ready invocation or approval>
Context to carry: <plan/task-pack path, failed validation, scope evidence>这比只说“回到 plan”更可靠，因为它保留了阻塞原因和下一步上下文。
Context Governance
上下文治理的原则是 summary-first、source-first、runtime excluded by default。
| 路径范围 | 普通 workflow 默认处理 | 原因 |
|---|---|---|
.claude/**、.codex/**、.agents/skills/** | 排除 | generated runtime mirror，不是 source fix |
.spec-first/audits/**、.spec-first/governance/** | 排除 | runtime/audit artifact，体积大且需按任务精确读取 |
skills/（含 skill-local references/agents）、templates/、src/cli/ | 按任务读取 | source-of-truth |
docs/contracts/、README、host instruction source | 按需读取 | 项目与 workflow 合同 |
| 当前源码、测试、计划、需求、review 摘要 | 优先读取 | 当前任务直接证据 |
AGENTS.md 和 CLAUDE.md 通常已由宿主加载，普通 workflow 不应每次重新全文读取。只有用户点名、正在修改 instruction/runtime/setup、已加载指令明显 stale、或 code review 需要目录级项目标准时，才精确读取。
Verification Profile
Verification profile 描述“本次应该跑哪些检查”，不是替你执行检查的魔法。
| 来源 | 适用 |
|---|---|
显式 spec-first.verification.json | 团队已定义标准检查 |
| local profile / alias | 本机或项目局部覆盖 |
package.json 推断 | 没有 profile 时从 typecheck、test、lint、build 等脚本推断 |
| workflow closeout | 记录实际运行、未运行、失败、降级和原因 |
高质量 closeout 至少要回答：
- 运行了哪些检查
- 哪些检查通过、失败或未运行
- 未运行是否有 reason code
- 结果是否支持当前完成声明
- 是否仍有 residual risks
自然语言“测试应该没问题”不能替代 verification evidence。
Schema、契约测试与质量反馈
Spec-First 用 schema 和契约测试锁定公共协议：
| 质量面 | 例子 | 价值 |
|---|---|---|
| Workflow contracts | plan/work/review/setup 的入口合同 | 防止入口语义漂移 |
| Artifact schemas | task pack、review finding、quality gate result | 防止产物不可消费 |
| Release gates | package delivery、website sync、install matrix | 防止发布缺资产或文档失配 |
| AI Dev Quality Gate | workflow-runtime-contracts + advisory benchmark fixtures | 聚合阻断检查和反馈主题 |
Benchmark fixtures 是 advisory：它们声明场景、预期工作流、预期产物和验证命令，但不等同于真实端到端执行。质量门禁应把阻断失败和 advisory 失败分开。
Review Finding 证据要求
结构化 finding 应包含足够行动信息：
| 字段 | 说明 |
|---|---|
severity | P0-P3，决定优先级 |
confidence | 离散锚点，不使用伪精度 |
file / line | 可定位证据 |
why_it_matters | 影响解释 |
evidence | source/test/log/contract/diff/user evidence |
autofix_class | safe、gated、manual、advisory |
owner | downstream resolver、human、release 等 |
requires_verification | 修复后是否需要额外验证 |
外部工具证据可以作为 supporting evidence，但如果没有直接证据配对，不能升级为高置信 finding、root cause 或 merge block。
安全与隐私边界
持久化 artifact、review report、handoff 和 solution docs 应避免写入 raw sensitive evidence。
| 禁止进入 durable docs 的内容 | 正确处理 |
|---|---|
| raw external-tool dump、大 JSON、完整 MCP 输出 | 写 compact summary + artifact path + limitation |
| credentialed URLs、tokens、Authorization/Cookie | redaction 后再记录 |
| internal hostnames、private process/route dumps | summary-first，必要时保留安全路径 |
私钥、.env、工具凭据、签名材料 | 由 secret deny patterns 拦截或人工排除 |
| generated runtime mirror 全文 | 指向 source-of-truth 或 setup/update 路径 |
Provider readiness 只是机械 setup fact，不证明业务结论。Graph、CodeGraph、MCP 等输出最适合做 exploration-tier orientation：帮助决定下一步读哪里，而不是直接给出最终答案。
新增 Skill / Agent / 入口的接入门槛
新增能力时先回答三类边界：
| 问题 | 要求 |
|---|---|
| 它是 workflow command、standalone skill 还是 internal helper | 不把 internal helper 暴露为用户入口 |
| Source truth 在哪里 | 修改 skills/（含 skill-local references/agents）、templates/、src/cli/，不修 runtime mirror |
| 谁消费它的产物 | 明确 Inputs、Outputs、Artifacts、Failure Modes、Downstream Consumers |
质量上至少考虑：
- 是否需要 README / Guide / Reference 更新
- 是否影响 Claude、Codex 与 preview hosts 的多宿主投递
- 是否需要 contract test 或 content audit 覆盖
- 是否需要 fresh-source eval 或 source 文件检查
- 是否需要更新
CHANGELOG.md
实践检查表
| 准备声明完成前，确认 | 问题 |
|---|---|
| Source/runtime 边界 | 是否修改了 source，而不是 generated mirror |
| Handoff | 是否有摘要、路径、限制、下一步 |
| Verification | 是否跑了匹配改动的最小检查 |
| Evidence | 结论能否回到 source/test/log/contract/user evidence |
| Context | 是否避免了 full artifact / raw output 广播 |
| Security | 是否移除了 token、credentialed URL、private dump |
| Changelog | 用户可见 source 变更是否记录 |
阅读下一步
- 运行时治理：理解 source assets 如何生成 runtime mirrors。
- 工作流系统：理解每个 workflow 的证据姿态和交接边界。
- Best Practices：把这些原则应用到真实项目协作中。