@jtf19/vibecoding-kit 0.1.0

package/templates/CLAUDE.md

@@ -0,0 +1,88 @@
+<!-- vibecoding:start version=0.2.0 -->
+# CLAUDE.md
+
+本项目使用 Vibecoding Kit。你可以把它理解成一个受控 agent 沙盒：正常向 agent 提需求，agent 会先做轻量任务分流，再按风险选择最小合适流程，完成前绑定验证证据。
+
+默认真实模式是 **Vibe Guided**（`automation_profile: "vibe-guided"`）。`default` 是旧配置兼容别名；新安装使用 `vibe-guided`。
+
+## 你怎么用
+
+直接描述任务即可，例如：
+
+```text
+帮我实现这个小功能。
+先定位这个 bug 的原因。
+帮我确认这个分支能不能交付。
+```
+
+默认规则：
+
+- 小任务：直接处理，完成前做最小验证。
+- 不清楚或有风险的任务：先确认目标、范围、验收和验证方式。
+- bug 或失败：先复现并定位根因，再修改。
+- 交付或收口：先看验证证据，再判断能否交付。
+- review feedback：先分类，判断是否阻塞，再说明修复和验证路径。
+
+## 业务项目降级交互协议
+
+安装后的业务项目默认使用轻量产品体验：先做任务分流和证据判断，只有风险、阶段切换或交接需要时才显式进入完整 workflow。不要把源码仓库维护者路线图、runtime stage 长表或 release 内部检查强塞给普通业务任务。
+
+## 首次会话验收
+
+第一次会话只检查入口体验是否正确，不要求执行 workflow skill：
+
+- agent 先按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`，再做 `using-vibecoding` 轻量分流。
+- 目标不清时先澄清目标、范围和验收。
+- 输出可见下一步人工动作，而不是隐藏执行。
+- 不注入完整 skill 内容，不自动测试，不调用 subagent，不触碰 git / PR / push / merge。
+
+## Start Here Contract / Agent 入口
+
+workflow skills 位于 `.vibecoding/skills/`。处理开发任务前，先按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`，并按其规则完成轻量 workflow 判断。不要只按平台原生 Skill registry 检索 `using-vibecoding`；如果该文件存在但 registry 未注册，不应提示入口缺失。
+
+Start Here Contract：入口只做轻量 route、当前人工下一步、验证策略或证据缺口；不注入完整 workflow skill 长表，不执行命令，不调用 subagent，不触碰 git。
+
+需要本地只读辅助时，可在 Vibecoding Kit 所在位置运行：
+
+```bash
+node tools/vibe-runtime/index.mjs workflow --start --prompt "<request>" --json --root <project-root>
+```
+
+摘要优先入口：先读 `workflow_start.entry_summary`。如果 `entry_summary.state_gap_is_expected=true`，说明当前请求适合先收敛目标、范围或验收，不是 runtime failure。
+
+`skill_route_registry_v1` 只用于检查 `using-vibecoding`、runtime route map、模板入口和 workflow 文档是否同步；它不授权执行、写源码、subagent、平台 API 或 git。
+
+## 入口上下文策略
+
+默认使用 `tiny_context`：只加载 `.vibecoding/skills/using-vibecoding/SKILL.md` 中的入口判断、当前人工下一步和安全边界，避免 `no_full_skill_injection_by_default` 退化。
+
+需要实现、排障或完成前验证时，可升级到 `balanced_context`：补充当前 profile、证据摘要和少量 recipe，但仍不展示完整 runtime stage 长表。
+
+`full_maintenance_context` 只给维护者显式使用，用于查看 runtime stage、release/check marker 或长期治理说明；业务项目默认不使用。
+
+判断能否交付时，先读 `completion_evidence.task_completion_summary`。只有摘要指出证据缺口时，再看 `blocked_reasons`、readiness gates 和底层 evidence detail。
+
+P61 marker：`p61_token_context_economy_v2`、`prompt_mutation=false`、`embeddings=false`、`remote_config=false`、`dynamic_tool_execution=false`、`model_invocation=false`、`command_execution=false`。
+
+## Installed Agent Experience Contract v2
+
+安装后的业务项目使用一屏可验收合同，而不是维护者 runtime stage 长表；机器可检合同 kind 为 `installed-agent-experience-contract-v2`。
+
+覆盖 prompt：`first_turn`、`continue_task`、`bug_debug`、`completion_closeout`、`review_feedback`。Stage 25 marker：`installed_business_ux_regression_pack` 要求默认 `tiny_context`、一屏轻量体验、`full_maintenance_context` 和维护者 runtime stage 长表不默认展示。
+
+固定禁止 marker：`hidden_execution=false`、`command_execution=false`、`skill_execution_claimed=false`、`subagent_dispatch_claimed=false`、`business_source_write=false`、`git_write_claimed=false`、`platform_api=false`、`model_invocation=false`。
+
+## Profile 说明
+
+默认安装后是轻量治理：`automation_profile` 使用 `vibe-guided`，`execution_profile` 使用 `manual`。这表示 agent 可以做任务分流和证据判断，但不获得自动执行、自动测试、业务源码写入或 git 写入许可。
+
+`execution-enabled` 需要用户显式配置才可用，并绑定 `controlled-local-runtime`。开启它只表示受控本地前台执行 gate 可进入 preflight / candidate / approval / allowlist / evidence audit；它不授权 source/git/subagent，不会自动写业务源码、commit、push、PR、merge、调用平台 API/model/MCP，或启动 daemon/watcher/hidden background chain。
+
+## 安全边界
+
+默认不授权自动执行命令、自动写源码、自动测试、调用 subagent、平台 API、git、push、PR 或 merge。
+
+只有用户明确允许，且 brief 完整、边界清楚时，才可以进入更强流程。
+
+完整规则见 `.vibecoding/VIBE-CODING.md`。
+<!-- vibecoding:end -->

package/templates/VIBE-CODING.md

@@ -0,0 +1,157 @@
+# Vibecoding Kit 规则
+
+本文件是安装后项目的完整 Vibecoding 规则。根目录 `AGENTS.md` / `CLAUDE.md` 只保留低成本入口；详细任务分流、验证和安全边界以本文为准。
+
+## 核心心智
+
+Vibecoding Kit 是受控 agent 沙盒：
+
+- 用户正常提需求。
+- agent 先判断任务类型和风险级别。
+- 小任务直接处理，复杂任务先收敛目标和验收。
+- 完成前必须有验证证据，或明确说明无法验证的原因。
+- 不隐藏执行 workflow skill、subagent、测试、git、worktree、平台 API 或业务源码写入。
+
+## 资产位置
+
+workflow skills 位于 `.vibecoding/skills/`。
+
+新会话或开发任务开始时，优先加载 `using-vibecoding` 并做轻量任务分流。
+
+## Start Here
+
+### Start Here Contract
+
+新会话或开发任务开始时，agent 的可验收行为是：
+
+1. 先按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`；如果平台 Skill registry 没有注册该 skill，但文件存在，继续按文件路径读取。
+2. 默认只加载 `Bootstrap contract`、轻量 route、当前人工下一步和安全边界，不注入完整 skill 长表。
+3. 首次回复只声明 route、下一步人工动作、验证策略或证据缺口；不要声称已经执行 workflow skill。
+4. 缺少目标、范围、验收或验证方式时先澄清；bug 未复现或根因不明时先定位。
+5. 未经明确授权，不执行命令、不写业务源码、不调用 subagent、不触碰 git、PR、push、merge 或平台 API。
+
+需要本地只读辅助时，可在 Vibecoding Kit 所在位置运行：
+
+```bash
+node tools/vibe-runtime/index.mjs workflow --start --prompt "<request>" --json --root <project-root>
+```
+
+该命令只生成入口合同、可见 skill 回执、驾驶舱和下一步建议；不执行 workflow skill、不调用 subagent、不写源码、不创建状态目录。
+
+### Installed Agent Experience Contract v2
+
+安装后的业务项目默认使用 `installed-agent-experience-contract-v2`：一屏说明 agent 应怎样开始、继续、排障和收口，而不是暴露维护者 runtime stage 长表。
+
+可复制验收 prompt：
+
+- `first_turn`：`我想给这个项目加一个小功能，请先判断下一步。`
+- `continue_task`：`继续按已有计划推进下一步，但先告诉我当前 TODO、验证策略和停止条件。`
+- `bug_debug`：`这个命令失败了，先定位原因，再说明修复和验证路径。`
+- `completion_closeout`：`请判断这个任务能不能收口，给出验证证据、缺口和下一步人工动作。`
+- `review_feedback`：`这段 review feedback 怎么处理？先分类、说明是否阻塞、验证路径和停止条件。`
+
+期望响应 shape：先按文件路径读取 `using-vibecoding`，再说明 lightweight route 或 strict skill-first visible route、可见下一步、验证策略或证据缺口。处理 review feedback 时先分类，说明是否阻塞下一任务、验证路径和停止条件，不盲修、不自动调用 reviewer。完成收口先读 `completion_evidence.task_completion_summary`；如果摘要指出缺口，再看 `blocked_reasons`、readiness gates 和底层 evidence detail。Stage 25 marker：`installed_business_ux_regression_pack` 要求默认 `tiny_context`、一屏轻量体验、`full_maintenance_context` 和维护者 runtime stage 长表不默认展示。固定禁止 marker：`hidden_execution=false`、`command_execution=false`、`skill_execution_claimed=false`、`subagent_dispatch_claimed=false`、`business_source_write=false`、`git_write_claimed=false`、`platform_api=false`、`model_invocation=false`。
+
+默认真实模式是 **Vibe Guided**（`automation_profile: "vibe-guided"`）：轻量入口、本地只读、人工确认、完成前 evidence。`default` 是旧配置兼容别名，解析时归一化为 `vibe-guided`。它不授权隐藏执行、真实 subagent、业务源码写入、git worktree、commit、push、PR 或 merge。维护者对比 profile 属于源码仓库治理文档，不是业务项目日常入口。
+
+`execution_profile: "manual"` 是默认执行边界。只有用户显式运行 `profile --set execution-enabled --confirm` 后，才会把 profile alias 绑定到 `controlled-local-runtime`；这仍只允许本地前台 allowlisted run，并要求 preflight、candidate、approval、queue 和 evidence audit。`execute --preflight`、candidate 和 approval JSON 会暴露 `controlled_execution_gate`，其中 `manual_approval_required=true`、`evidence_audit_required=true`，并把 arbitrary shell、hidden background chain、automatic repair、git/source 写入、平台 API/model/MCP、真实 subagent、scheduler/daemon/watcher 都标记为 blocked。`execution-enabled` 不授权 source/git/subagent：不写业务源码、不自动 commit/push/PR/merge、不创建真实 subagent、不调用平台 API/model/MCP、不启动 daemon/watcher 或 hidden background chain。
+
+`autopilot-lab` 是后续实验 profile，只能在用户明确配置且任务级授权预算完整时进入预算评审。预算至少要说明 allowed paths、allowed commands、最大变更文件数、最大变更行数、最大运行时间、最大修复次数、required verification 和 stop conditions。默认安装不启用 `autopilot-lab`；`vibe-guided` 和 `execution-enabled` 都不会静默升级到 `autopilot-lab`。它不授权命令执行、源码写入、git、subagent、平台 API/model/MCP 或后台链路，只让 agent 能解释和验证低打扰自动化的边界。
+
+`runbook_executor_preview` 是 `autopilot-lab` 之后的只读 dry-run 合同：它把本地 plan 映射成 ordered steps、required gates、allowed action preview、blocked actions、expected evidence 和 budget gaps。preview gate 即使给出 `ok=true`，也只代表预览合同结构可评审；它不授权 command execution、source write、git write、subagent、平台 API/model/MCP 或后台链路。缺少预算、路径、验证命令或 evidence 时，先补人工输入，不进入执行。
+
+`bounded_foreground_command_executor` 是更强的本地前台命令 gate：只有同时具备 `automation_profile: "autopilot-lab"`、`execution_profile: "execution-enabled"`、`execution_profile_policy: "controlled-local-runtime"`、candidate、approval、local lock、allowlisted builtin action、explicit `--confirm --run --auto-run` 和 evidence audit 时，才允许运行一个固定 argv profile。当前 allowlist 只包含 `stage10-runtime-execution-syntax-check`，命令为 `node --check tools/vibe-runtime/runtime-execution-command.mjs`，固定 `shell=false`、`foreground_only=true`、`one_shot=true`、`timeout_ms=20000`。它记录 stdout/stderr 摘要、exit code、duration、command digest 和 budget consumption；失败不会自动 repair，也不会授权 source/git/subagent/platform/model/MCP/background。
+
+- 不要声称已使用某个 skill，除非当前响应实际按该 skill 的目标、边界和 handoff 要求执行。
+- subagent 只有在用户明确允许、brief 完整、边界清楚时才使用。
+
+## 摘要优先判读
+
+运行 `workflow --start` 时，先读取 `workflow_start.entry_summary`，再按需查看底层 `blocked_reasons`。如果 `entry_summary.state_gap_is_expected=true`，说明当前请求适合先做目标、范围或验收收敛；这不是 runtime failure，也不表示必须已有 workflow state。
+
+同时读取 `workflow_start.workflow_discipline_summary` 确认入口纪律：默认 `context_policy.default_context=tiny_context`、`full_skill_injection=false`，并且 `visible_claims.skill_execution_claimed=false`、`workflow_execution_claimed=false`、`command_execution_claimed=false`、`subagent_dispatch_claimed=false`、`git_write_claimed=false`、`source_write_claimed=false`。这些字段只证明当前入口是可见分流和人工下一步，不授权隐藏执行、状态写入、源码写入、git 或 subagent。
+
+完成或判断能否交付时，先读取 `completion_evidence.task_completion_summary`。只有当摘要指出证据缺口、阻塞层或下一步人工动作不清时，再下钻 readiness gates、evidence inventory 和 closeout detail。
+
+摘要只用于解释和分流，不授权自动执行命令、测试、写入、subagent、平台 API、git、push、PR 或 merge。
+
+## 本地 transcript intake
+
+如 adapter 手动导出了项目内 transcript JSON，可用只读 intake 进行结构和边界检查：
+
+```bash
+node tools/vibe-runtime/index.mjs evals --transcript-intake --from-file <local-transcript-json> --json --root <project-root>
+```
+
+该路径只读取本地 JSON，规范化 turn、marker、artifact ref 和边界字段；不连接平台 API、不调用模型、不创建 subagent session、不执行 transcript 中记录的命令、不写 `.vibecoding-state/`、不触碰 git。copy-ready 示例由 `tools/vibe-runtime/runtime-platform-transcript-example-pack.mjs` 提供，覆盖 session-start、workflow entry、SDD brief/report/review chain、review blocker、resume dedupe 和 completion evidence。
+
+## 默认交互协议
+
+安装后的业务项目使用降级交互协议：默认轻量分流、小任务低打扰、风险任务再升级 workflow。根目录入口不要求 agent 先阅读 runtime stage 长表；维护者路线、release suite、architecture baseline 和内部治理细节属于源码仓库 L3 文档。
+
+Vibecoding workflow 是任务路由和质量护栏，不是每次都完整执行的仪式。
+
+处理开发任务前，先轻量判断任务类型和风险级别；只有风险、阶段或交接需要时，才显式进入对应 workflow。
+
+## 任务分流
+
+- 明确小任务：直接执行，必要时说明验证方式，完成前做最小验证。
+- 新功能、重构、架构调整：先确认目标、边界和验收；需求模糊时进入 `vibe-brainstorming`，产品问题、目标用户、场景或价值假设不清时进入 `vibe-product-discovery`，需要产品规格时进入 `vibe-product-spec`，涉及 UI/UX 时进入 `vibe-ui-design`，需要架构取舍时进入 `vibe-planning`。
+- 已有方案但缺少任务拆解：进入 `vibe-writing-plans`。
+- bug、失败、异常行为：先复现和定位根因；未复现或未定位根因时不要直接修改。
+- 大改动、并行任务、风险性重构或分支收口前：先判断是否需要 `vibe-workspace-isolation`。
+- review 或合并前检查：聚焦阻塞问题和高风险问题。
+- 产品规格或 UI contract 已实现后：进入 `vibe-product-acceptance` 补充产品体验、用户路径、UI 状态和指标验收。
+- 处理 review feedback：先理解反馈、复现依据和验收条件，不要盲修。
+- 上下文过长或需要交接：使用 `vibe-context-compact`。
+- subagent 只有在用户明确允许、brief 完整、边界清楚时才使用。
+
+## Architecture-first coding
+
+修改源码前，先做轻量 `Architecture Decision Frame` 判断；简单任务可以用一句话完成，但不能跳过职责归属：
+
+1. `owner`：先找到拥有该职责的 owner module；不要因为文件当前打开或最近修改，就默认写进去。
+2. `layer`：标清改动属于 entry、dispatcher、command wrapper、domain core、state、validation、presentation、test/smoke、config/docs 中哪一层。
+3. `dependency direction`：依赖只能指向更低或同层稳定模块；core 不反向依赖 CLI、command、doctor、check。
+4. `data flow`：确认输入、转换、IO、输出和错误 envelope 的路径清楚，不把跨层数据回溯塞进调用方。
+5. `state lifecycle`：确认状态由谁创建、验证、消费、迁移和持久化；不在非 owner 模块临时写状态。
+6. `contract sync`：CLI 参数、JSON envelope、artifact、digest、README marker、template、doctor/runtime-check/release-check 需要同步时一并纳入范围。
+7. `blast radius`：说明影响是局部、跨模块还是触及执行链路；高风险链路先停下来确认计划。
+8. `evolution path`：新增概念、命令、验证族或 smoke 组时，优先创建/扩展具名模块，而不是扩张大文件。
+9. `complexity containment`：避免参数爆炸、万能 helper、跨 domain common、长函数和隐式共享状态。
+10. `risk class`：涉及 execution、scheduler、daemon、source apply、merge、retry、queue、lease、persistent state 时，按高风险处理并要求更强验证。
+
+## 质量底线
+
+- 修改前明确验证策略；可以是测试、静态检查、手动复现路径或其它可验证证据。
+- 实现完成后必须做完成前验证，或明确说明无法验证的原因。
+- 没有实际验证证据时，不声明“完成”“通过”或“可交付”。
+- 不为简单任务输出完整 workflow handoff。
+- 只有跨阶段、长任务、计划交接或上下文压缩时，才输出 `Workflow Handoff`。
+- 用户显式规则优先；当用户规则与默认 workflow 冲突时，先说明冲突并选择不越权的最小下一步。
+- 不要声称已使用某个 skill，除非当前响应实际按该 skill 的目标、边界和 handoff 要求执行。
+
+## Skill route drift guard
+
+`skill_route_registry_v1` 是安装入口的 Stage 21 只读漂移检查 marker。`using-vibecoding`、runtime route map、模板入口和 workflow 文档必须保持 `route_registry_id` / `required_skill` / `next_gate` / `handoff_required` 同步；它只用于漂移检测，不授权执行、写源码、subagent、平台 API 或 git。
+
+## 升级到完整 workflow 的条件
+
+- 需求模糊：`vibe-brainstorming`
+- 产品问题、目标用户、场景或价值假设不清：`vibe-product-discovery`
+- 产品方向明确但缺少 PRD、用户故事、功能要求或验收标准：`vibe-product-spec`
+- 规格涉及界面、交互、文案、UI 状态、响应式或可访问性：`vibe-ui-design`
+- 需要架构选择：`vibe-planning`
+- 已有方案但任务、文件、验收或风险边界不清：`vibe-writing-plans`
+- 计划包含多个潜在独立任务：`vibe-dispatching-parallel-work`
+- bug 未复现、根因不明、构建或测试异常：`vibe-systematic-debugging`
+- 大改动、并行任务、风险性重构或分支收口前：`vibe-workspace-isolation`
+- 新增或修改 Vibecoding workflow skill：`vibe-writing-skills`
+- 请求 review 或合并前检查：`vibe-requesting-code-review` -> `vibe-review`
+- 处理 review feedback：`vibe-receiving-code-review`
+- 产品规格或 UI contract 需要体验验收：`vibe-product-acceptance`
+- 准备提交、PR 或收口：`vibe-verification-before-completion` -> `vibe-finishing-a-development-branch`
+
+## 边界
+
+第一阶段不使用大型 MCP、复杂 memory、完整 codebase index 或大规模 agents 编排。

package/templates/architecture-design.md

@@ -0,0 +1,139 @@
+---
+artifact_kind: architecture-design
+version: 1
+source_skill: vibe-planning
+status: draft
+next_skill: vibe-writing-plans
+---
+
+# Architecture Design Artifact
+
+## Goal
+
+- architecture_goal:
+- risk_class:
+- delivery_slice:
+
+## Input
+
+- product_spec_artifact:
+- ui_design_artifact:
+- constraints:
+
+## Architecture Decision Frame
+
+- responsibility_owner:
+- layer_and_dependency_direction:
+- data_flow:
+- state_lifecycle:
+- contract_sync:
+- blast_radius:
+- evolution_path:
+- complexity_pressure:
+- architecture_decisions:
+
+## Module Ownership
+
+- owners:
+- new_modules:
+- entrypoints:
+
+## Layer And Dependency Direction
+
+- layers:
+- allowed_dependencies:
+- forbidden_dependencies:
+
+## Data Flow
+
+- inputs:
+- transformations:
+- io_boundaries:
+- outputs:
+- error_envelope:
+
+## State Lifecycle
+
+- state_created_by:
+- state_validated_by:
+- state_consumed_by:
+- persistence:
+
+## Contract Sync
+
+- cli_args:
+- json_envelope:
+- artifact_templates:
+- docs:
+- doctor_runtime_release_checks:
+
+## Blast Radius
+
+- touched_layers:
+- commands:
+- fixtures:
+- release_smoke:
+
+## Verification Strategy
+
+- verification_strategy:
+- static_checks:
+- smoke_checks:
+- manual_checks:
+
+## Artifact Gate Productization
+
+- product_gate_ref:
+- ui_gate_ref:
+- architecture_gate_ref:
+- delivery_traceability_ref:
+- implementation_task_registry_ref:
+- completion_bundle_ref:
+- gate_contract: read_only_local_artifact_validation
+- forbidden_runtime_actions: command_execution, test_execution, git_write, pr, merge, subagent, platform_api
+
+## Risks
+
+- architecture_risks:
+- delivery_risks:
+- rollback_notes:
+
+## Non Goals
+
+- out_of_scope:
+
+## Reference Registry
+
+reference_registry:
+  architecture_decision_refs:
+    - adr-example
+
+## Evidence
+
+- evidence_sources:
+- not_verified:
+
+## Boundary
+
+- writes: false
+- state_directory_created: false
+- command_execution: false
+- test_execution: false
+- skill_execution: false
+- subagent: false
+- mcp: false
+- git: false
+
+## Handoff
+
+current_skill: vibe-planning
+next_skill: vibe-writing-plans
+reason:
+handoff:
+  goal:
+  scope:
+  key_decisions:
+  files:
+  risks:
+  acceptance:
+stop_condition: none

package/templates/delivery-traceability.yaml

@@ -0,0 +1,52 @@
+version: 1
+artifact_kind: delivery-traceability
+source_skill: vibe-writing-plans
+status: draft
+next_skill: vibe-test-driven-development
+
+# Evidence
+evidence_sources:
+  - not_collected_yet
+
+# Boundary
+boundary:
+  writes: false
+  state_directory_created: false
+  command_execution: false
+  test_execution: false
+  skill_execution: false
+  subagent: false
+  mcp: false
+  git: false
+# Artifact Gate Productization
+artifact_gate_productization:
+  gate_contract: read_only_local_artifact_validation
+  upstream_artifacts:
+    - product-spec.md
+    - ui-design-contract.md
+    - architecture-design.md
+  registry_owner: implementation-plan.md#Implementation Task Registry
+  completion_bundle: completion --evidence-bundle
+  not_authorized:
+    command_execution: false
+    test_execution: false
+    git_write: false
+    pr: false
+    merge: false
+    subagent: false
+    platform_api: false
+
+# Reference Registry
+# links[].*_ref values must exist in upstream product/spec/UI/architecture/scenario/acceptance artifacts when used by completion --evidence-bundle.
+links:
+  - id: trace-create-project-happy-path
+    requirement_ref: req-create-project
+    product_story_ref: story-create-project
+    ui_flow_ref: flow-create-project
+    architecture_decision_ref: adr-runtime-readonly-gate
+    implementation_task_ref: task-runtime-gate
+    test_evidence_ref: test-runtime-gate
+    scenario_ref: create-project-happy-path
+    product_acceptance_ref: acceptance-create-project
+    commit_readiness_ref: commit-readiness-local
+    status: not_verified

package/templates/evidence/README.md

@@ -0,0 +1,117 @@
+# Evidence Templates
+
+`templates/evidence/` 提供最小可复制的 local evidence envelope。它们用于帮助团队把测试结果、diff coverage 和 task refs 整理成 runtime 可验证的本地 artifact。
+
+核心边界：runtime 只读验证 envelope、digest、refs 和 boundary assertions；它不运行测试、不读取 git diff、不证明 evidence 的生成环境真实性。
+
+## Evidence Supply Chain v2
+
+P57 把 starter kit 从两个 JSON 模板升级为一条可审计的本地证据链。链路按 artifact owner 分层，而不是让 runtime 回头执行或收集事实：
+
+```text
+requirements / product / UI / architecture artifact
+  -> implementation task registry
+  -> CI or human generated test evidence
+  -> CI or human generated diff coverage
+  -> completion evidence bundle
+  -> human readiness decision
+```
+
+注释：前四层由用户、团队或 CI 生成；runtime 只读取本地文件，检查 refs、digest、coverage 和 boundary assertions 是否自洽。
+
+| 链路层 | 典型 artifact | owner | runtime 职责 |
+| --- | --- | --- | --- |
+| 需求 / 产品 / UI / 架构 | `product-spec.md`、`ui-design-contract.md`、`architecture-design.md` | 用户 / 团队 | 只读 methodology gate |
+| implementation task | `implementation-plan.md` 的 `Implementation Task Registry` | 用户 / 团队 | 检查 task refs 是否可绑定 |
+| test evidence | `test-evidence.json` | 用户 / CI | 检查 command、exit code、digest、task/scenario refs |
+| diff coverage | `diff-coverage.json` | 用户 / CI | 检查 changed files、planned files、task coverage 和 digest |
+| completion bundle | `completion --evidence-bundle` 的本地输出 | runtime | 输出 readiness、blocked reasons 和下一步人工动作 |
+
+`ok=false` 表示本地 evidence 缺口或引用不一致，不是 runtime failure；先看 `completion_evidence.task_completion_summary`，再按 blocked reasons 修正上游 artifact。
+
+## 模板职责
+
+| 文件 | 职责 | 生成 owner |
+| --- | --- | --- |
+| `test-evidence.json` | 记录测试命令、退出码、输出摘要、task refs 和 scenario refs | 用户 / CI / agent 辅助后人工复核 |
+| `diff-coverage.json` | 记录计划文件、实际变更文件、task coverage、operation 和文件 digest | 用户 / CI / agent 辅助后人工复核 |
+
+## 最小使用流程
+
+1. 复制模板到业务项目或当前交付目录。
+2. 替换所有示例值和 `sha256:replace-*` 占位值。
+3. 确保 `task_refs` 能对齐 `implementation-plan.md` 的 `Implementation Task Registry`。
+4. 如果有 scenario artifact，确保 `scenario_refs` 能对齐对应 scenario；没有 scenario artifact 时使用团队约定的稳定 ref。
+5. 保持 `boundary_assertions` 为保守声明：runtime 没有运行测试、没有读取 git diff、没有写 git。
+6. 运行 completion evidence bundle，只根据本地输出的 blocked reasons 修正 evidence。
+
+## Starter kit 复制清单
+
+Team-mode 最小 starter kit 只需要四个业务项目文件：
+
+```text
+product-spec.md
+implementation-plan.md
+test-evidence.json
+diff-coverage.json
+```
+
+来源建议：
+
+```bash
+cp templates/product-spec.md product-spec.md
+cp templates/implementation-plan.md implementation-plan.md
+cp templates/evidence/test-evidence.json test-evidence.json
+cp templates/evidence/diff-coverage.json diff-coverage.json
+```
+
+Windows PowerShell 可用：
+
+```powershell
+Copy-Item templates/product-spec.md product-spec.md
+Copy-Item templates/implementation-plan.md implementation-plan.md
+Copy-Item templates/evidence/test-evidence.json test-evidence.json
+Copy-Item templates/evidence/diff-coverage.json diff-coverage.json
+```
+
+不要直接复制 `examples/full-chain/` 到业务项目作为日常流程；full-chain 只用于高风险发布或审计。
+
+## 必须替换的字段
+
+`test-evidence.json`：
+
+- `runs[].command`
+- `runs[].exit_code`
+- `runs[].timestamp`
+- `runs[].output_digest`
+- `runs[].task_refs`
+- `runs[].scenario_refs`
+
+`diff-coverage.json`：
+
+- `planned_files`
+- `changed_files`
+- `unexpected_files`
+- `missing_files`
+- `task_coverage[].task_ref`
+- `task_coverage[].changed_files[].path`
+- `task_coverage[].changed_files[].operation`
+- `task_coverage[].changed_files[].digest`
+
+## 验证命令
+
+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
+```
+
+## Trust tier
+
+- `L1 manual evidence`：人工记录，适合个人试用、低风险修复或迁移过渡。
+- `L2 CI generated evidence`：CI 生成，适合团队常规交付。
+- `L3 provenance-backed evidence`：CI artifact、签名或受控存储提供来源证明，适合高风险发布或审计。
+
+不要通过扩权 runtime 来提高 trust tier。更高可信度应来自 CI/provenance，而不是让 runtime 自动运行测试、读取 git diff 或提交。

package/templates/evidence/diff-coverage.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "artifact_kind": "diff-coverage-evidence",
+  "status": "provided",
+  "diff_coverage_ref": "diff-example",
+  "planned_files": ["src/example.js"],
+  "changed_files": ["src/example.js"],
+  "unexpected_files": [],
+  "missing_files": [],
+  "task_coverage": [
+    {
+      "task_ref": "task-example",
+      "status": "covered",
+      "changed_files": [
+        {
+          "path": "src/example.js",
+          "operation": "modify",
+          "digest": "sha256:replace-with-file-digest"
+        }
+      ]
+    }
+  ],
+  "boundary_assertions": {
+    "runtime_read_git_diff": false,
+    "command_execution": false,
+    "test_execution": false,
+    "git": false,
+    "git_write": false,
+    "commit": false,
+    "push": false,
+    "pr": false,
+    "merge": false
+  }
+}

package/templates/evidence/test-evidence.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "artifact_kind": "test-evidence",
+  "status": "provided",
+  "test_evidence_ref": "test-example",
+  "runs": [
+    {
+      "id": "test-example",
+      "command": "npm test",
+      "exit_code": 0,
+      "timestamp": "2026-03-14T00:00:00.000Z",
+      "output_digest": "sha256:replace-with-output-digest",
+      "task_refs": ["task-example"],
+      "scenario_refs": ["scenario-example"],
+      "status": "pass"
+    }
+  ],
+  "boundary_assertions": {
+    "runtime_executed_command": false,
+    "command_execution": false,
+    "test_execution": false,
+    "git": false,
+    "git_write": false,
+    "commit": false,
+    "push": false,
+    "pr": false,
+    "merge": false
+  }
+}