minimal-vibe-coding-kit 0.4.2 → 0.5.1

package/.grok/skills/tutien/scripts/story-ledger.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// Deterministic storage helpers for the agent-authored living chronicle.
+// This module never generates story prose. It only builds an aggregate-only
+// evidence packet and validates the plot/chapter ledger written by the agent.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+export const STORY_SCHEMA = 1;
+export const STORY_CONTEXT_SCHEMA = 'tutien-story-context-v1';
+export const STORY_STATE_SCHEMA = 'tutien-story-state-v1';
+export const STORY_CHAPTER_SCHEMA = 'tutien-story-chapter-v1';
+
+const sha16 = (value) => crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, 16);
+
+export function storyPaths(root = process.cwd()) {
+  const base = path.join(path.resolve(root), '.vibekit', 'reports', 'tutien', 'story');
+  return {
+    base,
+    plot: path.join(base, 'plot.md'),
+    state: path.join(base, 'story-state.json'),
+    context: path.join(base, 'latest-context.json'),
+    chapters: path.join(base, 'chapters')
+  };
+}
+
+// Preserve letters from every language, including Han characters. Latin
+// scripts are normalized so Vietnamese titles remain readable in filenames.
+export function slugifyChapterTitle(title) {
+  const raw = String(title ?? '').trim();
+  if (!raw) throw new Error('chapter title is required');
+  const slug = raw
+    .normalize('NFD')
+    .replace(/\p{M}+/gu, '')
+    .toLocaleLowerCase('und')
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80)
+    .replace(/-+$/g, '');
+  if (!slug || slug === '.' || slug === '..') throw new Error('chapter title does not produce a safe filename');
+  return slug;
+}
+
+export function chapterFilename(number, title) {
+  if (!Number.isInteger(number) || number < 1 || number > 9999) {
+    throw new Error('chapter number must be an integer from 1 to 9999');
+  }
+  return `${String(number).padStart(4, '0')}-${slugifyChapterTitle(title)}.md`;
+}
+
+export function listChapters(root = process.cwd()) {
+  const dir = storyPaths(root).chapters;
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((file) => /^\d{4}-[\p{L}\p{N}][\p{L}\p{N}-]*\.md$/u.test(file))
+    .map((file) => ({ file, number: Number(file.slice(0, 4)), path: path.join(dir, file) }))
+    .sort((a, b) => a.number - b.number || a.file.localeCompare(b.file));
+}
+
+export function nextChapterNumber(root = process.cwd()) {
+  const chapters = listChapters(root);
+  return chapters.length ? chapters[chapters.length - 1].number + 1 : 1;
+}
+
+export function resolveStoryLanguage(requested = 'auto', invocationText = '', fallback = 'en') {
+  const explicit = String(requested).toLowerCase();
+  if (['vi', 'en', 'zh'].includes(explicit)) return explicit;
+  if (/\p{Script=Han}/u.test(invocationText)) return 'zh';
+  if (/[À-ỹĐđ]/u.test(invocationText) || /\b(hãy|giúp|của|và|không|chương|tu tiên)\b/iu.test(invocationText)) return 'vi';
+  return ['vi', 'en', 'zh'].includes(fallback) ? fallback : 'en';
+}
+
+function safeSlug(value, fallback = null) {
+  const text = String(value ?? '');
+  return /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(text) ? text : fallback;
+}
+
+function safeValidationCommand(value) {
+  const text = String(value ?? '');
+  return /^(?:npm run|yarn|pnpm|bun run) [A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/.test(text) ? text : null;
+}
+
+function storyFacts(model, profile = {}) {
+  const cultivation = model.cultivation ?? null;
+  const progression = cultivation?.progression ?? null;
+  return {
+    project: {
+      id: safeSlug(profile.projectId, 'repo'),
+      type: safeSlug(profile.projectType),
+      primaryLanguage: safeSlug(profile.primaryLanguage),
+      domains: (profile.domains ?? []).map((v) => safeSlug(v)).filter(Boolean).slice(0, 12),
+      stack: (profile.stack ?? []).map((v) => safeSlug(v)).filter(Boolean).slice(0, 12),
+      validationCommands: (profile.validationCommands ?? []).map((v) => safeValidationCommand(v)).filter(Boolean).slice(0, 3),
+      metadataSources: (profile.metadataSources ?? []).map((v) => safeSlug(String(v).replace(/\.[^.]+$/, ''))).filter(Boolean).slice(0, 12),
+      authorsCount: Number.isInteger(profile.authorsCount) && profile.authorsCount >= 0 ? profile.authorsCount : null
+    },
+    evidence: {
+      window: model.coverage?.window ?? { start: null, end: null },
+      sessions: model.coverage?.sessions ?? 0,
+      prompts: model.coverage?.userPrompts ?? 0,
+      commits: model.coverage?.commits ?? 0,
+      confidence: model.coverage?.confidence ?? 'low',
+      tokens: {
+        reported: model.tokens?.reportedTotal ?? 0,
+        estimated: model.tokens?.estimatedTotal ?? 0,
+        unknownTurns: model.tokens?.unknownTurns ?? 0
+      },
+      realm: model.realm ? { name: model.realm.name, score: model.score } : null,
+      problems: (model.problems ?? []).map((p) => ({
+        type: p.problemType,
+        confidence: p.confidence,
+        priority: p.priority
+      })),
+      classification: cultivation ? {
+        faction: cultivation.classification?.faction?.id ?? null,
+        affiliation: cultivation.classification?.affiliation?.id ?? null,
+        paths: (cultivation.classification?.paths ?? []).map((p) => p.id)
+      } : null,
+      progression: progression ? {
+        tuVi: progression.tuVi?.window ?? 0,
+        congDuc: progression.congDuc?.window ?? 0,
+        nghiepLuc: progression.nghiepLuc?.window ?? 0,
+        daoHanhWindows: progression.daoHanh?.windows ?? 0,
+        overlap: progression.overlap ?? 0
+      } : null
+    }
+  };
+}
+
+export function buildStoryContext(model, options = {}) {
+  const facts = storyFacts(model, options.profile ?? {});
+  const evidenceKey = sha16(JSON.stringify({
+    storySchema: STORY_SCHEMA,
+    project: facts.project.id,
+    range: options.range ?? 'all',
+    evidence: facts.evidence
+  }));
+  return {
+    schema: STORY_CONTEXT_SCHEMA,
+    storySchema: STORY_SCHEMA,
+    evidenceKey,
+    language: resolveStoryLanguage(options.language, options.invocationText, options.conversationLanguage),
+    style: safeSlug(options.style, 'auto'),
+    focus: safeSlug(options.focus, 'balanced'),
+    policyState: model.policyState ?? 'clear',
+    canWriteChapter: model.suppressGamification !== true,
+    ...facts
+  };
+}
+
+export function writeStoryContext(root, context) {
+  if (context?.schema !== STORY_CONTEXT_SCHEMA) throw new Error(`story context must use ${STORY_CONTEXT_SCHEMA}`);
+  const paths = storyPaths(root);
+  fs.mkdirSync(paths.base, { recursive: true });
+  fs.writeFileSync(paths.context, `${JSON.stringify(context, null, 2)}\n`);
+  return paths.context;
+}
+
+function chapterFrontmatter(text) {
+  const match = String(text).match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return null;
+  const get = (key) => match[1].match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim().replace(/^['"]|['"]$/g, '') ?? null;
+  return {
+    schema: get('schema'),
+    chapter: Number(get('chapter')),
+    title: get('title'),
+    evidenceKey: get('evidence_key')
+  };
+}
+
+export function validateStoryTree(root = process.cwd()) {
+  const paths = storyPaths(root);
+  const chapters = listChapters(root);
+  const errors = [];
+  if (chapters.length && !fs.existsSync(paths.plot)) errors.push('plot.md is required when chapters exist');
+
+  let state = null;
+  if (fs.existsSync(paths.state)) {
+    try {
+      state = JSON.parse(fs.readFileSync(paths.state, 'utf8'));
+      if (state.schema !== STORY_STATE_SCHEMA) errors.push(`story-state.json must use ${STORY_STATE_SCHEMA}`);
+    } catch {
+      errors.push('story-state.json must contain valid JSON');
+    }
+  } else if (chapters.length) {
+    errors.push('story-state.json is required when chapters exist');
+  }
+
+  const evidenceKeys = new Set();
+  for (let i = 0; i < chapters.length; i += 1) {
+    const expected = i + 1;
+    const item = chapters[i];
+    if (item.number !== expected) errors.push(`chapter sequence must be contiguous: expected ${expected}, found ${item.number}`);
+    const fm = chapterFrontmatter(fs.readFileSync(item.path, 'utf8'));
+    if (!fm) {
+      errors.push(`${item.file} is missing YAML frontmatter`);
+      continue;
+    }
+    if (fm.schema !== STORY_CHAPTER_SCHEMA) errors.push(`${item.file} must use ${STORY_CHAPTER_SCHEMA}`);
+    if (fm.chapter !== item.number) errors.push(`${item.file} frontmatter chapter must equal ${item.number}`);
+    if (!fm.title) errors.push(`${item.file} requires a title`);
+    if (!fm.evidenceKey || !/^[0-9a-f]{16}$/.test(fm.evidenceKey)) errors.push(`${item.file} requires a 16-hex evidence_key`);
+    else if (evidenceKeys.has(fm.evidenceKey)) errors.push(`${item.file} repeats evidence_key ${fm.evidenceKey}`);
+    else evidenceKeys.add(fm.evidenceKey);
+  }
+
+  if (state) {
+    if (state.lastChapter !== chapters.length) errors.push(`story-state.json lastChapter must equal ${chapters.length}`);
+    const consumed = state.consumedEvidenceKeys ?? [];
+    if (!Array.isArray(consumed) || consumed.some((key) => !/^[0-9a-f]{16}$/.test(key))) {
+      errors.push('story-state.json consumedEvidenceKeys must be an array of 16-hex keys');
+    }
+    for (const key of evidenceKeys) {
+      if (!consumed.includes(key)) errors.push(`story-state.json is missing consumed evidence key ${key}`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    chapters: chapters.length,
+    nextChapter: chapters.length + 1,
+    paths: Object.fromEntries(Object.entries(paths).map(([key, value]) => [key, path.relative(path.resolve(root), value)]))
+  };
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const command = process.argv[2] ?? 'status';
+  const root = path.resolve(process.argv[3] ?? process.cwd());
+  if (!['status', 'validate'].includes(command)) {
+    console.error('usage: story-ledger.mjs [status|validate] [repo-root]');
+    process.exit(2);
+  }
+  const result = validateStoryTree(root);
+  console.log(JSON.stringify(result, null, 2));
+  if (command === 'validate' && !result.ok) process.exit(1);
+}

package/.grok/skills/tutien/scripts/villains.mjs

@@ -0,0 +1,196 @@
+// Phase 3 villain engine. Evidence chooses the problem and the
+// counter-technique; a deterministic seed chooses only the villain's name and
+// wording. Nothing here can change a count, severity, evidence, or advice.
+//
+// Safety rails (all enforced, not optional):
+//  - a villain appears only when its problem confidence >= threshold (0.80);
+//  - at most one boss and two minor villains per report;
+//  - villains=off, tone=neutral, or any emergency signal -> no villains;
+//  - challenge lines are authored safe and re-checked against banned
+//    categories before emission;
+//  - origin stories use only an allowlist of sanitized context slugs — never
+//    raw prompts, secrets, names, emails, or identity-bearing paths.
+
+import crypto from 'node:crypto';
+import { normalizeTone } from './command.mjs';
+
+export const VILLAIN_THRESHOLD = 0.8;
+export const MAX_BOSS = 1;
+export const MAX_MINOR = 2;
+export const DEFAULT_COOLDOWN_WINDOWS = 2;
+
+// Defense-in-depth: challenge lines are written to avoid these, but every
+// emitted line is re-scanned so a future edit cannot slip an attack through.
+const BANNED_CATEGORY = [
+  /\b(stupid|idiot|idiotic|incompetent|dumb|moron|useless|worthless|pathetic|loser|failure of a)\b/i,
+  /\b(insane|crazy|psycho|mental|deranged|unhinged|tẩu hỏa nhập ma)\b/i,
+  /\b(retard|cripple|disabled|handicapped)\b/i,
+  /\b(sin|heretic against god|infidel|kafir|damned to hell)\b/i,
+  /\b(man up|like a girl|woman driver|too emotional for a)\b/i,
+  /\b(race|racial|ethnic slur|your people)\b/i,
+  /\b(broke|poor|can't afford|worthless salary|financial failure)\b/i,
+  /\b(kill|die|hurt you|destroy you|i will end)\b/i,
+  /\b(f[u*]ck|sh[i*]t|damn you|bastard)\b/i,
+  /\b(humiliat|shame on you|you should be ashamed|embarrass yourself)\b/i
+];
+
+export function containsBannedCategory(text) {
+  return BANNED_CATEGORY.some((re) => re.test(String(text)));
+}
+
+// Only these context fields may shape an origin story, and each must be a
+// strict slug: no slashes, dots, at-signs, spaces, or traversal — so neither
+// free text nor path-like or identity-bearing values can ride along.
+const CONTEXT_ALLOWLIST = ['projectType', 'primaryLanguage', 'fileCategory', 'validationLabel', 'metricCategory'];
+const SLUG = /^[a-z0-9][a-z0-9_-]{0,39}$/i;
+
+export function sanitizeContext(ctx = {}) {
+  const out = {};
+  for (const key of CONTEXT_ALLOWLIST) {
+    const v = ctx[key];
+    if (typeof v === 'string' && SLUG.test(v)) out[key] = v;
+  }
+  return out;
+}
+
+// Two authored variants per tone per archetype. The seed picks the index, so
+// changing the seed changes wording only. The serene/spirited vocabulary is
+// local to this coding-reflection game and always targets the workflow pattern,
+// never the person or any unrelated support/companion persona.
+const LINES = {
+  'repeated-failure': {
+    serene: [
+      { vi: 'Giữa làn sương mỏng, Luân Hồi Ma Ảnh hiện bóng khi lỗi cũ quay thêm một vòng.', en: 'In the thin mountain mist, the Error-Cycle Wraith appears as the old error completes another circle.' },
+      { vi: 'Một lần thử giống hệt khẽ lay chuông, gọi Luân Hồi Ma Ảnh trở lại đạo lộ.', en: 'One unchanged retry stirs the bell that calls the Error-Cycle Wraith back to the path.' }
+    ],
+    spirited: [
+      { vi: 'Luân Hồi Ma Ảnh lại gõ chuông: “Không đổi giả thuyết, sao đổi được kết cục?”', en: 'The Error-Cycle Wraith rings its bell again: “Without a new hypothesis, what new ending could appear?”' },
+      { vi: 'Vòng lặp cũ vừa khép, Luân Hồi Ma Ảnh đã bày sẵn bàn trà chờ vòng kế tiếp.', en: 'The old loop has barely closed, and the Error-Cycle Wraith has already set tea for the next.' }
+    ]
+  },
+  'too-many-prompts': {
+    serene: [
+      { vi: 'Cửu Hoàn Tâm Ma dệt một nhiệm vụ thành nhiều vòng sương khi cột mốc chưa hiện rõ.', en: 'The Ninefold Loop Heart-Shadow weaves one task into rings of mist when its checkpoints remain unclear.' },
+      { vi: 'Nơi ranh giới nhiệm vụ nhạt dần, Cửu Hoàn Tâm Ma lặng lẽ nối thêm một vòng.', en: 'Where a task boundary fades, the Ninefold Loop Heart-Shadow quietly adds another circle.' }
+    ],
+    spirited: [
+      { vi: 'Cửu Hoàn Tâm Ma đếm lượt yêu cầu thay cột mốc; đã đến lúc đổi chiếc vòng kế tiếp thành một tiêu chí hoàn thành.', en: 'The Ninefold Loop Heart-Shadow is counting prompts instead of checkpoints; turn the next circle into a done-criterion.' },
+      { vi: 'Lượt yêu cầu càng tản như lá thu, Cửu Hoàn Tâm Ma càng dễ giấu mất lối ra.', en: 'The more prompts scatter like autumn leaves, the easier the Ninefold Loop Heart-Shadow hides the exit.' }
+    ]
+  },
+  'conflicting-instructions': {
+    serene: [
+      { vi: 'Nghịch Lệnh Ma Quân hiện giữa hai đạo lệnh không thể cùng đứng vững.', en: 'The Lord of Clashing Edicts appears between two instructions that cannot stand together.' },
+      { vi: 'Hai đạo lệnh ngược chiều làm mặt hồ dậy sóng, và Nghịch Lệnh Ma Quân bước ra.', en: 'Two opposing edicts ripple the still lake, and the Lord of Clashing Edicts steps forth.' }
+    ],
+    spirited: [
+      { vi: 'Nghịch Lệnh Ma Quân giơ hai cuộn lệnh và hỏi: “Cuộn nào mới thật sự dẫn đường?”', en: 'The Lord of Clashing Edicts raises two scrolls and asks: “Which one truly leads the way?”' },
+      { vi: 'Hai lệnh cùng tranh ngôi; Nghịch Lệnh Ma Quân chỉ cần ta chưa lập thứ tự ưu tiên.', en: 'Two edicts contest the throne; the Lord of Clashing Edicts needs only an absent precedence rule.' }
+    ]
+  },
+  'unrecovered-failure': {
+    serene: [
+      { vi: 'Vô Nghiệm Ảnh Quân ẩn sau một thất bại chưa được soi lại bằng lần kiểm chứng mới.', en: 'The Unverified Trial Wraith rests behind a failure that has not yet met a fresh validation.' },
+      { vi: 'Một lỗi bị bỏ lại làm bóng Vô Nghiệm Ảnh Quân dài thêm trên bậc đá.', en: 'A failure left behind lengthens the Unverified Trial Wraith’s shadow across the stone steps.' }
+    ],
+    spirited: [
+      { vi: 'Vô Nghiệm Ảnh Quân phủi bụi trên ghế đá: một lần kiểm chứng thành công là đủ để mời nó rời đi.', en: 'The Unverified Trial Wraith dusts its stone seat; one passing validation is enough to send it on its way.' },
+      { vi: 'Chưa có lần chạy lại, Vô Nghiệm Ảnh Quân vẫn ung dung giữ chỗ bên cổng hoàn thành.', en: 'Without a rerun, the Unverified Trial Wraith calmly keeps its seat beside the completion gate.' }
+    ]
+  },
+  'work-without-proof': {
+    serene: [
+      { vi: 'Vô Chứng Đan Ảnh lảng vảng bên lò luyện khi lời tuyên bố hoàn thành chưa có bằng chứng đi cùng.', en: 'The Proofless Elixir Shade lingers by the furnace when a claim of completion carries no evidence.' },
+      { vi: 'Một bản ghi Git thiếu kết quả kiểm chứng để lại làn khói mỏng cho Vô Chứng Đan Ảnh nương thân.', en: 'A commit without validation leaves a thread of smoke where the Proofless Elixir Shade can dwell.' }
+    ],
+    spirited: [
+      { vi: 'Vô Chứng Đan Ảnh nâng chén trà bên viên đan chưa thử; một dòng kiểm chứng sẽ làm màn khói tan ngay.', en: 'The Proofless Elixir Shade raises tea beside an untested pill; one validation line will clear the smoke.' },
+      { vi: 'Không có biên nhận kiểm chứng, Vô Chứng Đan Ảnh cứ ngỡ lò luyện thuộc về mình.', en: 'Without a validation receipt, the Proofless Elixir Shade starts to think the furnace is its own.' }
+    ]
+  }
+};
+
+// Roll the villain cooldown forward one reporting window. Villains shown this
+// run reset to a full cooldown; villains from prior runs that were not shown
+// decrement and drop at zero. Feeds the next run's `priorVillains`.
+export function advanceVillainState(prevState = [], shownVillains = []) {
+  const next = new Map();
+  for (const p of prevState) {
+    const remaining = Math.max(0, (p.windowsRemaining ?? 0) - 1);
+    if (remaining > 0) next.set(p.problemId, { problemId: p.problemId, windowsRemaining: remaining, priority: p.priority });
+  }
+  for (const v of shownVillains) {
+    next.set(v.problemId, { problemId: v.problemId, windowsRemaining: v.cooldownWindows ?? DEFAULT_COOLDOWN_WINDOWS, priority: v.priorityAtShow ?? v.priority ?? 0 });
+  }
+  return [...next.values()].sort((a, b) => a.problemId.localeCompare(b.problemId));
+}
+
+export function villainSeed({ projectId = 'repo', window = 'all', schemaVersion = 1 } = {}) {
+  return crypto.createHash('sha256').update(`${projectId}${window}${schemaVersion}`).digest('hex');
+}
+
+// Deterministic non-negative index from the seed and a per-villain salt.
+function seedIndex(seed, salt, n) {
+  if (n <= 1) return 0;
+  const h = crypto.createHash('sha256').update(`${seed}${salt}`).digest();
+  return h[0] % n;
+}
+
+// problems: the raw output of detectProblems(analysis).
+// options: { tone, villains, threshold, emergency, seedInputs, context,
+//            priorVillains: [{ problemId, windowsRemaining, priority }] }.
+export function buildVillains(problems, options = {}) {
+  const tone = normalizeTone(options.tone);
+  if (options.villains === 'off') return { villains: [], suppressed: 'villains-off' };
+  if (tone === 'neutral' || options.emergency) return { villains: [], suppressed: 'neutral-context' };
+
+  const threshold = options.threshold ?? VILLAIN_THRESHOLD;
+  const seed = villainSeed(options.seedInputs);
+  const context = sanitizeContext(options.context);
+  const prior = new Map((options.priorVillains ?? []).map((p) => [p.problemId, p]));
+
+  const eligible = problems
+    .filter((p) => p.confidence >= threshold && LINES[p.problemId])
+    .sort((a, b) => b.priority - a.priority || a.problemId.localeCompare(b.problemId));
+
+  const cards = [];
+  let bosses = 0;
+  let minors = 0;
+  for (const p of eligible) {
+    // Cooldown: skip a villain still cooling down unless its problem worsened.
+    const was = prior.get(p.problemId);
+    if (was && was.windowsRemaining > 0 && p.priority <= was.priority) continue;
+
+    let role;
+    if (bosses < MAX_BOSS) { role = 'boss'; bosses += 1; }
+    else if (minors < MAX_MINOR) { role = 'minor'; minors += 1; }
+    else break;
+
+    const toneLines = LINES[p.problemId][tone] ?? LINES[p.problemId].serene;
+    const idx = seedIndex(seed, p.problemId, toneLines.length);
+    const challenge = toneLines[idx];
+
+    if (containsBannedCategory(challenge.vi) || containsBannedCategory(challenge.en)) {
+      // Fail safe: drop the theatrics, keep the finding (rendered plainly).
+      continue;
+    }
+
+    cards.push({
+      problemId: p.problemId,
+      role,
+      priority: p.priority,
+      archetype: p.meta.villain,
+      tone,
+      challenge,
+      originSignals: [`metric:${p.meta.problemType}`, ...Object.values(context)],
+      evidenceRefs: p.evidence.eventIds ?? [],
+      confidence: p.confidence,
+      rebuttal: p.meta.counterTechnique,
+      microQuest: p.meta.microQuest,
+      victory: p.meta.victory,
+      cooldownWindows: DEFAULT_COOLDOWN_WINDOWS,
+      safetyFlags: ['failure-mode-not-person', 'evidence-bound']
+    });
+  }
+  return { villains: cards, suppressed: null };
+}

package/.vibekit/docs/BACKBONE_REFERENCE.md

@@ -40,6 +40,8 @@ If no command is known, leave `validate` as a safe echo and ask the user to fill
 
 The `conventions` section is created during first-time init and must be reviewed before writing. It should capture repo-specific rules with evidence, not a fixed framework template.
 
+`conventions.review_required_before_write: true` means: before writing to agent surfaces or instruction files — rules, skills, workflows, commands, root instruction files, and `backbone.yml` itself — the agent must show the proposed diff and wait for explicit approval. It does not gate ordinary code edits inside `policy.editable_paths`. Skills that offer a "clean, proceed in the same turn" path (for example `claim`) must downgrade to propose-and-wait for writes this flag covers.
+
 Include:
 
 - Naming style for files, directories, and symbols.

package/.vibekit/docs/INSTALL.md

@@ -127,8 +127,10 @@ The installer also includes `visual-design-loop` for Claude, Codex, and Grok sur
 
 ## User-invoked utility skills
 
-Three user-invoked skills install across Claude, Codex, Cursor, and Grok surfaces:
+Five user-invoked skills install across Claude, Codex, Cursor, and Grok surfaces:
 
 - `memento`: write a `MEMENTO.md` working note before closing a multi-day task (`/memento`), then resume from it in the next session (`/memento resume`).
 - `coding-level`: set the explanation register from 0 (ELI5) to 5 (expert peer) with `/coding-level N`; stays active until reinvoked.
 - `prompt-sharpener`: sharpen a rough prompt into a precise one with `/prompt-sharpener <rough prompt>`, then execute the sharpened version immediately in the same turn.
+- `claim`: vet a request to bring something new into the repo with `/claim <request>` — validate URLs and references against official sources, check fit with existing rules and skills, confirm anything unclear, then integrate and document it.
+- `tutien`: turn Git history and explicitly supplied AI-chat exports into a private, funny xianxia "cultivation" report with `/tutien` (realm, token use, workflow habits, evidence-bound suggestions); read-only, aggregate-only by default, and `/tutien off` disables the mode.

package/.vibekit/init/CLAUDE-template.md

@@ -18,6 +18,8 @@ This file is intentionally small. Shared rules live in `AGENTS.md`, project fact
 - `/daily-enhance` - propose rule, skill, and workflow improvements.
 - `/coding-level N` - set explanation depth 0-5; the project default lives in `backbone.yml` `conventions.custom_rules`.
 - `/prompt-sharpener <rough prompt>` - sharpen a rough prompt into a precise one, then execute it in the same turn.
+- `/claim <request>` - vet a request to bring something new into the repo (validate sources, fit-check, confirm, integrate, document).
+- `/tutien` - private, funny xianxia "cultivation" progress report from Git history + supplied AI-chat exports; `/tutien off` disables it.
 
 ## Hard rules
 

package/.vibekit/scripts/mvck.mjs

@@ -168,12 +168,12 @@ function parseProfiles(profileRaw) {
   return profiles;
 }
 const CLAUDE_DIRS = ['.claude/agents', '.claude/commands', '.claude/rules'];
-const CLAUDE_SKILLS = [
-  'autoresearch-coding', 'agentshield-security-review', 'daily-workflow-curator', 'vibekit-init', 'visual-design-loop',
-  'clearthought', 'sequential-thinking', 'reviewing-4p-priorities', 'path-sensitive-shell-safety', 'memento', 'coding-level', 'parallel-analysis', 'prompt-sharpener'
-];
+// Skill registries come from the central distribution manifest so the
+// installer and the validator cannot drift apart.
+const skillsManifest = JSON.parse(fs.readFileSync(path.join(kitRoot, '.vibekit/skills/skills-manifest.json'), 'utf8'));
+const CLAUDE_SKILLS = skillsManifest.skills.map((s) => s.name);
 const CURSOR_DIRS = ['.cursor/rules', '.cursor/commands'];
-const CURSOR_SKILLS = ['clearthought', 'sequential-thinking', 'reviewing-4p-priorities', 'path-sensitive-shell-safety', 'memento', 'coding-level', 'parallel-analysis', 'prompt-sharpener'];
+const CURSOR_SKILLS = skillsManifest.skills.filter((s) => (s.surfaces || []).includes('cursor')).map((s) => s.name);
 const CODEX_DIRS = ['.agents', '.codex', '.codex-plugin'];
 const GROK_DIRS = ['.grok'];
 const GITIGNORE_BLOCK = `# BEGIN: minimal-vibe-coding-kit\n.autoresearch/\nresults.tsv\n.vibekit/INIT_DONE\n.vibekit/FINALIZE_DONE\n.vibekit/reports/\n.vibekit/update-backup/\n_vibekit-cleanup/\nCLAUDE.local.md\n# END: minimal-vibe-coding-kit`;

package/.vibekit/scripts/pack-dry-run.mjs

@@ -1,16 +1,51 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const cache = process.env.MVCK_NPM_CACHE || path.join(os.tmpdir(), 'mvck-npm-cache');
-const result = spawnSync(npm, ['pack', '--dry-run'], {
-  stdio: 'inherit',
+const result = spawnSync(npm, ['pack', '--dry-run', '--json'], {
+  encoding: 'utf8',
   env: {
     ...process.env,
     npm_config_cache: cache
   }
 });
 
-process.exit(result.status ?? 1);
+if (result.status !== 0) {
+  process.stderr.write(result.stderr || '');
+  process.exit(result.status ?? 1);
+}
+
+let packed;
+try {
+  packed = new Set(JSON.parse(result.stdout)[0].files.map((file) => file.path));
+} catch (err) {
+  console.error(`FAIL could not parse npm pack --dry-run --json output: ${err.message}`);
+  process.exit(1);
+}
+
+// Every skill file present on disk must ship in the tarball. A skill directory
+// added without its package.json `files` entry fails here with the missing path.
+const skillRoots = ['.vibekit/skills', '.claude/skills', '.cursor/skills', '.agents/skills', '.grok/skills'];
+const expected = [];
+function walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = path.posix.join(dir, entry.name);
+    if (entry.isDirectory()) walk(rel);
+    else expected.push(rel);
+  }
+}
+for (const root of skillRoots) {
+  if (fs.existsSync(root)) walk(root);
+}
+
+const missing = expected.filter((rel) => !packed.has(rel));
+for (const rel of missing) console.error(`FAIL packaged tarball is missing ${rel}`);
+if (missing.length > 0) {
+  console.error(`Pack dry-run: ${missing.length} of ${expected.length} on-disk skill files are not packaged.`);
+  process.exit(1);
+}
+console.log(`PASS pack dry-run: all ${expected.length} on-disk skill files are packaged (${packed.size} files in tarball)`);

package/.vibekit/scripts/validate-kit.mjs

@@ -47,15 +47,31 @@ for (const [surface, present] of Object.entries(surfacePresent)) {
   if (!present) console.log(`INFO surface ${surface} not installed; skipping its checks`);
 }
 
-const KIT_SKILLS = [
-  'autoresearch-coding', 'agentshield-security-review', 'daily-workflow-curator', 'vibekit-init',
-  'clearthought', 'sequential-thinking', 'reviewing-4p-priorities', 'visual-design-loop',
-  'path-sensitive-shell-safety', 'memento', 'coding-level', 'parallel-analysis', 'prompt-sharpener'
-];
-const CURSOR_KIT_SKILLS = [
-  'clearthought', 'sequential-thinking', 'reviewing-4p-priorities', 'path-sensitive-shell-safety',
-  'memento', 'coding-level', 'parallel-analysis', 'prompt-sharpener'
-];
+// Skill registries come from the central distribution manifest shared with
+// the installer; validation fails closed when the manifest is missing.
+const MANIFEST_REL = '.vibekit/skills/skills-manifest.json';
+const skillsManifest = readJson(MANIFEST_REL);
+if (!skillsManifest || !Array.isArray(skillsManifest.skills)) {
+  fail(`missing or invalid ${MANIFEST_REL}; installer and validator registries derive from it`);
+}
+const manifestSkills = skillsManifest?.skills ?? [];
+const KIT_SKILLS = manifestSkills.map((s) => s.name);
+const CURSOR_KIT_SKILLS = manifestSkills.filter((s) => (s.surfaces || []).includes('cursor')).map((s) => s.name);
+
+// Fail closed: a canonical skill directory that is not in the manifest would
+// otherwise escape mirror, package, and install validation entirely.
+const canonicalSkillDirs = exists('.vibekit/skills')
+  ? fs.readdirSync(path.join(root, '.vibekit/skills'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)
+  : [];
+for (const dir of canonicalSkillDirs) {
+  if (KIT_SKILLS.includes(dir)) continue;
+  const msg = `canonical skill dir .vibekit/skills/${dir} is not registered in ${MANIFEST_REL}`;
+  if (isKitSourceRepo) fail(msg);
+  else warn(`${msg}; register it to get mirror, package, and install validation`);
+}
+for (const skill of KIT_SKILLS) {
+  if (!canonicalSkillDirs.includes(skill)) fail(`manifest skill ${skill} has no canonical dir .vibekit/skills/${skill}`);
+}
 
 const required = [
   'AGENTS.md', '.vibekit/init/CLAUDE-template.md', '.vibekit/init/FIRST_TIME_INIT.md', '.vibekit/init/FIRST_PROMPT.md', 'backbone.yml',
@@ -142,21 +158,15 @@ if (exists('.vibekit/docs/AUTORESEARCH_LEDGER.md')) {
   stalePhrase ? fail(`.vibekit/docs/AUTORESEARCH_LEDGER.md contains stale phrase: ${stalePhrase}`) : ok('autoresearch ledger has no stale build placeholders');
 }
 
-const skillMirrors = {
-  'autoresearch-coding': ['.claude/skills/autoresearch-coding', '.agents/skills/autoresearch-coding', '.grok/skills/autoresearch-coding'],
-  'agentshield-security-review': ['.claude/skills/agentshield-security-review', '.agents/skills/agentshield-security-review', '.grok/skills/agentshield-security-review'],
-  'daily-workflow-curator': ['.claude/skills/daily-workflow-curator', '.agents/skills/daily-workflow-curator', '.grok/skills/daily-workflow-curator'],
-  'vibekit-init': ['.claude/skills/vibekit-init', '.agents/skills/vibekit-init', '.grok/skills/vibekit-init'],
-  'clearthought': ['.claude/skills/clearthought', '.cursor/skills/clearthought', '.agents/skills/clearthought', '.grok/skills/clearthought'],
-  'sequential-thinking': ['.claude/skills/sequential-thinking', '.cursor/skills/sequential-thinking', '.agents/skills/sequential-thinking', '.grok/skills/sequential-thinking'],
-  'reviewing-4p-priorities': ['.claude/skills/reviewing-4p-priorities', '.cursor/skills/reviewing-4p-priorities', '.agents/skills/reviewing-4p-priorities', '.grok/skills/reviewing-4p-priorities'],
-  'path-sensitive-shell-safety': ['.claude/skills/path-sensitive-shell-safety', '.cursor/skills/path-sensitive-shell-safety', '.agents/skills/path-sensitive-shell-safety', '.grok/skills/path-sensitive-shell-safety'],
-  'visual-design-loop': ['.claude/skills/visual-design-loop', '.agents/skills/visual-design-loop', '.grok/skills/visual-design-loop'],
-  'memento': ['.claude/skills/memento', '.cursor/skills/memento', '.agents/skills/memento', '.grok/skills/memento'],
-  'coding-level': ['.claude/skills/coding-level', '.cursor/skills/coding-level', '.agents/skills/coding-level', '.grok/skills/coding-level'],
-  'parallel-analysis': ['.claude/skills/parallel-analysis', '.cursor/skills/parallel-analysis', '.agents/skills/parallel-analysis', '.grok/skills/parallel-analysis'],
-  'prompt-sharpener': ['.claude/skills/prompt-sharpener', '.cursor/skills/prompt-sharpener', '.agents/skills/prompt-sharpener', '.grok/skills/prompt-sharpener']
-};
+// Mirror registry is derived from the manifest so a skill cannot be
+// registered for install yet skipped by parity validation.
+const MANIFEST_SURFACE_DIRS = { claude: '.claude/skills', cursor: '.cursor/skills', codex: '.agents/skills', grok: '.grok/skills' };
+const skillMirrors = {};
+for (const skill of manifestSkills) {
+  skillMirrors[skill.name] = (skill.surfaces || [])
+    .filter((surface) => MANIFEST_SURFACE_DIRS[surface])
+    .map((surface) => `${MANIFEST_SURFACE_DIRS[surface]}/${skill.name}`);
+}
 
 function validateSkillMirror(sourceRel, mirrorRel) {
   if (!exists(sourceRel)) { fail(`missing canonical skill dir ${sourceRel}`); return; }