@jtf19/vibecoding-kit 0.1.0

package/docs/architecture.md

@@ -0,0 +1,77 @@
+# Architecture
+
+Vibecoding Kit is organized around explicit ownership. Runtime behavior, release checks, install assets, and documentation should not collapse into one large module.
+
+## Module map
+
+```mermaid
+flowchart TD
+  user[User request] --> entry[CLAUDE.md / AGENTS.md]
+  entry --> skills[skills/]
+  entry --> adapters[adapters/]
+  entry --> hooks[hooks/]
+
+  cli[bin/vibe.mjs] --> init[tools/vibe-init/]
+  cli --> doctor[tools/vibe-doctor/]
+  cli --> lifecycle[tools/vibe-lifecycle/]
+  cli --> profile[tools/vibe-profile/]
+  cli --> plugin[tools/vibe-plugin-pack/]
+
+  runtime[tools/vibe-runtime/] --> state[(.vibecoding-state/ explicit only)]
+  checks[tools/vibe-runtime-check/] --> source[repo source]
+  release[tools/vibe-release-check/] --> source
+  release --> examples[examples/]
+  release --> templates[templates/]
+
+  init --> installed[Installed project .vibecoding/]
+  templates --> installed
+  skills --> installed
+  adapters --> installed
+  hooks --> installed
+```
+
+## Ownership boundaries
+
+| Area | Owner responsibility | Must not own |
+| --- | --- | --- |
+| `bin/` | Thin CLI command routing | Runtime logic, release policy |
+| `skills/` | Workflow skill text, boundaries, handoff discipline | Platform-specific packaging |
+| `adapters/` | Platform adapter metadata and install notes | Shared workflow semantics |
+| `hooks/` | Lightweight bootstrap and handoff helpers | Hidden execution or daemon behavior |
+| `templates/` | Installed entry and evidence templates | Repo-only maintainer docs |
+| `tools/vibe-init/` | Installed layout creation and managed block behavior | Runtime state machine |
+| `tools/vibe-doctor/` | Repo and installed layout diagnostics | Source mutation |
+| `tools/vibe-runtime/` | Local workflow envelopes, evidence, and explicit state commands | GitHub, npm, CI, release-check, doctor |
+| `tools/vibe-runtime-check/` | Read-only source contracts | Runtime execution |
+| `tools/vibe-release-check/` | Release smoke suites and package/install boundaries | Runtime core ownership |
+| `docs/` | User, maintainer, and release guidance | Executable behavior |
+| `examples/` | Reproducible adoption and compliance examples | Product runtime code |
+| `fork/` | Reference submodules only | npm package contents or runtime assets |
+
+## Dependency direction
+
+- Runtime core can depend on stable local model helpers in its own layer.
+- Runtime core must not depend on GitHub, npm publishing, CI, doctor, runtime-check, or release-check.
+- Release checks may inspect package metadata, repo layout, docs, examples, and runtime command output.
+- Install tooling may copy curated assets into `.vibecoding/`, but must not copy `fork/`.
+- Docs can describe all layers, but docs must not be the only enforcement for package and safety boundaries.
+
+## State lifecycle
+
+Vibecoding Kit keeps default behavior lightweight:
+
+1. Entry files route the agent to the minimum suitable workflow.
+2. Skills define workflow expectations and handoff boundaries.
+3. Runtime commands only create `.vibecoding-state/` when the invoked command explicitly allows it.
+4. Doctor and runtime-check are read-only diagnostics.
+5. Release-check verifies repo, install, runtime, and package boundaries before publication.
+
+## High-risk areas
+
+Treat these changes as high risk and require stronger validation:
+
+- Command execution or allowlists.
+- Scheduler, daemon, queue, retry, lease, or persistent state behavior.
+- Source writes, source apply, merge, git operations, PR, push, tag, or release workflows.
+- Platform API, MCP, model, or real subagent invocation.
+- Installed layout or JSON envelope changes consumed by external agents.

package/docs/ci-evidence-onboarding.md

@@ -0,0 +1,143 @@
+# CI Evidence Onboarding
+
+本文档说明如何把 Vibecoding Kit 的 local evidence 从 `L1 manual evidence` 升级到 `L2 CI generated evidence`。
+
+核心边界：CI 可以生成 evidence，runtime 只读验证本地 JSON envelope。runtime 不运行测试、不读取 git diff、不访问 CI API、不提交、不创建 PR。
+
+## 目标
+
+- 让团队用 CI 生成 `test-evidence.json` 和 `diff-coverage.json`。
+- 保持 evidence contract 与 `templates/evidence/` 一致。
+- 让 completion readiness 基于用户或 CI 提供的本地 artifact，而不是基于 runtime 自动执行。
+- 把需求、产品、UI、架构、implementation task、diff coverage、test evidence 和 completion bundle 串成可复验的本地证据链。
+
+## Evidence Supply Chain v2 for CI
+
+CI 在 P57 链路中只承担 producer 角色：它可以运行项目自己的测试、计算项目自己的 diff metadata、写出本地 JSON evidence；runtime 仍只是 consumer。
+
+```text
+CI/user facts
+  -> ci-evidence-input.json
+  -> test-evidence.json + diff-coverage.json
+  -> completion --evidence-bundle
+  -> completion_evidence.task_completion_summary
+```
+
+迁移到团队 CI 时，建议把 `ci-evidence-input.json` 视为 CI job 的显式交接合同：所有 command、exit code、timestamp、changed files、task refs、scenario refs 和 digest 都来自 CI 或人工输入。runtime 不访问 CI API、不读取真实 git diff、不运行自动测试。
+
+## 推荐数据流
+
+```mermaid
+flowchart TD
+  A[CI runs tests] --> B[Capture command, exit_code, timestamp]
+  B --> C[Compute output_digest]
+  C --> D[Write test-evidence.json]
+
+  E[CI computes changed files or diff coverage] --> F[Bind changed files to task_refs]
+  F --> G[Compute file or diff digest]
+  G --> H[Write diff-coverage.json]
+
+  D --> I[Runtime completion evidence bundle]
+  H --> I
+  I --> J[Human readiness decision]
+```
+
+注释：CI 负责生成证据，runtime 负责只读验证证据格式、refs、digest 和边界声明。
+
+## 最小 CI 示例
+
+仓库内提供无依赖 Node 示例，展示如何从 CI/user-provided input 生成 team-mode evidence：
+
+```bash
+node examples/ci/generate-test-evidence.mjs --from-file examples/ci/ci-evidence-input.example.json --out .tmp/ci-evidence/test-evidence.json
+node examples/ci/generate-diff-coverage.mjs --from-file examples/ci/ci-evidence-input.example.json --out .tmp/ci-evidence/diff-coverage.json
+node tools/vibe-runtime/index.mjs completion --evidence-bundle --from-product-spec examples/golden-path/product-spec.md --from-plan examples/golden-path/implementation-plan.md --from-test-evidence .tmp/ci-evidence/test-evidence.json --from-diff-coverage .tmp/ci-evidence/diff-coverage.json --json
+```
+
+这些脚本位于 `examples/ci/`，是 evidence producer 示例，不是 runtime core。迁移到真实 CI 时，把 `ci-evidence-input.example.json` 替换成 CI job 产出的命令、退出码、输出摘要、changed files、task refs 和 scenario refs。
+
+最小输入映射：
+
+| 输入字段 | 来源 owner | 注意事项 |
+| --- | --- | --- |
+| test command / exit code / timestamp | CI job | 必须来自真实执行记录，runtime 不补跑测试 |
+| output digest | CI job 或 artifact 生成步骤 | 可以来自日志摘要或 artifact 摘要，但不能保留占位值 |
+| planned files / changed files | CI 或团队 diff 脚本 | runtime 不读取 git diff，只验证你提供的本地 JSON |
+| task refs / scenario refs | implementation plan / scenario artifact | refs 必须稳定，并能和计划或场景文件对齐 |
+| boundary assertions | evidence producer | 必须声明 runtime 没有运行测试、读取 git diff 或写 git |
+
+GitHub Actions 示例位于 `examples/ci/github-actions-readiness.yml`。它故意不放在 `.github/workflows/` 下，因此不会自动启用本仓库 CI；业务项目需要显式复制后再按自己的测试命令、task refs、scenario refs、planned files 和 changed files 修改。
+
+## 最小 CI 步骤
+
+1. 运行团队真实测试命令。
+2. 记录测试命令、退出码和时间戳。
+3. 对测试输出或日志摘要计算 digest，写入 `runs[].output_digest`。
+4. 把测试结果绑定到 `implementation-plan.md` 中的 `task_ref`。
+5. 生成或收集 changed files / diff coverage。
+6. 把每个 changed file 绑定到对应 `task_coverage[].task_ref`。
+7. 对文件内容、diff 片段或 CI artifact 摘要计算 digest。
+8. 运行 completion evidence bundle 做只读验证。
+
+## `test-evidence.json` 生成要求
+
+CI 至少应填写：
+
+- `runs[].command`：CI 实际运行的测试命令。
+- `runs[].exit_code`：真实退出码。
+- `runs[].timestamp`：CI 执行时间。
+- `runs[].output_digest`：测试输出、日志或 artifact 摘要的 digest。
+- `runs[].task_refs`：覆盖的 implementation task refs。
+- `runs[].scenario_refs`：覆盖的 scenario refs；如果当前 team mode 没有 scenario artifact，可以使用团队约定的稳定 ref。
+- `boundary_assertions`：声明 runtime 没有执行命令、测试或 git 操作。
+
+## `diff-coverage.json` 生成要求
+
+CI 至少应填写：
+
+- `planned_files`：来自 implementation plan 的预期文件。
+- `changed_files`：CI 观察到的实际变更文件。
+- `unexpected_files`：不在计划内的文件；非空通常应阻塞 readiness。
+- `missing_files`：计划中预期但未出现的文件；非空需要人工解释。
+- `task_coverage[].task_ref`：对应 implementation task。
+- `task_coverage[].changed_files[].operation`：例如 `add`、`modify`、`delete`、`docs`。
+- `task_coverage[].changed_files[].digest`：文件内容、diff 片段或 artifact 摘要 digest。
+- `boundary_assertions`：声明 runtime 没有读取 git diff、运行测试或写 git。
+
+## 可保留但 runtime 不强制验证的信息
+
+这些信息有助于人工审计，但当前 runtime 不把它们作为 deterministic contract：
+
+- CI provider 名称。
+- CI job URL。
+- build id / run id。
+- artifact URL。
+- artifact digest。
+- commit SHA。
+- workflow name。
+
+如果需要更高可信度，把这些信息放入 CI artifact、构建日志或受控存储中；runtime 继续只读验证本地 envelope。
+
+## 验证命令
+
+Team mode 最小验证：
+
+```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 implementation-plan --from-file implementation-plan.md --json
+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 验证在此基础上继续补 product discovery、UI design、architecture、traceability、acceptance 和 commit readiness artifact。
+
+## 禁止把 CI onboarding 做成 runtime 扩权
+
+不要为了提高可信度而让 runtime：
+
+- 自动运行测试。
+- 自动读取 git diff。
+- 自动访问 CI provider API。
+- 自动生成可信 evidence。
+- 自动提交、push、创建 PR 或 merge。
+
+可信度应来自 CI/provenance 层；runtime 的职责是 deterministic local validation。

package/docs/development.md

@@ -0,0 +1,71 @@
+# Development Guide
+
+This guide is for contributors changing Vibecoding Kit itself.
+
+## Requirements
+
+- Node.js 18 or newer.
+- No runtime third-party npm dependencies are required for the current toolchain.
+
+## Common commands
+
+```bash
+npm run check
+npm run check:arch
+npm run check:doctor
+npm run release:fast
+npm run release:install
+npm run pack:dry-run
+```
+
+Use focused checks during development. Before a pull request, run the checks that match the changed area.
+
+| Changed area | Minimum validation |
+| --- | --- |
+| Docs only | `npm run release:fast`, `npm run check:arch` |
+| Skills or templates | `npm run check`, `npm run release:fast` |
+| Install, adapters, hooks | `npm run release:install`, `npm run check:doctor` |
+| Runtime envelopes or command surface | `npm run check`, `npm run release:runtime:experience` or a narrower runtime suite |
+| Execution/state boundary | `npm run release:runtime:execution`, `npm run release:runtime:state`, then `npm run release:runtime` before release |
+| Package metadata or release boundary | `npm run release:fast`, `npm run pack:dry-run` |
+
+## Making changes
+
+1. Identify the owner module before editing.
+2. Keep the change narrow and avoid adding generic cross-domain helpers.
+3. Update docs, templates, package metadata, and release checks together when a contract changes.
+4. Preserve explicit approval gates for source writes, command execution, git, platform APIs, real subagents, and persistent state.
+5. Add or update a smoke check when a boundary should be enforced mechanically.
+
+## Adding or changing workflow skills
+
+- Edit the owning `skills/<name>/SKILL.md` file.
+- Keep trigger conditions, boundaries, handoff requirements, and stop conditions explicit.
+- If installed behavior changes, update `templates/`, adapter docs, and install release checks.
+
+## Changing CLI commands
+
+- `bin/vibe.mjs` should stay a thin wrapper.
+- Put command behavior in the owning `tools/vibe-*` module.
+- Update `README.md`, relevant tool README files, and release-check coverage when command surface changes.
+
+## Package and release boundaries
+
+The npm package should include curated project assets only. It must not include:
+
+```text
+fork/
+.tmp/
+.vibecoding/
+.vibecoding-state/
+node_modules/
+.git/
+.cursor/
+.cursor-local-assistant-v2/
+```
+
+Use `package.json.files` as the package allowlist and `npm run pack:dry-run` to inspect the result.
+
+## Submodules
+
+`fork/` contains reference repositories. They are not runtime dependencies and are not included in npm package contents. If you use a reference project to inform a design, copy the distilled conclusion into this repository's own docs, skills, adapters, or tools instead of copying third-party source.

package/docs/evidence-authoring.md

@@ -0,0 +1,188 @@
+# Evidence Authoring Guide
+
+本文档说明 Vibecoding Kit 的 evidence 文件应该如何产生、由谁负责，以及 runtime 会验证什么。
+
+核心边界：runtime 只验证用户或 CI 提供的本地 evidence envelope；它不运行测试、不读取 git diff、不提交、不调用平台 API。
+
+## Evidence Supply Chain v2
+
+P57 的证据链目标是让一次交付能从“为什么做”追到“能否收口”，但每一段仍由对应 owner 提供本地 artifact：
+
+```text
+需求 / 产品 / UI / 架构
+  -> implementation task registry
+  -> diff coverage
+  -> test evidence
+  -> completion evidence bundle
+```
+
+链路要求：
+
+- 需求、产品、UI、架构 artifact 给出验收来源和设计边界。
+- `Implementation Task Registry` 是 task refs 的唯一对齐点。
+- `diff-coverage.json` 解释哪些文件变化对应哪些 task refs。
+- `test-evidence.json` 解释哪些测试输出覆盖哪些 task refs 和 scenario refs。
+- completion bundle 只读汇总 evidence，不补跑测试、不读取真实 git、不替用户批准交付。
+
+如果 completion bundle 返回 `ok=false`，先把它当作 evidence gap：阅读 `completion_evidence.task_completion_summary`，再检查 `blocked_reasons`。不要把 `ok=false` 解释成系统失败，也不要通过扩权 runtime 来“修复”缺口。
+
+## 职责划分
+
+| 职责 | Owner | Vibecoding runtime 是否执行 |
+| --- | --- | --- |
+| 运行测试 | 用户 / CI | 否 |
+| 计算真实 diff coverage | 用户 / CI | 否 |
+| 生成 evidence envelope | 用户 / CI / agent 辅助后人工复核 | 否 |
+| 校验 envelope 字段、refs、digest 和边界声明 | Vibecoding runtime | 是，只读 |
+| 判断 completion readiness | Vibecoding runtime | 是，只读 |
+| `git add` / `commit` / `push` / PR / merge | 用户 | 否 |
+
+## Evidence 来源模式
+
+### 1. Manual evidence
+
+适合个人试用、小改动或临时迁移。
+
+要求：
+
+- 人工记录实际运行过的 command。
+- 保留 `timestamp`。
+- 保留 `output_digest`，即使它来自人工记录的输出摘要。
+- 明确 `task_refs` 和 `scenario_refs`。
+- 明确所有边界字段为 false。
+
+局限：manual evidence 依赖人的诚实和流程纪律，适合低风险或过渡阶段。
+
+### 2. CI generated evidence
+
+适合团队常规交付。
+
+推荐流程：
+
+```text
+CI runs tests / coverage / diff scripts
+  -> CI writes test-evidence.json / diff-coverage.json
+  -> user downloads or commits evidence artifact
+  -> runtime validates local envelope
+  -> human reviews readiness
+```
+
+runtime 不需要访问 CI API。CI URL、job id、artifact digest 可以作为普通字段或 evidence text 保留，但 runtime 只对当前 contract 中的 deterministic 字段做判断。平台无关的 CI evidence 生成流程见 `docs/ci-evidence-onboarding.md`。
+
+### 3. Agent assisted evidence
+
+适合让 agent 帮忙整理 evidence，但不适合让 agent 单方面声明可信。
+
+允许：
+
+- agent 根据用户提供的日志草拟 JSON envelope。
+- agent 检查 `task_refs`、`scenario_refs`、`changed_files` 是否对齐。
+- agent 提醒缺少 digest、timestamp 或边界字段。
+
+不允许：
+
+- agent 未经用户或 CI 证据就声称测试已通过。
+- agent 伪造 `output_digest` 的来源。
+- runtime 自动运行测试、读取 git diff 或提交。
+
+## Evidence Trust Tiers
+
+Evidence 的可信度来自生成来源，不来自 runtime 本身。runtime 只读验证 envelope 是否完整、可对齐、边界声明是否保守；它不会单独证明测试真的在可信环境运行过。
+
+| Tier | 名称 | 适用场景 | 最小要求 | runtime 能证明什么 |
+| --- | --- | --- | --- | --- |
+| `L1` | manual evidence | 个人试用、低风险修复、迁移过渡 | 人工记录 command、exit code、timestamp、digest、task refs | envelope 字段完整，refs / digest / boundary contract 可验证 |
+| `L2` | CI generated evidence | 团队常规交付 | CI 生成 `test-evidence.json` / `diff-coverage.json`，保留 job id、artifact digest 或日志摘要 | 本地 envelope 与 task / scenario / changed files 对齐 |
+| `L3` | provenance-backed evidence | 高风险发布、审计、合规 | CI artifact、受控存储、签名或可追溯构建日志提供来源证明 | runtime 验证本地 envelope；真实性由 CI/provenance 层证明 |
+
+采用建议：
+
+- 从 `L1` 跑通 team-mode 结构。
+- 团队稳定后，把测试和 diff coverage 生成迁移到 `L2`。
+- 只有发布审计或合规要求出现时，才要求 `L3`。
+
+不要通过扩权 runtime 来提高 trust tier。更高可信度应来自 CI/provenance，而不是让 runtime 自动运行测试、读 git diff 或提交。
+
+## 最小模板
+
+复制模板后再填写真实 evidence，不要直接信任示例占位值。模板目录内的最小 onboarding 说明见 `templates/evidence/README.md`：
+
+```bash
+cp templates/evidence/test-evidence.json test-evidence.json
+cp templates/evidence/diff-coverage.json diff-coverage.json
+```
+
+Windows PowerShell 可用：
+
+```powershell
+Copy-Item templates/evidence/test-evidence.json test-evidence.json
+Copy-Item templates/evidence/diff-coverage.json diff-coverage.json
+```
+
+### `test-evidence.json` 必填含义
+
+模板位置：`templates/evidence/test-evidence.json`。
+
+最小关注字段：
+
+- `runs[].command`：用户或 CI 实际运行过的测试命令。
+- `runs[].exit_code`：真实退出码。
+- `runs[].timestamp`：测试执行时间。
+- `runs[].output_digest`：测试输出或日志摘要的 digest，占位值必须替换。
+- `runs[].task_refs`：必须能对齐 `implementation-plan.md` 的 `Implementation Task Registry`。
+- `runs[].scenario_refs`：如果有 scenario artifact，应绑定对应 scenario；team-mode 最小 demo 可以保留团队自定义 scenario ref。
+- `boundary_assertions`：用于声明 runtime 没有执行命令、测试或 git 操作。
+
+### `diff-coverage.json` 必填含义
+
+模板位置：`templates/evidence/diff-coverage.json`。
+
+最小关注字段：
+
+- `planned_files`：计划中允许或预期触碰的文件。
+- `changed_files`：用户或 CI 观察到的实际变更文件。
+- `unexpected_files` / `missing_files`：显式记录偏差；非空通常会降低 readiness。
+- `task_coverage[].task_ref`：必须能对齐 `Implementation Task Registry`。
+- `task_coverage[].changed_files[].operation`：应匹配该 task 允许的操作，例如 `add`、`modify`、`docs`。
+- `task_coverage[].changed_files[].digest`：文件内容或 diff 片段摘要，占位值必须替换。
+- `boundary_assertions`：用于声明 runtime 没有读取 git diff、运行命令、测试或写 git。
+
+## 常见失败对照
+
+| blocked reason / 现象 | 通常原因 | 修复方向 |
+| --- | --- | --- |
+| 缺少 `output_digest` | `test-evidence.json` 仍是模板占位或没有记录测试输出摘要 | 用真实测试日志、CI artifact 或人工摘要重新计算 digest |
+| `task_refs` 无法对齐 | evidence 引用了 implementation plan 中不存在的 task id | 统一 `implementation-plan.md` 的 `Implementation Task Registry` 和 evidence refs |
+| `unexpected_files` 非空 | 实际改动超出计划文件 | 更新计划解释新增文件，或回收不属于本任务的改动 |
+| `operation mismatch` | diff coverage 的 operation 与计划允许操作不一致 | 修正 task 计划或 diff coverage 中的 operation |
+| `commit_execution_authorized=true` / `git_write=true` | evidence 把 git 动作授权给了 runtime | 改回 false；提交、push、PR 仍由用户或 CI 显式执行 |
+
+## Trust boundary
+
+Vibecoding Kit 能证明：
+
+- envelope 是本地可读 JSON。
+- 必要字段存在。
+- `task_refs` 能与 `Implementation Task Registry` 对齐。
+- `scenario_refs` 能与 scenario artifact 对齐。
+- `changed_files` 被 task coverage 解释。
+- operation、digest、unexpected/missing files 和边界声明符合 contract。
+
+Vibecoding Kit 不能单独证明：
+
+- 测试真的在可信环境运行过。
+- diff coverage 一定来自真实 git diff。
+- digest 一定由 CI 生成而不是人工填写。
+- 人工没有篡改 evidence。
+
+如果需要更高可信度，把真实性放到 CI / provenance 层：由 CI 生成 evidence，并通过构建日志、artifact digest、签名或受控存储提供来源证明；runtime 继续只读验证本地 envelope。
+
+## 推荐采用顺序
+
+1. 先跑 `examples/golden-path/`，理解最小 team-mode evidence 结构。
+2. 从 `templates/evidence/` 复制 `test-evidence.json` 和 `diff-coverage.json`。
+3. 在业务项目中手写一份 manual evidence，跑通 methodology gate 和 completion readiness。
+4. 把 `test-evidence.json` 和 `diff-coverage.json` 改为 CI 生成；具体流程见 `docs/ci-evidence-onboarding.md`。
+5. 高风险交付再升级到 full compliance bundle。
+
+不要为了降低摩擦而让 runtime 自动执行测试、读 git diff 或提交；这会破坏 Vibecoding Kit 的核心信任边界。

package/docs/golden-path.md

@@ -0,0 +1,179 @@
+# Golden Path：分层采用路径
+
+本文档给 Vibecoding Kit 的新用户和维护者一个最小上手路线。它不是新的 workflow，也不是自动执行系统；它只说明应该从哪一层开始采用证据链。
+
+文档层级：L2 团队采用层入口。首次安装先读 L1 的 `README.md`、`docs/user-guide.md` 和 `docs/quick-recipes.md`；只有维护 runtime、release 或长期治理时才进入 L3 的 `docs/runtime-roadmap.md`。
+
+## 目标
+
+- 先让用户跑通最小路径，再逐步升级到完整 evidence chain。
+- 降低首次理解成本，避免一开始要求用户掌握所有 artifact。
+- 保持 runtime 只读边界：不自动运行测试、不读取 git diff、不提交、不调用 subagent / MCP / platform API。
+
+## 两档体验与三层采用
+
+`safe governance mode` 是默认体验：轻量入口、本地只读、人工确认，适合 quickstart / team / full compliance 三层采用路径。
+
+`legacy-workflow-discipline mode` 只在显式 opt-in 时启用：它强化 `using-vibecoding` 入口纪律、连续计划推进、SDD task loop、evidence 串联、review blocker 和本地 transcript behavior eval。该模式仍只把 SDD dispatch、workspace contract、task-commit gate 和 evidence chain 写成 `.vibecoding-state/` 下的本地 sidecar；不真实调用 subagent、不自动创建 git worktree、不自动提交、不默认写业务源码。
+
+## 三层采用模型
+
+先按风险选最小足够层级：
+
+- `quickstart mode`：只证明安装和入口纪律，不要求业务 artifact。
+- `team mode`：常规功能交付，只要求 `product-spec.md`、`implementation-plan.md`、`test-evidence.json`、`diff-coverage.json`。
+- `full compliance mode`：只在高风险发布或审计时启用完整产品/UI/架构/验收/commit readiness 链路。
+
+| 模式 | 适合对象 | 需要理解的内容 | 推荐产物 | 验证方式 |
+| --- | --- | --- | --- | --- |
+| `quickstart mode` | 首次安装、个人试用、评估入口纪律 | 安装、doctor、workflow start、只读边界 | 无强制业务 artifact | `node bin/vibe.mjs doctor --root <project-root>` |
+| `team mode` | 团队规范、常规功能交付 | 需求到实现计划、测试证据 envelope、人工收口 | `product-spec.md`、`implementation-plan.md`、`test-evidence.json`、`diff-coverage.json` | methodology gate + completion readiness |
+| `full compliance mode` | 高风险交付、发布前审计、平台治理 | 完整产品/UI/架构/交付/测试/commit readiness 链路 | full-chain artifact bundle | `completion --evidence-bundle ... --json` |
+
+## Quickstart mode
+
+目标：证明项目入口已安装，并让 agent 遵守轻量 workflow 判断。`workflow --start` 是入口判断，不是“必须已有 workflow state 才能成功”的 gate；对新会话或规划类请求，缺少 state 通常表示需要先确认目标、范围、验收和验证策略，而不是 runtime failure。
+
+首次会话验收 prompt：`我想给这个项目加一个小功能，请先判断下一步。` 预期 agent 先按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`，输出 route、下一步人工动作和验证策略缺口；不注入完整 skill，不执行命令，不调用 subagent，不写源码或 git。
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform cursor
+node bin/vibe.mjs doctor --root ../my-project
+node tools/vibe-runtime/index.mjs workflow --start --prompt "implement a small feature" --json
+```
+
+边界：
+
+- 不需要先写完整 PRD。
+- 不创建 `.vibecoding-state/`。
+- 不执行 workflow skill。
+- 不调用 subagent。
+- 不写业务源码。
+
+## Team mode
+
+目标：让团队在不引入完整合规成本的前提下，形成可验证的交付闭环。
+
+如果想先跑通最小示例，使用仓库内 demo：
+
+```bash
+npm run demo:golden-path
+```
+
+维护本仓库时，runtime 分层 suite 只作为局部回归入口：改 UX / entry / advice 时优先跑 `npm run release:runtime:experience`，改 handoff / evidence / ledger 时优先跑 `npm run release:runtime:state`，改 hook / scheduler / subagent / platform 边界时优先跑 `npm run release:runtime:execution`。发布收口仍以 full `npm run release:runtime` 为准。若 release 收口或验证耗时异常，可加 `node tools/vibe-release-check/index.mjs --suite fast --timing --quiet` 查看维护者决策辅助；这只用于诊断耗时分布，不改变业务项目采用路径。
+
+等价底层命令如下：
+
+```bash
+node tools/vibe-runtime/index.mjs methodology --gate --kind product-spec --from-file examples/golden-path/product-spec.md --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind implementation-plan --from-file examples/golden-path/implementation-plan.md --json
+node tools/vibe-runtime/index.mjs completion --evidence-bundle --from-product-spec examples/golden-path/product-spec.md --from-plan examples/golden-path/implementation-plan.md --from-test-evidence examples/golden-path/test-evidence.json --from-diff-coverage examples/golden-path/diff-coverage.json --json
+```
+
+推荐最小产物：
+
+```text
+product-spec.md
+implementation-plan.md
+test-evidence.json      # 可从 templates/evidence/test-evidence.json 复制
+diff-coverage.json      # 可从 templates/evidence/diff-coverage.json 复制
+```
+
+建议顺序：
+
+```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 implementation-plan --from-file implementation-plan.md --json
+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
+```
+
+说明：这里的 evidence 文件由用户或 CI 提供。runtime 只检查 envelope、digest、task refs、scenario refs 和边界声明，不运行测试、不读取 git diff。team mode 的 completion bundle 用于生成 readiness 报告；如果故意省略 full compliance artifact，顶层 `ok` 可能为 `false`，这表示 full-chain artifact 不完整，不等于本地 evidence alignment 失败。最小闭环先看 `completion_evidence.task_completion_summary`：`local_task_ready=true` 且 `minimum_local_evidence_missing=[]` 表示 team-mode 本地任务已 ready；`full_compliance_evidence_missing` 只表示升级到 full compliance 前还缺 artifact 或 engineering evidence。需要定位本地失败时，再查看 `test_evidence_gate_ok`、`diff_coverage_gate_ok` 和 `implementation_alignment_ok`。更完整的判断顺序见 `docs/readiness-interpretation.md`；具体排障见 `docs/readiness-troubleshooting.md`。Evidence 模板位于 `templates/evidence/`，模板目录入口见 `templates/evidence/README.md`；生成责任、可信边界和 CI 接入建议见 `docs/evidence-authoring.md`。
+
+## Golden Path -> Your Project
+
+跑通仓库内 demo 后，把它迁移到业务项目时只复制最小 team-mode 资产，不复制 full-chain fixture。复制清单如下：
+
+```text
+product-spec.md              # 可从 templates/product-spec.md 起草
+implementation-plan.md       # 可从 templates/implementation-plan.md 起草
+test-evidence.json           # 从 templates/evidence/test-evidence.json 复制后替换真实值
+diff-coverage.json           # 从 templates/evidence/diff-coverage.json 复制后替换真实值
+```
+
+迁移时只做四件事：
+
+1. 用业务需求替换 `product-spec.md`，保留 artifact marker 和验收段落。
+2. 用真实任务替换 `implementation-plan.md` 的 `Implementation Task Registry`，确保每个 task 有稳定 `task_ref`、预期文件和 operation。
+3. 用真实测试或 CI 输出替换 `test-evidence.json` 的 `command`、`exit_code`、`timestamp`、`output_digest`、`task_refs` 和 `scenario_refs`。
+4. 用真实 changed files 替换 `diff-coverage.json` 的 `planned_files`、`changed_files`、`task_coverage[].task_ref`、`task_coverage[].changed_files[].operation` 和 digest。
+
+最后确认所有 `boundary_assertions` 仍声明 runtime 没有运行测试、读取 git diff 或写 git，并按顺序运行 gate。
+
+推荐业务项目验证命令：
+
+```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 implementation-plan --from-file implementation-plan.md --json
+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
+```
+
+判断方式：team mode 先看 `completion_evidence.task_completion_summary.local_task_ready` 和 `minimum_local_evidence_missing`。当 `local_task_ready=true` 且本地最小缺口为空时，本地 evidence gate 与 implementation alignment 已通过；只有发布审计、高风险变更或跨团队合规要求出现时，才按 `full_compliance_evidence_missing` 升级到 full compliance。
+
+Evidence 可信度建议从 `L1 manual evidence` 起步，团队常规交付升级到 `L2 CI generated evidence`，高风险交付再要求 `L3 provenance-backed evidence`。runtime 只验证本地 envelope；真实性证明属于 CI/provenance 层。
+
+## Full compliance mode
+
+目标：在发布前证明需求、产品、UI、架构、实现计划、测试证据、diff coverage 和 commit readiness 全链路可追踪。
+
+推荐产物：
+
+```text
+product-discovery.md
+product-spec.md
+ui-design-contract.md
+architecture-design.md
+delivery-traceability.yaml
+implementation-plan.md
+scenario-acceptance.yaml
+product-acceptance.md
+test-evidence.json
+diff-coverage.json
+commit-readiness.json
+evidence.json
+```
+
+可使用仓库内 full-chain reference 先跑通：
+
+```bash
+npm run demo:full-chain
+```
+
+等价底层命令如下：
+
+```bash
+node tools/vibe-runtime/index.mjs completion --evidence-bundle --from-product-discovery examples/full-chain/product-discovery.md --from-product-spec examples/full-chain/product-spec.md --from-ui-design examples/full-chain/ui-design-contract.md --from-architecture examples/full-chain/architecture-design.md --from-traceability examples/full-chain/delivery-traceability.yaml --from-plan examples/full-chain/implementation-plan.md --from-scenarios examples/full-chain/scenario-acceptance.yaml --from-product-acceptance examples/full-chain/product-acceptance.md --from-test-evidence examples/full-chain/test-evidence.json --from-diff-coverage examples/full-chain/diff-coverage.json --from-commit-readiness examples/full-chain/commit-readiness.json --from-evidence examples/full-chain/evidence.json --json
+```
+
+`examples/full-chain/` 是完整 compliance 正例，预期顶层 `ok=true`。它不替代 `examples/golden-path/`；Golden Path 仍然是 team-mode readiness demo。
+
+## 升级规则
+
+- 如果只是验证安装和入口纪律，停在 `quickstart mode`。
+- 如果团队开始要求任务、测试和 diff coverage 可追踪，升级到 `team mode`。
+- 如果交付需要跨产品、UI、架构、验收和 commit readiness 的审计，升级到 `full compliance mode`。
+- 不要为了“完整”而强迫所有任务走 full compliance；复杂度应该随风险升级。
+
+## 不变边界
+
+无论采用哪一层，Vibecoding Kit 都保持：
+
+- `automatic_next_skill_execution=false`
+- `test_execution=false`
+- `git_write=false`
+- `commit=false`
+- `push=false`
+- `pr=false`
+- `merge=false`
+- `subagent=false`
+- `mcp=false`
+- `platform_api=false`