spec-graph-bootstrap

Spec-First Graph Bootstrap

spec-graph-bootstrap 的目标是把当前仓库准备成 CRG query-first 状态：

source files
  -> spec-first crg build
  -> graph.db + graph-quality.json + graph-index-status.json + code-navigation.json + repo-topology.json + graph-operations.jsonl
  -> locate / path / explain / impact / review-context / lifecycle hooks
  -> LLM reads evidence and decides

边界必须保持清晰：

• 脚本只做确定性事实准备：解析源码、更新图索引、写健康状态、返回候选证据。
• LLM 负责语义判断：选择修改点、取舍影响面、决定验证范围。
• Hook 输出是 advisory input，不是 hard gate，也不是状态机。
• 当 graph 不可用时，恢复路径是 direct repo reads 或重新 build graph，不读取旧文档包作为 fallback。

调用方式

$spec-graph-bootstrap [target-repo-path]

target-repo-path 省略时使用当前工作目录。宿主 workflow 入口是 /spec:graph-bootstrap 或 $spec-graph-bootstrap；package CLI 入口是 spec-first crg <subcommand>，不是 spec-first graph-bootstrap。

Workspace Root Handling

如果 target 是父目录 workspace（父目录下有多个独立 git repo），先运行 workspace preflight，而不是对父目录执行 repo-local build：

spec-first crg workspace scan --root=<workspace>
spec-first crg workspace status --root=<workspace>
spec-first crg workspace context --root=<workspace> --task="<task>"

workspace 层只生成 .spec-first/workspace/workspace-index.json 和 workspace-status.json 这类轻量事实；不得创建父目录 .spec-first/graph/graph.db。workspace context 的 candidates 是 advisory input，LLM/user 选择 child repo 后，才运行 repo-local 命令：

spec-first crg workspace build --root=<workspace> --repo=<child-slug-or-path>
spec-first crg hook before-plan --repo=<child-repo> --task="<task>"

如果任务跨多个 child repos，先拆成显式的顺序 repo-local runs；Phase 1 不执行一个隐藏的 combined workspace work-run。

Phase 0: Target And Readiness

1. 解析目标仓库绝对路径。
2. 如存在 host setup marker，读取 host-setup.json 的 readiness ledger v1：
   • overall_status
   • baseline_ready
   • tools.<tool>.host_config_status
   • tools.<tool>.project_status
   • crg.cli_status
   • crg.native_modules_status
   • next_actions[]
3. fallback-active 只表示 host config 可用但可能由 fallback scope 提供；它不等于项目 graph 已 ready。
4. 若 ledger 不存在或不可读，只报告 limitation，继续用本地 CLI probe。

CRG probe:

spec-first crg --help
spec-first crg stats --repo=<target>

Ledger 中的 crg.* 字段是上一轮 setup 写入的 host fact，只能作为提示。当前轮是否能继续，应以本地 CRG probe 和后续 build / stats / query 命令的实际结果为准。若 ledger 报 crg.native_modules_status=missing，但本地 spec-first crg ... 命令可正常执行，只报告 ledger 可能 stale，不要要求用户先修 native modules，也不要停留在 MCP setup 环节反复确认。

判定：

• stats ready 且 node count > 0：进入 Phase 2。
• graph 缺失、为空、打不开、或原生模块不可用：进入 Phase 1。

Phase 1: Build Graph Index

直接执行图构建：

spec-first crg build --repo=<target>

用户显式进入 $spec-graph-bootstrap / /spec:graph-bootstrap 后，repo-local graph build 是该 workflow 的核心动作，不需要再二次确认。仅在 target 是父级 workspace 且 child repo 选择不明确、或命令将写入非目标 repo 时，才停下来让 LLM/user 选择明确的 child repo。

构建成功后必须确认 control-plane 产物：

.spec-first/graph/graph-index-status.json
.spec-first/graph/code-navigation.json
.spec-first/graph/graph-quality.json
.spec-first/graph/repo-topology.json
.spec-first/graph/graph-operations.jsonl

graph.db 是代码事实真源；graph-quality.json 是当前 active generation 的质量投影，用于暴露 parser coverage、unresolved edge rate、confidence distribution、community/flow 限制等 advisory facts；其他 JSON 文件提供状态、导航、topology 和审计线索。若 operation log 写入失败，不得阻断 graph build 主产出。

Phase 2: Query Smoke

至少执行一组低成本查询，确认 query-first 面可用：

spec-first crg workflow-context --stage=plan --repo=<target>
spec-first crg locate --repo=<target> --query="<task or area>" --limit=5
spec-first crg explain --repo=<target> --node="<node-or-file-id>"

如果没有具体任务，locate query 可使用仓库入口、主要模块、测试入口等中性问题。查询结果只作为候选事实，不要把第一个候选当最终答案。

Phase 3: Workflow Handoff

完成 bootstrap 后，把后续工作引导到 CRG lifecycle hooks：

spec-first crg hook before-plan --repo=<target> --task="<task>"
spec-first crg hook before-work --repo=<target> --plan=<plan.md>
spec-first crg hook after-work --repo=<target> --work-run=<id>
spec-first crg hook before-review --repo=<target> --since=<base>

Hook 内部会读取 stage-specific workflow context，并建议后续 locate / path / explain / review-context 查询。LLM 必须结合计划、diff、本地源码和测试结果做最终判断。

Phase 4: Fallback And Limitations

当 graph unavailable：

• 明确写出 fallback mode：direct_repo_reads。
• 读取当前任务需要的源码、测试、配置和 README。
• 不把旧静态上下文包当事实层。
• 不发明 graph evidence；只能说明 graph 缺失、不可打开或为空。

当 query 输出不足：

• 继续用 targeted local reads 补证据。
• 记录 limitation，例如 parser coverage、unresolved edges、missing graph, empty graph。
• 不用规则引擎替 LLM 做语义裁决。

Done Signals

完成本 workflow 时应向用户报告：

• graph state：ready / degraded / unavailable / missing。
• control-plane 产物是否存在。
• graph quality：graph-quality.json 是否存在；若存在，报告 parser coverage、unresolved edge count/rate、top limitations；若缺失，说明 workflow 仍可继续但质量摘要不可用。
• 至少一条可用的后续 query 或 hook 命令。
• 如果 fallback，被建议读取的 direct repo paths。
• 如果 build 失败，错误原因和下一步修复命令。