@jtf19/vibecoding-kit 0.1.0

package/docs/release-guide.md

@@ -0,0 +1,481 @@
+# 发布说明
+
+本文档定义 Vibecoding Kit 第一阶段的发布包边界和发布前检查步骤。
+
+## 发布目标
+
+第一阶段发布物应满足：
+
+- 可被用户阅读：从 `README.md` 能进入安装、诊断、验收和示例路径。
+- 可被用户安装：通过 `node bin/vibe.mjs init` 安装到业务项目，或兼容使用 `tools/vibe-init/index.mjs`。
+- 可被用户复验：通过 `node bin/vibe.mjs doctor` 检查 repo layout 或 installed layout，或兼容使用 `tools/vibe-doctor/index.mjs`。
+- 可被维护者说明：明确哪些内容属于发布包，哪些内容只是参考或临时产物。
+
+## 发布包应包含
+
+```text
+README.md
+package.json
+LICENSE
+CHANGELOG.md
+CONTRIBUTING.md
+SECURITY.md
+CODE_OF_CONDUCT.md
+bin/
+CLAUDE.md
+AGENTS.md
+skills/
+adapters/
+hooks/
+templates/
+  product-discovery.md
+  product-spec.md
+  ui-design-contract.md
+  product-acceptance.md
+  scenario-acceptance.yaml
+  architecture-design.md
+  delivery-traceability.yaml
+tools/
+docs/
+examples/
+```
+
+其中：
+
+- `skills/`：workflow skills 主体，包含需求、产品发现、产品规格、UI/UX contract、架构规划、执行、验证、review 和 git 收口纪律。
+- `adapters/`：Claude、Codex、Cursor 平台适配文件。
+- `hooks/`：会话入口 bootstrap、handoff 检查和后续自动化预留。
+- `templates/`：安装到业务项目根目录的入口文件模板，以及产品发现、产品规格、UI contract、产品验收、场景验收、架构设计、交付追踪矩阵和 implementation plan artifact 模板。
+- `bin/` 和 `package.json`：无依赖 `vibe` CLI wrapper，负责路由到现有工具。
+- `tools/`：无依赖 Node.js 工具，包括 `vibe-init`、`vibe-doctor`、`vibe-lifecycle`、`vibe-plugin-pack`、`vibe-compact`、`vibe-runtime-check`、`vibe-runtime` 和 `vibe-release-check`。
+- `docs/`：安装、验收、发布和实现说明。
+- `examples/`：平台最小接入示例说明、`examples/golden-path/` team-mode readiness demo、`examples/full-chain/` full compliance reference、`examples/ci/` CI evidence producer recipe，以及 runtime fixtures。`examples/runtime-fixtures/negative/` 保存只读负例输入，用于证明缺 architecture、traceability ref 不存在、test evidence 缺 `output_digest`、diff coverage 出现 `unexpected_files`、commit boundary 扩权、changed file 缺 task_ref、required task 未覆盖、operation mismatch、风险 task 缺测试证据时 release fast smoke 会得到 `ok=false`。
+
+## 发布包不应包含
+
+```text
+.tmp/
+.vibecoding/
+.vibecoding-state/
+fork/
+node_modules/
+.git/
+.github/
+.cursor/
+.cursor-local-assistant-v2/
+```
+
+不应包含未验证实验产物、编辑器缓存、临时安装目标、本地 runtime ledger 或参考项目源码。
+
+## layout 边界
+
+repo layout 用于 Vibecoding Kit 源码仓库：
+
+```text
+skills/
+adapters/
+hooks/
+docs/
+examples/
+templates/
+tools/
+bin/
+package.json
+README.md
+CLAUDE.md
+AGENTS.md
+```
+
+installed layout 用于业务项目：
+
+```text
+CLAUDE.md
+AGENTS.md
+.vibecoding/
+  skills/
+  adapters/
+  hooks/
+  VIBE-CODING.md
+  config.json
+```
+
+`docs/` 和 `examples/` 只有在用户传入 `--with-docs` 时安装到 `.vibecoding/`。
+
+`--with-runtime` 只会在 `.vibecoding/runtime-installed.json` 写入 Stage 55 opt-in manifest，不会把 `tools/vibe-runtime/` 或 `tools/vibe-doctor/` 复制进业务项目。installed project 的 runtime / doctor 调用必须来自外部 Vibecoding kit 源仓库或打包 CLI。
+
+## 平台安装边界
+
+- `--platform claude`：生成 `CLAUDE.md`，安装 `.vibecoding/adapters/claude/`。
+- `--platform cursor`：生成 `AGENTS.md`，安装 `.vibecoding/adapters/cursor/`。
+- `--platform codex`：生成 `AGENTS.md`，安装 `.vibecoding/adapters/codex/`。
+- `--platform all`：安装三平台 adapter，并生成 `CLAUDE.md` 和 `AGENTS.md`。
+
+`vibe-init` 不覆盖用户非 managed 内容。入口文件不存在时创建带 managed block 的模板；入口文件已有 managed block 时只替换该 block；入口文件存在但没有 block 时默认不写，用户需要先 `--merge=preview` 再显式 `--merge=append`。
+
+## 安装体验增强边界
+
+安装体验增强路线见 `docs/install-experience-roadmap.md`。该路线独立于 runtime roadmap，发布说明中按 install lifecycle 审核：
+
+- `init`：项目接入、平台 adapter 和 installed layout。
+- `doctor`：repo layout / installed layout 诊断。
+- `update` / `repair` / `uninstall`：由 `.vibecoding/config.json` 驱动，默认 dry-run，写入必须显式 `--confirm` 或 `--yes`。
+- managed block：只允许修改 Vibecoding 管理区，不覆盖用户自有入口规则；无 block 时必须 preview 或显式 append。
+- session-start bootstrap：只注入轻量启动提示，不加载完整长 workflow，不写 runtime state；可执行入口为 `.vibecoding/hooks/session-start/session-start.mjs`。
+- plugin pack：从 `adapters/` 生成 `.cursor-plugin` / `.codex-plugin` / `.claude-plugin` / `.opencode-plugin` / `.pi-extension` 草案目录，默认输出到 `.tmp/`，用于 marketplace 前置 smoke；`--dry-run` 只输出计划和审计边界，不写文件、不 tag、不创建 GitHub release、不上传 marketplace。
+- P62 adapter/plugin 分发成熟度：`adapter_packaging_consistency` 要求五个平台 `claude,codex,cursor,opencode,pi` 都从 `adapters/<platform>/` 生成并可用 `--check` 回比；`install_experience_score` 只评估安装链路是否可解释，不执行发布。固定 marker：`p62_adapter_plugin_maturity`、`dry_run_auditable=true`、`adapter_marker_drift=false`、`npm_publish=false`、`git_tag=false`、`github_release=false`、`marketplace_upload=false`、`platform_api=false`。
+- P62 adapter/plugin 分发成熟度：`p62_adapter_plugin_maturity` 只把 `adapter_packaging_consistency` 和 `install_experience_score` 作为人工审计口径；五个平台固定为 `platforms=claude,codex,cursor,opencode,pi`，plugin draft 必须保持 `dry_run_auditable=true`、`writes=false`、`draft_output_write=false`、`project_install=false`、`npm_publish=false`、`git_tag=false`、`github_release=false`、`marketplace_upload=false`、`platform_api=false`、`adapter_marker_drift=false`。
+
+发布边界：
+
+- 默认安装不创建 `.vibecoding-state/`。
+- 默认安装不启用 runtime。
+- 平台插件安装不等同于项目级 `vibe init`。
+- `.cursor-plugin` / `.codex-plugin` / `.claude-plugin` 当前是 `vibe plugin pack` 生成的草案产物，不作为常驻手写副本进入源码事实来源。
+- 当前推荐入口是 `node bin/vibe.mjs init`、`node bin/vibe.mjs doctor`、`node bin/vibe.mjs repair --dry-run`、`node bin/vibe.mjs uninstall --dry-run` 和 `node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins --check`；原 `node tools/vibe-init/index.mjs` 和 `node tools/vibe-doctor/index.mjs` 继续作为兼容入口。
+
+## 标准验证脚本
+
+`npm run pack:dry-run` 使用 `npm pack --dry-run --json`，输出 npm 将纳入包内的文件清单，便于维护者审计 `files` allowlist 和 forbidden prefix。它只做本地 dry-run，不发布 npm、不打 tag、不创建 GitHub release、不上传 marketplace。
+
+```bash
+npm run check
+npm run check:arch
+npm run check:doctor
+npm run release:fast
+npm run release:runtime
+npm run release:install
+npm run pack:dry-run
+npm run release:learning
+npm run release:tokens
+npm run demo:golden-path
+npm run demo:full-chain
+```
+
+等价底层命令仍可直接执行：
+
+```bash
+node tools/vibe-runtime-check/index.mjs
+node tools/vibe-architecture-check/index.mjs --root . --json
+node tools/vibe-doctor/index.mjs
+node tools/vibe-release-check/index.mjs --suite fast --quiet
+node tools/vibe-release-check/index.mjs --suite runtime --quiet
+node tools/vibe-release-check/index.mjs --suite golden-path --quiet
+node tools/vibe-release-check/index.mjs --suite full-chain --quiet
+```
+
+`release:fast` 是日常 readiness smoke；`demo:golden-path` 验证 team-mode local evidence alignment，顶层 `ok=false` 可表示尚未提供 full-chain artifact；`demo:full-chain` 验证完整 compliance reference，预期顶层 `ok=true`；`release:runtime` 是更完整的 runtime command / governance / workflow smoke，失败时按输出定位具体 command。
+
+## Productization release evidence pack
+
+P52 收口时，维护者 evidence pack 固定记录 P44-P51/P53 的影响面和本地验证结果，而不是生成新的 runtime artifact。
+
+证据包至少覆盖：
+
+- `three_layer_docs`：README、user guide、quick recipes、team adoption 和 runtime roadmap 的 L1/L2/L3 分层入口。
+- `install_lifecycle_ux`：`init`、`doctor`、`repair --dry-run`、`uninstall --dry-run`、managed block 和 plugin pack dry-run 边界。
+- `team_evidence_starter_kit`：本地 CI evidence producer、golden-path team-mode、常见 blocked reason 和 `ok=false` 解释。
+- `installed_adapter_ux`：Claude / Cursor / Codex / OpenCode / Pi 安装后轻量交互协议，不注入维护者长路线。
+- `workflow_cockpit_readonly`：`workflow --cockpit` / `self_check_summary` 只读自检闭环，不执行 skill、subagent、scheduler 或 git。
+- `behavior_release_gate`：transcript / replay negative fixture 覆盖自动提交、隐式 subagent、跳过 evidence、误读 `ok=false` 和无验证完成声明。
+- `packaging_dry_run`：`npm run pack:dry-run` 和 plugin draft dry-run 均固定 `writes=false`、`npm_publish=false`、`git_tag=false`、`github_release=false`、`marketplace_upload=false`。
+- `feedback_learning_token_entry`：feedback / learning / token 入口保持候选观察和 deterministic advice，固定 `skill_mutation=false`、`prompt_mutation=false`、`shell_interception=false`、`model_invocation=false`。
+- `technical_debt_register`：文档、架构、验证和产品体验债务都有 owner、paydown 方式和 blocked validation。
+
+P52 不创建 `.vibecoding-state/`，不清理用户无关文件，不提交、不 push、不创建 PR、不调用平台 API、不调用模型、不调用 subagent。收口时必须确认 `.tmp` absent、source `.vibecoding-state` absent、target `.vibecoding-state` absent，并记录 `runtime-check`、`check:arch`、`release:install`、`release:fast`、`release:behavior` 和 `pack:dry-run` 的通过证据。
+
+## 第二阶段维护检查
+
+第二阶段首轮新增聚合检查：
+
+```bash
+node tools/vibe-release-check/index.mjs
+```
+
+UX-6 平台插件草案也可以单独用源码工具入口验证：
+
+```bash
+node tools/vibe-plugin-pack/index.mjs --platform all --out .tmp/vibe-plugins --dry-run
+node tools/vibe-plugin-pack/index.mjs --platform all --out .tmp/vibe-plugins
+node tools/vibe-plugin-pack/index.mjs --platform all --out .tmp/vibe-plugins --check
+```
+
+第二阶段第二批新增简洁输出模式和分组检查：
+
+```bash
+node tools/vibe-release-check/index.mjs --quiet
+node tools/vibe-release-check/index.mjs --suite fast --quiet
+node tools/vibe-release-check/index.mjs --suite install --timing
+node tools/vibe-release-check/index.mjs --profile runtime --quiet
+node tools/vibe-release-check/index.mjs --keep-tmp
+```
+
+`--suite` 支持 `all`、`fast`、`install`、`runtime`、`full-chain`、`golden-path`、`learning` 和 `tokens`；`--profile` 是 `--suite` 的别名。`--timing` 只输出耗时分布，不改变检查范围。`--keep-tmp` 保留临时验证目录，便于失败后排查。`--quiet` 只压缩正常通过时的输出，检查失败时仍输出失败命令的详细信息。
+
+该命令聚合 repo doctor、只读 runtime check、runtime ledger smoke、submodule status、plugin pack dry-run / generate / check、init check / dry-run / install、installed doctor、merge preview 和 vibe-compact smoke test。
+
+Runtime ledger smoke 同时覆盖 JSON handoff、legacy YAML-like handoff、`status` ledger 摘要、只读 JSON envelope、`next --dry-run` 建议状态，以及产品/UI artifact gate 和 completion evidence bundle：
+
+- `methodology --gate --kind product-spec --from-file examples/runtime-fixtures/product-spec.md --json` 只读验证产品规格 artifact。
+- `methodology --gate --kind ui-design --from-file examples/runtime-fixtures/ui-design-contract.md --json` 只读验证 UI contract artifact。
+- `methodology --gate --kind scenario-acceptance --from-file examples/runtime-fixtures/scenario-acceptance.yaml --json` 只读验证场景验收 DSL。
+- `completion --evidence-bundle --from-product-discovery ... --from-evidence examples/runtime-fixtures/evidence.json --json` 只读聚合产品/UI/场景/验收/工程证据。
+- 所有新增 smoke 都必须保持 `writes=false`、`state_directory_created=false`、`command_execution=false`、`test_execution=false`、`browser_execution=false`、`skill_execution=false`、`git=false`、`platform_api=false`、`subagent=false`、`mcp=false`。
+
+Runtime ledger smoke 同时覆盖 JSON handoff、legacy YAML-like handoff、`status` ledger 摘要、只读 JSON envelope 和 `next --dry-run` 建议状态：
+
+- JSON handoff 是 Stage 3 推荐输入格式。
+- JSON-first 解析支持纯 JSON 文件和 markdown fenced JSON block。
+- legacy fallback 保留旧 handoff 文本兼容。
+- `status --json`、`validate-handoff --json`、`next --dry-run --json` 和 `tasks --dry-run --json` 输出可解析 JSON envelope。
+- `tasks --dry-run --task <task-id> --json` 只输出选中 task；readiness / `blocked_by` 按完整 ledger dependency graph 计算。
+- 写入类 `--json` 必须明确失败，release smoke 覆盖 `record-handoff --json`、`artifacts --json`、`tasks --write --json` 和 `reset --json`。
+- `record-handoff` 成功后输出 handoff quality 提示，warning 不阻止写入、不改变 ledger 结构、不执行 `next_skill`。
+- `status` 输出当前 ledger 摘要，并保持只读、不创建或修改 workflow state。
+- `next --dry-run` 输出 `idle`、`ready`、`blocked`、`stopped` 文本建议。
+- `next --dry-run --dispatch-intent --json` 输出 adapter-ready intent、runtimeBridge、platform_hints、gate preview 和 `dispatch_event=false` safety 标记；该 smoke 必须证明不创建 `.vibecoding-state/dispatches/`。
+- `next --confirm --dispatch` 是 Stage 6 confirm-dispatch gate；成功只写 `.vibecoding-state/dispatches/<timestamp>.json`，输出 adapter-readable dispatch envelope，不执行 skill、不调用 subagent / MCP / daemon、不触碰 git / worktree。
+- `next --confirm --dispatch --json` 输出可解析执行结果 envelope，包含 `mode: confirm-dispatch`、`dispatch.adapter_ready=true`、`safety.confirmed=true` 和 `safety.dispatch_event=true`。
+- release smoke 覆盖缺少 `--confirm`、缺少 `--dispatch`、`--dry-run --dispatch`、非 allowed transition、review gate blocked、task readiness blocked 等失败分支，且失败分支不得写 `.vibecoding-state/dispatches/`。
+- `dispatches --list`、`dispatches --show <event-file>` 和 `dispatches --verify <event-file>` 是 Stage 6.5 read-only dispatch audit；release smoke 覆盖空列表、合法 event 列出/查看/校验、`--json` 可解析、损坏 JSON、非 `confirm-dispatch` event、缺少 forbidden actions 和路径越界输入。
+- `dispatches --claim <event-file> --actor <id>`、`dispatches --ack <event-file> --actor <id> --status picked|skipped|failed` 和 `dispatches --claims` 是 Stage 7 Dispatch Claim / Ack Gate；release smoke 覆盖无 event claim 失败且不创建 claim 目录、合法 claim 写 `.vibecoding-state/dispatch-claims/<event-file>.claim.json`、重复 active claim 失败、缺少或非法 actor 失败、未 claim ack 失败、actor mismatch 失败、非法 `consumed` 状态失败、`skipped` / `failed` 缺少 reason 失败、claim event digest mismatch 失败、合法 ack 保留 `claim.ack.reason`、claim / ack 不修改原始 dispatch event，以及 claim state list 可读。Stage 7.5 / 7.6 增强覆盖 stale claim audit、event digest mismatch audit 和 recovery preview；`reassign_allowed=false`、`retry_allowed=false`，不自动 reassign，不修改 dispatch event 或 claim state。
+- Stage 7 只记录人工 pickup 状态，不执行 skill、不调用平台 API、不调用 subagent / MCP / daemon、不触碰 git / worktree 或业务源码。
+- `dispatches --pickup` 是 Stage 8 pickup package；只读输出 adapter / human 可复制的 pickup package，不自动 claim、不创建 session、不执行 skill。Stage 8.4 / 8.6-8.10 增强覆盖 `ready_for_adapter`、`event_valid`、`claim_picked`、`target_skill_present`、`entry_file_present`、`pickup_verification`、`platform_capability`、`adapter_dry_run` 以及 `event_sha256` / `claim_sha256` / `workflow_sha256` / `handoff_sha256` digest-bound package；Claude 使用 `CLAUDE.md`，Cursor / Codex 使用 `AGENTS.md`，三者当前都是 manual/no-session/no-API/no-stdin。
+- `execute --from-dispatch` 的 Stage 9 `--preflight` / `--dry-run` / `--confirm --actor` 只审计、预览或写 planned execution envelope，不真实执行 workflow skill。Stage 9.1-9.11 增强覆盖 dry-run execution plan、confirm planned envelope、claim picked gate、no execution boundary、execution envelope safety、immutability、preflight no-write、planned envelope verify、stable `idempotency_key`、policy snapshot、allowlisted skills snapshot、expected write boundary 和 forbidden write boundary。兼容 marker 仍保留 Stage 9.2 / 9.5 的 policy snapshot 与 idempotency 口径。
+- Stage 11.1 `execute --from-dispatch <event-file> --confirm --actor <id> --run` 只执行 allowlist 内本地受监管 runtime action，先持久化同一 execution file 的 `running` record，再更新同一文件为 terminal `supervised-run` lifecycle record 和 evidence；`executions --list/show/verify` 只读审计 execution records。
+- Stage 11.1 release smoke 覆盖 corrupted execution records：缺 lifecycle、缺 running 首态、terminal status mismatch、timestamp 非法或倒序、缺 `evidence.stdout_excerpt`、bad `runtime_action`、`skill_execution=true`、`platform_api=true`、`git=true` 和 `worktree=true` 都必须 verify 失败。
+- Stage 11 release smoke 覆盖缺少 `--confirm`、actor mismatch、未 claim、claim 未 `picked`、target skill 不在 allowlist、execution 路径越界、dispatch / claim immutability、run 文本 `runtime_action=true`、dry-run / confirm 文本 `runtime_action=false`、`skill_execution=false`、no platform API、no subagent / MCP / daemon、no git / worktree / business source write。
+- `daemon --dry-run` / `daemon --scan --dry-run` / `daemon --once --confirm` 是 Stage 10 default-off no-op gate；不启动 long-running worker、不扫描执行 dispatch、不调用 `execute`。`daemon --scan --dry-run` 只读输出 candidates、blocked items、stale claims、stale running executions、retry preview、`retry_allowed=false`、lock / lease contract 和 watcher disabled；`daemon --once --confirm` 只写 no-op envelope，并记录 `scan_noop=true`、`scheduler_policy_dry_run=true`、`lock_acquired=false`、`lease_required=true`、`heartbeat_started=false`，不创建真实 worker、不 pickup、不 execute、不 retry、不改 dispatch/claim/execution。
+- `stop_condition` 有实际内容时必须进入 `blocked` 建议状态。
+- `next --dry-run` 仍只输出建议，不执行 `next_skill`。
+
+默认会清理 `.tmp/`。只有传入 `--keep-tmp` 时保留临时验证目录。
+
+维护者需要研究 `fork/` 参考项目时，先执行：
+
+```bash
+git submodule update --init --recursive
+```
+
+`fork/` 仍是开发参考，不进入发布包，也不会被 `vibe-init` 安装到业务项目。
+
+## Stage 52-65 能力收敛发布审计
+
+Stage 52-65 已从单点 runtime 能力推进为一条完整的本地治理收口链。以 `add644b` 为基线，到当前 `HEAD` 的提交链覆盖 8 个提交、19 个文件，主要改动集中在 `tools/vibe-runtime/`、`tools/vibe-runtime-check/`、`tools/vibe-release-check/`、runtime docs、安装边界和 workflow 入口规则。
+
+能力归属：
+
+- Stage 52：`release --gate` 与 `release --verify-gate`，把 eval-backed release gate 写入 `.vibecoding-state/release-gates/`，并保持 required eval chain 可验证。
+- Stage 53：`feedback --ledger` 与 `feedback --verify-ledger`，把 planner/router/orchestrator/release gate 反馈收敛为本地 feedback ledger。
+- Stage 54：`policies --catalog` 与 `policies --summary`，把 runtime guardrails 固化为只读 builtin policy catalog 和 digest。
+- Stage 55：`vibe-init --with-runtime` 只写 `.vibecoding/runtime-installed.json` opt-in manifest，不把 runtime CLI 复制进业务项目。
+- Stage 56：`governance --compatibility --report` 只读检查旧 artifact / trace source / policy baseline 兼容性，不自动迁移或重签 digest。
+- Stage 57：`governance --pr-readiness` 生成可选 PR readiness governance sidecar，不创建 PR、不 push、不 merge。
+- Stage 58：`governance --pr-review-intake` 从本地 evidence file 摄取 PR/review/CI 证据，不调用平台 API 或外部网络。
+- Stage 59：`governance --convergence --report` 冻结 external reference / ECC / Token Savior / Distill 与 Vibecoding 的能力收敛差距矩阵，只读不写状态。
+- Stage 60：`methodology --route --intent` 提供 workflow route 建议和 trigger discipline，不执行 skill、不制造“已使用 skill”的证据。
+- Stage 61-62：`learning --observe`、`learning --instincts`、`learning --promote` 建立 observation / candidate instinct / promotion sidecar 链，不自动修改正式 skills 或入口文件。
+- Stage 63-64：`tokens --compact-output`、`tokens --profile`、`tokens --metrics`、`tokens --rewrite-preview` 建立确定性 token economy，不拦截 shell、不执行命令、不隐藏原始输出。
+- Stage 65：`release --gate --with-convergence` 可选绑定 convergence evidence；未显式启用时不改变 Stage 52 required release gate 主链。
+
+发布判断：Stage 52-65 属于本地、确定性、sidecar-first 的治理能力扩展。它们可以进入当前发布说明，但仍应标注为 default-off / optional 的 runtime governance 能力，不应描述成自动 PR、自动 subagent、自动学习修改 skill、自动 token shell interception 或 Distill 风格 LLM distillation。
+
+提交历史风险：最近提交信息包含异常的 Markdown fence 前缀 ```` ``` ````。这不影响源码内容或验证链，但会降低 release notes 和 changelog 的可读性。默认不 amend、不 rebase、不 force push；如需修正，只能在用户明确要求并接受重写历史风险后单独处理。
+
+## P64 Contributor / Closeout Guardrails
+
+P64 `p64_contributor_closeout_guardrails` 把完成、提交、PR 和 subagent 相关收口纪律固定为人工下一步提示，而不是执行授权。
+
+收口输出必须清楚显示：`current_contract_not_authorized=true`、`completion_claim_requires_evidence=true`、`commit_requires_manual_review=true`、`pr_requires_manual_review=true`、`subagent_requires_explicit_permission=true`。当 evidence 不足时，只给 `manual_next_action_only`、`evidence_gap_only` 和 `do_not_do_yet_visible`，不得把下一步写成已经执行。
+
+禁止动作固定：`git_execution=false`、`git_write=false`、`commit=false`、`push=false`、`pr=false`、`merge=false`、`remote_review_request=false`、`subagent=false`、`platform_api=false`、`model_invocation=false`、`business_source_write=false`、`hidden_execution=false`。
+
+P64 不新增命令、不创建 PR、不提交、不询问远端 review、不调用 subagent、不调用平台 API。Stage 120 staged commit readiness、Stage 124 human completion bundle 和现有 behavior negative fixture 只作为人工判断证据，不授权动作。
+
+## Runtime Contract、只读检查器与本地 Ledger
+
+当前发布包包含 runtime 分阶段规划、只读 contract 检查器和显式本地 workflow state ledger：
+
+```text
+docs/runtime-roadmap.md
+docs/runtime-contract.md
+tools/vibe-runtime-check/
+tools/vibe-runtime/
+```
+
+`vibe-runtime-check` 只检查 workflow skill 是否具备可被未来 runtime 消费的 handoff marker，并检查 `tools/vibe-runtime/` 与 `.vibecoding-state/` ignore 边界。它不写 `.vibecoding-state/`，不自动执行 `next_skill`，不调用 subagent，不创建 worktree，不执行 git 写入，不安装依赖，也不引入 MCP、agent graph、daemon 或后台 worker。
+
+`vibe-runtime` 只在用户显式运行时写入 `.vibecoding-state/workflow.json`。`status` 不创建文件，有状态时只读展示当前 ledger 摘要；`record-handoff` 只在已存在 root 下记录 handoff，不创建 root，`next --dry-run` 只输出 `idle` / `ready` / `blocked` / `stopped` 文本建议，`reset --confirm` 只删除 `.vibecoding-state/`。Stage 3 推荐 JSON handoff，采用 JSON-first 解析纯 JSON 文件或 markdown fenced JSON block，并通过 legacy fallback 兼容旧 YAML-like handoff。它不是自动 orchestrator，不进入下一 skill，不执行 workflow 动作。
+
+## 轻量流程纪律 Skill
+
+当前发布包包含第二批 external reference 映射 skill：
+
+```text
+skills/vibe-brainstorming/
+skills/vibe-test-driven-development/
+skills/vibe-finishing-a-development-branch/
+```
+
+这些 skill 只增强构思、测试/验证策略和交付收口纪律，仍通过显式 `Workflow Handoff` 推进。不引入 runtime 编排器，不自动执行下一个 skill，不复制 `fork/<external-reference>` 的脚本资产。
+
+## Review Flow Skill
+
+当前发布包包含 review 闭环纪律 skill：
+
+```text
+skills/vibe-requesting-code-review/
+skills/vibe-receiving-code-review/
+```
+
+`vibe-requesting-code-review` 只整理 review 目标、范围、依据、验证证据和重点风险，不自动派发 reviewer，不调用 subagent，不创建 PR，不执行 GitHub API 或 MCP 集成。
+
+`vibe-receiving-code-review` 只负责理解、验证、分类和排序 review feedback，不自动执行修复，不把 reviewer 建议当作自动成立的需求变更。需要修复时先进入 `vibe-test-driven-development`，需要复现或定位根因时进入 `vibe-systematic-debugging`。
+
+`vibe-review` 继续负责审查行为、边界、风险和交付质量，不变成复杂调度器。
+
+## Product / UI Workflow Discipline
+
+当前发布包包含产品发现、产品规格、UI contract、架构设计、交付追踪矩阵和产品体验验收纪律：
+
+```text
+skills/vibe-product-discovery/
+skills/vibe-product-spec/
+skills/vibe-ui-design/
+skills/vibe-planning/
+skills/vibe-writing-plans/
+skills/vibe-product-acceptance/
+```
+
+`vibe-product-discovery` 负责产品问题、目标用户、场景、价值假设和成功指标，不写实现计划。`vibe-product-spec` 负责 PRD / capability spec、用户故事、功能要求、非功能要求和产品验收标准，不替代架构规划。`vibe-ui-design` 负责屏幕、用户路径、组件职责、UI 状态、文案、交互、响应式和可访问性 contract，不写前端代码。`vibe-planning` 可输出 `architecture-design.md`，`vibe-writing-plans` 可输出或引用 `delivery-traceability.yaml`。`vibe-product-acceptance` 负责产品体验验收，补充用户路径、UI 状态、可访问性、指标和体验缺口证据，不替代工程验证或 git 收口。
+
+这些 skill 默认只通过显式 `Workflow Handoff` 推进，不启用 runtime 自动调用链、不调用 subagent、不接 MCP、不生成设计稿、不创建 PR、不执行 git 操作。`completion --evidence-bundle --from-product-discovery ... --from-architecture ... --from-traceability ... --from-commit-readiness ...` 只聚合 full-chain evidence，`commit-readiness` digest 只作为人工提交决策输入，不授权 git add/commit/push/PR/merge。
+
+## Skill Writing Discipline
+
+当前发布包包含 skill 编写纪律：
+
+```text
+skills/vibe-writing-skills/
+```
+
+`vibe-writing-skills` 用于新增或修改 workflow skill 前明确触发场景、职责边界、输入输出、`next_skill`、同步清单和验收标准。它不引入 graphviz、skill 自动生成器、subagent 测试或 runtime 编排器，也不复制 `fork/<external-reference>` 的大型脚本或 prompt 资产。
+
+## Subagent Driven Development Gate
+
+当前发布包包含轻量 subagent 执行边界纪律：
+
+```text
+skills/vibe-subagent-driven-development/
+```
+
+`vibe-subagent-driven-development` 用于独立任务 brief 完整、工作区边界清楚且用户明确允许 subagent 时，判断 subagent 执行 gate、brief 要求、任务级 review gate 和最终 review gate。它不自动调用 subagent，不选择模型，不生成 review package，不实现 reviewer prompt 文件，不维护 progress ledger runtime，也不引入 MCP、agent graph、后台 worker 或平台私有 runtime。
+
+## Workspace Isolation Discipline
+
+当前发布包包含轻量工作区隔离纪律：
+
+```text
+skills/vibe-workspace-isolation/
+```
+
+`vibe-workspace-isolation` 用于大改动、并行任务、风险性重构或分支收口前判断当前工作区是否适合原地工作、是否已经隔离、是否应先收口，或是否需要停止等待用户确认隔离方案。它不自动执行 `git worktree add`，不切换分支，不修改 `.gitignore`，不 stash、commit、reset、checkout 或删除用户变更，也不创建平台私有 runtime。
+
+## Parallel Work Dispatch Discipline
+
+当前发布包包含轻量并行任务分发纪律：
+
+```text
+skills/vibe-dispatching-parallel-work/
+```
+
+`vibe-dispatching-parallel-work` 用于计划包含多个潜在独立任务时，判断独立性、共享状态、冲突风险和顺序依赖，并产出自包含任务 brief。它不自动调用 subagent，不选择模型，不生成 review package，不引入 agent graph 或 runtime 编排器，也不替代 `vibe-executing-plans` 的默认逐项执行职责。
+
+## Hook 辅助自动化
+
+当前发布包包含 hook 提示模板，用于辅助 workflow 显式推进：
+
+```text
+hooks/session-start/
+hooks/workflow-handoff/
+hooks/post-tool-compact/
+```
+
+这些 hook 只提供提示和检查点，不做 runtime 自动调用链、不调用工具、不维护跨阶段状态。
+
+## Stage 69/70 发布候选收口归档
+
+Stage 69 使用 Stage 68 的 `release --notes` 能力，对 Stage 52-68 的本地提交链、diff stat 和验证摘要完成了一次自举式 release-notes 证据回填。验证输入来自 `.tmp/stage69-release-notes-root/evidence/stage69-release-evidence.txt`，确认 `release --notes --preview --json` 不创建状态目录，`release --notes --confirm --json` 只写一个 `.release-notes.json` sidecar，`release --verify-notes` 可复验，并能拒绝 source digest drift、unsafe source path 和 boundary expansion。
+
+Stage 70 将 Stage 52-69 整理为发布候选基线：复跑 `node tools/vibe-runtime-check/index.mjs --root D:\workspace_mine\vibe-coading` 与 `node tools/vibe-release-check/index.mjs --quiet` 通过，并确认 `git status --short; git diff --stat` 无 tracked 输出。
+
+Stage 69/70 不新增 runtime 命令、不改变 Stage 68 release-notes sidecar 语义、不把 release notes 纳入 required release gate 主链，也不提交 `.tmp`、`.vibecoding-state` 或 release-check sandbox 产物。历史 commit subject 中的 Markdown fence 前缀继续作为 hygiene 风险记录，不 amend、不 rebase、不 force push。
+
+Stage 73 在 `d266421` 之后完成提交后基线确认与 release-notes 证据刷新：使用 Stage 68 的 `release --notes` 能力在 `.tmp/stage73-release-notes-root/` sandbox 内生成本地 evidence 与一个 `.release-notes.json` sidecar，验证 preview no-state、confirm one sidecar、`release --verify-notes` 正向通过，并确认 source digest drift、unsafe source path 和 boundary expansion 均会被拒绝。Stage 73 产物只用于本地复验，不进入发布包、不复制到源码目录、不提交。
+
+## 发布前固定检查
+
+```bash
+node tools/vibe-doctor/index.mjs
+node tools/vibe-runtime-check/index.mjs
+node tools/vibe-runtime/index.mjs status --root .tmp/vibe-runtime-ledger
+node tools/vibe-runtime/index.mjs artifacts --dry-run --root .tmp/vibe-runtime-ledger
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-target --platform all --dry-run
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-target --platform auto --check
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-target --platform auto --merge=preview
+node bin/vibe.mjs --help
+node bin/vibe.mjs init --target .tmp/vibe-cli-target --platform all --dry-run
+node bin/vibe.mjs init --target .tmp/vibe-cli-target --platform all
+node bin/vibe.mjs doctor --root .tmp/vibe-cli-target
+node bin/vibe.mjs init --target .tmp/vibe-managed-target --platform cursor
+node bin/vibe.mjs init --target .tmp/vibe-managed-target --platform cursor --merge=preview
+node bin/vibe.mjs init --target .tmp/vibe-managed-target --platform cursor --merge=append
+node bin/vibe.mjs doctor --root .tmp/vibe-managed-target
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-target --platform all
+node tools/vibe-doctor/index.mjs .tmp/vibe-init-target
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-target --platform all --with-docs
+node tools/vibe-doctor/index.mjs .tmp/vibe-init-target
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-claude --platform claude
+node tools/vibe-doctor/index.mjs .tmp/vibe-init-claude
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-cursor --platform cursor
+node tools/vibe-doctor/index.mjs .tmp/vibe-init-cursor
+node tools/vibe-init/index.mjs --target .tmp/vibe-init-codex --platform codex
+node tools/vibe-doctor/index.mjs .tmp/vibe-init-codex
+```
+
+期望：全部 doctor 输出 `Result: passed`。
+
+相关维护文档：
+
+- `docs/acceptance-checklist.md`
+- `docs/install-experience-roadmap.md`
+- `docs/runtime-roadmap.md`
+- `docs/runtime-contract.md`
+- `docs/submodule-guide.md`
+
+## 清理
+
+验证后清理：
+
+```bash
+rm -rf .tmp .vibecoding-state
+```
+
+Windows PowerShell：
+
+```powershell
+if (Test-Path ".tmp") { Remove-Item -Recurse -Force ".tmp" }
+if (Test-Path ".vibecoding-state") { Remove-Item -Recurse -Force ".vibecoding-state" }
+```
+
+## 发布判断
+
+满足以下条件即可发布第一阶段：
+
+- repo layout doctor 通过。
+- all 平台 dry-run、默认安装、with-docs 安装通过。
+- Claude、Cursor、Codex 单平台安装通过。
+- README、工具文档、示例项目和验收清单彼此引用一致。
+- 临时目录已清理。
+- runtime artifacts 仅在显式 `artifacts --write` 时写入 `.vibecoding-state/*.md`，不进入发布包。
+- Stage 9 supervised executor 仅在 `execute --from-dispatch --confirm --actor` 成功后写入 `.vibecoding-state/executions/` planned execution envelope；release-check 必须覆盖 Stage 9.1-9.11 dry-run execution plan、confirm planned envelope、claim picked gate、no execution boundary、execution envelope safety、immutability、execution preflight audit、planned envelope verify、stable `idempotency_key`、policy snapshot、write boundary preview、preflight no-write、dry-run no-write、actor mismatch、claim not picked、`runtime_action=false`、只写 execution envelope 和不修改 dispatch/claim。
+- Stage 10 daemon gate 默认关闭；release-check 必须覆盖 Stage 10.1 command gate、Stage 10.2 once-run envelope、Stage 10.3-10.6 scheduler scan dry-run / scheduler policy dry-run / stale claim and stale running audit / retry preview、Stage 10.8 once scan no-op envelope、Stage 10.11-10.13 lock / watcher / lease heartbeat contract、`daemon` 无参数失败、`daemon --once` 缺 confirm 失败、`daemon --dry-run` no-write、`daemon --scan --dry-run` no-write、`daemon --once --confirm` 只写 `.vibecoding-state/daemon-runs/` daemon run envelope、`default_enabled=false`、`long_running=false`、`watcher=false`、`dispatch_scan_execution=false`，以及不启动 long-running worker / watcher、不把 scan 结果作为执行输入、不调用 execute、不 pickup claim、不触碰 git / worktree。

package/docs/release-notes.md

@@ -0,0 +1,75 @@
+# Release Notes：安装采用与发布收口
+
+本文记录当前发布收口的用户可见价值。它不是新的 release gate，也不改变 runtime、install 或 adapter 的执行边界。
+
+## Install / adapter adoption parity
+
+Claude、Cursor、Codex 三个平台的 installed layout 已统一到同一套采用语义：
+
+- Claude 入口文件是 `CLAUDE.md`。
+- Cursor / Codex 入口文件是 `AGENTS.md`。
+- workflow skills 安装到 `.vibecoding/skills/`。
+- 平台 adapter 安装到 `.vibecoding/adapters/<platform>/`。
+- session-start bootstrap 安装到 `.vibecoding/hooks/session-start/`。
+
+维护目标是让业务项目安装后先看到 summary-first 入口，再按风险逐步采用 Golden Path，而不是一开始理解完整治理体系。
+
+## Installed project roundtrip coverage
+
+`npm run release:install` 现在覆盖 installed project 的关键 marker：
+
+- 根入口文档包含 `workflow_start.entry_summary`。
+- completion 证据入口包含 `completion_evidence.task_completion_summary`。
+- adapter install 文档保持 summary-first 和安全边界说明。
+- `using-vibecoding` skill、adapter docs、session-start bootstrap 在安装产物中可被复验。
+
+这条检查证明安装后的业务项目语义和源码模板一致，避免只在源码仓库里正确、安装后丢失入口提示。
+
+## Install suite owner split
+
+安装 suite 的 installed-project marker 期望由 `tools/vibe-release-check/release-check-install-suite.mjs` 拥有，release-check entry 只负责聚合和调度。
+
+这个拆分降低了 release-check entry 的职责密度：安装语义变化时优先查看 install suite owner，不把新规则继续塞回总入口。
+
+## runtime-check diagnostics maintainability
+
+install placement contract 的 diagnostics 输出由 `tools/vibe-runtime-check/release-check-install-placement-contracts.mjs` 拥有。runtime-check entry 只导入并调用 formatter。
+
+维护者排查安装放置合同问题时，优先运行：
+
+```bash
+node tools/vibe-runtime-check/index.mjs --root . --diagnostics
+```
+
+默认 runtime-check 输出和 gate 语义不因 diagnostics owner split 改变。
+
+## Safety boundary unchanged
+
+本轮收口只提升安装采用说明、installed-project 复验和 diagnostics 可维护性，不新增运行能力：
+
+- 不创建 `.vibecoding-state/`。
+- 不隐藏运行测试或命令。
+- 不自动执行 workflow skill。
+- 不读取或写入业务源码。
+- 不提交、push、创建 PR 或 merge。
+- 不调用 subagent、MCP 或平台 API。
+
+## Recommended validation commands
+
+维护者收口优先使用 package scripts：
+
+```bash
+npm run release:install
+npm run release:fast
+npm run check:arch
+npm run check
+```
+
+如果只改文档入口，通常可先跑：
+
+```bash
+npm run release:fast
+npm run check:arch
+```
+
+涉及安装模板、adapter 或 installed-project marker 时必须补跑 `npm run release:install`。