Control-plane Artifacts
当前 .spec-first/ 主要保存 runtime setup facts、workspace advisory facts、专项审查 run artifacts 和 work closeout evidence。它们回答“当前机器和当前 workflow 运行看到了什么”，不是长期手工维护知识库。
长期协作文档仍在 docs/ideation/、docs/brainstorms/、docs/plans/、docs/tasks/ 和 docs/solutions/。
当前目录
| 路径 | 生成者 | 用途 | Git 边界 |
|---|---|---|---|
.spec-first/config/ | spec-runtime-setup | required MCP、helper、provider readiness 和 runtime capability facts | 默认不提交 |
.spec-first/workspace/ | parent workspace setup / resolver / clean | child repo 候选、scenario fingerprint、orphan quarantine 等 advisory summary | 默认不提交 |
.spec-first/sessions/ | spec-first session ... | opt-in 多 actor session advisory | 默认不提交 |
.spec-first/app-audit/runs/<run-id>/ | spec-app-consistency-audit | App consistency audit 机器事实与报告 | 默认不提交 |
.spec-first/workflows/spec-work/<workspace-slug>/<run-id>/ | spec-work closeout producer | compact work evidence、验证摘要、source refs | 默认不提交 |
.spec-first/workflows/quality-gates/* | quality gate scripts | AI dev quality gate 或 verification evidence | 默认不提交 |
Provider Pack 产物
CodeGraph / Graphify 不写入旧的 canonical readiness 目录。它们使用 provider-native 输出：
| 路径 | 来源 | 说明 |
|---|---|---|
.codegraph/codegraph.db | CodeGraph | local code graph database；spec-first 默认忽略 |
graphify-out/ | Graphify | 当前 provider-native 产物（GRAPH_REPORT.md / graph.json 等） |
.graphify/ | Graphify (legacy) | 旧版 spec-first 适配目录；仅在 setup 迁移或历史证据中出现 |
.codex/skills/graphify/、.claude/skills/graphify/ | Graphify project skill install | provider-owned runtime/project output |
.git/hooks/* | Graphify hook install | provider-native refresh hook，setup 只报告不强制提交 |
这些 provider-native 输出只能作为候选证据。下游 workflow 声称某个实现、影响面或风险时，仍要引用当前源码、diff、测试、日志或用户证据。
Durable Docs
| 路径 | 生成者 | 是否通常提交 |
|---|---|---|
docs/ideation/*-ideation.md | spec-ideate | 是 |
docs/brainstorms/*-requirements.md | spec-brainstorm / spec-prd | 是 |
docs/plans/*-plan.md | spec-plan | 是 |
docs/tasks/*-tasks.md | spec-write-tasks | 视团队协作需要 |
docs/solutions/**/* | spec-compound / spec-compound-refresh | 是 |
缺失时怎么处理
| 缺失或 stale | 处理 |
|---|---|
.spec-first/config/* | 运行当前宿主的 spec-runtime-setup |
| provider 输出缺失 | 完整 setup 需要重新验证 baseline；普通 workflow 可继续 direct reads，但必须披露 setup degraded / incomplete |
| work run evidence 缺失 | 不把 closeout artifact 当 source scope authority，回到当前 diff/source/tests |
| durable docs 缺失 | 回到对应 workflow：ideate、brainstorm、prd、plan、write-tasks 或 compound |
下一步
- 产物目录与 Git 边界：查看所有 spec-first 产物分类
- Runtime Setup：查看 setup 如何写
.spec-first/config/* - Provider Pack：查看 CodeGraph / Graphify 产物和边界