Spec Runtime Setup

Runtime Setup

spec-runtime-setup is the canonical runnable entrypoint for the Runtime Setup workflow across supported hosts (Claude/Qoder command spelling runtime-setup). Host-specific setup spellings are not separate products. Runtime Setup prepares deterministic host/runtime facts for spec-first workflows. It installs or verifies required MCP servers and baseline helper tooling, diagnoses manual helpers such as agent-browser, writes setup-owned project facts, and reports concrete next actions. It does not provide code-understanding authority; downstream workflows use bounded direct source reads, rg, ast-grep, git diff, tests/logs, and user-provided evidence.

Contract Summary

核心边界：Node module 准备确定性的 readiness facts；LLM workflow 决定如何使用这些事实。Setup 不得判断代码理解的语义充分性，也不得要求普通工作必须先依赖外部分析服务。CodeGraph/Graphify readiness 准备完成后，setup 可以建议将 spec-rule-miner 作为基于证据生成项目 AI coding rule 的后续步骤，但不得自行调用 rule mining、合成 rule 或写入 docs/ai/project-rules.md。

Scenario Capability

Follows docs/contracts/workflows/scenario-capability-matrix.md (default). Overrides: none

Source Of Truth

Canonical package source-of-truth 是 skills/spec-runtime-setup/setup-registry.json，由共置的 setup-registry.schema.json 校验，schema version 为 setup-registry.v10。Generated host 从已加载 skill 目录消费共置的 registry projection；该 projection 是 generated runtime，不是第二个 source。当前完整 Runtime Setup 必备项包括 sequential-thinking、context7、ffmpeg、CodeGraph 与 Graphify；CodeGraph/Graphify first generation 和真实 query probe 属于标准 setup completion，而不是长期可跳过的 optional tail。--only codegraph / --only graphify 仅用于高级子集修复，不改变完整 setup 的必备定义。

Generated host runtime mirrors and host-local MCP config files are projections or outputs, not source. If setup prose or scripts change, update source first and use spec-first init only for runtime regeneration.

Required Harness Runtime

setup-registry.json 负责必需 MCP definition、helper readiness 与 install safety、required Provider metadata、external dependency pin、host target、artifact contract 和 platform override。Loader 针对当前 host/platform 确定性展开 registry default，不判断 Provider readiness 或语义充分性。当前 helper 检查包括 ffmpeg、agent-browser 与 ast-grep capability detection；ffmpeg 是 setup completion 的 baseline-blocking helper，agent-browser 仍保持 report-only/non-blocking。对 agent-browser，dependency_status: ready 只表示 CLI/runtime/global skill 安装完整，不等于 execution_readiness: ready；exact-origin capability 缺口必须保留其 canonical reason、conformance_status、repair_scope 与 next_action。

所有可执行 setup 行为均由共置的 Node 入口及 scripts/ 下的 module 负责。不得在 workflow prose 中重新实现 registry query、host config 写入、Provider 命令或 facts reconciliation。

Loaded Skill 入口

从当前已加载的 spec-runtime-setup/SKILL.md 所在目录解析 SKILL_DIR。每次 runtime 调用都必须使用该目录中的共置 Node 入口：

node "$SKILL_DIR/scripts/setup.cjs" <mode-and-target-arguments>

绝不能从项目 cwd 或 source checkout 路径解析该命令。Generated command surface 使用其 companion support root 作为 SKILL_DIR。进入支持 mutation 的 mode 前，通过执行工具的 per-call environment overlay 传入 MCP_SETUP_HOST=claude|codex|cursor|kiro|opencode|qoder|zcode；只读诊断可以报告 advisory host candidate，但不能把它们转换为 write authority。

scripts/check-health 是带 Node shebang 的 compatibility shim，委托给 setup.cjs --check。Windows 直接调用 node <loaded-skill-root>/scripts/setup.cjs --check，不存在 platform-specific companion entry。

Optional provider readiness is reported through provider_readiness[] (provider-readiness.v2). Setup may populate lifecycle display bits such as installed, configured, indexed, server_reachable, and query_verified, plus setup-owned runtime metadata such as native_interfaces, first_generation, steady_state, and usage_note. Graphify may add first_generation.scope_provenance to separate requested scope from the scope verified by a contained receipt bound to the current graph.json; receipt missing/mismatch/invalid keeps first-generation status unknown for that request. A missing legacy receipt leaves core readiness unknown and the graph advisory-only; a mismatched or invalid receipt sets readiness_status=degraded, so selected setup/verify cannot report completion for an unproved requested scope. steady_state may include project-local hook readiness facts for optional provider refresh setup, such as Graphify hook_installed, hook_verified, hook_status=blocked, and refresh_mode=manual-only. Downstream decision health is still driven by readiness_status; lifecycle, first-generation, provenance, and hook fields explain boundaries and next actions, not semantic truth. Graphify hook blocked/failed/skipped 不得单独把 package、host integration、artifact integrity 与 query probe 的成功结果改写为 Provider degraded。The human status table may derive readiness_scope and probe_status from existing lifecycle bits to separate install/index readiness from real server/query probes; these display columns are not new machine schema fields. Provider self-reported fresh maps to unknown; provider self-reported stale may map to stale because it is conservative. query_verified=true is reserved for a real probe or explicit real-environment signal, not for package installation alone. A false or missing server_reachable / query_verified display value means the probe is not verified in this setup run unless a failure reason says otherwise; it must not be summarized as confirmed provider query availability.

Project Preflight / Local Setup

Project-local setup has two separate surfaces:

1. Setup-owned facts: .spec-first/config/tool-facts.json, .spec-first/config/runtime-capabilities.json, and when applicable .spec-first/workspace/scenario-fingerprint-setup.json.
2. Local config bootstrap: .spec-first/config.local.example.yaml, local override state for .spec-first/config.local.yaml, and .gitignore coverage for .spec-first/*.local.yaml. Missing local override means defaults-active，不是“未处理的可选项”。

The readiness ledger and runtime capabilities include generated_runtime_manifest.status (current, stale, missing, or unknown) based only on state.manifestVersion versus the bundled manifest version; this is a deterministic freshness fact, not proof that generated prose is semantically correct. Missing/stale remediation is emitted as structured next_action_command={cwd,command,args} plus next_action_headless_command; next_action is explanation only and must never contain an executable cd ... && ... compound string. Scenario fingerprint wrapper failures are warn-and-continue: report scenario_fingerprint_setup status and keep the rest of setup actionable instead of blocking ordinary direct-evidence workflows.

Local config bootstrap is a first-class Runtime Setup capability, but it remains project-local and local-only. It checks and can explicitly refresh .spec-first/config.local.example.yaml, explicitly create .spec-first/config.local.yaml, and explicitly ensure .spec-first/*.local.yaml is ignored. It reports legacy project config signals for manual review, but it does not copy legacy files, translate old key names, or treat old defaults as spec-first truth.

Three-Stage Setup Flow

即使内部 Node module 执行多项检查，Runtime Setup 仍应将面向用户的流程保持为三个阶段：

Stage 1: Diagnose Target And Readiness

Resolve the project target first. --repo <path> selects an exact Git root; --folder <path> selects that exact logical project directory whether it is nested inside a Git worktree or has no Git boundary at all. With no target flag, a pure non-Git directory with no child repos becomes the single folder target, while a non-Git parent with discovered child repos keeps the bounded all-repos behavior. Provider artifacts and setup facts stay in the exact target; generated host runtime health uses the enclosing Git root when one exists, otherwise the folder itself. Then inspect:

• host runtime identity and write authority;
• required MCP/helper dependency readiness;
• generated runtime manifest freshness;
• project-local config status for .spec-first/config.local.example.yaml, .spec-first/config.local.yaml, and .gitignore coverage;
• legacy project config signals;
• required CodeGraph/Graphify readiness；--only 时只执行选定子集，但不得把子集成功表述为完整 setup 完成。

This stage is read-only except for diagnostic facts written by verify-only paths that are already setup-owned. Missing required Provider/helper capability blocks Runtime Setup completion；它仍不阻止能够使用 direct source evidence 的普通 plan/work/review/debug workflow。

Stage 2: Apply Authorized Setup Actions

Apply only actions authorized by the selected mode:

• project-local config actions: refresh example config, create local override, ensure ignore coverage, and optionally delete obsolete legacy markdown only after explicit approval;
• host config action：只能通过共置 Node 入口与显式 host authority 写入 MCP/runtime config；
• helper/provider actions: standard bare workflow 安装或验证 required baseline，并默认运行 CodeGraph/Graphify bounded first-generation/query verification；--only codegraph、--only graphify 或 --only codegraph,graphify 仅收窄为高级子集修复。

Project-local config actions never install providers or edit host config. Host/provider actions never migrate local config keys. Legacy project config is a manual-review signal unless the user chooses a documented cleanup action.

Stage 3: Summarize Facts And Next Action

Render a grouped final status that separates:

• dependency/runtime readiness;
• generated runtime freshness;
• project-local config status;
• project setup facts;
• host configured dependencies;
• helper/provider readiness and install safety;
• next actions.

The summary must make skipped, declined, optional, degraded, and action-required rows visible. Do not collapse these boundaries into a single "setup complete" statement.

Setup Posture And Project Conventions

Runtime Setup follows an Explore -> Present -> Decide -> Write posture, with fast-path execution for bare invocations:

1. Explore host, target repo, generated runtime manifest, existing setup facts, .spec-first/config.local.yaml, verification profile visibility, provider artifacts, and project instructions.
2. Present & Decide:
   • Bare invocation (default spec-runtime-setup): After exploration, present a consolidated single summary of all pending operations (missing dependencies, config changes, provider installations) and request one confirmation before batch execution. The user approves the entire setup plan with a single response.
   • Explicit modes: --check and --plan are read-only. --verify-only is a facts-only mutation mode: it may write setup-owned facts, scenario fingerprints, and ledgers only, without requesting confirmation for those bounded writes.
   • Subset repairs (--only ..., --refresh): Execute the narrowed scope immediately after exploration; subset authorization is implicit in the flag itself.
3. Decide only where the runtime setup workflow has authority: install/verify helper tools, configure host MCP/runtime wiring, refresh setup-owned facts, or choose a documented degraded path. Team workflow conventions and semantic project decisions remain LLM/owner judgment in downstream workflows.
4. Write only setup-owned facts, supported local config examples, host runtime config through documented targets, and generated runtime refreshes through spec-first init. Do not write team-shared tracker policy, label vocabulary, external PR request-surface policy, issue acceptance decisions, or durable rejected-scope decisions from setup.

.spec-first/config.local.yaml is a local-only override file, not team-shared source of truth. Current active local config consumers are:

• verification_profile_path, read by the verification profile loader as a local execution preference;
• feedback_sources and sweep_*, read and written by spec-sweep;
• pulse_*, read and written by spec-product-pulse;
• spec_promote_spiral_optout, read and written by spec-promote;
• plan_skip_scoping_confirm, exposed for downstream planning workflows that support persisted scoping-confirmation preference;
• plan_output, brainstorm_output 和 ideate_output，分别由 spec-plan、spec-brainstorm 和 spec-ideate 读取。

plan_output、brainstorm_output 和 ideate_output 都是 active local rendering preferences。对应 consumer 只读取未注释且有效的 md / html 值；缺失、无效或仍被注释的值分别回退到 spec-plan=md、spec-brainstorm=md、spec-ideate=html。Pipeline override 仍由各 consumer 自己决定。Runtime Setup 只暴露并保护这些 key，不调用对应 workflow，也不把本地 rendering preference 提升为 runtime authority。没有真实 reader 的 CE/local delegation key 不进入本地 config surface。Setup must not auto-delegate, skip scoping confirmation, or change host model/runtime behavior merely because a key exists. Missing local config is not a blocker; defaults remain advisory and must not be reported as repo truth.

If setup later reports project convention facts, they must be deterministic existence facts only, such as whether CONTEXT.md, CONTEXT-MAP.md, docs/adr/, or a project guidance index exists. Setup must not judge whether terminology is correct, an ADR applies, a proposed issue/PR should be accepted or rejected, an out-of-scope concept matches, or implementation satisfies a request.

Host Authority And Write Safety

当前唯一公开入口是 spec-runtime-setup（Claude/Qoder 命令拼写 runtime-setup）；不提供 spec-mcp-setup / mcp-setup 兼容别名。调用它的 host runtime surface 是权威 host evidence。Generated host-specific runtime surface 必须在调用支持 mutation 的 Node mode 前，通过 per-call environment 固定 MCP_SETUP_HOST=<host>。缺少显式 canonical MCP_SETUP_HOST=claude|codex|cursor|kiro|opencode|qoder|zcode 时，setup.cjs 必须 fail closed；不得根据 PATH、generated runtime 目录、旧 .spec-first/config/* facts 或其他平台的 host config 文件推断 mutation target。只读诊断可以展示 advisory host candidate，但这些 candidate 不具备 write authority。

在写入任何 host config 或刷新 setup-owned facts 前，workflow 必须让 setup.cjs 从显式 entrypoint host pin 解析 host authority 与 effective registry target。旧 setup facts 只能作为 drift comparison evidence：若其与当前 entrypoint host 不一致，应报告 host-marker drift，并为当前 host 刷新 setup-owned facts，不得把旧 host 当作当前 host。绝不能仅依据 prose 手动选择 .kiro/settings/mcp.json、.qoder/settings.local.json、.cursor/mcp.json、Codex TOML 或 Claude managed/user config。

不得使用 Write、Update、Edit 等 host file-edit 工具修改 .spec-first/config/tool-facts.json、.spec-first/config/runtime-capabilities.json 或 host MCP config 文件。只有 authority、target、containment、conflict 与 verification gate 全部通过后，setup.cjs 及其确定性的 host-config/facts module 才能执行这些写入。

Workflow Modes

• --check: inspect current dependency/runtime status only; do not write setup facts, host config, or install tools.
• --verify-only / --refresh-facts: verify readiness and refresh setup-owned facts. --verify-only is a facts-only mutation mode and may write setup-owned facts, scenario fingerprints, and ledgers only; it must not install providers, edit host config, bootstrap project config, or refresh generated runtime.
• --plan: render install/config operations and safety results; do not write setup facts, host config, or install tools.
• --project-config：仅执行 project-local config bootstrap。按请求刷新 example，仅在显式 action 后创建 local override，按请求确保 .spec-first/*.local.yaml ignore coverage，并报告 legacy project config signal 而不迁移它们。该 mode 不安装 MCP server、不配置 host runtime，也不执行 helper/Provider first generation。
• Bare invocation (spec-runtime-setup in the current host): default full setup workflow. Resolve target，运行默认 required-provider plan；无 blocker 时执行等价的 --only codegraph,graphify apply、验证 baseline/Provider/runtime/project status，并写 setup facts。Bare workflow invocation 本身已授权自动修复 selected target 中 registry 管理的 host-config-conflict，不需要二次确认；它不授权绕过 higher-precedence、unsafe path、unreadable config、symlink/path escape 或 literal secret gate。
• --only <ids>: advanced headless/subset repair path. --only codegraph, --only graphify, or --only codegraph,graphify narrows provider execution and does not require a confirmation prompt；子集结果必须标记为 partial scope，不能声称完整 setup ready。
• --repair-host-config：显式授权 setup 仅替换 registry 管理且已确认冲突的 MCP 条目；保留同一 host config 中的其他用户字段和 server，并执行事务回滚与 post-write verification。Bare full setup 由 workflow 自动携带该 flag 处理 selected-target managed drift；显式 subset/repair 调用则必须由用户提供。可单独用于 baseline host config repair，也可与 --only ... 组合，在修复后继续 Provider install-init。没有该 flag 时，显式 --plan 必须在 package/provider mutation 前报告 host-config-conflict 并阻断；高优先级 target 冲突、不可读配置、symlink/path escape 和 literal secret 不能通过该 flag 绕过。
• --refresh: Graphify 显式刷新路径。已有 graphify-out/ 时，与 --only graphify 一起使用；setup 调用官方 graphify update <workspace> 更新现有 code graph，并在更新后重新执行完整性与裸 query probe，再原子写入与当前 graph.json SHA-256 绑定的 scope provenance receipt。它不创建 spec-first 顶层 staging/backup；若只有旧版适配目录 .graphify/，普通 setup 会先将其原子迁移为 graphify-out/，两个 artifact root 同时存在则 fail closed。它是 manual-only steady state 的按需更新方式，不是修复项目外 core.hooksPath 的动作，也不代表完整 semantic extraction。普通 setup 或 --verify-only 返回 core-ready readiness_status=unknown 时，不得仅因 unknown 自动追加或执行 --refresh；unknown 表示缺少当轮 currentness evidence，不表示 query probe 失败或 required setup 未完成。
• --requirement-workspace <target-relative-path>: optional Graphify input-scope override. Omit it for normal project-workspace setup; default input scope is the resolved execution root. This flag narrows Graphify input only; it does not change the CodeGraph root, setup facts owner, or the Provider-native graphify-out/ artifact owner.
• --repo <path> must resolve to the exact Git repository root. A nested path is invalid and fails closed instead of being promoted to an ancestor root; use --folder when the nested directory is the intended logical project.
• --folder <path> selects the exact logical project directory and does not require Git. CodeGraph writes .codegraph/, Graphify writes graphify-out/, and setup writes .spec-first/config/ under that folder. If it is nested inside a Git repository, generated spec-first runtime readiness is checked at the enclosing Git root so setup does not request a duplicate child .agents/skills; a standalone non-Git folder uses itself as the runtime projection root. Missing/stale runtime returns a structured interactive action rooted at that projection plus a headless variant containing -y -u <name> --lang <zh|en>; the folder is never passed to Git-only init --repo. Git health remains an additional fact and never rewrites the folder target. Graphify commit hooks and Git HEAD baselines are skipped as not-applicable for target_kind=non-git-folder, including a nested folder whose parent is a Git repo, while first generation, query, explicit refresh, and CodeGraph indexing remain supported.
• --user-scope：Kiro/Qoder/Cursor/OpenCode 写入 user-level MCP config 的 opt-in。缺少该 flag 时，即使由 generated host skill/command 间接调用，setup 也只为 Kiro 写 workspace .kiro/settings/mcp.json、为 Qoder 写 local .qoder/settings.local.json、为 Cursor 写 project .cursor/mcp.json，或为 OpenCode 写 project opencode.json。OpenCode user scope 解析 ${XDG_CONFIG_HOME}/opencode/opencode.json；project/user scope 任一存在更高优先级 JSONC sibling 时都以 host-config-jsonc-precedence-blocked 阻断 JSON mutation。

OpenCode host config mutation 把 MCP entry 与 opencode-governed-assets-v1 permission policy 视为同一 bounded transaction。Permission policy 只允许当前 projected runtime state 中的精确 governed skill names，禁止 wildcard/global allow，并让 bash、edit、task、webfetch、websearch 等危险工具保持 ask；遇到 conflicting user rule、unsafe last-match ordering 或 post-write verification failure 时 fail closed / rollback。Uninstall 只删除仍与 expected value 精确匹配的 managed entries，不删除整份 opencode.json，也不覆盖 unrelated user fields。

Graphify setup 使用受控 Provider route；标准 bare workflow 默认选择 Graphify，--only graphify 是高级子集修复入口。当前 pin 是 PyPI graphifyy@0.9.29，要求 Python >=3.10。Setup 只使用已安装的 uv（优先）或 pipx，将 release-reviewed direct wheel 安装到隔离 tool environment；uv 禁止 managed Python download，缺少兼容 Python 或 tool manager 时返回 action-required，不自动 bootstrap，也不回退 plain pip。Package readiness 同时验证 distribution identity、version、CLI version、absolute launcher 与 interpreter。显式 Graphify mutation setup 只有在 Python package/artifact/query/host 都 verified，且 Git 项目中的 project-local hook 也 verified（非 Git 项目不适用）时，才默认卸载已确认的全局 @sentropic/graphify，并只删除仍保持原 target 且解析到该 npm package 的旧 symlink。External/unsafe hook target 下不执行 incumbent cleanup；未知命令、普通文件和其他 symlink 一律不改。

Graphify Provider只接受PyPI graphifyy dependency。失败恢复使用固定wheel重装、contained artifact backup恢复与Python readiness复验。

缺少 --requirement-workspace 时使用已解析 project workspace，并直接采用 Provider 原生默认目录 graphify-out/ 作为唯一 current artifact，不注入 GRAPHIFY_OUT。首次生成固定运行 graphify extract . --code-only，不探测 API key、不触发 semantic backend；支持代码文件非空但生成零节点时 fail closed。已有 graphify-out/ 且未提供 --refresh 时只验证 package、host integration、裸 query，以及当前项目授权域内可用时的 optional hook，不修改 current graph。graphify-out 已存在但不是非 symlink 真实目录时，以 graphify-artifact-root-unsafe 在任何 host/runtime mutation 前阻断；仅有旧版 .graphify/ 时原子迁移目录而不重建图；.graphify/ 与 graphify-out/ 同时存在时以 graphify-artifact-root-conflict 阻断，避免双 source-of-truth。显式 --refresh 使用官方 graphify update <workspace> 在现有图上更新代码索引，复用 Provider 自带的 repo lock、临时 graph、shrink guard 与未变节点保留能力；spec-first 不再为日常刷新创建顶层 .graphify.staging-*、.graphify.backup-* 或 migration journal。旧版本遗留 journal 仅保留兼容恢复，不是新 refresh 的回滚机制。Apply/refresh 当轮有生成与 query 证据时可为 fresh；只读 verify 没有当轮 currentness 证据时为 unknown。

Claude、Codex、Cursor、Kiro 使用 Python Provider 的真实 project install surface；setup 只在 recognized Provider-owned skill/reference/rule/steering 与 ## graphify section 内规范化 graphify-out/，并将 Claude/Codex host hook command绑定 verified launcher。Qoder 不调用不存在的 --platform qoder，由 spec-first-owned Qoder instruction提供 direct CLI/fallback adapter。Graphify Git hook 是 project-local optional auto-refresh：setup 先用 git rev-parse --git-path hooks 解析有效 hooks root，只有 lexical containment 与 no-follow symlink containment 均证明目标位于当前项目内时，才以进程级 core.hooksPath pin 运行 hook install/uninstall/status，并在命令后重新解析目标。共享 worktree/submodule metadata、resolve failure 或 symlink escape 下，不运行 hook 命令、不读取外部 hook 内容、不修改 local/global core.hooksPath、不复制或串联全局 hooks；返回 blocked + manual-only，但不阻断已经通过的 Graphify 核心 readiness。有效 hooks root 位于项目外（如全局 core.hooksPath）时，setup 只读 post-commit/post-checkout 两个普通文件，检测 Provider marker 与会重新生成 legacy root 的 GRAPHIFY_OUT=.graphify override；绝不 write/execute/hook status，也不修改 core.hooksPath 或串联全局 hooks。只有 post-commit marker 存在且两个文件均无 legacy override 时才报告 hook_status=verified-external + refresh_mode=commit-hook-external-verified；只有 post-checkout marker、marker 缺失或文件不可读时返回 blocked + manual-only，legacy override 则使用 graphify-external-hook-legacy-artifact-override 明确阻断。这里的 manual-only/verified-external 只描述 spec-first 只读可验证的 external commit-time posture，不是 project-owned verified（hook_installed/hook_verified 保持 false）。不得声称外部 hook 不存在、不会执行或“安装失败”；external execution 始终是 unverified。Project-local verified hook 仍要求 post-commit 与 post-checkout 各有唯一 Provider marker block、verified interpreter和允许的 _rebuild_code命令；spec-first 会移除旧版 GRAPHIFY_OUT=.graphify 注入，确保 hook 使用 Provider 原生默认目录。Marker 外用户内容保持不变，也不会被默认 smoke执行。Setup 不编辑 shell profile、不启动 watch、不安装 graphifyy[mcp]，也不把 Graphify candidate提升为 confirmed truth。

CodeGraph setup 使用受控 MCP/Provider route。被选中后，setup 安装 setup-registry.json 声明的 pinned CodeGraph dependency，使用 codegraph serve --mcp 配置 host MCP，运行 codegraph init，并探测 codegraph status。若 status 报告 Pending Changes 或要求 codegraph index -f，setup 先执行一次 bounded codegraph sync，再运行 codegraph status；仍存在 pending change 或 sync 失败时，返回带 diagnostic 的 action-required。若 post-sync status 仍要求 codegraph index -f，setup 执行一次 bounded full reindex 并复查 status。索引 ready 后必须运行 bounded codegraph query __spec_first_readiness_probe__ --limit 1 --json real query probe；只有命令真实成功才设置 query_verified=true，失败则报告 codegraph-query-probe-failed degraded readiness。Full reindex 或 query probe 失败时保留现有 .codegraph/ artifact，报告 degraded/actionable readiness，不删除 index。这些一次性的 sync/reindex 分支属于 install-init repair，不代表 spec-first 接管 steady-state ownership。