@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-compact/README.md

@@ -0,0 +1,65 @@
+# Vibe Compact
+
+`vibe-compact` 是第二阶段首轮新增的本地轻量文本整理工具。
+
+它用于把长日志、命令输出或 handoff 草稿整理成固定结构，辅助 `vibe-context-compact` skill 使用。
+
+## 使用
+
+从文件读取：
+
+```bash
+node tools/vibe-compact/index.mjs --input .tmp/long-output.txt
+```
+
+从管道读取：
+
+```bash
+some-command | node tools/vibe-compact/index.mjs
+```
+
+限制每段最多保留行数：
+
+```bash
+node tools/vibe-compact/index.mjs --input .tmp/long-output.txt --max-lines 4
+```
+
+输出 markdown 格式：
+
+```bash
+node tools/vibe-compact/index.mjs --input .tmp/long-output.txt --format markdown
+```
+
+如果输入为空，工具会返回失败并输出明确错误：
+
+```text
+Error: input is empty.
+```
+
+## 输出结构
+
+默认 `--format text` 输出：
+
+```text
+目标：
+当前状态：
+关键决策：
+已完成：
+未完成：
+风险：
+下一步：
+关键文件：
+```
+
+`--format markdown` 输出稳定标题和列表，便于粘贴到 handoff 文档中。
+
+## 边界
+
+当前工具不做：
+
+- 不接 MCP。
+- 不接远程模型。
+- 不做跨项目 memory。
+- 不保证语义理解，只做规则化文本筛选和结构化整理。
+
+如果输出中出现 `未识别到明确内容`，应由 agent 或用户补齐对应事实，不能把空缺当作已完成。

package/tools/vibe-compact/compact-contract.mjs

@@ -0,0 +1,63 @@
+export const compactSections = [
+  ['目标', ['目标', 'goal', 'objective', '目的']],
+  ['当前状态', ['当前状态', 'status', 'state', 'progress']],
+  ['关键决策', ['关键决策', 'decision', 'decisions', '约定']],
+  ['已完成', ['已完成', 'done', 'completed', 'finished']],
+  ['未完成', ['未完成', 'todo', 'pending', 'remaining', 'next']],
+  ['风险', ['风险', 'risk', 'risks', 'blocker', '阻塞']],
+  ['下一步', ['下一步', 'next step', 'next', '后续']],
+  ['关键文件', ['关键文件', 'files', 'file', '路径']],
+];
+
+export function compactUsage() {
+  return `Vibecoding Compact
+
+Usage:
+  node tools/vibe-compact/index.mjs [--input <file>] [--max-lines <number>] [--format text|markdown]
+  command | node tools/vibe-compact/index.mjs
+
+Options:
+  --input      Read text from a file. If omitted, stdin is used.
+  --max-lines  Max evidence lines per section. Default: 6.
+  --format     Output format: text or markdown. Default: text.
+  --help       Show this help.
+`;
+}
+
+export function parseCompactArgs(argv) {
+  const options = {
+    input: null,
+    maxLines: 6,
+    format: 'text',
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--input') {
+      options.input = argv[index + 1];
+      index += 1;
+    } else if (arg === '--max-lines') {
+      options.maxLines = Number.parseInt(argv[index + 1], 10);
+      index += 1;
+    } else if (arg === '--format') {
+      options.format = argv[index + 1];
+      index += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!Number.isInteger(options.maxLines) || options.maxLines < 1) {
+    throw new Error('--max-lines must be a positive integer.');
+  }
+
+  if (!['text', 'markdown'].includes(options.format)) {
+    throw new Error('--format must be text or markdown.');
+  }
+
+  return options;
+}

package/tools/vibe-compact/index.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import process from 'node:process';
+import {
+  compactSections,
+  compactUsage,
+  parseCompactArgs,
+} from './compact-contract.mjs';
+
+function readInput(options) {
+  if (options.input) return fs.readFileSync(options.input, 'utf8');
+  return fs.readFileSync(0, 'utf8');
+}
+
+function normalizeLine(line) {
+  return line.replace(/\s+/g, ' ').trim();
+}
+
+function isNoise(line) {
+  if (!line) return true;
+  if (/^[-=]{3,}$/.test(line)) return true;
+  if (/^(debug|trace)\b/i.test(line)) return true;
+  if (/^\[[0-9]{2}:[0-9]{2}:[0-9]{2}/.test(line)) return true;
+  return false;
+}
+
+function scoreLine(line, keywords) {
+  const lower = line.toLowerCase();
+  let score = 0;
+
+  for (const keyword of keywords) {
+    if (lower.includes(keyword.toLowerCase())) score += 3;
+  }
+
+  if (/\b(error|failed|fail|warning|warn|blocked|risk|todo|next|done|passed|missing)\b/i.test(line)) score += 2;
+  if (/[`'"].+[`'"]/.test(line)) score += 1;
+  if (/[A-Za-z0-9_.-]+\/[A-Za-z0-9_./-]+/.test(line)) score += 2;
+  if (line.length >= 20 && line.length <= 180) score += 1;
+
+  return score;
+}
+
+function collect(lines, keywords, maxLines) {
+  return lines
+    .map((line, index) => ({ line, index, score: scoreLine(line, keywords) }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .slice(0, maxLines)
+    .sort((a, b) => a.index - b.index)
+    .map((item) => item.line);
+}
+
+function renderText(groups) {
+  const output = [];
+
+  for (const [title, matches] of groups) {
+    output.push(`${title}：`);
+    if (matches.length === 0) {
+      output.push('- 未识别到明确内容');
+    } else {
+      for (const line of matches) output.push(`- ${line}`);
+    }
+  }
+
+  return output.join('\n');
+}
+
+function renderMarkdown(groups) {
+  const output = ['# Vibecoding Compact Handoff'];
+
+  for (const [title, matches] of groups) {
+    output.push('', `## ${title}`);
+    if (matches.length === 0) {
+      output.push('- 未识别到明确内容');
+    } else {
+      for (const line of matches) output.push(`- ${line}`);
+    }
+  }
+
+  return output.join('\n');
+}
+
+function compact(text, maxLines, format) {
+  const lines = text.split(/\r?\n/).map(normalizeLine).filter((line) => !isNoise(line));
+  const groups = compactSections.map(([title, keywords]) => [title, collect(lines, keywords, maxLines)]);
+
+  if (format === 'markdown') return renderMarkdown(groups);
+  return renderText(groups);
+}
+
+try {
+  const options = parseCompactArgs(process.argv.slice(2));
+
+  if (options.help) {
+    console.log(compactUsage());
+    process.exit(0);
+  }
+
+  const text = readInput(options);
+  if (text.trim().length === 0) {
+    throw new Error('input is empty.');
+  }
+
+  console.log(compact(text, options.maxLines, options.format));
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  console.error('');
+  console.error(compactUsage());
+  process.exit(1);
+}

package/tools/vibe-doctor/README.md

@@ -0,0 +1,200 @@
+# Vibe Doctor
+
+`vibe-doctor` 用于检查 Vibecoding Kit 第一阶段结构是否完整。
+
+## 支持的布局
+
+源码仓库布局：
+
+```text
+bin/
+package.json
+skills/
+adapters/
+hooks/
+docs/
+examples/
+README.md
+CLAUDE.md
+AGENTS.md
+```
+
+业务项目安装布局：
+
+```text
+CLAUDE.md          # 按平台可选
+AGENTS.md          # 按平台可选
+.vibecoding/
+  skills/
+  hooks/
+  adapters/
+  VIBE-CODING.md
+  config.json
+```
+
+如果检测到 `.vibecoding/skills/`，会按安装布局检查；否则按源码仓库布局检查。
+
+## 检查内容
+
+它会检查：
+
+- layout 是否可识别。
+- 根入口文件是否存在或按平台可选。
+- 安装布局中的入口文件是否引用 `Vibecoding Kit`、`.vibecoding/skills/`、必要入口 skill 和 `.vibecoding/VIBE-CODING.md`。
+- 安装布局中的 `.vibecoding/VIBE-CODING.md` 是否包含完整交互协议、任务分流、质量底线和升级条件。
+- 安装布局中的 Vibecoding 入口是否包含且只包含一个 managed block。
+- `.vibecoding/config.json` 是否存在、JSON 有效，并保留 install lifecycle contract。
+- session-start bootstrap 文件、adapter plugin 元数据和 hook 示例是否保持轻量启动边界。
+- UX-6 plugin pack 工具是否存在，并保留 `adapters/` 事实来源、session-start bootstrap、dry-run/check 和不打包 runtime state 的边界。
+- 源码仓库入口文件是否包含完整 workflow marker。
+- 安装布局根入口文件是否包含轻量 agent 沙盒入口；完整降级交互协议 marker：默认交互协议、任务分流、质量底线和升级到完整 workflow 的条件，应位于 `.vibecoding/VIBE-CODING.md`。
+- 核心 skills 是否存在，包括产品发现、产品规格、UI 设计和产品体验验收 workflow。
+- skill frontmatter 是否包含 `name` 和 `description`。
+- workflow skills 是否包含 `下一步调用` 和 `Workflow Handoff`。
+- `using-vibecoding` 是否包含轻量路由、升级条件、完整 workflow 参考和 handoff 规则，并覆盖产品、UI、架构、实现、验收、完成收口分流。
+- `docs/install-experience-roadmap.md`、`docs/runtime-roadmap.md`、`docs/runtime-contract.md`、`tools/vibe-runtime-check/` 和 `tools/vibe-runtime/` 是否存在于 repo layout。
+- `package.json` 和 `bin/vibe.mjs` 是否存在于 repo layout。
+- repo layout 是否包含 Stage 3/4/4.7/5.x/6.x/6.5/7/8/9/10/11 runtime markers：JSON handoff、JSON-first parser、legacy fallback、`status` ledger 摘要、`validate-handoff` 只读校验、`record-handoff` quality hint、`next --dry-run` 文本建议、Stage 4 artifacts dry-run/write marker、tasks dry-run/write marker、`tasks --task` 单任务选择 marker、task id 路径安全与唯一性 marker（含 Windows 保留设备名、重复 id 和尾随点边界）、`depends_on` dependency contract、cyclic task dependency 负路径、`Task readiness` 只读摘要、`review_status` / `needs_fix` / `waived` review gate marker、`goal` / `key_decisions` / `tasks` artifacts 上下文 marker、`Risk gate` / `Evidence gate` / `Evidence gaps to fill` / `Spec compliance gate` 产物职责 marker、Stage 4.7 `status --json` / `validate-handoff --json` / `next --dry-run --json` / `tasks --dry-run --json` 只读 JSON envelope marker、filtered dependency readiness 和写入类 `--json` 负向 smoke marker、Stage 5.x `next --dry-run --dispatch-intent` / `runtimeBridge` / `platform_hints` / `dispatch_event=false` marker、Stage 6.x `next --confirm --dispatch` / `confirm-dispatch` / dispatch envelope / allowed transition / review gate / task readiness gate / dispatches marker、Stage 6.5 `dispatches --list` / `dispatches --show` / `dispatches --verify` / read-only dispatch audit / confirm-dispatch event verification marker、Stage 7 `dispatches --claim` / `dispatches --ack` / `dispatches --claims` / `dispatch-claims` / Stage 7.1 claim input hardening / Stage 7.2 ack lifecycle hardening / Stage 7.3 claims audit hardening / claim actor gate / duplicate claim / actor mismatch / original event immutability marker、Stage 8 `dispatches --pickup` / pickup package / Stage 8.1 pickup package manifest / Stage 8.2 pickup readiness gates / Stage 8.3 pickup read-only audit / platform entry / auto claim / session / no platform API marker、Stage 9 `execute --from-dispatch` / execution envelope / Stage 9.1 execution preflight gates / Stage 9.2 planned execution envelope / Stage 9.3 immutability guarantees / claim actor gate / no skill execution marker、Stage 10 `daemon --dry-run` / `daemon --once --confirm` / daemon-runs / Stage 10.1 daemon command gate / Stage 10.2 once-run envelope / Stage 10.3 failure isolation / observability / default-off daemon / no-op once-run marker、Stage 11 `execute --confirm --run` / `supervised-run` / `runtime_action` / `executions --list|show|verify` / execution lifecycle / allowlist / no-write marker，以及 release smoke marker。
+- repo layout 是否包含 `.vibecoding-state/` 本地 ledger 忽略边界。
+- Claude / Codex / Cursor adapters 是否完整。
+- adapter JSON 是否有效。
+- 源码仓库中的安装入口模板是否存在。
+- 安装布局中可选文档是否按 `--with-docs` 安装。
+- warn / fail 是否能给出 `fix:` 修复建议。
+- 源码仓库中的 `fork/` submodule 参考路径是否存在。
+- README、release guide、acceptance checklist 是否包含关键入口链接。
+
+## 单平台识别
+
+installed layout 下，doctor 会根据 `.vibecoding/adapters/` 中实际存在的平台目录判断检查范围，并输出 `Platforms:`：
+
+- `Platforms: claude`：只要求 `CLAUDE.md` 和 `.vibecoding/adapters/claude/`。
+- `Platforms: cursor`：只要求 `AGENTS.md` 和 `.vibecoding/adapters/cursor/`。
+- `Platforms: codex`：只要求 `AGENTS.md` 和 `.vibecoding/adapters/codex/`。
+- `Platforms: claude, codex, cursor`：要求 `CLAUDE.md`、`AGENTS.md` 和三平台 adapter。
+
+Cursor 和 Codex 共用 `AGENTS.md`。doctor 不会要求未安装平台的 adapter。
+
+## 入口文件 warning 处理
+
+installed layout 下，如果目标项目已有 `CLAUDE.md` 或 `AGENTS.md`，`vibe-init` 不会覆盖用户非 managed 内容。
+
+如果入口文件没有包含 Vibecoding 接入信息，doctor 会输出 `passed with warnings`，例如：
+
+```text
+[warn] CLAUDE.md may need manual Vibecoding merge
+```
+
+如果入口文件包含 Vibecoding 信息但没有 managed block，doctor 也会输出 warning，提示后续无法安全自动升级该入口文件。
+
+处理方式：
+
+- 先运行 `node bin/vibe.mjs init --target <project> --platform auto --merge=preview` 查看将要加入的 managed block。
+- 确认无冲突后运行 `node bin/vibe.mjs init --target <project> --platform auto --merge=append`。
+- 如果已有 managed block，默认安装会只替换该 block；也可以显式使用 `--merge=replace`。
+- 如果 doctor 提示 multiple / incomplete managed block，先手动修复为唯一完整 block，再重新运行 doctor。
+
+## 安装 lifecycle config
+
+installed layout 下，doctor 会校验 `.vibecoding/config.json`：
+
+- `version=1`
+- `profile=standard`
+- `interaction=lightweight`
+- `platforms` 只包含 `claude` / `codex` / `cursor`
+- `runtime.enabled` 是显式 boolean
+- `managed_entries` 记录哪些入口文件由 Vibecoding managed block 管理
+- `lifecycle.update` / `lifecycle.repair` / `lifecycle.uninstall` 记录命令边界
+
+如果 config 缺失、损坏或和入口文件 managed block 状态不一致，优先运行：
+
+```bash
+node bin/vibe.mjs repair --root <project> --dry-run
+```
+
+确认计划安全后再运行：
+
+```bash
+node bin/vibe.mjs repair --root <project> --confirm
+```
+
+## Stage 55 installed runtime opt-in
+
+如果业务项目存在 `.vibecoding/runtime-installed.json`，doctor 会额外验证：
+
+- `manifest_kind=installed-runtime-opt-in`
+- `opt_in=true` 且 `default_enabled=false`
+- 业务项目只保存 `.vibecoding/` 内的元数据，不宣称本地 `tools/` 执行入口
+- runtime 调用边界为 external kit repo / package，业务项目路径通过 `\<project-root\>` 传入
+- hooks、daemon、MCP、state 目录默认创建、自动 runtime action 仍全部关闭
+
+这保证 installed project 的职责只是承载 opt-in 声明，而不是伪装成完整 runtime 分发体。
+
+## 使用
+
+在项目根目录运行：
+
+```bash
+node bin/vibe.mjs doctor
+```
+
+也可以指定检查目标目录：
+
+```bash
+node bin/vibe.mjs doctor --root /path/to/project
+```
+
+兼容调用：
+
+```bash
+node tools/vibe-doctor/index.mjs /path/to/project
+```
+
+## 输出
+
+示例：
+
+```text
+Vibecoding Kit Doctor
+Root: /path/to/project
+Layout: installed
+Platforms: cursor
+
+[ok] .vibecoding/skills/ exists
+[ok] .vibecoding/skills/using-vibecoding/SKILL.md exists
+[ok] AGENTS.md references downgraded interaction protocol
+[ok] .vibecoding/docs skipped
+
+Result: passed
+Checks: 48 ok, 0 warn, 0 fail
+```
+
+## 相关文档
+
+- `README.md`：快速安装、诊断和第一阶段边界。
+- `tools/vibe-init/README.md`：安装工具说明。
+- `tools/vibe-lifecycle/README.md`：安装后 update / repair / uninstall 生命周期说明。
+- `tools/vibe-plugin-pack/README.md`：平台原生插件草案生成和校验说明。
+- `tools/vibe-runtime-check/README.md`：只读 runtime contract 检查器说明。
+- `tools/vibe-runtime/README.md`：显式 workflow state ledger 说明。
+- `docs/install-experience-roadmap.md`：安装体验增强 stage 路线。
+- `docs/runtime-roadmap.md`：可选 runtime 分阶段路线。
+- `docs/runtime-contract.md`：runtime contract 和禁止自动动作。
+- `docs/acceptance-checklist.md`：固定验收命令序列。
+- `docs/release-guide.md`：发布包边界和发布前检查。
+
+## 第一阶段边界
+
+当前工具是无依赖 Node.js 单文件脚本。
+
+它不做：
+
+- MCP 检查。
+- 跨会话 memory 检查。
+- codebase index 检查。
+- 平台真实安装验证。
+- agent runtime 调用。
+- workflow state 写入。
+- `next_skill` 自动执行。
+
+这些属于后续阶段。