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.v9。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；只读诊断可以报告 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. 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, 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. 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. In a non-Git parent workspace, default to all discovered supported child repos; --repo <child> is the explicit narrowing control. Continue only when discovery yields a bounded child set, and keep every repo-local write within its child target. 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, --plan, --verify-only): Present detailed diagnostics without requesting confirmation; these modes do not mutate.
   • 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;
• work_delegate_*, exposed for downstream execution workflows that support delegated work;
• 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。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 时，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 才能执行这些写入。

Claude Host Pin

When this generated Claude command or workflow Skill invokes .claude/spec-first/workflows/spec-runtime-setup/scripts/*, set MCP_SETUP_HOST=claude in the script environment. Treat spec-runtime-setup / runtime-setup command entry as authoritative Claude host evidence; do not infer Kiro, Qoder, or Codex from PATH, existing runtime directories, or stale setup facts.

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; do not install tools or edit host config.
• --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。它不创建 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 <repo-relative-path>: optional Graphify input-scope override. Omit it for normal project-workspace setup; default input scope is the resolved project workspace.
• --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。

Default Full Setup Flow

For bare spec-runtime-setup, execute with batch authorization and single confirmation:

1. Resolve the project target. In a non-Git parent workspace, default to all discovered supported child repos; use --repo <child> only to narrow the run. Every repo-local write remains contained in its child target.
2. Run the read-only check。若 example config missing/outdated 或 local-config ignore rule missing，先运行 --project-config --refresh-example --ensure-gitignore；.spec-first/config.local.yaml 缺失保持 defaults-active，不创建空 override。
3. Run node "$SKILL_DIR/scripts/setup.cjs" --plan --repo <resolved-project-root> for a single-repo target. For the default parent-workspace batch, preview every discovered child with its own --repo <child> target before the shared apply. Plan 默认选择 registry 中 setup_required=true 的 CodeGraph/Graphify，并同时预览 baseline MCP/helper、host config、Provider artifact、hook 与 facts writes。
4. If the plan reports an unresolved target, higher-precedence conflict, unsafe path, unreadable config, or unsupported install path, stop with the exact blocker. If it reports a selected-target host-config-conflict, show config path/key/drift fields。Bare workflow invocation 本身已授权自动修复 selected target 中 registry 管理的 host-config-conflict：自动携带 --repair-host-config 重新 preview 并继续 apply，不再请求用户二次确认。
5. Present consolidated setup summary and request single confirmation: Show all pending operations in one grouped summary (missing dependencies, config changes, provider installations). Ask exactly one yes/no confirmation for the whole batch, using the platform's blocking question tool when available (e.g. AskUserQuestion in Claude Code, request_user_input in Codex) and falling back to a plain-text yes/no prompt in chat when no blocking tool exists in the harness. Never ask a second confirmation per item. On approval, immediately proceed to step 6. On decline, exit with the diagnostic summary and no mutation.
6. Plan 无 blocker 且用户确认后，批量执行 apply：单仓使用 node "$SKILL_DIR/scripts/setup.cjs" --only codegraph,graphify --repo <resolved-project-root>；默认 parent-workspace batch 则从 parent 运行 node "$SKILL_DIR/scripts/setup.cjs" --only codegraph,graphify，由 resolver 对全部 discovered child 执行。两条路径都携带已授权的 repair/target/workspace flags。
7. Apply 必须完成 ffmpeg/baseline helper、CodeGraph init/index/query、Graphify package/host integration/graph/query、host config、project status 和 facts verification。Graphify hook 只在有效目标位于项目内时作为 optional auto-refresh enhancement 安装并验证；blocked/skipped/failed 必须显式展示 steady-state limitation，但不得单独把 core-ready 完整 setup 改为 action-required。任一真正 required item 未 ready 时，完整 setup 返回 action-required；不得以 direct-source fallback 把 setup 本身报告为 complete。

Subset / Repair Flow

Use --only codegraph, --only graphify, --only codegraph,graphify, or Graphify --refresh for advanced subset repair:

1. 运行带相同 selection 的 plan，再执行 apply；--only 自身就是该子集 mutation 的授权。
2. Host conflict 仍需独立 --repair-host-config 授权；higher-precedence、unsafe path、unreadable config 和 literal secret 永远 fail closed。
3. 子集成功只证明所选 scope ready。最终完整 setup readiness 仍以 spec-runtime-setup --verify-only 对全部 required items 的结果为准。

Per-Requirement Workspace Graph (Multi-Repo)

从一个非 Git 的需求文件夹(多仓父目录,内含多个独立 clone 的子 Git 仓)运行 setup 时,先分清两条路径:

1. 子仓 provider/MCP setup(各 child 的 CodeGraph/Graphify/host config):父目录无 target 参数时默认 all-repos；--repo <child> 收窄到单仓，--all-repos 可用于显式表达同一批处理范围。
2. 父目录双层图(per-child CodeGraph + workspace Graphify merge):--workspace-graph --repos a,b,... 或 .spec-first/workspace.yaml manifest。
   不要写 --workspace-graph --all-repos——--all-repos 只服务子仓 batch,不是 workspace-graph 的仓集确认。

从子仓开始时的轻量引导

这是一段静态引导，不会自动声明 workspace membership、CodeGraph 已安装，或 workspace graph 已构建：

• 问题只涉及当前子仓时，如 Provider 可用，以当前子仓作为 projectPath 使用 CodeGraph；结果只是导航候选，重要结论仍由源码、测试、diff 或日志确认。
• 问题跨多个子仓时，回到非 Git 的需求父工作区。仅当 workspace graph 状态和目标仓范围均已确认时才使用 Graphify；随后直接检查候选子仓。
• 不要假设 workspace graph 存在或仍然 current，不要从该引导推断成员关系，也不要把任一 Provider 输出当作语义证明。

本轮不向 child AGENTS.md / CLAUDE.md 注入独立受管 marker，也不提供对应的 clean 生命周期；父目录 routing block 仍由显式 workspace graph lifecycle 管理。

首次接入 requirement workspace 时先运行 spec-first init --all-repos（或逐仓 spec-first init --repo <child>）让所选宿主的 child projection current，再运行 spec-runtime-setup --only codegraph,graphify --workspace-graph。Projection current 后，workspace graph 命令会为该 workspace 建立两层代码图：

1. 每子仓战术图:codegraph init 生成 工程N/.codegraph/codegraph.db;.codegraph/ 写入该子仓 .git/info/exclude(经 git rev-parse --git-path 解析,正确处理 .git-as-file/worktree,并做 realpath+containment 校验)以保持子仓 git status 干净;CodeGraph MCP server 全局 install 一次,跨仓查询通过 projectPath。Build、refresh-only 与 status 均只把 contained、stable、非 symlink、非空的 canonical DB 视为 artifact ready；目录中的日志、锁文件或空 DB 不构成完成证据。
2. workspace 跨仓宏观图:Graphify extract --code-only 每子仓子图 + merge-graphs 合并图,全部 out-of-tree 写到 需求文件夹/graphify-out/(子仓物理零侵入)。单/零子仓分别产出 single-source / not-applicable。所有 Graphify JSON 在 promotion/status 前通过 no-follow stable descriptor 做任意大小的完整流式语法校验，不以非空、首尾括号或 Provider 零退出替代 artifact 完整性。构建结果原子写入 graphify-out/workspace-graph-state.json;workspace-graph-state.v3 保留 source snapshot、merged artifact SHA-256、repo/merge artifact promotion cleanup pending 与可为 null 的 refresh_hook。异步模式的 workspace-child-hook-contract.v2 receipt 包含 canonical managed-block SHA-256、绝对 Node/async/setup/CodeGraph/Graphify 路径、runtime host 与 bundled version。status 保留主要 build reason，并把 cleanup pending 作为独立 limitation 暴露；只有在最近构建 complete、无 cleanup pending、repo 集合与 source snapshot 未变化、两个 hook 内容/执行位/runtime path/version 均符合 receipt，且 CodeGraph/Graphify artifacts、非 symlink 合并图与路由块均存在时才报告 ready。旧 v1/v2 state、v1 hook receipt 或缺少 refresh_hook 的 state 不自动迁移；升级后需显式重跑 workspace build，以原子替换 state 和 managed hooks。

CodeGraph 1.5.0 的 MCP watcher 只绑定 server 默认项目，通过 projectPath 打开的其他子仓不会各自启动 watcher。Graphify 0.9.x 原生 child hook 只重建 child 默认 output，也不能更新上述 out-of-tree 子图并重收敛 merged graph。因此 workspace 模式使用 spec-first 自有 contained post-commit / post-checkout managed hook：显式 build 先通过现有 Provider resolver 确认绝对 CodeGraph 与 Graphify launcher，只有两个 launcher、当前 host 与 bundled version 都完整时才固化进 hook；managed block 放在 shell shebang 后、用户正文前，避免既有 exit / exec / set -e 令刷新不可达，malformed block 在 install/clean 时均 fail closed。上下文不完整时不安装 PATH-dependent hook并降级为 explicit。Status 依据 receipt 重建 canonical block digest，检查两个 hook 的内容、POSIX 执行位、记录的 runtime files 可用性与当前 bundled version；漂移时统一将 workspace status 降为 partial、effective refresh mode 降为 explicit，并保留 per-child workspace-child-hook-* reason code。Git 事件 detached 触发 refresh-only setup，它必须同时携带 internal marker、两个 pinned launcher 与有效 lifecycle credential；在 lifecycle lease 内对全部 confirmed child 运行 bounded codegraph sync <repo>，再执行 Graphify extract / merge-graphs，不得再次执行 CodeGraph global install/init、managed exclude、routing injection 或 hook installation。Refresh-only 期间保留上一份 completed state，由 async/lifecycle facts 表达 in-flight，最终再原子发布新 state，避免并发 Git 事件被 active-state gate 丢弃。graphify-out/workspace-async-refresh.lock 只负责 event single-flight/coalesce/release handoff；.spec-first/workspace-graph-lifecycle.lock 独占所有后台 build、显式 build、clean 与 status writer，async setup child 只能校验 wrapper 继承的 token。显式 build/clean 抢锁失败时必须在 provider、图、routing、hook、state mutation 前返回 workspace-graph-lifecycle-busy；活 PID 但 start marker 无法确认时保持 busy，不按年龄抢占，successor release 会清理已失去 canonical ownership 的 quarantine residue。clean 删除 state 后，旧 hook/worker 会在 trigger 与获得 lifecycle lease 后复核 enablement 并停止。可恢复的 provider partial 允许下一次 Git 事件重试；需要 owner 确认、路由写入失败或 runtime/hook contract 漂移保持显式修复。status receipt 带 attempt_id，成功 build 只清除开始时观察到的 generation。与其他 provider mutation 相同，workspace build 在 selected child 的当前 host projection 缺失或过期时必须于 mutation 前阻断。hook 不可安全安装、非 Git 变化或需要即时刷新时，重新运行同一 --workspace-graph --repos ... 命令。不得把 watcher、hook marker、派发成功或最近一次 success receipt 表述成 workspace freshness 保证；消费侧仍以 source snapshot/status 为准。

仓集来源是 需求文件夹/.spec-first/workspace.yaml manifest 与 --repos <a,b> 的并集；manifest 先处理，同仓重复声明时保留 manifest alias/entry，CLI 只增补其他 confirmed 仓。自动发现仅作候选，需确认后才建。自动发现只扫描需求根的直接子目录；重复 alias 或嵌套仓根会返回 workspace-targets-ambiguous 并阻止 build/clean，必须先由 owner 消除歧义。

workspace.yaml 是为六宿主 projected runtime 保持零依赖的严格 YAML 子集，不是通用 YAML：支持顶层 schema_version、repos、exclusions，2 空格列表缩进、repos 下 4 空格的 path/可选 alias、普通或单/双引号字符串和行尾注释。禁止 tab、flow collection ([]/{})、anchor/tag、block scalar、多行值及未声明字段；不符合时返回 workspace-manifest-unparseable 或 workspace-manifest-schema-invalid，不得猜测或静默忽略。可用格式：

schema_version: workspace-manifest.v1
repos:
  - path: api # workspace-relative
  - path: 'web client'
    alias: web
exclusions:
  - vendor

相关 flag(同一 workspace-graph 域):

Machine contract:

--json 输出完整 envelope;自动化消费者必须同时读取 status、reason_code、pending_confirm[]、state/freshness 与 per-repo 字段,不能只检查文件存在或进程是否打印成功文本。显式 --workspace-graph-status 是只读诊断,即使对象 absent/partial 也可 exit 0,由 envelope 表达 readiness。

边界(per-需求 隔离):每个需求文件夹自成一体,不复用其它需求的图,不写机器级 global graph;projectPath 解析限定当前 workspace 根内;discovery 与所有 Git-metadata 写入均 symlink-contained;图输出是 advisory candidate,结论回子仓源码确认。删除需求文件夹即清空其图(无机器级残留)。

从当前 Git repo(非父 workspace)运行 --workspace-graph* 会被跳过(该能力面向非 Git 多仓父目录)。

Workflow

1. Identify the current host from the generated host-specific runtime surface invoking the unified spec-runtime-setup entrypoint.
2. If invoked from a non-Git parent workspace, resolve all discovered supported child repos by default; --repo <child> narrows the run. Writes must stay within each resolved child target.
3. 运行共置 Node 入口，使其加载 setup-registry.v9、校验 schema，并展开 effective host/platform registry。
4. 让 setup.cjs 按所选 mode 诊断或安装必需的 package-backed MCP tool；standard workflow 默认选择 registry required Provider，--only 只用于高级子集修复；host config 只能通过 registry target 写入，并记录结构化 execution facts。
5. 让同一 Node 入口验证 baseline helper 与 required Provider。agent-browser 保持 diagnostic/manual-command only，并通过 sibling spec-test-browser canonical wrapper 读取 capability facts；安装完整但 exact-origin execution blocked 时报告 degraded 而非重复安装，且不影响 baseline completion。ffmpeg、CodeGraph 与 Graphify 核心能力必须进入完整 setup completion。Provider first generation 与 project-local auto-refresh setup 只能通过静态 Provider module 与 bounded argv-array process runner 执行。若默认 project-root scope 中的 graphify extract . 失败，setup 可以先尝试 code-only graphify update .，再返回 failed readiness。若 Graphify 已安装但不在用户原始 PATH 中可见，报告 manual visibility action，不编辑 shell profile。Graphify hook 仅在有效 hooks root 位于项目内时允许 bounded repair；blocked/failed hook 记录 next_actions 与 manual-only limitation，不得标记 hook refresh 已验证，也不得单独把已通过的核心 Provider readiness 改为 degraded。
6. Run project-local config bootstrap where the selected mode authorizes it. Bare setup reports example/local/gitignore/legacy status；missing local override 记为 defaults-active。Explicit project-config actions may refresh the example, create the local override, and ensure ignore coverage. Do not auto-delete legacy project config or migrate legacy keys.
7. 使用 setup.cjs --verify-only 写入 readiness ledger、reconcile host pointer facts、写入 project setup facts，并渲染分组 status block。必须分别读取 generated_runtime_manifest.status 与 baseline_ready；baseline_ready=true 不能掩盖 stale generated runtime。状态为 stale 或 missing 时，使用符合 topology 的命令刷新 runtime：当前 repo 或 parent workspace runtime 使用 spec-first init -y，单个 child repo 使用 spec-first init --repo <child> -y，只有明确要批量刷新 child root 时才显式运行 spec-first init --all-repos -y；随后重新验证。若刚运行 spec-first update 后状态仍 stale，应将其视为 degraded refresh evidence，并展示相同 fallback 命令，不得报告 runtime freshness 为 ready。
8. Report the status exactly enough for the user to act: ready rows need no action; action-required rows name the missing dependency/config/target step; generated runtime manifest rows name the init refresh command when stale or missing.

Output Shape

The final setup output should contain:

• Execution result: separate Required MCP/helper dependencies and Generated runtime manifest rows; report baseline_ready as dependency readiness and generated_runtime_manifest.status as generated runtime freshness.
• MCP servers: required baseline MCP tool dependency/host/project readiness、CodeGraph host config readiness 和 next action；--only subset 必须显式标注 scope。
• Helper tools: helper install and readiness status.
• Provider tools: provider readiness status, derived readiness_scope / probe_status, and lifecycle display bits when present. Summaries must distinguish install/index readiness from server/query verification.
• Host configured dependencies: configured MCP/hooks/allowlist/setup/verification command facts.
• Install safety: helper install source, risk, review, and mirror provenance.
• Project local config: example config, local override, gitignore safety rule, legacy markdown config signal, and retired legacy local config status. Human labels and machine fields should be de-branded; active setup facts must use .spec-first local config paths and neutral legacy field names.
• Project setup facts: status for tool-facts.json and runtime-capabilities.json.
• Verification profile: current verification profile visibility placeholder; full profile execution is v1.13 scope.
• Next steps: either fix action-required rows, narrow to an explicit child repo when a single-repo retry is needed, continue to the user-intent workflow, or suggest spec-rule-miner as a separate follow-up after CodeGraph/Graphify readiness is prepared. This suggestion is advisory; setup must not treat rule-miner output as setup readiness and must not call spec-rule-miner automatically.

tool-facts.json records setup-owned tool and helper readiness:

{
  "schema_version": "tool-facts.v2",
  "tools": {},
  "helper_tools": {},
  "items": [],
  "configured_dependencies": [],
  "schema_capabilities": [
    "items",
    "configured_dependencies",
    "tool-existence",
    "provider-readiness-generic"
  ],
  "source": {
    "repo_status": "git-repo"
  }
}

runtime-capabilities.json should record direct evidence posture instead of provider capabilities:

{
  "schema_version": "runtime-capabilities.v1",
  "direct_evidence": {
    "bounded_source_reads": true,
    "ripgrep": true,
    "ast_grep": true,
    "git_diff": true,
    "tests_and_logs": true
  }
}

Boundaries

Setup does:

• verify Node/npm/npx and required helper dependencies;
• 按 setup-registry.json 配置 warm package-backed MCP server；
• write host MCP config through managed/user host targets;
• replace only an authorized conflicting managed MCP entry through --repair-host-config; bare full setup supplies this authorization for selected-target registry-managed drift, while explicit subset/repair calls require the flag, unrelated host config is preserved, and higher-precedence or unsafe targets remain blocked;
• write Kiro MCP config to workspace .kiro/settings/mcp.json by default, and to ~/.kiro/settings/mcp.json only after explicit user-scope opt-in;
• write Qoder MCP config to local .qoder/settings.local.json by default, and to ~/.qoder/settings.json only after explicit user-scope opt-in;
• write Cursor MCP config to project .cursor/mcp.json by default, and to ~/.cursor/mcp.json only after explicit user-scope opt-in;
• write project-local setup facts;
• refresh .spec-first/config.local.example.yaml, create .spec-first/config.local.yaml, and ensure .spec-first/*.local.yaml ignore coverage only through explicit project-local config bootstrap actions;
• report the legacy project markdown signal for manual review and the retired legacy local config status without migrating either;
• perform explicit provider-native first generation for approved providers when the target workspace is resolved, or verify Graphify install readiness withou

…(truncated)