@jtf19/vibecoding-kit 0.1.0

package/docs/workflow-chaining.md

@@ -0,0 +1,539 @@
+# Workflow Chaining：第一阶段流程调用与协作规范
+
+## 目标
+
+第一阶段不做复杂 runtime、MCP 编排器或 agent graph。
+
+流程协作采用轻量状态机：
+
+```text
+using-vibecoding 选择入口
+当前 workflow skill 完成当前阶段
+当前 workflow skill 输出 next_skill 和 handoff
+下一个 workflow skill 读取 handoff 后继续
+```
+
+## 核心原则
+
+- 显式声明下一步，不做隐式自动跳转。
+- 每个阶段只完成自己的职责。
+- 阶段之间通过 `Workflow Handoff` 传递状态。
+- 如果缺少必要输入，`next_skill` 必须是 `none`，并说明 `stop_condition`。
+- 第一阶段不保存数据库状态，不依赖 MCP，不调度多 agent。
+
+## Skill Route Registry Drift Guard
+
+`skill_route_registry_v1` 是 Stage 21 的只读漂移检查 marker。`using-vibecoding` 的轻量 route 表、runtime methodology route map、workflow readiness normalization、安装模板入口和本文档必须保持同一组机器可读字段：
+
+```text
+route_registry_id: skill-route:<intent>
+required_skill: <first workflow skill>
+next_gate: <spec|plan|tdd|debug|review|completion|automation|manual_workflow_judgment>
+stop_condition: <human-readable stop condition>
+handoff_required: true|false
+```
+
+该 registry 只用于 drift guard，不替代人类说明，不执行 workflow skill，不写状态，不调用 subagent / MCP / platform API，不触碰 git。
+
+## Skill Contract Schema Drift Guard
+
+`skill_contract_schema_v1` 是 Stage 22 的只读 skill 合同 schema marker。它把每个 workflow skill 的人类说明、handoff 和 gate marker 映射成 runtime-check 可解析字段，不替代 skill 文档，也不执行任何 workflow skill。
+
+```text
+entry_conditions: when the skill is allowed or required
+required_inputs: goal, scope, evidence, handoff, or review source needed before continuing
+required_outputs: route, plan, evidence, handoff, blocker, or next manual action expected from the skill
+stop_conditions: conditions that require asking the user or stopping before code/action claims
+handoff_contract: Workflow Handoff fields required for the next stage
+evidence_required_before_claiming_done: true|false|conditional
+forbidden_claims: claims the agent must not make without matching evidence or explicit user gate
+```
+
+该 schema 只用于 parser、drift guard 和 release/runtime-check 证据；不写 `.vibecoding-state/`，不调用 subagent / MCP / platform API，不触碰 git，不声明 skill 已执行。
+
+## Readiness Gate Split Drift Guard
+
+`readiness_gate_split_v1` 是 Stage 24 的只读 readiness gate 拆分 marker。它把“能不能说完成”“能不能本地 commit”“能不能请求 review”“能不能 handoff”“能不能作为 release candidate”拆成独立 gate：`report_done`、`local_commit`、`review_request`、`handoff`、`release_candidate`。
+
+```text
+readiness_gate_id: <report_done|local_commit|review_request|handoff|release_candidate>
+blocker_code: <MISSING_TEST_EVIDENCE|MISSING_DIFF_COVERAGE|MISSING_REVIEW_EVIDENCE|MISSING_LOCAL_COMMIT_AUTHORIZATION|MISSING_RELEASE_EVIDENCE>
+execution_authorized: false
+git_authorized: false
+platform_authorized: false
+```
+
+`readiness --gates --from-file <local-evidence-file> --json` 只读取本地 evidence 并输出各 gate 的 blocker code；`readiness --score` 仍然只表示 observability readiness score。local commit gate 只输出 readiness，不自动 `git add` / `git commit`，也不授权 PR、push、merge 或 release。
+
+## 分层采用边界
+
+Vibecoding Kit 支持从 `quickstart mode`、`team mode` 到 `full compliance mode` 渐进采用。分层采用只改变用户需要准备的 artifact 数量，不改变 runtime 行为边界：runtime 仍只做只读检查、显式 ledger 和 deterministic evidence 聚合，不自动执行 workflow skill、不运行测试、不读取 git diff、不提交、不调用 subagent / MCP / platform API。
+
+- `quickstart mode`：验证安装、入口文件、doctor 和 `workflow --start` 回执。`workflow --start` 只做只读入口判断；当没有 `.vibecoding-state/` 且请求本身是规划/分析/阶段推进时，缺少 goal/scope/acceptance 是“需要先收敛计划”的正常信号，不是 runtime failure。Stage 93 的 `workflow_discipline_summary` 同步声明 `tiny_context`、`full_skill_injection=false`、`skill_execution_claimed=false`、`command_execution_claimed=false`、`subagent_dispatch_claimed=false`、`git_write_claimed=false`，用于证明入口只推荐人工下一步。
+- `team mode`：用 `product-spec.md`、`implementation-plan.md` 和本地 evidence envelope 建立常规团队交付闭环。
+- `full compliance mode`：用完整 product/UI/architecture/delivery/implementation/test/diff/commit readiness artifact 形成发布前证据链。
+
+详细采用路径见 `docs/golden-path.md`。
+
+## 标准 Handoff 字段
+
+每个 workflow skill 输出末尾必须包含：
+
+```text
+## Workflow Handoff
+
+current_skill:
+next_skill:
+reason:
+handoff:
+  goal:
+  scope:
+  key_decisions:
+  files:
+  risks:
+  acceptance:
+stop_condition:
+```
+
+字段含义：
+
+- `current_skill`：当前完成的 workflow。
+- `next_skill`：建议进入的下一个 workflow；没有下一步时写 `none`。
+- `reason`：为什么进入这个下一步。
+- `handoff.goal`：当前目标。
+- `handoff.scope`：当前范围。
+- `handoff.key_decisions`：已经确定的关键决策。
+- `handoff.files`：相关文件或目录。
+- `handoff.risks`：风险和未验证点。
+- `handoff.acceptance`：验收标准。
+- `stop_condition`：停止条件或等待用户补充的信息。
+
+## Runtime Contract、只读检查和显式状态账本
+
+产品/UI 到交付收口的完整 evidence chain 现在包含 cross-artifact ref validation：`delivery-traceability.yaml` 中的 refs 必须能在 product/spec/UI/architecture/scenario/product acceptance artifact 中找到。`test-evidence.json` 只作为本地 evidence intake envelope，绑定 `command`、`exit_code`、`timestamp`、`output_digest`、`scenario_refs`；`diff-coverage.json` 只读取用户提供的 `planned_files`、`changed_files`、`unexpected_files`、`missing_files`；`commit-readiness.json` 或 runtime commit readiness envelope 只能作为人工 git 决策输入，保持 `commit_execution_authorized=false` 和 `git_write=false`。Release fast 同时包含 negative fixtures，证明坏 ref、缺 output digest、diff unexpected files 和 commit boundary 扩权会输出 `ok=false`。
+
+`docs/runtime-roadmap.md` 和 `docs/runtime-contract.md` 描述未来可选 runtime 层。
+
+当前 runtime 相关能力包含：
+
+```text
+node tools/vibe-runtime-check/index.mjs
+node tools/vibe-runtime/index.mjs status --json
+node tools/vibe-runtime/index.mjs validate-handoff --from-file handoff.md
+node tools/vibe-runtime/index.mjs validate-handoff --from-file handoff.md --json
+node tools/vibe-runtime/index.mjs record-handoff --from-file handoff.json
+node tools/vibe-runtime/index.mjs record-handoff --from-file handoff.md
+node tools/vibe-runtime/index.mjs next --dry-run
+node tools/vibe-runtime/index.mjs next --dry-run --json
+node tools/vibe-runtime/index.mjs next --dry-run --dispatch-intent
+node tools/vibe-runtime/index.mjs next --dry-run --dispatch-intent --json
+node tools/vibe-runtime/index.mjs next --confirm --dispatch
+node tools/vibe-runtime/index.mjs next --confirm --dispatch --json
+node tools/vibe-runtime/index.mjs dispatches --list
+node tools/vibe-runtime/index.mjs dispatches --list --json
+node tools/vibe-runtime/index.mjs dispatches --show <event-file>
+node tools/vibe-runtime/index.mjs dispatches --verify <event-file>
+node tools/vibe-runtime/index.mjs dispatches --claim <event-file> --actor <id>
+node tools/vibe-runtime/index.mjs dispatches --ack <event-file> --actor <id> --status picked
+node tools/vibe-runtime/index.mjs dispatches --claims
+node tools/vibe-runtime/index.mjs execute --from-dispatch <event-file> --dry-run
+node tools/vibe-runtime/index.mjs execute --from-dispatch <event-file> --confirm --actor <id>
+node tools/vibe-runtime/index.mjs execute --from-dispatch <event-file> --confirm --actor <id> --run
+node tools/vibe-runtime/index.mjs executions --list
+node tools/vibe-runtime/index.mjs executions --show <execution-file>
+node tools/vibe-runtime/index.mjs executions --verify <execution-file>
+node tools/vibe-runtime/index.mjs artifacts --dry-run
+node tools/vibe-runtime/index.mjs artifacts --write
+node tools/vibe-runtime/index.mjs tasks --dry-run
+node tools/vibe-runtime/index.mjs tasks --dry-run --json
+node tools/vibe-runtime/index.mjs tasks --dry-run --task task-1
+node tools/vibe-runtime/index.mjs tasks --dry-run --task task-1 --json
+node tools/vibe-runtime/index.mjs tasks --write
+node tools/vibe-runtime/index.mjs tasks --write --task task-1
+node tools/vibe-runtime/index.mjs methodology --gate --kind product-spec --from-file examples/runtime-fixtures/product-spec.md --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind ui-design --from-file examples/runtime-fixtures/ui-design-contract.md --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind scenario-acceptance --from-file examples/runtime-fixtures/scenario-acceptance.yaml --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind architecture-design --from-file examples/runtime-fixtures/architecture-design.md --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind delivery-traceability --from-file examples/runtime-fixtures/delivery-traceability.yaml --json
+node tools/vibe-runtime/index.mjs methodology --gate --kind implementation-plan --from-file examples/runtime-fixtures/implementation-plan.md --json
+node tools/vibe-runtime/index.mjs completion --evidence-bundle --from-product-discovery examples/runtime-fixtures/product-discovery.md --from-product-spec examples/runtime-fixtures/product-spec.md --from-ui-design examples/runtime-fixtures/ui-design-contract.md --from-architecture examples/runtime-fixtures/architecture-design.md --from-traceability examples/runtime-fixtures/delivery-traceability.yaml --from-plan examples/runtime-fixtures/implementation-plan.md --from-scenarios examples/runtime-fixtures/scenario-acceptance.yaml --from-product-acceptance examples/runtime-fixtures/product-acceptance.md --from-test-evidence examples/runtime-fixtures/test-evidence.json --from-diff-coverage examples/runtime-fixtures/diff-coverage.json --from-commit-readiness examples/runtime-fixtures/commit-readiness.json --from-evidence examples/runtime-fixtures/evidence.json --json
+node tools/vibe-runtime/index.mjs reset --confirm
+```
+
+输入格式和 dry-run 建议：
+
+- `JSON handoff` 是 Stage 3 推荐格式。
+- `JSON-first` 解析优先读取纯 JSON 文件或 markdown fenced JSON block。
+- `legacy fallback` 保留旧 YAML-like `Workflow Handoff` 兼容。
+- `methodology --gate --kind product-discovery|product-spec|ui-design|product-acceptance|scenario-acceptance --from-file <artifact>` 是产品/UI artifact 只读 gate；它检查 frontmatter、必填 section/field、evidence、handoff、boundary 和 digest，不执行 workflow skill。
+- `methodology --gate --kind architecture-design --from-file <artifact>` 是架构设计 artifact 只读 gate；它检查 architecture decision frame、module ownership、dependency direction、data flow、state lifecycle、contract sync、blast radius、verification strategy、Evidence 和 Boundary。
+- `methodology --gate --kind delivery-traceability --from-file <artifact>` 是交付追踪矩阵只读 gate；它检查需求、产品、UI、架构、任务、测试、场景、验收和 commit-readiness ref 是否形成可追踪 links。
+- `methodology --gate --kind implementation-plan --from-file <artifact>` 是实现计划 task registry 只读 gate；它检查 `Implementation Task Registry` 中的 `task_id`、expected files、allowed paths、expected operations、risk/test contract 和 Boundary。
+- `completion --evidence-bundle --from-product-discovery ... --from-evidence ...` 是产品/UI 完成前 evidence bundle；提供 `--from-architecture`、`--from-traceability`、`--from-plan`、`--from-test-evidence`、`--from-diff-coverage` 和 `--from-commit-readiness` 时，会聚合完整交付链路，并验证 `implementation_alignment_gate`，但仍不运行测试、浏览器或 git。
+- `record-handoff` 成功后输出 `Handoff quality:`，提示空范围、风险、验收、相关文件、证据和停止条件语义；提示不拒绝写入、不改变 ledger 结构、不执行下一步。
+- `next --dry-run` 输出 `idle` / `ready` / `blocked` / `stopped` 文本建议，并可展示任务状态和 review 状态摘要。
+- `next --dry-run --dispatch-intent` 只读输出 adapter-ready dispatch intent 预览；`--json` 版本包含 `runtimeBridge`、`platform_hints`、transition / stop_condition / review / task readiness gate 和 `dispatch_event=false` safety 标记。
+- `next --confirm --dispatch` 是显式 confirm-dispatch gate；成功只写 `.vibecoding-state/dispatches/<timestamp>.json`，不自动执行 skill、不调用平台 API、不调用 subagent / MCP / daemon、不触碰 git / worktree。
+- `dispatches --list`、`dispatches --show <event-file>` 和 `dispatches --verify <event-file>` 是 read-only dispatch audit；只读取 dispatch event 并做 confirm-dispatch event verification，不标记 consumed、不执行 skill、不写文件。
+- `dispatches --claim <event-file> --actor <id>` 是 Stage 7 显式 claim gate；通过 event verification 后只写 `.vibecoding-state/dispatch-claims/<event-file>.claim.json`，不修改原始 dispatch event，不执行 skill，不调用平台 API、不调用 subagent / MCP / daemon、不触碰 git / worktree。
+- `dispatches --ack <event-file> --actor <id> --status picked|skipped|failed` 只更新 claim state；ack 必须由同一 actor 执行，重复 active claim、未 claim、actor mismatch、非法 status 或非法 event 都必须失败。Stage 7 不使用 `consumed` 状态；`skipped` / `failed` 必须提供 non-empty reason，ack 前必须通过 claim event digest enforcement。
+- `dispatches --claims` 只列出 claim state 摘要，缺少 claim 目录时返回空列表且不创建目录；摘要包含 stale claim audit、event digest match 和 recovery preview，`reassign_allowed=false` / `retry_allowed=false`。
+- `dispatches --pickup <event-file>` 是 Stage 8 pickup package；只读输出 adapter / human 可复制的 pickup package，不自动 claim、不创建 session、不执行 skill。
+- `dispatches --pickup-verify <event-file>` 独立验证 pickup package，`dispatches --pickup-dry-run <event-file>` 模拟 adapter 会读取的 entry、dispatch、claim 和 digest；Claude 使用 `CLAUDE.md`，Cursor / Codex 使用 `AGENTS.md`，三者均为 manual/no-session/no-API/no-stdin automation。
+- Stage 8 pickup package 输出 readiness、pickup verification、platform capability matrix、no-session adapter dry-run 以及 `event_sha256` / `claim_sha256` / `workflow_sha256` / `handoff_sha256` digest-bound package。
+- `execute --from-dispatch <event-file> --preflight` 只读输出 execution preflight audit，不写 execution envelope。
+- `execute --from-dispatch <event-file> --dry-run` 只预览 execution plan，不写 execution envelope。
+- `execute --from-dispatch <event-file> --confirm --actor <id>` 是 Stage 9 planned execution envelope；只写 `.vibecoding-state/executions/`，不执行 workflow skill。
+- 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`、execution policy snapshot 和 write boundary preview。兼容 marker 仍保留 Stage 9.1 execution preflight gates、Stage 9.2 execution preflight audit / planned execution envelope、Stage 9.3 immutability guarantees 和 Stage 9.5 idempotency / policy snapshot。
+- `daemon --dry-run` 只预览 once-run gate，`daemon --scan --dry-run` 只读输出 scheduler audit，`daemon --once --confirm` 只写 no-op daemon run envelope。
+- Stage 10.3-10.6/10.8/10.11-10.13 覆盖 candidates、blocked items、stale claims、stale running executions、retry preview、`retry_allowed=false`、lock / lease contract、watcher disabled、`scan_noop=true`、`scheduler_policy_dry_run=true` 和 `heartbeat_started=false`；不创建真实 worker、不 pickup、不 execute、不 retry、不改 dispatch/claim/execution。
+- `execute --from-dispatch <event-file> --confirm --actor <id> --run` 是 Stage 11 supervised-run；只执行 allowlist 内本地受监管 runtime action，生成 handoff package / evidence，并写 execution lifecycle record。
+- `executions --list`、`executions --show <execution-file>` 和 `executions --verify <execution-file>` 是 read-only execution audit；只读取 `.vibecoding-state/executions/`，不写状态、不执行 skill。
+- Stage 11 保持 `runtime_action=true`、`skill_execution=false`、`auto_execution=false`；不调用平台 API，不调用 subagent / MCP / daemon，不触碰 git / worktree，不写业务源码，不修改 dispatch event 或 claim state。
+- `artifacts --dry-run` 预览 task brief、review gate 和 evidence skeleton，不写文件。
+- `artifacts --write` 只写 `.vibecoding-state/*.md` 产物，不写业务源码、不执行 `next_skill`。
+- `tasks --dry-run` 预览任务级 brief、report、review gate 和 evidence skeleton，不写文件。
+- `tasks --dry-run --json` 输出 machine-readable task selection，不输出 artifact 正文，不写文件。
+- `tasks --dry-run --task <task-id> --json` 的 `tasks` 列表只包含选中 task，`summary.selected_count=1`；readiness / `blocked_by` 仍按完整 ledger dependency graph 计算。
+- `tasks --write` 只写 `.vibecoding-state/tasks/<task-id>/*.md` 产物，不写业务源码、不执行任务、不调用 subagent；task id 必须通过路径安全校验。
+- 写入类命令遇到 `--json` 必须明确失败，包括 `record-handoff --json`、`artifacts --json`、`tasks --write --json` 和 `reset --json`。
+- 任务级 `review_status` 只用于状态摘要和 review gate artifacts，不触发 review 执行或 workflow 自动推进。
+- `stop_condition` 有实际内容时，建议状态必须是 `blocked`。
+- no automatic next_skill execution：runtime 只记录和建议，不执行下一步。
+
+边界：
+
+- runtime 是可选层，不替代 workflow skill。
+- `.vibecoding-state/` 只在用户显式运行 `record-handoff` 时创建。
+- `status` 只读，不创建文件；有状态时展示当前 ledger 摘要。
+- `next --dry-run` 只输出建议，不执行 `next_skill`。
+- `artifacts --dry-run` 只预览文件化产物，不写文件；`task-brief.md` 聚焦任务交接，`review-gate.md` 聚焦 review 风险和完成门禁，`evidence.md` 聚焦已有证据和待补验证。
+- `artifacts --write` 只写 `.vibecoding-state/*.md`。
+- `reset --confirm` 只删除 `.vibecoding-state/`。
+- 当前不调用 subagent。
+- 当前不创建 worktree、不执行 git 写入、不安装依赖。
+- 当前不引入 MCP、agent graph、daemon 或后台 worker。
+
+## Hook 辅助自动化
+
+Hook 辅助自动化只把显式流程规则变成提示，不改变流程边界。
+
+可使用的提示模板：
+
+```text
+hooks/session-start/session-start.md
+hooks/workflow-handoff/workflow-handoff.md
+hooks/post-tool-compact/README.md
+```
+
+作用范围：
+
+- `session-start`：提醒先选择 workflow，并识别目标、范围、风险、验收和 `next_skill`。
+- `workflow-handoff`：提醒阶段结束后检查 `Workflow Handoff`。
+- `post-tool-compact`：提醒长输出需要显式压缩或交接。
+
+边界：
+
+- hook 只提醒，不自动执行下一个 skill。
+- hook 不调用工具。
+- hook 不维护 runtime 状态机。
+- `next_skill` 仍是显式建议，不是自动跳转。
+
+## 流程图
+
+### 新功能 / 产品功能 / 重构
+
+```text
+using-vibecoding
+  -> vibe-brainstorming
+  -> vibe-product-discovery      # 需要产品问题、用户、场景或指标发现时
+  -> vibe-product-spec           # 需要 PRD / capability spec 时
+  -> vibe-ui-design              # 涉及界面、交互、UI 状态或可访问性时
+  -> vibe-planning
+  -> vibe-writing-plans
+  -> vibe-test-driven-development
+  -> vibe-executing-plans
+  -> vibe-product-acceptance     # 存在产品规格或 UI contract 时
+  -> vibe-verification-before-completion
+  -> vibe-finishing-a-development-branch
+  -> none
+```
+
+### 计划并行边界判断
+
+```text
+using-vibecoding
+  -> vibe-writing-plans
+  -> vibe-dispatching-parallel-work
+  -> vibe-test-driven-development | vibe-subagent-driven-development | vibe-workspace-isolation | vibe-writing-plans | vibe-planning | none
+```
+
+### Subagent 执行 gate
+
+```text
+using-vibecoding
+  -> vibe-subagent-driven-development
+  -> vibe-verification-before-completion | vibe-dispatching-parallel-work | vibe-writing-plans | vibe-workspace-isolation | vibe-test-driven-development | vibe-executing-plans | none
+```
+
+### 工作区隔离边界判断
+
+```text
+using-vibecoding
+  -> vibe-workspace-isolation
+  -> vibe-writing-plans | vibe-subagent-driven-development | vibe-test-driven-development | vibe-finishing-a-development-branch | none
+```
+
+### 明确小任务
+
+```text
+using-vibecoding
+  -> vibe-test-driven-development
+  -> vibe-implementation
+  -> vibe-verification-before-completion
+  -> none
+```
+
+### Bug / 失败 / 异常行为
+
+```text
+using-vibecoding
+  -> vibe-systematic-debugging
+  -> vibe-test-driven-development
+  -> vibe-implementation
+  -> vibe-verification-before-completion
+  -> none
+```
+
+### Review
+
+```text
+using-vibecoding
+  -> vibe-requesting-code-review
+  -> vibe-review
+  -> vibe-receiving-code-review | vibe-verification-before-completion | none
+```
+
+### Skill 编写
+
+```text
+using-vibecoding
+  -> vibe-writing-skills
+  -> vibe-writing-plans | vibe-test-driven-development | vibe-planning | none
+```
+
+### 上下文压缩
+
+```text
+using-vibecoding
+  -> vibe-context-compact
+  -> none
+```
+
+## 各 Skill 下一跳规则
+
+### `vibe-product-discovery`
+
+- 产品问题、目标用户、场景和指标明确：`next_skill: vibe-product-spec`。
+- 只是明确小工程任务：`next_skill: vibe-planning`。
+- 问题或价值假设仍不清：`next_skill: none`。
+- 原始目标需要重新定义：`next_skill: vibe-brainstorming`。
+
+### `vibe-product-spec`
+
+- 有界面、交互、文案或体验影响：`next_skill: vibe-ui-design`。
+- 无 UI 影响且规格清楚：`next_skill: vibe-planning`。
+- 产品问题或切片不清：`next_skill: vibe-product-discovery`。
+- 缺少关键决策：`next_skill: none`。
+
+### `vibe-ui-design`
+
+- UI contract 明确：`next_skill: vibe-planning`。
+- 产品规格不清：`next_skill: vibe-product-spec`。
+- 不存在 UI 影响：`next_skill: vibe-planning`。
+- 缺少关键视觉或交互决策：`next_skill: none`。
+
+### `vibe-product-acceptance`
+
+- 产品体验验收通过：`next_skill: vibe-verification-before-completion`。
+- 工程实现缺口明确：`next_skill: vibe-implementation`。
+- 架构或任务边界需要调整：`next_skill: vibe-planning`。
+- 产品规格需要调整：`next_skill: vibe-product-spec`。
+- 缺少验收证据且无法补齐：`next_skill: none`。
+
+### `vibe-brainstorming`
+
+- 方向、约束和方案已确认：`next_skill: vibe-planning`
+- 发现只是明确小任务：`next_skill: vibe-implementation`
+- 需求仍不清或等待用户决策：`next_skill: none`
+
+`vibe-runtime` 只把这些 `next_skill` 建议转成可审计状态：Stage 6 写 dispatch event，Stage 7 写 claim / ack，Stage 8 输出 pickup package，Stage 9 `execute --from-dispatch` 只在人工确认后写 execution envelope，Stage 10 `daemon --once --confirm` 只写 daemon run envelope。它不隐式自动跳转、不执行目标 skill、不调用平台 API、不调度多 agent、不依赖 MCP、不启动 watcher / long-running worker、不触碰 git / worktree。
+
+### `vibe-planning`
+
+- 计划明确但还需要拆成可执行任务：`next_skill: vibe-writing-plans`
+- 小任务范围明确且可直接落地：`next_skill: vibe-implementation`
+- 需求不清：`next_skill: none`
+- 发现目标本身需要重新澄清：`next_skill: none`
+
+### `vibe-writing-plans`
+
+- 计划完整且可执行，并且没有工作区隔离或并行边界判断需求：`next_skill: vibe-test-driven-development`
+- 任务存在大范围改动、风险性重构或当前工作区污染风险，需要先判断是否隔离：`next_skill: vibe-workspace-isolation`
+- 任务存在独立并行候选，需要先判断冲突边界和任务 brief：`next_skill: vibe-dispatching-parallel-work`
+- 需求或范围不清：`next_skill: vibe-planning`
+- 缺少关键输入：`next_skill: none`
+
+### `vibe-dispatching-parallel-work`
+
+- 任务独立、brief 完整，但执行前需要判断是否隔离当前工作区：`next_skill: vibe-workspace-isolation`
+- 任务独立、brief 完整、用户明确允许 subagent，且工作区边界清楚：`next_skill: vibe-subagent-driven-development`
+- 任务独立、brief 完整、用户允许后续并行执行，且工作区边界清楚但不使用 subagent：`next_skill: vibe-test-driven-development`
+- 任务不独立或冲突风险高，但可顺序执行：`next_skill: vibe-test-driven-development`
+- 任务边界、依赖或验收不清：`next_skill: vibe-writing-plans`
+- 需求范围需要重新澄清：`next_skill: vibe-planning`
+- 缺少关键输入或用户未允许并行策略且后续必须并行才有意义：`next_skill: none`
+
+### `vibe-workspace-isolation`
+
+- 当前任务可原地工作且还需拆解：`next_skill: vibe-writing-plans`
+- 当前任务可原地工作、任务 brief 已完整且用户明确允许 subagent：`next_skill: vibe-subagent-driven-development`
+- 当前任务可原地工作且验证策略可直接定义：`next_skill: vibe-test-driven-development`
+- 当前已经在可接受隔离环境且任务还需拆解：`next_skill: vibe-writing-plans`
+- 当前已经在可接受隔离环境、任务 brief 已完整且用户明确允许 subagent：`next_skill: vibe-subagent-driven-development`
+- 当前已经在可接受隔离环境且验证策略可直接定义：`next_skill: vibe-test-driven-development`
+- 当前工作区有未收口变更：`next_skill: vibe-finishing-a-development-branch`
+- 建议创建隔离工作区但需要用户确认：`next_skill: none`
+- 隔离判断所需信息不足：`next_skill: none`
+
+### `vibe-test-driven-development`
+
+- 验证策略明确且来自计划执行：`next_skill: vibe-executing-plans`
+- 验证策略明确且是明确小任务：`next_skill: vibe-implementation`
+- 验收或行为不清：`next_skill: vibe-planning`
+- 无法定义可靠验证且阻塞：`next_skill: none`
+
+### `vibe-executing-plans`
+
+- 所有任务完成：`next_skill: vibe-verification-before-completion`
+- 执行中发现验证失败且原因不明：`next_skill: vibe-systematic-debugging`
+- 计划缺陷阻塞执行：`next_skill: vibe-writing-plans`
+- 范围变化：`next_skill: vibe-planning`
+- 缺少用户确认：`next_skill: none`
+- 用户改为明确允许 subagent 且任务 brief 已完整：`next_skill: vibe-subagent-driven-development`
+
+### `vibe-subagent-driven-development`
+
+- brief 完整、用户允许、工作区边界清楚，且后续执行和 review gate 已完成：`next_skill: vibe-verification-before-completion`
+- brief 不完整或任务边界不清：`next_skill: vibe-dispatching-parallel-work` 或 `next_skill: vibe-writing-plans`
+- 工作区边界未确认：`next_skill: vibe-workspace-isolation`
+- 用户不允许 subagent、平台不支持或任务强耦合但可顺序执行：`next_skill: vibe-test-driven-development` 或 `next_skill: vibe-executing-plans`
+- review feedback 需要处理：`next_skill: vibe-receiving-code-review`
+- 验证失败且原因不明：`next_skill: vibe-systematic-debugging`
+- 缺少关键输入或必须等待用户确认：`next_skill: none`
+
+### `vibe-debugging`
+
+- 根因明确且需要修改：`next_skill: vibe-implementation`
+- 无法复现、证据不足或需要用户补充环境：`next_skill: none`
+- 问题实际来自需求或边界不清：`next_skill: vibe-planning`
+
+### `vibe-systematic-debugging`
+
+- 根因明确且修复范围清楚：`next_skill: vibe-test-driven-development`
+- 根因明确且已有计划任务：`next_skill: vibe-test-driven-development`
+- 无法复现或证据不足：`next_skill: none`
+- 发现需求或验收不清：`next_skill: vibe-planning`
+
+### `vibe-implementation`
+
+- 实现完成：`next_skill: vibe-verification-before-completion`
+- 实现中发现范围变化：`next_skill: vibe-planning`
+- 发现新异常：`next_skill: vibe-systematic-debugging`
+
+### `vibe-writing-skills`
+
+- skill 设计明确且需要拆成实施任务：`next_skill: vibe-writing-plans`
+- 只是小改已有 skill 且范围明确：`next_skill: vibe-test-driven-development`
+- skill 边界、触发场景或验收不清：`next_skill: vibe-planning`
+- 缺少关键输入：`next_skill: none`
+
+### `vibe-requesting-code-review`
+
+- review 输入完整：`next_skill: vibe-review`
+- 缺少完成前验证证据：`next_skill: vibe-verification-before-completion`
+- review 范围或验收依据不清：`next_skill: vibe-planning`
+- 缺少关键输入：`next_skill: none`
+
+### `vibe-review`
+
+- 有阻塞或高风险 feedback 需要处理：`next_skill: vibe-receiving-code-review`
+- 有阻塞问题且修复路径明确：`next_skill: vibe-test-driven-development`
+- 仅需验证：`next_skill: vibe-verification-before-completion`
+- 无需继续：`next_skill: none`
+
+### `vibe-receiving-code-review`
+
+- feedback 明确且需要修复：`next_skill: vibe-test-driven-development`
+- feedback 需要先复现或定位根因：`next_skill: vibe-systematic-debugging`
+- feedback 涉及需求、范围或架构冲突：`next_skill: vibe-planning`
+- feedback 无需处理或已给出技术性拒绝理由：`next_skill: vibe-verification-before-completion`
+- feedback 不清楚或缺少关键上下文：`next_skill: none`
+
+### `vibe-verification`
+
+- 阶段性验证通过但尚未做完成前证据确认：`next_skill: vibe-verification-before-completion`
+- 已经完成交付前证据确认：`next_skill: none`
+- 验证失败且原因不明：`next_skill: vibe-systematic-debugging`
+- 验证失败但修复明确：`next_skill: vibe-implementation`
+
+### `vibe-verification-before-completion`
+
+- 证据充分且无阻塞：`next_skill: vibe-finishing-a-development-branch`
+- 证据不足但可以补验证：`next_skill: vibe-verification`
+- 验证失败且原因不明：`next_skill: vibe-systematic-debugging`
+- 验证失败且修复明确：`next_skill: vibe-implementation`
+- 验收标准不清：`next_skill: vibe-planning`
+
+### `vibe-finishing-a-development-branch`
+
+- 验证不足：`next_skill: vibe-verification-before-completion`
+- 发现明确修复缺口：`next_skill: vibe-implementation`
+- 用户选择继续提交或 PR：`next_skill: none`
+- 用户选择保留或停止：`next_skill: none`
+
+### `vibe-context-compact`
+
+- 默认：`next_skill: none`
+- 用户明确要求继续：按 handoff 中的 `下一步` 选择对应 skill。
+
+## 输出约束
+
+- 不要把 `Workflow Handoff` 写成可选项。
+- 不要省略 `next_skill`。
+- 不要在 stop_condition 未满足时继续执行。
+- 不要把“建议”伪装成已经完成的下一阶段。
+
+## 示例
+
+```text
+## Workflow Handoff
+
+current_skill: vibe-planning
+next_skill: vibe-implementation
+reason: 目标、范围、模块和验收标准已经明确，可以进入实现。
+handoff:
+  goal: 增加 Cursor adapter 的安装说明。
+  scope: 只修改 docs 和 adapters/cursor。
+  key_decisions:
+    - 第一阶段不实现复杂 hook runtime。
+  files:
+    - docs/install-cursor.md
+    - adapters/cursor/install.md
+  risks:
+    - 未在真实 Cursor 插件环境中验证。
+  acceptance:
+    - 文档说明安装路径。
+    - 验收 prompt 能触发 verification 流程。
+stop_condition: none
+```

package/examples/ci/README.md

@@ -0,0 +1,61 @@
+# CI Evidence Examples
+
+These scripts are CI/user-side evidence producers. They do not belong to runtime core and do not make evidence trusted by themselves.
+
+## Evidence Supply Chain v2
+
+P57 treats this folder as a producer example in the wider local evidence chain:
+
+```text
+ci-evidence-input.example.json
+  -> generate-test-evidence.mjs / generate-diff-coverage.mjs
+  -> local evidence JSON
+  -> read-only completion evidence bundle
+  -> human readiness decision
+```
+
+The scripts only transform CI/user-provided facts into local JSON. They do not read real git diff, do not run tests, do not call CI APIs, and do not convert `ok=false` into a system failure.
+
+`github-actions-readiness.yml` is an example recipe only. It lives under `examples/ci/`, not `.github/workflows/`, so this repository does not auto-enable it.
+
+## Generate 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
+```
+
+Then run the read-only completion bundle gate:
+
+```bash
+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
+```
+
+## Starter kit data contract
+
+The starter kit has one narrow data flow:
+
+```text
+project test/diff facts -> ci-evidence-input.json -> generated evidence JSON -> read-only completion bundle
+```
+
+Replace the example input with project-owned values before using it in a real CI job:
+
+- test command, exit code, timestamp and output digest.
+- planned files, changed files and per-file digest.
+- implementation task refs and scenario refs.
+- boundary assertions showing runtime did not execute tests, read git diff or write git.
+
+## GitHub Actions recipe
+
+`examples/ci/github-actions-readiness.yml` shows the intended CI data flow:
+
+1. CI runs the real project test command.
+2. CI captures exit code, timestamp, output digest and changed-file metadata.
+3. CI calls `generate-test-evidence.mjs` and `generate-diff-coverage.mjs` to write local JSON evidence.
+4. CI calls `completion --evidence-bundle` for read-only validation.
+5. CI uploads JSON artifacts using CI-owned artifact storage.
+
+Copy the file into `.github/workflows/readiness.yml` in a business project only when you explicitly want to enable it. Keep task refs, scenario refs, planned files and changed files project-specific.
+
+Boundary: the scripts generate local JSON evidence from CI/user-provided input. `vibe-runtime` still does not run tests, read git diff, call CI APIs, commit, push, create PRs, call subagents, or call MCP.

package/examples/ci/ci-evidence-input.example.json

@@ -0,0 +1,56 @@
+{
+  "test": {
+    "id": "test-golden-path-demo",
+    "evidence_ref": "test-golden-path-demo",
+    "command": "npm run demo:golden-path",
+    "exit_code": 0,
+    "timestamp": "2026-03-14T00:00:00.000Z",
+    "output_text": "Result: passed",
+    "task_refs": ["task-golden-path-demo"],
+    "scenario_refs": ["scenario-golden-path-demo"]
+  },
+  "diff": {
+    "evidence_ref": "diff-golden-path-demo",
+    "planned_files": [
+      "examples/golden-path/README.md",
+      "examples/golden-path/product-spec.md",
+      "examples/golden-path/implementation-plan.md",
+      "examples/golden-path/test-evidence.json",
+      "examples/golden-path/diff-coverage.json"
+    ],
+    "changed_files": [
+      {
+        "path": "examples/golden-path/README.md",
+        "operation": "docs",
+        "task_ref": "task-golden-path-demo",
+        "digest_source": "golden-path readme fixture"
+      },
+      {
+        "path": "examples/golden-path/product-spec.md",
+        "operation": "docs",
+        "task_ref": "task-golden-path-demo",
+        "digest_source": "golden-path product spec fixture"
+      },
+      {
+        "path": "examples/golden-path/implementation-plan.md",
+        "operation": "docs",
+        "task_ref": "task-golden-path-demo",
+        "digest_source": "golden-path implementation plan fixture"
+      },
+      {
+        "path": "examples/golden-path/test-evidence.json",
+        "operation": "add",
+        "task_ref": "task-golden-path-demo",
+        "digest_source": "golden-path test evidence fixture"
+      },
+      {
+        "path": "examples/golden-path/diff-coverage.json",
+        "operation": "add",
+        "task_ref": "task-golden-path-demo",
+        "digest_source": "golden-path diff coverage fixture"
+      }
+    ],
+    "unexpected_files": [],
+    "missing_files": []
+  }
+}