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. 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 时，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 才能执行这些写入。

Kiro Host Pin

When this generated Kiro spec-runtime-setup runtime surface invokes .kiro/skills/spec-runtime-setup/scripts/*, set MCP_SETUP_HOST=kiro in the script environment. Do not rely on automatic host detection from PATH, because Claude Code, Codex, Cursor, Kiro, and Qoder CLIs can coexist on the same machine.

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。

Default Full Setup Flow

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

1. Resolve the project target. Use --repo <git-root> for an exact Git repository or --folder <project-folder> for an exact logical directory, including a fully non-Git project. With no flag, a pure non-Git directory becomes the folder target unless bounded child repos are discovered. An invalid nested --repo stops before plan, host, provider, or facts work; the same path is valid through --folder.
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-git-root> for a Git target or node "$SKILL_DIR/scripts/setup.cjs" --plan --folder <resolved-folder> for a folder 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。计划必须分别显示 absolute execution root、runtime projection root、Graphify input scope 和 absolute artifact root；input scope 变窄或 runtime 复用都不改变 artifact ownership。
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：Git 目标使用 --repo <resolved-git-root>，folder 目标使用 --folder <resolved-folder>；默认 parent-workspace batch 则从 parent 运行且不带 target flag，由 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 消费 setup 返回的结构化 runtime init action：当前 repo/folder/parent 使用 action 自带的 projection cwd，单个 child 或 all-repos 使用 workspace verify 返回的对应 argv；交互式 action 不带 -y，headless action 必须显式提供 developer name 与 language。不得把 cwd/path 拼成 shell compound command；随后重新验证。若刚运行 spec-first update 后状态仍 stale，应将其视为 degraded refresh evidence，并展示相同 fallback action，不得报告 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 con

…(truncated)