@jtf19/vibecoding-kit 0.1.0

package/examples/ci/generate-diff-coverage.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) throw new Error(`Unexpected argument: ${arg}`);
+    const key = arg.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`Missing value for --${key}`);
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(String(value)).digest('hex')}`;
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function groupCoverage(changedFiles) {
+  const groups = new Map();
+  for (const item of changedFiles) {
+    const taskRef = item.task_ref || 'task-unassigned';
+    const current = groups.get(taskRef) || [];
+    current.push({
+      path: item.path,
+      operation: item.operation || 'modify',
+      digest: item.digest || sha256(item.digest_source || item.path || ''),
+    });
+    groups.set(taskRef, current);
+  }
+  return Array.from(groups.entries()).map(([taskRef, files]) => ({
+    task_ref: taskRef,
+    status: 'covered',
+    changed_files: files,
+  }));
+}
+
+function evidenceFromInput(input) {
+  const diff = input.diff || {};
+  const changedFiles = diff.changed_files || [];
+  return {
+    version: 1,
+    artifact_kind: 'diff-coverage-evidence',
+    status: 'provided',
+    diff_coverage_ref: diff.evidence_ref || 'ci-diff-coverage',
+    planned_files: diff.planned_files || [],
+    changed_files: changedFiles.map((item) => item.path),
+    unexpected_files: diff.unexpected_files || [],
+    missing_files: diff.missing_files || [],
+    task_coverage: groupCoverage(changedFiles),
+    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,
+    },
+  };
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options['from-file']) throw new Error('Missing --from-file <ci-evidence-input.json>');
+  if (!options.out) throw new Error('Missing --out <diff-coverage.json>');
+  writeJson(options.out, evidenceFromInput(readJson(options['from-file'])));
+  console.log(`Wrote ${options.out}`);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/examples/ci/generate-test-evidence.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) throw new Error(`Unexpected argument: ${arg}`);
+    const key = arg.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`Missing value for --${key}`);
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(String(value)).digest('hex')}`;
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function testStatus(exitCode) {
+  return Number(exitCode) === 0 ? 'pass' : 'fail';
+}
+
+function evidenceFromInput(input) {
+  const test = input.test || {};
+  const runId = test.id || input.evidence_ref || 'ci-test-run';
+  return {
+    version: 1,
+    artifact_kind: 'test-evidence',
+    status: 'provided',
+    test_evidence_ref: test.evidence_ref || runId,
+    runs: [
+      {
+        id: runId,
+        command: test.command || 'replace-with-ci-test-command',
+        exit_code: Number(test.exit_code ?? 1),
+        timestamp: test.timestamp || new Date().toISOString(),
+        output_digest: test.output_digest || sha256(test.output_text || ''),
+        task_refs: test.task_refs || [],
+        scenario_refs: test.scenario_refs || [],
+        status: test.status || testStatus(test.exit_code ?? 1),
+      },
+    ],
+    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,
+    },
+  };
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options['from-file']) throw new Error('Missing --from-file <ci-evidence-input.json>');
+  if (!options.out) throw new Error('Missing --out <test-evidence.json>');
+  writeJson(options.out, evidenceFromInput(readJson(options['from-file'])));
+  console.log(`Wrote ${options.out}`);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/examples/ci/github-actions-readiness.yml

@@ -0,0 +1,108 @@
+# Example only. Copy this file into .github/workflows/readiness.yml in a business project when you want to enable it.
+# This repository intentionally keeps the workflow under examples/ci/ so it is not auto-enabled.
+
+name: Vibecoding Readiness Evidence
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  readiness-evidence:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run project tests
+        id: tests
+        shell: bash
+        run: |
+          set +e
+          npm test > .tmp-test-output.txt 2>&1
+          status=$?
+          cat .tmp-test-output.txt
+          echo "exit_code=$status" >> "$GITHUB_OUTPUT"
+          exit $status
+
+      - name: Build CI evidence input
+        if: always()
+        shell: bash
+        run: |
+          mkdir -p .tmp/ci-evidence
+          node - <<'NODE'
+          const crypto = require('node:crypto');
+          const fs = require('node:fs');
+
+          const output = fs.existsSync('.tmp-test-output.txt') ? fs.readFileSync('.tmp-test-output.txt', 'utf8') : '';
+          const outputDigest = `sha256:${crypto.createHash('sha256').update(output).digest('hex')}`;
+          const changedFiles = process.env.CHANGED_FILES
+            ? process.env.CHANGED_FILES.split('\n').filter(Boolean)
+            : [];
+
+          const input = {
+            test: {
+              id: 'ci-test-run',
+              evidence_ref: 'ci-test-run',
+              command: 'npm test',
+              exit_code: Number(process.env.TEST_EXIT_CODE || 1),
+              timestamp: new Date().toISOString(),
+              output_digest: outputDigest,
+              task_refs: ['replace-with-implementation-task-ref'],
+              scenario_refs: ['replace-with-scenario-ref']
+            },
+            diff: {
+              evidence_ref: 'ci-diff-coverage',
+              planned_files: ['replace-with-planned-file'],
+              changed_files: changedFiles.map((file) => ({
+                path: file,
+                operation: 'modify',
+                task_ref: 'replace-with-implementation-task-ref',
+                digest_source: file
+              })),
+              unexpected_files: [],
+              missing_files: []
+            }
+          };
+
+          fs.writeFileSync('.tmp/ci-evidence/ci-evidence-input.json', `${JSON.stringify(input, null, 2)}\n`, 'utf8');
+          NODE
+        env:
+          TEST_EXIT_CODE: ${{ steps.tests.outputs.exit_code }}
+          # In a real project, compute this in a prior CI step. Do not make runtime read git diff.
+          CHANGED_FILES: ""
+
+      - name: Generate Vibecoding evidence JSON
+        if: always()
+        run: |
+          node examples/ci/generate-test-evidence.mjs --from-file .tmp/ci-evidence/ci-evidence-input.json --out .tmp/ci-evidence/test-evidence.json
+          node examples/ci/generate-diff-coverage.mjs --from-file .tmp/ci-evidence/ci-evidence-input.json --out .tmp/ci-evidence/diff-coverage.json
+
+      - name: Read-only readiness validation
+        if: always()
+        run: |
+          node tools/vibe-runtime/index.mjs completion --evidence-bundle \
+            --from-product-spec product-spec.md \
+            --from-plan implementation-plan.md \
+            --from-test-evidence .tmp/ci-evidence/test-evidence.json \
+            --from-diff-coverage .tmp/ci-evidence/diff-coverage.json \
+            --json
+
+      - name: Upload readiness evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: vibecoding-readiness-evidence
+          path: .tmp/ci-evidence/*.json
+          if-no-files-found: error

package/examples/claude-project/README.md

@@ -0,0 +1,57 @@
+# Claude Example Project
+
+用于验证 Vibecoding Kit 在 Claude 项目中的最小接入形态。
+
+## 安装
+
+在 Vibecoding Kit 源码仓库中执行：
+
+```bash
+node tools/vibe-init/index.mjs --target examples/claude-project --platform claude
+node tools/vibe-doctor/index.mjs examples/claude-project
+```
+
+## 期望结构
+
+```text
+CLAUDE.md
+.vibecoding/
+  skills/
+  adapters/claude/
+  hooks/
+  VIBE-CODING.md
+```
+
+## 安装后快照
+
+默认安装后，业务项目根目录只新增 Claude 主动读取的入口文件：
+
+```text
+CLAUDE.md
+```
+
+Vibecoding Kit 资产集中放在 `.vibecoding/`：
+
+```text
+.vibecoding/
+  skills/
+  adapters/claude/
+  hooks/
+  VIBE-CODING.md
+```
+
+`docs/` 和 `examples/` 只有在使用 `--with-docs` 时才会安装到 `.vibecoding/` 下。默认不把这些目录铺到业务项目根目录。
+
+## 人工 smoke prompt
+
+```text
+我想给这个项目加一个新功能，先帮我规划一下。
+```
+
+期望：优先进入 `using-vibecoding`，再进入 `vibe-brainstorming` 或 `vibe-planning`。
+
+详细安装后人工 smoke 流程见仓库根目录的 `docs/install-claude.md`。
+
+## 说明
+
+示例目录用于说明平台接入方式，不要求业务项目复制 `examples/` 到根目录。

package/examples/codex-project/README.md

@@ -0,0 +1,57 @@
+# Codex Example Project
+
+用于验证 Vibecoding Kit 在 Codex 项目中的最小接入形态。
+
+## 安装
+
+在 Vibecoding Kit 源码仓库中执行：
+
+```bash
+node tools/vibe-init/index.mjs --target examples/codex-project --platform codex
+node tools/vibe-doctor/index.mjs examples/codex-project
+```
+
+## 期望结构
+
+```text
+AGENTS.md
+.vibecoding/
+  skills/
+  adapters/codex/
+  hooks/
+  VIBE-CODING.md
+```
+
+## 安装后快照
+
+默认安装后，业务项目根目录只新增 Codex 主动读取的公共 agent 入口文件：
+
+```text
+AGENTS.md
+```
+
+Vibecoding Kit 资产集中放在 `.vibecoding/`：
+
+```text
+.vibecoding/
+  skills/
+  adapters/codex/
+  hooks/
+  VIBE-CODING.md
+```
+
+`docs/` 和 `examples/` 只有在使用 `--with-docs` 时才会安装到 `.vibecoding/` 下。默认不把这些目录铺到业务项目根目录。
+
+## 人工 smoke prompt
+
+```text
+这个功能不工作，帮我排查。
+```
+
+期望：进入 `vibe-systematic-debugging`，先明确现象和复现证据，再输出修复和验证方式。
+
+详细安装后人工 smoke 流程见仓库根目录的 `docs/install-codex.md`。
+
+## 说明
+
+示例目录用于说明平台接入方式，不要求业务项目复制 `examples/` 到根目录。

package/examples/cursor-project/README.md

@@ -0,0 +1,57 @@
+# Cursor Example Project
+
+用于验证 Vibecoding Kit 在 Cursor 项目中的最小接入形态。
+
+## 安装
+
+在 Vibecoding Kit 源码仓库中执行：
+
+```bash
+node tools/vibe-init/index.mjs --target examples/cursor-project --platform cursor
+node tools/vibe-doctor/index.mjs examples/cursor-project
+```
+
+## 期望结构
+
+```text
+AGENTS.md
+.vibecoding/
+  skills/
+  adapters/cursor/
+  hooks/
+  VIBE-CODING.md
+```
+
+## 安装后快照
+
+默认安装后，业务项目根目录只新增 Cursor 主动读取的公共 agent 入口文件：
+
+```text
+AGENTS.md
+```
+
+Vibecoding Kit 资产集中放在 `.vibecoding/`：
+
+```text
+.vibecoding/
+  skills/
+  adapters/cursor/
+  hooks/
+  VIBE-CODING.md
+```
+
+`docs/` 和 `examples/` 只有在使用 `--with-docs` 时才会安装到 `.vibecoding/` 下。默认不把这些目录铺到业务项目根目录。
+
+## 人工 smoke prompt
+
+```text
+实现完成了，帮我确认能不能交付。
+```
+
+期望：进入 `vibe-verification-before-completion`，明确当前回合验证证据、未验证项、阻塞、风险和可交付判断；如果证据充分，再建议 `vibe-finishing-a-development-branch`。
+
+详细安装后人工 smoke 流程见仓库根目录的 `docs/install-cursor.md`。
+
+## 说明
+
+示例目录用于说明平台接入方式，不要求业务项目复制 `examples/` 到根目录。

package/examples/full-chain/README.md

@@ -0,0 +1,63 @@
+# Full-Chain Compliance Example
+
+`examples/full-chain/` 是完整 readiness compliance 参考示例，用来证明 Vibecoding Kit 可以在本地只读条件下产出顶层 `ok=true` 的 completion evidence bundle。
+
+它和 `examples/golden-path/` 的定位不同：
+
+- `examples/golden-path/`：team-mode readiness demo，只覆盖最小产品规格、实现计划、测试证据和 diff coverage；顶层 `ok=false` 可以只是缺少 full-chain artifact。
+- `examples/full-chain/`：full compliance reference，包含产品、UI、架构、交付追踪、实现计划、测试证据、diff coverage、commit readiness 和工程 evidence。
+
+## Artifact chain
+
+P58 Artifact Gate Productization 把这个目录定义为 copy-ready 的交付链示例：维护者可以从 artifact gate 看到 requirements、product、UI、architecture、implementation task registry、test evidence、diff coverage 和 commit readiness 如何闭环。
+
+链路职责保持分层：methodology gate 只读检查 artifact，`Implementation Task Registry` 负责 task refs 对齐，completion bundle 负责聚合本地证据和 blocked reasons。这个示例不授权 runtime 自动运行检查、不读取真实 git、不提交、不创建 PR。
+
+```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
+```
+
+## Verify the example
+
+推荐入口：
+
+```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
+```
+
+预期关键结果：
+
+```text
+ok=true
+task_completion_summary.readiness_classification=full_compliance_ready
+task_completion_summary.local_task_ready=true
+task_completion_summary.full_compliance_ready=true
+task_completion_summary.minimum_local_evidence_missing=[]
+task_completion_summary.full_compliance_evidence_missing=[]
+expanded_delivery_chain=true
+implementation_alignment_ok=true
+commit_boundary_ok=true
+git_write=false
+commit=false
+```
+
+## Boundary
+
+这个目录只提供静态 artifact 示例。runtime 仍然只读验证本地 artifact，不运行测试、不读取 git diff、不提交、不 push、不创建 PR、不调用 CI provider API。

package/examples/full-chain/architecture-design.md

@@ -0,0 +1,128 @@
+---
+artifact_kind: architecture-design
+version: 1
+source_skill: vibe-planning
+status: accepted
+next_skill: vibe-writing-plans
+---
+
+# Full-Chain Architecture Design Example
+
+## Goal
+
+- architecture_goal: Insert a delivery methodology gate between UI contract and implementation planning.
+- risk_class: medium contract extension with read-only runtime behavior.
+- delivery_slice: Architecture artifact, traceability artifact, and completion evidence digest binding.
+
+## Input
+
+- product_spec_artifact: examples/full-chain/product-spec.md
+- ui_design_artifact: examples/full-chain/ui-design-contract.md
+- constraints: Local-only deterministic gates; no git, test, browser, subagent, MCP, platform API, or state write.
+
+## Architecture Decision Frame
+
+- responsibility_owner: tools/vibe-runtime/runtime-delivery-methodology-gates.mjs owns delivery artifact validation.
+- layer_and_dependency_direction: runtime-interaction-command delegates to command wrapper; command wrapper delegates to core gate; core reads local files only.
+- data_flow: local architecture or traceability artifact -> parser -> checks -> digest-bound envelope -> manual follow-up.
+- state_lifecycle: none; no .vibecoding-state creation.
+- contract_sync: templates, fixtures, docs, doctor, runtime-check, release-check, CLI usage, completion bundle.
+- blast_radius: templates, skills, runtime methodology gate, completion evidence bundle, validation and release smoke.
+- evolution_path: new delivery gate module keeps architecture/traceability rules separate from product/UI rules.
+- complexity_pressure: avoids expanding runtime index and avoids common cross-domain mutable helper state.
+- architecture_decisions: Use deterministic marker checks first; semantic traceability scoring remains out of scope.
+
+## Module Ownership
+
+- owners: tools/vibe-runtime/runtime-delivery-methodology-gates.mjs
+- new_modules: runtime-delivery-methodology-gates.mjs, runtime-delivery-methodology-command.mjs
+- entrypoints: tools/vibe-runtime/index.mjs remains thin through existing interaction dispatch.
+
+## Layer And Dependency Direction
+
+- layers: CLI args -> interaction command -> delivery command wrapper -> delivery gate core.
+- allowed_dependencies: command wrapper may import gate core; gate core may import local read/digest helpers.
+- forbidden_dependencies: gate core must not import doctor, runtime-check, release-check, git, platform, or execution modules.
+
+## Data Flow
+
+- inputs: architecture-design.md and delivery-traceability.yaml.
+- transformations: parse frontmatter/YAML markers and required fields.
+- io_boundaries: read local files inside root only.
+- outputs: JSON/text envelope with checks, blocked_reasons, source_bindings, and gate_digest.
+- error_envelope: missing files, unsupported kind, missing fields, and unsafe boundary markers become blocked reasons or explicit errors.
+
+## State Lifecycle
+
+- state_created_by: none
+- state_validated_by: deterministic runtime gate only
+- state_consumed_by: completion evidence bundle and human workflow handoff
+- persistence: none
+
+## Contract Sync
+
+- cli_args: methodology --gate uses existing --kind and --from-file; completion bundle adds local artifact inputs.
+- json_envelope: delivery_methodology_gate and expanded completion_evidence_bundle.
+- artifact_templates: architecture-design.md and delivery-traceability.yaml.
+- docs: README, runtime contract, workflow chaining, acceptance checklist, release guide, runtime README.
+- doctor_runtime_release_checks: doctor, runtime-check, release-check fast smoke.
+
+## Blast Radius
+
+- touched_layers: templates, skills, runtime read-only command, validation, docs, release smoke.
+- commands: methodology --gate, completion --evidence-bundle.
+- fixtures: examples/full-chain.
+- release_smoke: full-chain demo suite reads examples and checks read-only boundaries.
+
+## Verification Strategy
+
+- verification_strategy: Run fixture methodology gates, expanded completion bundle smoke, doctor, runtime-check, architecture-check, and release fast.
+- static_checks: node tools/vibe-runtime-check/index.mjs
+- smoke_checks: node tools/vibe-release-check/index.mjs --suite full-chain --quiet
+- manual_checks: confirm no git write automation was added.
+
+## Risks
+
+- architecture_risks: Structure can pass while semantic architecture quality remains weak.
+- delivery_risks: CLI usage, docs, and smoke manifest can drift if not checked together.
+- rollback_notes: Remove delivery gate module, template, fixture, completion inputs, and release smoke if contract must be reverted.
+
+## Non Goals
+
+- out_of_scope: Browser execution, test execution, semantic scoring, git automation, PR creation, and state persistence.
+
+## Reference Registry
+
+reference_registry:
+  architecture_decision_refs:
+    - adr-delivery-methodology-gate
+
+## Evidence
+
+- evidence_sources: This example and full-chain demo smoke.
+- not_verified: No production source behavior is executed by this artifact.
+
+## 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: Architecture owner, data flow, state lifecycle, and verification strategy are explicit enough for implementation planning.
+handoff:
+  goal: Plan the delivery gate and evidence bundle implementation.
+  scope: Runtime delivery methodology and completion evidence contract.
+  key_decisions: Keep validation deterministic, local-only, and no-git.
+  files: examples/full-chain/implementation-plan.md
+  risks: Semantic architecture quality is not scored.
+  acceptance: architecture-design example passes methodology gate.
+stop_condition: none

package/examples/full-chain/commit-readiness.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "artifact_kind": "commit-readiness-evidence",
+  "status": "provided",
+  "commit_readiness_ref": "commit-readiness-local",
+  "commit_subject": {
+    "suggested": "Add delivery evidence chain gates",
+    "commit_execution_authorized": false
+  },
+  "readiness": {
+    "completion_bundle_digest_required": true,
+    "diff_coverage_evidence_bound": true,
+    "manual_git_decision_required": true,
+    "runtime_git_execution_authorized": false
+  },
+  "boundary_assertions": {
+    "git": false,
+    "git_write": false,
+    "git_add": false,
+    "commit": false,
+    "push": false,
+    "pr": false,
+    "merge": false,
+    "tag": false,
+    "history_rewrite": false,
+    "command_execution": false,
+    "test_execution": false,
+    "subagent": false,
+    "mcp": false
+  }
+}