contextdevkit 1.8.0 → 1.9.0

package/templates/contextkit/tools/scripts/draft-changelog.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * `/draft-changelog` — build a `[Unreleased]` skeleton from Conventional Commits
+ * since the last tag (ADR-0030, OSS repo-ops).
+ *
+ * Reads `git log <lastTag>..HEAD`, parses Conventional Commit subjects, and groups
+ * them into Keep-a-Changelog sections (Added / Changed / Fixed / …). It DRAFTS —
+ * it never writes `docs/CHANGELOG.md`; the human reviews and pastes. Local git only
+ * (no network), every git call is timed out + defensive (rule 2): a non-repo or a
+ * git error prints a clean message, never a stack trace.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/draft-changelog.mjs           # since last tag
+ *   node contextkit/tools/scripts/draft-changelog.mjs --since v1.7.0
+ *   node contextkit/tools/scripts/draft-changelog.mjs --json
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Conventional-commit type → Keep-a-Changelog section. */
+const SECTION = {
+  feat: 'Added',
+  fix: 'Fixed',
+  perf: 'Changed',
+  refactor: 'Changed',
+  revert: 'Removed',
+  security: 'Security',
+  docs: 'Documentation',
+  chore: 'Chores',
+  build: 'Chores',
+  ci: 'Chores',
+  test: 'Chores',
+  style: 'Chores',
+};
+const ORDER = ['Added', 'Changed', 'Fixed', 'Removed', 'Deprecated', 'Security', 'Documentation', 'Chores', 'Other'];
+
+/** Runs git with a hard timeout; returns stdout or null on any failure. */
+function git(args) {
+  const res = spawnSync('git', args, { encoding: 'utf-8', timeout: 5000 });
+  return res.status === 0 ? (res.stdout || '').trim() : null;
+}
+
+function lastTag() {
+  return git(['describe', '--tags', '--abbrev=0']);
+}
+
+/** Parses a `feat(scope)!: subject` line into { section, scope, breaking, text }. */
+function parse(subject) {
+  const m = subject.match(/^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.+)$/);
+  if (!m) return { section: 'Other', scope: null, breaking: false, text: subject };
+  const [, type, scope, bang, text] = m;
+  return { section: SECTION[type.toLowerCase()] || 'Other', scope: scope || null, breaking: Boolean(bang), text };
+}
+
+function collect(since) {
+  if (git(['rev-parse', '--is-inside-work-tree']) !== 'true') return { error: 'not a git repository' };
+  const range = since ? `${since}..HEAD` : null;
+  const args = ['log', '--no-merges', '--pretty=%s'];
+  if (range) args.splice(1, 0, range);
+  const out = git(args);
+  if (out === null) return { error: since ? `git log failed for range ${range}` : 'git log failed' };
+  const subjects = out.split('\n').filter(Boolean);
+  const groups = {};
+  for (const s of subjects) {
+    const p = parse(s);
+    (groups[p.section] ||= []).push(p);
+  }
+  return { since, count: subjects.length, groups };
+}
+
+function render(result) {
+  if (result.error) return `ℹ️  ${result.error} — nothing to draft.`;
+  const lines = ['## [Unreleased]', ''];
+  if (result.count === 0) {
+    lines.push(`_No commits since ${result.since || 'the start'}._`);
+    return lines.join('\n');
+  }
+  for (const section of ORDER) {
+    const items = result.groups[section];
+    if (!items || items.length === 0) continue;
+    lines.push(`### ${section}`);
+    for (const it of items) {
+      const scope = it.scope ? `**${it.scope}:** ` : '';
+      const breaking = it.breaking ? '⚠️ BREAKING — ' : '';
+      lines.push(`- ${breaking}${scope}${it.text}`);
+    }
+    lines.push('');
+  }
+  lines.push(`_Drafted from ${result.count} commit(s) since ${result.since || 'the first commit'}. Review before pasting into docs/CHANGELOG.md — this command never writes it._`);
+  return lines.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const wantJson = argv.includes('--json');
+  const sinceIdx = argv.indexOf('--since');
+  const since = sinceIdx !== -1 && argv[sinceIdx + 1] ? argv[sinceIdx + 1] : lastTag();
+  const result = collect(since);
+  console.log(wantJson ? JSON.stringify(result, null, 2) : render(result));
+}
+
+main();

package/templates/contextkit/tools/scripts/validate-doc.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * `/validate-doc` — quality gate for OUR OWN planning artifacts (ADR-0030).
+ *
+ * Adapts EVO-METHOD/BMAD's `steps-v` document-validation chain (MIT) to
+ * ContextDevKit's artifacts: an ADR must pose its problem, decide plainly, and own
+ * its trade-offs; a roadmap must be measurable, not aspirational. The kit already
+ * validates *code wiring* (selfcheck) — this validates the *prose* of the decisions
+ * those tests are built on.
+ *
+ * Report-only by design (constitution §8 — never a false "pass", but also never a
+ * push-blocker): it prints findings and exits non-zero only so CI *could* gate on
+ * it; the slash command is advisory. Zero runtime deps (rule 1).
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/validate-doc.mjs <file.md>
+ *   node contextkit/tools/scripts/validate-doc.mjs <file.md> --json
+ *   node contextkit/tools/scripts/validate-doc.mjs --adr <file.md>      # force ADR rubric
+ *   node contextkit/tools/scripts/validate-doc.mjs --roadmap <file.md>  # force roadmap rubric
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+
+/** Leftover template tokens that mean the artifact was never filled in. */
+const PLACEHOLDERS = [/<short decision title>/i, /\bNNNN\b/, /YYYY-MM-DD/, /<who>/i, /<what we will do/i, /ADR-XXXX/];
+/** Words that signal a real trade-off was considered (Consequences quality). */
+const TRADEOFF_HINTS = /(trade-?off|negative|risk|harder|downside|we give up|cost)/i;
+/** Tokens that make a roadmap line measurable rather than aspirational. */
+const MEASURABLE_HINTS = /(\d|%|by\s+\w+|target|metric|KPI|reduce|increase|within|ship|release)/i;
+
+/** Splits a markdown doc into `## Heading` → body. Zero-dep, defensive. */
+function sections(text) {
+  const out = {};
+  const re = /^#{2,3}\s+(.+?)\s*$/gm;
+  const heads = [];
+  let m;
+  while ((m = re.exec(text))) heads.push({ title: m[1].trim(), start: m.index + m[0].length });
+  heads.forEach((h, i) => {
+    const end = i + 1 < heads.length ? heads[i + 1].start : text.length;
+    out[h.title.toLowerCase()] = text.slice(h.start, end).trim();
+  });
+  return out;
+}
+
+/** Detects the rubric to apply from the path + content. */
+function detectType(file, text) {
+  const name = basename(file).toLowerCase();
+  if (/\/decisions\//.test(file.replace(/\\/g, '/')) || /^\d{4}-/.test(name) || /\*\*Status\*\*/i.test(text)) return 'adr';
+  if (/roadmap/.test(name)) return 'roadmap';
+  return 'generic';
+}
+
+function err(code, message) {
+  return { level: 'error', code, message };
+}
+function warn(code, message) {
+  return { level: 'warn', code, message };
+}
+
+/** ADR rubric — sections present, status valid, no placeholders, trade-offs owned. */
+function validateAdr(text) {
+  const findings = [];
+  const sec = sections(text);
+  const has = (name) => Object.keys(sec).some((k) => k === name || k.startsWith(name));
+  for (const required of ['context', 'decision', 'consequences']) {
+    if (!has(required)) findings.push(err('MISSING_SECTION', `ADR is missing a "## ${required[0].toUpperCase() + required.slice(1)}" section.`));
+  }
+  if (!/\*\*status\*\*\s*:/i.test(text)) findings.push(err('NO_STATUS', 'ADR has no "**Status**:" line.'));
+  else if (!/\*\*status\*\*\s*:\s*(proposed|accepted|superseded)/i.test(text)) findings.push(warn('STATUS_VALUE', 'Status is not one of Proposed / Accepted / Superseded.'));
+  for (const re of PLACEHOLDERS) {
+    if (re.test(text)) findings.push(err('PLACEHOLDER', `Unfilled template placeholder still present: ${re}`));
+  }
+  const context = sec['context'] || '';
+  if (context && context.length < 200) findings.push(warn('THIN_CONTEXT', `Context is thin (${context.length} chars) — it should state the forces WITHOUT already giving the answer.`));
+  const consequences = Object.entries(sec).find(([k]) => k.startsWith('consequences'))?.[1] || '';
+  if (consequences && !TRADEOFF_HINTS.test(consequences)) findings.push(warn('NO_TRADEOFFS', 'Consequences states no trade-off / negative / risk — a decision with only upsides is usually under-examined.'));
+  if (!/follow-?up/i.test(text)) findings.push(warn('NO_FOLLOWUPS', 'No follow-ups noted — what does this decision obligate next?'));
+  return findings;
+}
+
+/** Roadmap rubric — items exist and read as measurable, not aspirational. */
+function validateRoadmap(text) {
+  const findings = [];
+  const items = text.split('\n').filter((l) => /^\s*[-*]\s+/.test(l) || /^\s*\d+\.\s+/.test(l));
+  if (items.length === 0) findings.push(warn('NO_ITEMS', 'No list items detected — is the roadmap populated?'));
+  const vague = items.filter((l) => l.replace(/^\s*[-*\d.]+\s*/, '').length > 12 && !MEASURABLE_HINTS.test(l));
+  if (items.length && vague.length / items.length > 0.5) {
+    findings.push(warn('NOT_MEASURABLE', `${vague.length}/${items.length} items read as aspirational (no number / date / target). Make outcomes measurable.`));
+  }
+  for (const re of PLACEHOLDERS) {
+    if (re.test(text)) findings.push(warn('PLACEHOLDER', `Template placeholder still present: ${re}`));
+  }
+  return findings;
+}
+
+function validate(file, forced) {
+  const text = readFileSync(file, 'utf-8').replace(/^/, '');
+  const type = forced || detectType(file, text);
+  const findings = type === 'adr' ? validateAdr(text) : type === 'roadmap' ? validateRoadmap(text) : validateRoadmap(text);
+  return { file, type, findings };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const wantJson = argv.includes('--json');
+  let forced = null;
+  if (argv.includes('--adr')) forced = 'adr';
+  if (argv.includes('--roadmap')) forced = 'roadmap';
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (!file) {
+    console.error('Usage: validate-doc.mjs <file.md> [--adr|--roadmap] [--json]');
+    process.exit(2);
+  }
+  if (!existsSync(file)) {
+    console.error(`File not found: ${file}`);
+    process.exit(2);
+  }
+  const report = validate(file, forced);
+  const errors = report.findings.filter((f) => f.level === 'error');
+  const warns = report.findings.filter((f) => f.level === 'warn');
+
+  if (wantJson) {
+    console.log(JSON.stringify({ ...report, errorCount: errors.length, warnCount: warns.length }, null, 2));
+  } else {
+    console.log(`\n📋 validate-doc — ${basename(file)} (${report.type} rubric)`);
+    console.log('─'.repeat(56));
+    if (report.findings.length === 0) console.log('  ✅ No issues — the artifact passes the rubric.');
+    for (const f of errors) console.log(`  ❌ [${f.code}] ${f.message}`);
+    for (const f of warns) console.log(`  ⚠️  [${f.code}] ${f.message}`);
+    console.log(`\n  ${errors.length} error(s), ${warns.length} warning(s). (advisory — never blocks a push)`);
+  }
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+main();

package/tools/install/cli.mjs

@@ -5,11 +5,13 @@
 export { LEVEL_LABELS } from '../../templates/contextkit/runtime/config/levels.mjs';
 
 export function parseArgs(argv) {
-  const args = { yes: false, rewire: false, force: false, uninstall: false, help: false, version: false, purge: false, update: false };
+  const args = { yes: false, rewire: false, force: false, uninstall: false, help: false, version: false, purge: false, update: false, migrate: false, dryRun: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--yes' || a === '-y') args.yes = true;
     else if (a === '--update') { args.update = true; args.yes = true; }
+    else if (a === '--migrate') args.migrate = true;
+    else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--rewire') args.rewire = true;
     else if (a === '--force') args.force = true;
     else if (a === '--uninstall') args.uninstall = true;
@@ -33,6 +35,8 @@ Usage:
                    [--mode greenfield|existing] [--yes] [--force]
   node install.mjs --update                   safe update: refresh engine + commands,
                                               keep your level/config/memory/CLAUDE.md
+  node install.mjs --migrate [--dry-run]      carry a legacy vibekit/ install forward
+                                              to contextkit/ (preview with --dry-run)
   node install.mjs --rewire --level <1-7>     only recompose .claude/settings.json
   node install.mjs --uninstall [--purge]      unwire hooks (--purge also removes engine)
   node install.mjs --help | --version
@@ -47,6 +51,9 @@ Flags:
   --force           overwrite CLAUDE.md / memory seeds if they exist
   --update          safe update: refresh engine/commands/agents + re-wire hooks for
                     the CURRENT level; never touches CLAUDE.md, config, or memory
+  --migrate         carry a legacy vibekit/ install forward to contextkit/ (moves the
+                    folder, preserves memory/config, rewires settings/CLAUDE.md/hooks)
+  --dry-run         with --migrate: report what would change without writing
   --rewire          only recompose settings.json for the given --level
   --uninstall       remove ContextDevKit hook wiring + git hooks (keeps memory)
   --purge           with --uninstall, also delete contextkit/ engine + commands/agents

package/tools/install/migrate.mjs

@@ -0,0 +1,162 @@
+/**
+ * Legacy-install migration: VibeDevKit (`vibekit/`) → ContextDevKit (`contextkit/`).
+ *
+ * Existing users installed the old `vibedevkit` package, which laid down a
+ * `vibekit/` platform folder, `/vibe-*` slash commands, `vibekit/...` hook
+ * wiring and `VibeDevKit` / `VIBE_*` references. After the rename, running
+ * `npx contextdevkit --update` must carry that install FORWARD — without data
+ * loss and without leaving two installs side by side.
+ *
+ * Strategy (idempotent, refuse-on-ambiguity — constitution rule 8):
+ *   1. detect a legacy `vibekit/` with no `contextkit/`;
+ *   2. MOVE the folder (atomic rename → preserves memory / config / pipeline / .env);
+ *   3. rewrite the rename tokens in the control files (settings.json, .gitignore,
+ *      .gitattributes, git hooks, contextkit/.env, CLAUDE.md — the last two backed
+ *      up to `*.bak` first, as they hold user content);
+ *   4. delete the stale `/vibe-*` + `setupvibedevkit` command files.
+ * The normal installer flow then refreshes the engine into `contextkit/`.
+ *
+ * Zero third-party deps (runs via `npx` on a bare machine). Rule 2: it never
+ * throws into the installer — all I/O is defensive; a failure degrades to a
+ * warning and leaves the project untouched.
+ */
+import { rename, cp, rm, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const LEGACY_DIR = 'vibekit';
+const NEW_DIR = 'contextkit';
+
+// Order matters: longest / most-specific tokens first so no rule eats another.
+const TOKENS = [
+  ['VibeDevKit', 'ContextDevKit'],
+  ['VIBEDEVKIT', 'CONTEXTDEVKIT'],
+  ['vibedevkit', 'contextdevkit'],
+  ['vibekit', 'contextkit'],
+  ['VIBE_', 'CONTEXT_'],
+  ['vibe-', 'context-'],
+];
+
+/** Control files whose kit-managed content carries old tokens. `backup` files hold user content. */
+const CONTROL = [
+  { rel: '.claude/settings.json', backup: false },
+  { rel: '.gitignore', backup: false },
+  { rel: '.gitattributes', backup: false },
+  { rel: 'CLAUDE.md', backup: true },
+  { rel: join(NEW_DIR, '.env'), backup: true }, // after the move
+];
+const GIT_HOOKS = ['pre-commit', 'commit-msg', 'pre-push'];
+const STALE_COMMANDS = [
+  '.claude/commands/vibe-stats.md',
+  '.claude/commands/setup/vibe-config.md',
+  '.claude/commands/setup/vibe-doctor.md',
+  '.claude/commands/setup/vibe-level.md',
+  '.claude/commands/setup/setupvibedevkit.md',
+];
+
+function rewriteTokens(text) {
+  let out = text;
+  for (const [from, to] of TOKENS) out = out.split(from).join(to);
+  return out;
+}
+
+/**
+ * Detects whether `target` holds a legacy install and whether the new folder
+ * already exists. A legacy install is a `vibekit/` with a config or runtime.
+ */
+export function detectLegacy(target) {
+  const legacy = join(target, LEGACY_DIR);
+  const isLegacy = existsSync(legacy) && (existsSync(join(legacy, 'config.json')) || existsSync(join(legacy, 'runtime')));
+  return { isLegacy, hasNew: existsSync(join(target, NEW_DIR)) };
+}
+
+async function rewriteFile(path, { backup, dryRun }) {
+  if (!existsSync(path)) return false;
+  let text;
+  try {
+    text = await readFile(path, 'utf-8');
+  } catch {
+    return false;
+  }
+  const next = rewriteTokens(text);
+  if (next === text) return false;
+  if (dryRun) return true;
+  if (backup && !existsSync(`${path}.bak`)) await writeFile(`${path}.bak`, text, 'utf-8').catch(() => {});
+  await writeFile(path, next, 'utf-8').catch(() => {});
+  return true;
+}
+
+async function moveFolder(from, to) {
+  try {
+    await rename(from, to);
+  } catch (err) {
+    if (err && err.code === 'EXDEV') {
+      // Cross-device (e.g. target on another volume): copy then remove.
+      await cp(from, to, { recursive: true, force: true });
+      await rm(from, { recursive: true, force: true });
+      return;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Runs the legacy → new migration on `target`. No-ops cleanly when there is
+ * nothing to migrate. NEVER throws — returns `{ migrated, report }`.
+ *
+ * @param {string} target project root
+ * @param {{ dryRun?: boolean }} [opts] `dryRun` reports without writing
+ * @returns {Promise<{ migrated: boolean, report: string[] }>}
+ */
+export async function migrateLegacy(target, opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const report = [];
+  let det;
+  try {
+    det = detectLegacy(target);
+  } catch {
+    return { migrated: false, report };
+  }
+  if (!det.isLegacy) return { migrated: false, report };
+
+  if (det.hasNew) {
+    report.push('⚠️  found BOTH vibekit/ (legacy) and contextkit/ — not merging automatically.');
+    report.push('    Your old data is in vibekit/. Move what you need into contextkit/, then delete vibekit/.');
+    return { migrated: false, report };
+  }
+
+  const tag = dryRun ? '[dry-run] would' : '✓';
+  report.push(dryRun ? '🔎 legacy VibeDevKit install detected (dry-run — no changes):' : '🔄 migrating legacy VibeDevKit install → ContextDevKit…');
+
+  // 1) move the folder — carries ALL user data (memory, config, pipeline, .env) forward.
+  if (!dryRun) {
+    try {
+      await moveFolder(join(target, LEGACY_DIR), join(target, NEW_DIR));
+    } catch (err) {
+      report.push(`⚠️  could not move vibekit/ → contextkit/ (${err?.code || err}); migration aborted, nothing changed.`);
+      return { migrated: false, report };
+    }
+  }
+  report.push(`  ${tag} vibekit/ → contextkit/ (memory, config, pipeline, .env preserved)`);
+
+  // 2) rewrite the control files (CLAUDE.md + .env are backed up to *.bak first).
+  for (const { rel, backup } of CONTROL) {
+    if (await rewriteFile(join(target, rel), { backup, dryRun })) report.push(`  ${tag} updated ${rel}${backup ? ' (backup *.bak)' : ''}`);
+  }
+
+  // 3) git-hook wrappers (best-effort; the installer re-installs them properly afterwards).
+  for (const hook of GIT_HOOKS) {
+    if (await rewriteFile(join(target, '.git', 'hooks', hook), { backup: false, dryRun })) report.push(`  ${tag} rewired .git/hooks/${hook}`);
+  }
+
+  // 4) delete the stale /vibe-* + setupvibedevkit command files (new ones reinstalled by the flow).
+  for (const rel of STALE_COMMANDS) {
+    const path = join(target, rel);
+    if (!existsSync(path)) continue;
+    if (!dryRun) await rm(path, { force: true }).catch(() => {});
+    report.push(`  ${tag} removed stale ${rel}`);
+  }
+
+  report.push(dryRun ? '🔎 dry-run complete — re-run without --dry-run to apply.' : '✅ migration complete — continuing with the engine refresh…');
+  return { migrated: !dryRun, report };
+}

package/tools/integration-test-migrate.mjs

@@ -0,0 +1,151 @@
+/**
+ * Integration test — legacy `vibekit/` → `contextkit/` migration (the rename).
+ *
+ * Scaffolds a throwaway project that looks like an OLD `vibedevkit` install,
+ * then drives the real installer to prove the migration:
+ *   - `--migrate --dry-run` changes nothing;
+ *   - `--migrate` moves the folder (preserving user memory/config/.env), rewrites
+ *     settings.json / CLAUDE.md / .gitignore / git hooks, backs up user files,
+ *     and deletes the stale /vibe-* commands;
+ *   - `--update` auto-migrates end-to-end and refreshes the engine (no dup hooks);
+ *   - BOTH folders present → refuse (no changes);
+ *   - re-running on a migrated project is a no-op.
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { KIT, node, run, git, reporter } from './it-helpers.mjs';
+
+const rep = reporter();
+const read = (p) => readFileSync(p, 'utf-8');
+const tmp = () => mkdtempSync(join(tmpdir(), 'contextkit-mig-'));
+
+/** Scaffolds a project that looks like a legacy VibeDevKit install. */
+function makeLegacy(proj, { withGit = false } = {}) {
+  if (withGit) {
+    git(['init', '-b', 'main'], proj);
+    git(['config', 'user.email', 'it@example.com'], proj);
+    git(['config', 'user.name', 'IT'], proj);
+  }
+  const w = (rel, body) => {
+    const p = join(proj, rel);
+    mkdirSync(join(p, '..'), { recursive: true });
+    writeFileSync(p, body, 'utf-8');
+  };
+  w('vibekit/config.json', JSON.stringify({ level: 5, setup: { completed: true }, ledger: {} }, null, 2));
+  w('vibekit/runtime/hooks/session-start.mjs', '// legacy dummy engine\n');
+  w('vibekit/memory/decisions/0001-user-decision.md', '# 0001 — a precious user ADR\nkeep me\n');
+  w('vibekit/.env', 'GOOGLE_AI_API_KEY=secret\nVIBE_GIT_TIMEOUT_MS=5000\n');
+  w('.claude/settings.json', JSON.stringify({
+    hooks: { SessionStart: [{ hooks: [{ type: 'command', command: 'node vibekit/runtime/hooks/session-start.mjs' }] }] } },
+    null, 2));
+  w('.claude/commands/setup/vibe-level.md', 'old vibe-level command\n');
+  w('.claude/commands/vibe-stats.md', 'old vibe-stats command\n');
+  w('CLAUDE.md', 'This project uses VibeDevKit. Engine in vibekit/runtime. Run /vibe-level to change level.\n');
+  w('.gitignore', '# VibeDevKit — local runtime state (do not commit)\nvibekit/memory/tech-debt-findings.json\n');
+}
+
+// ── Scenario A: dry-run changes nothing ──────────────────────────────────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj);
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate', '--dry-run']);
+    out.status === 0 ? rep.ok('--migrate --dry-run exits 0') : rep.bad(`dry-run status ${out.status}: ${out.stderr}`);
+    existsSync(join(proj, 'vibekit')) && !existsSync(join(proj, 'contextkit'))
+      ? rep.ok('dry-run left vibekit/ in place and created no contextkit/')
+      : rep.bad('dry-run mutated the filesystem');
+    read(join(proj, 'CLAUDE.md')).includes('vibekit/') ? rep.ok('dry-run left CLAUDE.md untouched') : rep.bad('dry-run rewrote CLAUDE.md');
+    /dry-run/i.test(out.stdout) ? rep.ok('dry-run output flags itself') : rep.bad('dry-run output missing the marker');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario B: real migration preserves data + rewrites references ──────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj);
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    out.status === 0 ? rep.ok('--migrate exits 0') : rep.bad(`--migrate status ${out.status}: ${out.stderr}`);
+
+    !existsSync(join(proj, 'vibekit')) ? rep.ok('vibekit/ is gone') : rep.bad('vibekit/ still present');
+    existsSync(join(proj, 'contextkit')) ? rep.ok('contextkit/ exists') : rep.bad('contextkit/ missing');
+
+    // user data preserved
+    const adr = join(proj, 'contextkit', 'memory', 'decisions', '0001-user-decision.md');
+    existsSync(adr) && read(adr).includes('precious user ADR') ? rep.ok('user ADR preserved through the move') : rep.bad('user ADR lost');
+    try {
+      JSON.parse(read(join(proj, 'contextkit', 'config.json'))).level === 5 ? rep.ok('config level 5 preserved') : rep.bad('config level changed');
+    } catch { rep.bad('config.json unreadable after migration'); }
+
+    // .env migrated + backed up
+    const env = read(join(proj, 'contextkit', '.env'));
+    env.includes('CONTEXT_GIT_TIMEOUT_MS') && !env.includes('VIBE_') ? rep.ok('.env VIBE_* → CONTEXT_*') : rep.bad('.env env-var not migrated');
+    existsSync(join(proj, 'contextkit', '.env.bak')) ? rep.ok('.env backed up to .env.bak') : rep.bad('.env.bak missing');
+
+    // settings.json rewired (no legacy paths, no duplicate)
+    const settings = read(join(proj, '.claude', 'settings.json'));
+    !settings.includes('vibekit/') && settings.includes('contextkit/runtime/hooks') ? rep.ok('settings.json rewired to contextkit/') : rep.bad('settings.json still references vibekit/');
+
+    // CLAUDE.md rewritten + backed up
+    const claude = read(join(proj, 'CLAUDE.md'));
+    !claude.includes('vibekit/') && claude.includes('contextkit/') && claude.includes('/context-level') && claude.includes('ContextDevKit')
+      ? rep.ok('CLAUDE.md references rewritten') : rep.bad('CLAUDE.md not fully rewritten');
+    existsSync(join(proj, 'CLAUDE.md.bak')) && read(join(proj, 'CLAUDE.md.bak')).includes('VibeDevKit')
+      ? rep.ok('CLAUDE.md backed up to .bak') : rep.bad('CLAUDE.md.bak missing/wrong');
+
+    // stale commands removed
+    !existsSync(join(proj, '.claude', 'commands', 'setup', 'vibe-level.md')) && !existsSync(join(proj, '.claude', 'commands', 'vibe-stats.md'))
+      ? rep.ok('stale /vibe-* command files removed') : rep.bad('stale command files left behind');
+
+    // .gitignore de-duplicated (now ContextDevKit)
+    read(join(proj, '.gitignore')).includes('ContextDevKit') ? rep.ok('.gitignore block rewritten') : rep.bad('.gitignore not migrated');
+
+    // idempotent: second run is a clean no-op
+    const again = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    again.status === 0 && /nothing to migrate/i.test(again.stdout) ? rep.ok('re-running --migrate is a no-op') : rep.bad('second --migrate was not a clean no-op');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario C: BOTH folders present → refuse, change nothing ────────────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj);
+    mkdirSync(join(proj, 'contextkit'), { recursive: true });
+    writeFileSync(join(proj, 'contextkit', 'config.json'), JSON.stringify({ level: 3 }), 'utf-8');
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    out.status === 0 ? rep.ok('refuse-both exits 0') : rep.bad(`refuse-both status ${out.status}`);
+    /BOTH/i.test(out.stdout) ? rep.ok('warns about BOTH installs') : rep.bad('no BOTH warning');
+    existsSync(join(proj, 'vibekit')) ? rep.ok('refuse-both left vibekit/ untouched') : rep.bad('refuse-both deleted vibekit/');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario D: --update auto-migrates AND refreshes the real engine ─────────
+(() => {
+  const proj = tmp();
+  try {
+    makeLegacy(proj, { withGit: true });
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--update']);
+    out.status === 0 ? rep.ok('--update on a legacy install exits 0') : rep.bad(`--update status ${out.status}: ${out.stderr}`);
+    !existsSync(join(proj, 'vibekit')) ? rep.ok('--update migrated away vibekit/') : rep.bad('--update left vibekit/');
+    // real engine refreshed (the dummy 1-line hook is replaced by the actual script)
+    const hook = join(proj, 'contextkit', 'runtime', 'hooks', 'session-start.mjs');
+    existsSync(hook) && read(hook).length > 200 ? rep.ok('--update refreshed the real engine') : rep.bad('engine not refreshed');
+    // no duplicate hooks: exactly one SessionStart group, referencing contextkit/
+    const s = JSON.parse(read(join(proj, '.claude', 'settings.json')));
+    const ss = s.hooks?.SessionStart || [];
+    ss.length === 1 && !JSON.stringify(s).includes('vibekit/') ? rep.ok('no duplicate hooks after --update') : rep.bad(`duplicate/legacy hooks remain (SessionStart groups: ${ss.length})`);
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+// ── Scenario E: fresh install is unaffected (no legacy → no-op) ──────────────
+(() => {
+  const proj = tmp();
+  try {
+    const out = run([join(KIT, 'install.mjs'), '--target', proj, '--migrate']);
+    out.status === 0 && /nothing to migrate/i.test(out.stdout) ? rep.ok('no-legacy --migrate is a clean no-op') : rep.bad('no-legacy --migrate misbehaved');
+  } finally { rmSync(proj, { recursive: true, force: true }); }
+})();
+
+rep.finish('Integration (migration)');

package/tools/integration-test-tooling.mjs

@@ -22,7 +22,7 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { KIT, run, readJson, reporter, installFixture } from './it-helpers.mjs';
+import { KIT, run, git, readJson, reporter, installFixture } from './it-helpers.mjs';
 
 const rep = reporter();
 const { ok, bad } = rep;
@@ -48,6 +48,30 @@ try {
   (() => { try { const g = JSON.parse(gitStatus.stdout); return g.isRepo === true && g.remoteUrl === null; } catch { return false; } })()
     ? ok('git.mjs reports repo + missing remote') : bad(`git.mjs failed: ${gitStatus.stdout || gitStatus.stderr}`);
 
+  // ADR-0030 — complexity rubric: regulated domain auto-routes + forces architectural tier.
+  const clsLgpd = script('complexity-rubric.mjs', 'classify', 'store user CPF and consent', '--json');
+  (() => { try { const j = JSON.parse(clsLgpd.stdout); return j.domain === 'lgpd' && j.requiredAgents.includes('privacy-lgpd') && j.tier === 'architectural' && j.needsAdr === true; } catch { return false; } })()
+    ? ok('complexity-rubric routes a regulated (LGPD) task to privacy-lgpd + architectural tier')
+    : bad(`complexity-rubric LGPD classify failed: ${clsLgpd.stdout || clsLgpd.stderr}`);
+  const clsTrivial = script('complexity-rubric.mjs', 'classify', 'fix typo in readme', '--json');
+  (() => { try { const j = JSON.parse(clsTrivial.stdout); return j.tier === 'trivial' && j.needsAdr === false && j.domain === 'general'; } catch { return false; } })()
+    ? ok('complexity-rubric classifies a trivial task with no ceremony')
+    : bad(`complexity-rubric trivial classify failed: ${clsTrivial.stdout || clsTrivial.stderr}`);
+
+  // ADR-0030 — validate-doc flags an unfilled ADR template (placeholders), runs the adr rubric.
+  const vdTpl = script('validate-doc.mjs', 'contextkit/memory/decisions/_TEMPLATE.md', '--json');
+  (() => { try { const j = JSON.parse(vdTpl.stdout); return j.type === 'adr' && j.errorCount > 0 && j.findings.some((f) => f.code === 'PLACEHOLDER'); } catch { return false; } })()
+    ? ok('validate-doc flags an unfilled ADR template (placeholders)')
+    : bad(`validate-doc template check failed: ${vdTpl.stdout || vdTpl.stderr}`);
+
+  // ADR-0030 — draft-changelog groups Conventional Commits since the last tag.
+  git(['add', '-A'], proj);
+  git(['commit', '-m', 'feat(x): add a thing', '--no-verify'], proj);
+  const dc = script('draft-changelog.mjs', '--json');
+  (() => { try { const j = JSON.parse(dc.stdout); return Array.isArray(j.groups?.Added) && j.groups.Added.some((i) => i.text.includes('add a thing')); } catch { return false; } })()
+    ? ok('draft-changelog groups Conventional Commits into Keep-a-Changelog sections')
+    : bad(`draft-changelog failed: ${dc.stdout || dc.stderr}`);
+
   // DevPipeline tests live in `integration-test-tooling-pipeline.mjs` (sibling).
 
   // Deep analysis: aggregates the deterministic scanners into one report.