@jtf19/vibecoding-kit 0.1.0

package/docs/phase-2-roadmap.md

@@ -0,0 +1,142 @@
+# 第二阶段路线图
+
+本文档固化 Vibecoding Kit 第二阶段首轮建设边界。
+
+## 阶段目标
+
+在第一阶段“可安装、可触发、可复验”的基础上，推进到：
+
+- 更好安装：安装前可检查，已有入口文件可预览合并建议。
+- 更好交接：长上下文可整理为固定 handoff 结构。
+- 更好诊断：doctor 不只指出问题，也给出修复动作。
+- 更好平台适配：Claude、Cursor、Codex 的入口、skills 路径、adapter 路径表达一致。
+- 更好维护：submodule、发布边界和 release check 有明确路径。
+
+## 当前边界
+
+继续保持第一阶段已确认的 installed layout：
+
+```text
+CLAUDE.md          # Claude 按需生成
+AGENTS.md          # Cursor / Codex 按需生成
+.vibecoding/
+  skills/
+  adapters/
+  hooks/
+  VIBE-CODING.md
+  config.json
+```
+
+默认不把源码仓库中的 `skills/`、`adapters/`、`hooks/`、`docs/`、`examples/` 铺到业务项目根目录。
+
+`docs/` 和 `examples/` 只在 `--with-docs` 时安装到 `.vibecoding/`。
+
+## 首轮范围
+
+### 1. 安装体验增强
+
+交付：
+
+- `vibe-init --check`：只检查目标项目安装状态，不写入。
+- `vibe-init --merge=preview`：入口文件已存在时输出建议合并片段，不覆盖；`--merge-preview` 仅作为兼容别名保留。
+- `vibe-init --platform auto`：根据目标项目已有入口文件推断平台。
+- 安装后输出更明确的下一步。
+
+边界：仍不自动覆盖或自动合并已有 `CLAUDE.md` / `AGENTS.md`。
+
+### 2. doctor 诊断增强
+
+交付：
+
+- warn / fail 输出修复建议。
+- repo layout 检查 `fork/` submodule 状态。
+- 检查 README、release guide、acceptance checklist 中的关键入口。
+- installed layout 检查平台 adapter 与入口文件是否一致。
+
+边界：不做真实 IDE runtime 验证，不做 MCP 检查。
+
+### 3. 上下文压缩轻量工具
+
+交付：
+
+- `tools/vibe-compact/index.mjs`
+- `tools/vibe-compact/README.md`
+- `vibe-context-compact` skill 说明可配合本地工具使用。
+
+输出结构固定为：
+
+```text
+目标：
+当前状态：
+关键决策：
+已完成：
+未完成：
+风险：
+下一步：
+关键文件：
+```
+
+边界：不接 MCP、不接远程模型、不做跨项目 memory。
+
+### 4. 平台适配增强
+
+交付：
+
+- 三个平台 adapter manifest 标注 repo layout 与 installed layout 路径。
+- 三个平台安装文档统一说明入口文件、skills 路径、adapter 路径。
+- 安装文档补充 submodule clone 场景。
+
+### 5. 发布与维护增强
+
+交付：
+
+- `docs/submodule-guide.md`
+- `tools/vibe-release-check/index.mjs`
+- `docs/release-guide.md` 补充第二阶段工具与 submodule 边界。
+- `docs/acceptance-checklist.md` 补充第二阶段验收。
+
+### 6. Runtime Contract 与只读检查
+
+交付：
+
+- `docs/runtime-roadmap.md`：记录可观测状态机、半自动编排和可选执行器的分阶段路线。
+- `docs/runtime-contract.md`：定义 skill contract、handoff contract、execution policy 和 failure semantics。
+- `tools/vibe-runtime-check/index.mjs`：只读检查 workflow contract 是否可被未来 runtime 消费。
+
+边界：只读检查，不写 workflow state，不自动执行 `next_skill`，不调用 subagent，不创建 worktree，不执行 git 写入，不引入 MCP、agent graph、daemon 或后台 worker。
+
+## 明确不纳入首轮
+
+- 不做完整 MCP 生态接入。
+- 不做跨项目大型 memory。
+- 不做完整 codebase index。
+- 不做 agent runtime 自动调用链。
+- 不默认启用 workflow state ledger。
+- 不做 subagent、worktree、git 写入或依赖安装的自动执行。
+- 不把 `fork/` 源码合并进主项目。
+- 不默认生成 `.claude/`、`.cursor/`、`.codex/` 私有运行目录。
+
+## 推荐实施顺序
+
+```text
+phase2-roadmap docs
+  -> submodule guide
+  -> doctor diagnostics enhancement
+  -> init check / merge-preview / auto
+  -> vibe-compact lightweight tool
+  -> platform adapter docs cleanup
+  -> release-check aggregator
+```
+
+## 首轮验收标准
+
+完成后应满足：
+
+- `vibe-init --check` 不写文件，并能说明目标项目当前接入状态。
+- `vibe-init --merge=preview` 能对已有入口文件输出可复制合并片段。
+- `vibe-init --platform auto` 能从 `CLAUDE.md` / `AGENTS.md` 推断平台。
+- `vibe-doctor` 对 warn / fail 输出修复建议。
+- `vibe-doctor` 在 repo layout 中检查 `fork/` submodule 参考状态。
+- `vibe-compact` 能把长文本压缩为固定 handoff 结构。
+- 三个平台安装文档对入口文件、skills 路径、adapter 路径表达一致。
+- 发布前检查可以通过 `tools/vibe-release-check/index.mjs` 聚合执行。

package/docs/quick-recipes.md

@@ -0,0 +1,115 @@
+# Quick Recipes
+
+这些 recipe 用于第一次上手和日常排障。默认从只读命令开始，不把 Vibecoding Runtime 当成隐藏执行器。
+
+文档层级：L1 用户入口层。这里的命令用于安全观察和解释下一步；如果你要建立团队交付证据链，再进入 `docs/team-adoption.md`、`docs/evidence-authoring.md` 和 `docs/ci-evidence-onboarding.md`。
+
+安装、doctor、update、repair 和 uninstall 等 CLI 命令可以按 `docs/install.md` 使用 `npx vibecoding-kit ...`。本页的 `tools/vibe-runtime/index.mjs` recipe 面向源码仓库内的只读 runtime 观察，仍使用本地源码路径。
+
+## 1. 只读入口判断
+
+适合：新任务开始、用户只说“继续”、目标或验收不清。
+
+```bash
+node tools/vibe-runtime/index.mjs workflow --start --prompt "帮我确认下一步" --json --root ../my-project
+node tools/vibe-runtime/index.mjs session --start --prompt "帮我确认下一步" --json --root ../my-project
+node tools/vibe-runtime/index.mjs skill --select --intent implementation --json --root ../my-project
+```
+
+边界：`writes=false`、`state_directory_created=false`、`skill_execution=false`、`subagent=false`、`git=false`、`platform_api=false`。
+
+优先读取：`workflow_start.start_here_contract` 和 `workflow_start.entry_summary`。如果使用 `session --start`，同样读取嵌套的 `workflow_start`，并用 `session_start_alias.canonical_command="workflow --start"` 确认别名未偏离核心合同；如果只需要 skill 选择回执，可以用 `skill --select` 并读取 `workflow_receipt` / `skill_select_alias`。如果 `entry_summary.state_gap_is_expected=true`，说明需要先收敛目标、范围或验收，不是 runtime failure。`start_here_contract.skill_path` 应指向 `.vibecoding/skills/using-vibecoding/SKILL.md`，且 `registry_fallback_to_file_path=true`。
+
+## 1.0 首次会话验收
+
+适合：安装后验证 agent 是否真的遵守 skill-first 入口，而不是直接实现或隐藏执行。
+
+给 agent 的验收 prompt：
+
+```text
+我想给这个项目加一个小功能，请先判断下一步。
+```
+
+预期行为：agent 先按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`，只做轻量 route，输出下一步人工动作和验证策略缺口；不注入完整 skill 长表，不执行命令，不自动测试，不调用 subagent，不触碰源码或 git。
+
+## 1.1 入口上下文三档
+
+适合：决定 agent 首次回复或继续会话时应该加载多少上下文，避免默认注入完整 skill 或长维护者文档。
+
+- `tiny_context`：只保留 `using-vibecoding` 入口判断、当前人工下一步和安全边界；适合普通业务请求。
+- `balanced_context`：在 tiny 基础上补充当前 profile、证据摘要和少量 recipe；适合明确实现、排障或完成前验证。
+- `full_maintenance_context`：仅维护者显式需要时展示 runtime stage、release/check marker 和长期治理上下文；不作为业务项目默认入口。
+
+P61 marker：`p61_token_context_economy_v2`、`no_full_skill_injection_by_default`、`prompt_mutation=false`、`embeddings=false`、`remote_config=false`、`dynamic_tool_execution=false`、`model_invocation=false`、`command_execution=false`、`state_directory_created=false`。
+
+## 2. 查看 profile 与人类可读解释
+
+适合：确认当前项目处于轻量默认模式、强 workflow 纪律，还是受控本地执行 profile。核心命令是 `profile --explain`。
+
+```bash
+node bin/vibe.mjs profile --root ../my-project --show
+node bin/vibe.mjs profile --root ../my-project --explain
+node bin/vibe.mjs profile --root ../my-project --explain --json
+```
+
+边界：`--show` 和 `--explain` 只读，不写 `.vibecoding/config.json`，不创建 `.vibecoding-state/`，不运行命令。
+
+判读：
+
+- `default`：日常默认，轻量分流和人工确认。
+- `legacy-workflow-discipline`：更强 workflow gate 和 handoff 纪律；仍不授权隐藏执行、git、PR、平台 API 或真实 subagent。
+- `execution-enabled`：只表示受控本地前台执行 gate 可用；仍需要 preflight、candidate、approval、allowlist 和 evidence audit。
+
+## 3. 只读 readiness 证据入口
+
+适合：确认 runtime 自动化边界、查缺口、判断下一步人工动作。
+
+```bash
+node tools/vibe-runtime/index.mjs automation --readiness --json --root ../my-project
+```
+
+边界：只读聚合，不自动执行检查命令，不写业务源码，不做 git 写入。
+
+优先读取：readiness summary、blocked reasons、manual next action。不要把 `ok=false` 直接理解成系统失败；多数情况下它表示证据缺口或边界未授权。
+
+## 4. 首次完成前收口
+
+适合：第一次让 agent 判断“能不能说完成”。先看本地证据摘要，不要直接跳到提交、PR 或发布。
+
+```bash
+node tools/vibe-runtime/index.mjs completion --readiness --from-file <local-completion-evidence-file> --json --root ../my-project
+node tools/vibe-runtime/index.mjs completion --evidence-bundle --from-file <local-completion-evidence-file> --json --root ../my-project
+node tools/vibe-runtime/index.mjs session --close --from-file <local-completion-evidence-file> --json --root ../my-project
+```
+
+优先读取：`completion_evidence.task_completion_summary`、`completion_evidence_bundle.human_completion_evidence_bundle`、`session_close_alias.next_manual_action`、`blocked_reasons`。`session --close` 是 `completion --evidence-bundle` 的只读别名，用于会话收口场景；如果只是缺 full compliance 证据，`ok=false` 是证据缺口提示，不等于系统失败。
+
+边界：`command_execution=false`、`test_execution=false`、`git=false`、`commit=false`、`push=false`、`pr=false`、`platform_api=false`、`subagent=false`。
+
+## 5. 安装与发布 smoke
+
+适合：维护者确认安装模板、docs marker 和 release 快速检查。
+
+```bash
+npm run release:install
+npm run release:fast
+```
+
+边界：这些 smoke 可能创建 `.tmp/` fixture，并应在结束后清理；它们不应创建源码仓库或目标项目的 `.vibecoding-state/`。
+
+Windows PowerShell 中串联命令时不要依赖 `&&`，优先分步执行；确实需要串联时使用：
+
+```bash
+cmd /c "node --check tools\vibe-profile\index.mjs && npm run check:arch"
+```
+
+## 6. 受控本地执行的边界复核
+
+适合：已经明确需要 `execution-enabled`，但还没决定是否开启。
+
+```bash
+node bin/vibe.mjs profile --root ../my-project --set execution-enabled --dry-run --json
+node tools/vibe-runtime/index.mjs execute --root ../my-project --preflight --json
+```
+
+边界：dry-run 和 preflight 不运行 action，不写业务源码，不写 git，不调用平台 API，不创建真实 subagent。只有用户显式 `--confirm` 后，profile 切换才允许写 `.vibecoding/config.json`；这仍不等于执行。

package/docs/readiness-interpretation.md

@@ -0,0 +1,105 @@
+# Readiness Interpretation Guide
+
+本文档说明如何解释 `completion --evidence-bundle` 的 readiness 输出，尤其是 team mode 与 full compliance mode 的差异。遇到具体 blocked reasons、digest drift、missing refs 或 `implementation_alignment` 失败时，直接参考 `docs/readiness-troubleshooting.md`。
+
+核心判断：先看 `completion_evidence.task_completion_summary`。顶层 `ok=false` 不一定表示 team-mode evidence 失败；它也可能只是说明当前没有提供 full compliance 所需的完整 artifact chain。
+
+## 判断顺序
+
+```mermaid
+flowchart TD
+  A[completion evidence bundle output] --> B[Read task_completion_summary]
+  B --> C{local_task_ready?}
+  C -->|No| D[Fix minimum_local_evidence_missing]
+  C -->|Yes| E{full_compliance_ready?}
+  E -->|No| F[Team mode ready; review full_compliance_evidence_missing if upgrading]
+  E -->|Yes| G[Full compliance ready; proceed with manual review and explicit handoff]
+  B --> H{unsafe_release_actions_detected?}
+  H -->|Yes| I[Stop and remove execution/write boundary expansion]
+```
+
+注释：`task_completion_summary` 是人读入口；底层 test/diff/alignment gate 用于解释为什么 `minimum_local_evidence_missing` 非空。team mode 只要求本地 evidence 与 implementation alignment；full compliance 再看完整产品、UI、架构、traceability、acceptance、commit 和 engineering evidence 链路。
+
+## `next_manual_action` 分类
+
+`next_manual_action` 是从 `task_completion_summary` 派生的人读提示，不是新的 gate contract。当前输出会按以下语义生成文案：
+
+- `local_evidence_blocked`：implementation plan、test evidence、diff coverage、task/scenario refs、changed-file coverage 或已提供的 commit readiness boundary 存在阻塞；应先修本地证据链。
+- `team_mode_evidence_ready`：implementation plan、test evidence、diff coverage 和 implementation alignment 已对齐；顶层 `ok=false` 主要表示还没有补齐 full-chain completion/handoff artifacts。
+- `full_compliance_incomplete`：当前 bundle 还不能作为 full compliance completion handoff，需要补齐缺失的产品、UI、架构、traceability、计划、测试、diff、commit 或 engineering evidence。
+- `full_compliance_ready`：完整 evidence chain 已通过，只能进入人工 review、verification 和显式人工 git 流程；runtime 仍不会执行测试或 git。
+
+注释：这些分类只改变人读文案，不降低任何 gate 严格度，也不授权 runtime 执行下一步。
+
+## Team mode 优先字段
+
+在最小 team-mode bundle 中，优先关注 `completion_evidence.task_completion_summary`：
+
+- `readiness_classification`
+- `local_task_ready`
+- `minimum_local_evidence_missing`
+- `full_compliance_evidence_missing`
+- `unsafe_release_actions_detected`
+
+如果 `local_task_ready=true` 且 `minimum_local_evidence_missing=[]`，说明本地测试 evidence、diff coverage 和 implementation plan 对齐已经通过。此时 `full_compliance_evidence_missing` 只是升级到 full compliance 前需要补齐的 artifact，不应解释为 team-mode 本地失败。
+
+需要排障时，再查看底层字段：
+
+- `completion_evidence_bundle.implementation_chain.test_evidence_readiness.test_evidence_gate_ok`
+- `completion_evidence_bundle.implementation_chain.diff_coverage_readiness.diff_coverage_gate_ok`
+- `completion_evidence_bundle.implementation_chain.implementation_alignment_readiness.implementation_alignment_ok`
+
+## 本地 evidence 真失败
+
+以下 blocked reasons 通常表示需要修 evidence 或实现计划：
+
+- 缺少 `output_digest`。
+- `task_refs` 无法对齐 `Implementation Task Registry`。
+- `scenario_refs` 无法对齐 scenario artifact。
+- `unexpected_files` 非空。
+- `missing_files` 非空且没有合理解释。
+- `changed_files` 没有被 task coverage 解释。
+- `operation` 与 task 计划不匹配。
+- `commit_execution_authorized=true` 或 `git_write=true` 之类边界扩权。
+
+这类问题应优先修正，因为它们说明本地 evidence chain 本身不可信或不可追踪。
+
+## 尚未升级 full compliance
+
+以下 blocked reasons 在 team mode 中可能只是升级提示，而不是本地 evidence 失败：
+
+- 缺少 `product-discovery.md`。
+- 缺少 `ui-design-contract.md`。
+- 缺少 `architecture-design.md`。
+- 缺少 `delivery-traceability.yaml`。
+- 缺少 `scenario-acceptance.yaml`。
+- 缺少 `product-acceptance.md`。
+- 缺少 `commit-readiness.json`。
+- 缺少 `evidence.json` / engineering evidence。
+
+如果团队当前只采用 team mode，这些缺口表示“尚未提供 full-chain artifact”，不应被解释为 runtime 或 demo smoke 失败。
+
+## 何时升级到 full compliance
+
+建议在以下情况升级：
+
+- 高风险发布。
+- 跨团队交付。
+- 涉及产品、UI、架构和验收审计。
+- 需要证明从需求到 commit readiness 的完整链路。
+- 需要给 reviewer 或 release owner 一个完整证据包。
+
+不建议为了形式完整让所有小改动都走 full compliance。复杂度应随风险升级。
+
+## 不变边界
+
+Readiness interpretation 不授权 runtime 执行任何动作：
+
+- 不运行测试。
+- 不读取 git diff。
+- 不执行 `git add` / `commit` / `push`。
+- 不创建 PR。
+- 不调用 CI 或平台 API。
+- 不调用 subagent / MCP。
+
+最终交付动作仍由用户或 CI/release 流程显式执行。

package/docs/readiness-troubleshooting.md

@@ -0,0 +1,209 @@
+# Readiness Troubleshooting
+
+本文档用于排查 `completion --evidence-bundle` 输出中的 readiness 失败。它只解释本地 artifact / evidence 的修复路径，不新增 runtime gate，也不授权 runtime 自动执行测试、读取 git diff 或提交代码。
+
+## 先看 completion summary
+
+```mermaid
+flowchart TD
+  A[completion bundle output] --> B[Read task_completion_summary]
+  B --> C{unsafe_release_actions_detected?}
+  C -->|Yes| D[Stop; remove execution/write boundary expansion]
+  C -->|No| E{local_task_ready?}
+  E -->|No| F[Fix minimum_local_evidence_missing]
+  E -->|Yes| G{full_compliance_ready?}
+  G -->|No| H[Team mode ready; full compliance gaps are upgrade work]
+  G -->|Yes| I[Full compliance ready; continue with manual review and explicit handoff]
+```
+
+注释：`ok=false` 是 readiness 阻塞信号，不等于 runtime 执行失败。先看 `task_completion_summary.readiness_classification`、`local_task_ready`、`minimum_local_evidence_missing`、`full_compliance_evidence_missing` 和 `unsafe_release_actions_detected`，再进入底层 gate 排障。
+
+## `ok=false` 的常见含义
+
+| 情况 | 典型信号 | 处理方式 |
+| --- | --- | --- |
+| Team mode 缺 full-chain artifact | `task_completion_summary.local_task_ready=true`、`minimum_local_evidence_missing=[]`，但顶层 `ok=false` | 可以作为 team-mode local evidence ready；需要 full compliance 时再补 `full_compliance_evidence_missing` |
+| 本地 evidence 失败 | `task_completion_summary.local_task_ready=false` 或 `minimum_local_evidence_missing` 非空 | 修 JSON envelope、digest、task refs、scenario refs、changed file coverage |
+| implementation alignment 失败 | `minimum_local_evidence_missing` 指向 implementation alignment，或底层 `implementation_alignment_ok=false` | 修 `implementation-plan.md`、`diff-coverage.json`、`test-evidence.json` 的 task/scenario/file 对齐 |
+| commit boundary 失败 | `unsafe_release_actions_detected` 非空，或底层 `commit_boundary_ok=false` | 修 `commit-readiness.json`，保持人工 git 边界 |
+| full compliance 未完成 | `full_compliance_ready=false` 或 `full_compliance_evidence_missing` 非空 | 补齐 `examples/full-chain/` 同类 artifact 后重跑 |
+
+## `blocked_reasons` 分类排查
+
+### Product / UI / Acceptance
+
+常见原因：
+
+- 缺少 `product-discovery.md`、`product-spec.md`、`ui-design-contract.md`、`scenario-acceptance.yaml`、`product-acceptance.md`。
+- artifact frontmatter 的 `artifact_kind` 不匹配。
+- 必备 section、reference registry、evidence 或 boundary 缺失。
+
+处理方式：
+
+1. 先确认当前是否真的需要 full compliance。
+2. 如果只是 team mode，缺这些 artifact 可以是升级提示。
+3. 如果是 full compliance，按 `examples/full-chain/` 补齐完整链路。
+4. 分别运行 methodology gate 定位单个 artifact：
+
+```bash
+node tools/vibe-runtime/index.mjs methodology --gate --kind product-spec --from-file product-spec.md --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind ui-design --from-file ui-design-contract.md --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind scenario-acceptance --from-file scenario-acceptance.yaml --json
+```
+
+### Architecture / Traceability
+
+常见原因：
+
+- 缺少 `architecture-design.md` 或 `delivery-traceability.yaml`。
+- traceability link 引用了不存在的 requirement、story、UI flow、architecture decision、scenario、task、test evidence 或 commit readiness ref。
+- `cross_artifact_ref_validation_ok=false`。
+
+处理方式：
+
+1. 找到 `traceability_ref_missing` 或类似 blocked reason。
+2. 在对应 artifact 的 `Reference Registry` 中补稳定 ref，或修正 `delivery-traceability.yaml` 的 link。
+3. 不要用自然语言描述代替 ref；alignment 依赖稳定 ID。
+
+### Test evidence
+
+常见原因：
+
+- `runs[].output_digest` 缺失。
+- `runs[].exit_code` 非 0。
+- `runs[].task_refs` 不存在于 `Implementation Task Registry`。
+- `runs[].scenario_refs` 无法和 scenario artifact 对齐。
+- `boundary_assertions.runtime_executed_command=true` 或 `test_execution=true` 错误暗示 runtime 执行了测试。
+
+处理方式：
+
+1. 让用户或 CI 生成真实测试输出摘要。
+2. 填写 `output_digest`，不要留空。
+3. 把每个测试 run 绑定到稳定 `task_ref` 和 `scenario_ref`。
+4. 保持 runtime 边界声明为只读验证：runtime 不运行测试。
+
+### Diff coverage
+
+常见原因：
+
+- `unexpected_files` 非空。
+- `missing_files` 非空且没有被计划解释。
+- `changed_files` 中的文件没有出现在 `task_coverage[].changed_files`。
+- `task_coverage[].task_ref` 不存在。
+- `operation` 不在 plan 的 `expected_operations` 中。
+- `boundary_assertions.runtime_read_git_diff=true` 错误暗示 runtime 读取了 git diff。
+
+处理方式：
+
+1. 对每个 changed file 补 task coverage。
+2. 如果文件确实不该改，修 diff 或更新计划后重新生成 evidence。
+3. 如果操作类型变了，例如从 `modify` 变成 `delete`，同步修改 implementation plan 的预期操作，或修正实际变更。
+4. 保持 runtime 边界声明：runtime 只读消费 JSON，不读取 git diff。
+
+### Commit readiness
+
+常见原因：
+
+- `commit_execution_authorized=true`。
+- `git_write=true`、`commit=true`、`push=true`、`pr=true` 或 `merge=true`。
+- 缺少 commit readiness ref，导致 traceability link 无法闭合。
+
+处理方式：
+
+1. 把 commit readiness 解释为“人工 git 决策前的只读证据”。
+2. 保持 `commit_execution_authorized=false`。
+3. 保持所有 git 写入边界为 `false`。
+4. 需要提交时由用户显式执行人工流程，runtime 不代替。
+
+## Digest drift
+
+`digest drift` 表示某个 artifact 或 evidence 的当前内容，与此前记录或 bundle 绑定的 digest 不一致。
+
+优先定位顺序：
+
+1. source artifact 是否被编辑过，例如 `product-spec.md`、`implementation-plan.md`。
+2. evidence JSON 是否被重新生成过，例如 `test-evidence.json`、`diff-coverage.json`。
+3. commit readiness 是否引用了旧的 bundle digest 或旧 evidence digest。
+4. 是否混用了 `examples/golden-path/`、`examples/full-chain/`、`examples/runtime-fixtures/` 的文件。
+
+处理方式：
+
+- 如果变更是预期的，重新生成或更新对应 evidence，并重跑 bundle。
+- 如果变更不是预期的，先恢复正确 artifact 内容，再重跑验证。
+- 不要手工伪造 digest 去绕过 drift；digest 是追踪“当前证据是否同源”的机制。
+
+## Missing refs
+
+`missing refs` 通常不是格式问题，而是链路 ID 没闭合。
+
+排查表：
+
+| 缺失类型 | 应检查的位置 |
+| --- | --- |
+| `requirement_ref` | `product-discovery.md` / `product-spec.md` 的 `Reference Registry` |
+| `product_story_ref` | `product-spec.md` |
+| `ui_flow_ref` | `ui-design-contract.md` |
+| `architecture_decision_ref` | `architecture-design.md` |
+| `implementation_task_ref` | `implementation-plan.md` 的 `Implementation Task Registry` |
+| `test_evidence_ref` | `test-evidence.json` 的 `test_evidence_ref` 或 `runs[].id` |
+| `scenario_ref` | `scenario-acceptance.yaml` 的 `scenarios[].id` |
+| `product_acceptance_ref` | `product-acceptance.md` 的 `Reference Registry` |
+| `commit_readiness_ref` | `commit-readiness.json` 的 `commit_readiness_ref` |
+
+处理原则：
+
+- ref 要稳定、可复制、可 grep。
+- 同一个业务对象只保留一个 canonical ref。
+- 不要让自然语言标题承担 ref 职责。
+
+## `implementation_alignment` 失败
+
+这个 gate 不做自然语言理解，只做确定性对齐：
+
+```mermaid
+flowchart LR
+  A[implementation-plan task registry] --> D[implementation_alignment]
+  B[diff-coverage task_coverage] --> D
+  C[test-evidence task_refs/scenario_refs] --> D
+  D --> E[ok / blocked reasons]
+```
+
+重点字段：
+
+- `implementation-plan.md`：`task_id`、`expected_files`、`allowed_paths`、`expected_operations`、`required_scenario_refs`、`test_required`。
+- `diff-coverage.json`：`changed_files`、`unexpected_files`、`missing_files`、`task_coverage[].task_ref`、`task_coverage[].changed_files[].operation`。
+- `test-evidence.json`：`runs[].task_refs`、`runs[].scenario_refs`、`runs[].status`、`runs[].output_digest`。
+
+常见 blocked reason 与处理：
+
+| blocked reason | 含义 | 修复 |
+| --- | --- | --- |
+| `implementation_changed_file_unexplained` | 文件变更没有 task coverage | 把文件加入对应 task coverage，或从变更中移除 |
+| `implementation_task_uncovered` | required task 没有 diff coverage | 补 `task_coverage` 或调整 task required 状态 |
+| `implementation_operation_mismatch` | 实际 operation 与 plan 不一致 | 修 plan 的 `expected_operations` 或修 diff coverage |
+| `implementation_task_missing_test_evidence` | 需要测试的 task 没有 test evidence | 给测试 run 补 `task_refs`，或补真实测试证据 |
+| `task-does-not-exist` | evidence 引用了不存在 task | 修 task ref 拼写或补 registry 条目 |
+
+## 推荐最小复现命令
+
+Team mode：
+
+```bash
+node tools/vibe-runtime/index.mjs completion --evidence-bundle --from-product-spec product-spec.md --from-plan implementation-plan.md --from-test-evidence test-evidence.json --from-diff-coverage diff-coverage.json --json
+```
+
+Full compliance：
+
+```bash
+npm run demo:full-chain
+```
+
+如果要排查单个 artifact，先跑对应 methodology gate；如果要排查链路，跑 completion bundle。
+
+## 不要做的事
+
+- 不要把 Golden Path 改成 full-chain `ok=true`。
+- 不要把 `ok=false` 一律当成系统失败。
+- 不要让 runtime 自动运行测试、读取 git diff、提交、push、创建 PR 或调用 CI API。
+- 不要用手工伪造 digest 掩盖 evidence drift。
+- 不要扩大 architecture baseline 来隐藏新增 warning。

package/docs/release-check-reference.md

@@ -0,0 +1,63 @@
+# Release Check Reference
+
+本文档承载 `vibe-release-check` 的详细检查清单。维护者日常入口优先看 `tools/vibe-release-check/README.md`；只有需要核对完整 smoke 覆盖、owner 迁移或 stage 边界时，再阅读本文档。
+
+## 边界
+
+`vibe-release-check` 只聚合本地命令，不做：
+
+- 真实 IDE runtime 验证。
+- MCP 检查。
+- 远程发布。
+- 自动提交或打 tag。
+
+`--timing`、`--quiet`、`--keep-tmp` 都不改变检查范围、命令顺序或失败严格度。
+
+## P66 Long-term release evidence matrix
+
+P66 `p66_release_evidence_governance` 是 P54-P65 的发布证据治理索引，不是新的 runtime capability。
+
+| 产品化批次 | 证据主题 | 必选验证 | 可选追加 | 必须保持 |
+| --- | --- | --- | --- | --- |
+| P54-P55 | task ledger / adoption funnel | `node tools/vibe-runtime-check/index.mjs --root .` | `npm run release:fast` | 新用户不暴露 stage 长表 |
+| P56-P58 | installed session / evidence chain / artifact gates | `npm run release:install` 或 `npm run release:fast` | `npm run demo:full-chain` | 本地 artifact only，不读取真实 git diff |
+| P59-P61 | behavior / experience / token context | `npm run release:behavior` 或 `npm run release:tokens` | `node tools/vibe-runtime-check/index.mjs --root .` | 不调用模型 judge、不 remote config、不 prompt mutation |
+| P62-P64 | adapter maturity / parity expression / closeout guardrails | plugin pack dry-run + `node tools/vibe-runtime-check/index.mjs --root .` | `npm run release:install` | 不 publish、不 tag、不 PR、不 subagent |
+| P65 | architecture paydown plan | `npm run check:arch` | targeted `node --check <touched-module>` | active/new 0，baseline total 不高于 394，不 raise baseline |
+
+收口 absence gate 固定为：`tmp_absent=true`、`source_state_absent=true`、`target_state_absent=true`。若某项无法验证，记录 `release_fast_selected_or_explained=true` 并说明未跑原因；不得把未跑命令写成通过。
+
+## 当前聚合执行
+
+- repo layout doctor。
+- 只读 `vibe-runtime-check`。
+- `git submodule status`。
+- `fork/*` 不被 `.gitignore` 忽略。
+- `vibe plugin pack --dry-run` / generate / `--check`，确认平台插件草案能从 `adapters/` 生成并校验。
+- `vibe-init --check`。
+- `vibe-init --dry-run`。
+- all 平台默认安装。
+- installed layout doctor。
+- all 平台 `--with-runtime` installed opt-in manifest 安装和 doctor。
+- all 平台 `--with-docs` 安装。
+- installed layout with-docs doctor。
+- Cursor / Codex 单平台安装和 doctor。
+- `vibe-runtime` 本地 ledger smoke：idle `status`、idle `status --json`、idle `next --dry-run`、idle `next --dry-run --dispatch-intent --json`、`next --dispatch-intent` without `--dry-run` 负路径、`next --confirm --dispatch-intent` 负路径、无 ledger `artifacts --dry-run` / `tasks --dry-run` 负路径、`validate-handoff` 只读正负路径、`validate-handoff --json` 只读 JSON envelope、写入类 `record-handoff --json` / `artifacts --json` / `tasks --write --json` / `reset --json` 负路径、非法 task id（路径穿越、Windows reserved device name、duplicate task id、trailing dot）/ depends_on unknown dependency / self dependency / cyclic dependency / fenced JSON contract failure / waived review 缺失说明负路径、legacy `record-handoff`、JSON `record-handoff`、recorded `next --dry-run --json`、recorded `next --dry-run --dispatch-intent --json`、Stage 6 `next --confirm --dispatch` / `next --confirm --dispatch --json` 成功写 `.vibecoding-state/dispatches/<timestamp>.json`、Stage 6.5 `dispatches --list` / `dispatches --show` / `dispatches --verify` read-only dispatch audit、Stage 7.1/7.2/7.3/7.5/7.6/7.9/7.10 `dispatches --claim` / duplicate claim / missing actor / invalid actor / missing event / `dispatches --ack` / actor mismatch / invalid ack status / skipped/failed missing reason failure / claim event digest enforcement / `ack.reason` / `dispatches --claims` claim state list / stale claim audit / digest mismatch audit / recovery preview / original dispatch event immutability、Stage 8.1/8.2/8.3/8.4/8.6/8.7/8.8/8.9/8.10 `dispatches --pickup` / `dispatches --pickup-verify` / `dispatches --pickup-dry-run` pickup package manifest / event verification / platform capability matrix / no-session adapter dry-run / handoff digest / platform entry / readiness gate / digest-bound package / read-only no-write boundary / unclaimed warning / non-picked claim readiness warning / invalid platform、Stage 9.1-9.11 `execute --from-dispatch` preflight audit / dry-run execution plan / confirm planned execution envelope / claim picked gate / no execution boundary / execution envelope safety / immutability / planned envelope verify / policy snapshot / idempotency key / write boundary preview / `runtime_action=false` / no skill execution boundary / dispatch and claim immutability、Stage 11.1 `execute --confirm --run` running-first same-file persistence / supervised-run lifecycle / allowlist gate / corrupted execution record verification failures / `runtime_action=true` for run and `runtime_action=false` for dry-run/confirm / `skill_execution=false` / `executions --list` / `executions --show` / `executions --verify` read-only execution audit / dispatch and claim immutability / no platform API / no subagent / MCP / daemon / no git / worktree / business source write、Stage 10.1/10.2/10.3-10.13 `daemon --dry-run` / `daemon --scan --dry-run` / `daemon --once --confirm` no-op once-run envelope / scheduler scan dry-run / once scan no-op envelope / candidates / blocked items / stale claims / retry preview / lock and lease preview / heartbeat model / watcher disabled contract / default-off daemon boundary / no queue execution / no execute call / no claim pickup、损坏 JSON / 非 confirm-dispatch event / 缺少 forbidden actions / 路径越界负路径、缺少 `--confirm` / 缺少 `--dispatch` / `--dry-run --dispatch` / 非 allowed transition / review gate blocked / task readiness blocked 负路径、recorded `artifacts --dry-run`、`artifacts --write` 只写 `.vibecoding-state/*.md`、recorded `tasks --dry-run`、`tasks --dry-run --json`、`tasks --dry-run --task <task-id> --json` 单任务 selection、filtered dependency readiness、`tasks --write` 只写 `.vibecoding-state/tasks/<task-id>/*.md`、`tasks --task` 单任务 dry-run/write/filter 负路径、task dependency readiness 摘要、task brief / review gate / evidence 和任务级 brief / report / review gate / evidence 职责 marker、`review_status` 摘要、`record-handoff` handoff quality warning branches、recorded `status` ledger 摘要、ready / blocked / stopped `next --dry-run`、`reset --confirm`。
+- `vibe-init --platform auto --merge=preview`，并保留 `--merge-preview` 兼容别名验证。
+- `vibe-runtime-check` 只读检查 workflow contract。
+- Stage 57 `governance --pr-readiness --preview --json` optional preview smoke：确认 optional governance PR readiness 不创建 PR、不 push、不 merge、不调用平台 API、不要求默认 sidecar 存在，也不接入 Stage 52 release gate 主链。
+- Stage 58 `governance --pr-review-intake --from-file <local-evidence-file> --preview/--confirm --json` optional smoke：确认本地 PR/review/CI evidence intake 预览不写状态、确认只写 `.pr-review-intake-governance.json`、`governance --list/show/verify` 可识别，unsafe evidence path 与 input evidence digest drift 负例失败；该 smoke 不创建 PR、不调用 GitHub/CI/review API、不自动执行 followup，也不接入 Stage 52 release gate 主链。
+- Stage 59 `governance --convergence --report --json` optional smoke：确认能力收敛差距报告只读输出 external reference workflow、ECC learning、Token Savior deterministic token economy、Distill deferred adapter 与 Vibecoding governance 维度，不创建 `.vibecoding-state/`，并拒绝缺少 `--report` 或 `--confirm` 写入尝试。
+- Stage 60 `methodology --route --intent <kind> --json` optional smoke：确认 workflow route 只读输出 `selected_workflow`、`first_skill`、`gate_kinds`、`trigger_discipline` 与 `route_digest`，不创建 `.vibecoding-state/`，未知 intent 回退到 `using-vibecoding -> vibe-brainstorming`，并确认 `methodology --gate --kind tdd --confirm --json` 只写 `.vibecoding-state/methodology-gates/*.methodology-gate.json`。
+- Stage 61 `learning --observe --from-file <session-evidence-file> --preview/--confirm --json` optional smoke：确认本地 learning observation preview 不写状态、confirm 只写 `.vibecoding-state/learning/*.learning-observation.json`、`learning --list/show/verify` 可识别，并覆盖 unsafe source path、source digest drift、scope 越权负例；该 smoke 不自动生成 candidate instinct、不 promotion、不修改正式 skill、prompt、hook、AGENTS.md 或 CLAUDE.md。
+- Stage 62 `learning --instincts --from-observations <learning-observation-file...>` 与 `learning --promote --instinct <candidate-instinct-file>` optional smoke：确认 candidate instinct preview 不写 `.candidate-instinct.json`、confirm 只写 `.vibecoding-state/learning/*.candidate-instinct.json`，promotion preview 不写 `.learning-promotion.json`、confirm 只写 `.vibecoding-state/learning/*.learning-promotion.json`，`learning --list/show/verify` 可审计三类 learning sidecar，并覆盖 unsafe observation path、candidate observation digest drift、promotion boundary 扩权负例；该 smoke 不自动修改正式 skill、AGENTS.md、CLAUDE.md、prompt 或 hook。
+- Stage 63 `tokens --catalog` 与 `tokens --compact-output --command <cmd-name> --from-file <output-file>` optional smoke：确认 token compactor catalog 只读，preview 不创建 `.vibecoding-state/`，confirm 只写 `.vibecoding-state/token-economy/*.token-compaction.json`，`tokens --verify` 可审计 token sidecar，并覆盖 compacted text digest drift 与 unsafe output path 负例；该 smoke 不拦截 shell、不执行命令、不隐藏原始输出、不调用模型、不自动 rewrite 用户命令。
+- Stage 64 `tokens --profile --name minimal|balanced|full`、`tokens --metrics --from-compactions <token-compaction-file...>` 与 `tokens --rewrite-preview --command <cmd>` optional smoke：确认 profile 与 rewrite preview 只读，metrics preview 不额外写 sidecar，metrics confirm 只写 `.vibecoding-state/token-economy/*.token-metrics.json`，`tokens --verify` 可审计 metrics sidecar，并覆盖 metrics digest drift 与 profile/rewrite 不执行、不拦截、不改写命令边界。
+- Stage 65 `release --gate --from-evals <eval-report-file...> --with-convergence` optional smoke：确认 release gate 可显式绑定 `governance --convergence --report` 的 convergence evidence，preview 不写状态，confirm 仍只写 `.release-gate.json`，`release --verify-gate` 可重建并验证 `convergence_digest` / `evidence_digest`，并覆盖 convergence evidence digest drift 与 `--verify-gate --with-convergence` 非法组合；该 smoke 不改变 Stage 52 required suites，不执行 PR/git/platform/model/subagent/MCP/daemon。
+- Stage 68 `release --notes --from-file <local-evidence-file>` optional smoke：确认 release notes preview 不创建 `.vibecoding-state/`，confirm 只写 `.vibecoding-state/release-notes/*.release-notes.json`，`release --verify-notes` 可审计 release-notes sidecar，并覆盖 source digest drift、unsafe source path、boundary 扩权负例；该 smoke 只记录 deterministic `commit_hygiene_findings`，不 amend、不 rebase、不 reset、不 force push、不 tag、不创建 PR，也不接入 Stage 52 release gate 主链。
+- Stage 121 `evals --behavior-contract --from-file <local-transcript-json>` smoke：确认真实 transcript artifact 可被只读转换成 `behavioral_evaluation_contract`，覆盖 workflow entry、`injectsFullSkill=false`、workflow order、required/forbidden markers、completion evidence、Stage 120 readiness 和 no git/platform/model/subagent side effect，并覆盖缺少 entry、跳过验证证据、自动提交、隐式 subagent、误读 `ok=false`、无验证完成声明、commit readiness 缺失等负例。
+- Stage 122 `platforms --bootstrap-matrix` smoke：确认 Claude / Cursor / Codex adapter manifest、安装文档和 hook/settings 示例保持 `adapter-bootstrap-conformance-matrix` 一致，覆盖 `required_adapter_files`、`manifest_parity_gate`、`bootstrap_policy_gate`、`install_doc_bootstrap_gate`、`injectsFullSkill=false`、`writesRuntimeState=false`、`autoRunsNextSkill=false`、`canAutoExecuteSkill=false`、`canCallSubagent=false`、`canTouchGit=false` 和 no install/hook/git/platform/subagent side effect。
+- Stage 123 `governance --traceability-map` smoke：确认 `skills/*/SKILL.md`、workflow handoff marker、runtime capability registry 和命令能力保持 `skill-to-runtime-traceability-map` 一致，覆盖 `skill_row_coverage`、`frontmatter_name_gate`、`workflow_handoff_gate`、`runtime_registry_group_gate`、`runtime_registry_command_gate`、`skill_runtime_traceability_invariants` 和 no skill/check/test/git/platform/subagent side effect。
+- Stage 124 `completion --evidence-bundle --from-file <local-completion-evidence-file>` smoke：确认 Stage 88 readiness 和 Stage 99 bundle 会被只读整理成 `human-completion-evidence-bundle`，覆盖 `one_screen_sections`、`evidence_receipt`、`delivery_gate`、`copy_ready_summary`、`manual_next_action`、`human_completion_evidence_invariants` 和 no check/test/git/platform/subagent side effect。
+- Stage 125 `governance --external-reference-regression-guard --from-external-reference <local-external reference-dir>` smoke：确认 Stage 115-124 对标能力不会从 registry、automation readiness、traceability 或 gap dimension scorecard 退化，覆盖 `protected_stage_sequence`、`protected_capabilities`、`dimension_scorecard`、`regression_gates`、`superiority_claim`、`regression_guard_invariants` 和 no command/check/test/git/platform/subagent side effect。
+- `vibe-compact` 本地压缩 smoke test。