minimal-vibe-coding-kit 0.4.2 → 0.5.0

package/.grok/skills/tutien/scripts/run-tutien.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { parseInvocation, TUTIEN_EXPERIENCE } from './command.mjs';
+import { analyze } from './analyze-history.mjs';
+import { renderReport, resolveLanguage, renderClassificationMarkdown } from './render-report.mjs';
+import { buildSnapshot, snapshotsToPrune } from './snapshot.mjs';
+import { compareSnapshots } from './compare.mjs';
+import { classifyProject } from './classify.mjs';
+
+// End-to-end executor for the advertised /tutien actions. All state lives
+// under the git-ignored .vibekit/reports/tutien/ of the current repo; the
+// runner never deletes anything (retention only prints a `trash` command).
+//
+//   run-tutien.mjs [on|off|status|preview|analyze|compare|explain|classify] [k=v ...]
+//
+// Approval boundary: `preview` prints the exact scope and an approval token;
+// `analyze` refuses to read anything until it receives approve=<that token>
+// for the identical scope.
+
+const sha16 = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+
+const root = process.cwd();
+const reportDir = path.join(root, '.vibekit', 'reports', 'tutien');
+const stateFile = path.join(reportDir, 'state.json');
+const snapDir = path.join(reportDir, 'snapshots');
+
+function loadState() {
+  try {
+    return JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  } catch {
+    return { mode: 'off' };
+  }
+}
+function saveState(state) {
+  fs.mkdirSync(reportDir, { recursive: true });
+  fs.writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function classifySources(sources) {
+  const spec = { jsonlFiles: [], transcriptFiles: [], gitRoot: null };
+  for (const s of sources) {
+    if (s === 'git') spec.gitRoot = root;
+    else if (s.endsWith('.jsonl')) spec.jsonlFiles.push(s);
+    else spec.transcriptFiles.push(s);
+  }
+  return spec;
+}
+
+const scopeToken = (sources, range) => sha16(JSON.stringify({ sources: [...sources].sort(), range }));
+
+// Project profile for classification: repo metadata only (backbone.yml
+// fields plus a distinct-commit-author COUNT — no names or emails are kept)
+// merged with explicit declarations from the invocation.
+function repoProfile(options) {
+  let description = null;
+  let primaryLanguage = null;
+  let projectType = null;
+  try {
+    const text = fs.readFileSync(path.join(root, 'backbone.yml'), 'utf8');
+    const grab = (re) => {
+      const m = text.match(re);
+      return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
+    };
+    description = grab(/^\s*description:\s*(.+)$/m);
+    primaryLanguage = grab(/^\s*primary_language:\s*(.+)$/m);
+    projectType = grab(/^\s*type:\s*(.+)$/m);
+  } catch {}
+  // Author identifiers are read transiently (mailmap-collapsed) and reduced to
+  // a distinct COUNT immediately; no email or name is retained or returned.
+  let authorsCount = null;
+  const res = spawnSync('git', ['log', '--use-mailmap', '--format=%aE'], { cwd: root, encoding: 'utf8' });
+  if (res.status === 0) authorsCount = new Set(res.stdout.split('\n').filter(Boolean)).size;
+  return {
+    description,
+    primaryLanguage,
+    projectType,
+    domains: options.domains ?? [],
+    authorization: options.authorization ?? null,
+    authorsCount,
+    declared: { faction: options.faction, affiliation: options.affiliation, paths: options.paths }
+  };
+}
+
+// Preview inspects no content: file existence and size only, plus the git
+// toplevel path. Nothing is parsed and nothing is written except the pending
+// approval in the state file.
+function previewLines(options) {
+  const lines = ['tutien preview — the observatory is open, but no scroll has been read; nothing is analyzed until this exact scope is approved.'];
+  if (options.sources.length === 0) lines.push('- (no sources; pass sources=git,/path/to/export.jsonl)');
+  for (const s of options.sources) {
+    if (s === 'git') {
+      lines.push(`- git: commit metadata of ${root} (read-only git log, current repository only)`);
+    } else {
+      let size = null;
+      try {
+        size = fs.statSync(s).size;
+      } catch {}
+      lines.push(size == null ? `- file: ${s} (NOT FOUND)` : `- file: ${s} (${size} bytes)`);
+    }
+  }
+  lines.push(`- range: ${options.range}`);
+  const token = scopeToken(options.sources, options.range);
+  lines.push(`To approve exactly this scope: analyze approve=${token} sources=${options.sources.join(',')}`);
+  return { lines, token };
+}
+
+const EXPLAIN = {
+  reportedTotal: 'Sum of provider-reported usable token totals; cumulative streaming records sharing a requestId are counted once (last value), independent chunks are summed. Records without a computable positive total never contribute.',
+  estimatedTotal: 'Sum of locally estimated usable token totals; never mixed into reportedTotal.',
+  unknownTurns: 'Assistant message turns whose usage is absent or has no usable total; claimed accuracy without numbers counts as unknown.',
+  retryLoops: 'Runs of 3+ exact/near-identical user prompts within one task with intervening assistant/tool events; confidence-scored candidates.',
+  conflicts: 'A "never/do not X" instruction followed in the same task by a later prompt requesting X; paired event IDs, confidence 0.6.',
+  realm: 'Weighted dimension score (delivery 30%, validation 25%, clarity 15%, recovery 15%, safety 10%, automation 5%) mapped to the realm ladder; requires >= 60% known-token coverage, otherwise "Chưa đủ thiên cơ".'
+};
+
+export function run(argsString = '') {
+  const { action, explicitAction, options } = parseInvocation(argsString);
+  const state = loadState();
+  const refuse = (msg) => ({ code: 2, out: [msg] });
+
+  if (action === 'off') {
+    state.mode = 'off';
+    delete state.pendingApproval;
+    saveState(state);
+    return { code: 0, out: ['Tutien mode is off. Normal kit writing style restored.'] };
+  }
+  if (action === 'on') {
+    state.mode = 'on';
+    saveState(state);
+    return { code: 0, out: ['Tutien mode is on — the mountain gate is open. Run preview to see the exact scope before any analysis.'] };
+  }
+  if (action === 'status') {
+    const snaps = fs.existsSync(snapDir) ? fs.readdirSync(snapDir).length : 0;
+    return {
+      code: 0,
+      out: [
+        `mode: ${state.mode ?? 'off'}`,
+        `experience: ${TUTIEN_EXPERIENCE.kind}`,
+        `voice: ${TUTIEN_EXPERIENCE.narrativeStyle}`,
+        `semantic namespace: ${TUTIEN_EXPERIENCE.semanticNamespace}`,
+        `pending approval: ${state.pendingApproval ?? 'none'}`,
+        `snapshots: ${snaps}`
+      ]
+    };
+  }
+
+  // Report actions. A bare `/tutien` re-activates the mode; an explicit
+  // report action while off is refused (off-mode suppression).
+  if ((state.mode ?? 'off') !== 'on') {
+    if (explicitAction) return refuse("tutien mode is off; run 'on' (or bare /tutien) first.");
+    state.mode = 'on';
+  }
+
+  if (action === 'preview') {
+    const { lines, token } = previewLines(options);
+    state.pendingApproval = token;
+    saveState(state);
+    return { code: 0, out: lines };
+  }
+
+  if (action === 'classify') {
+    // classify is a metadata-only action (no history content): it reads
+    // backbone.yml fields and a transient distinct-author count of the current
+    // repo. It states that scope before producing the classification.
+    let classification;
+    try {
+      classification = classifyProject(repoProfile(options));
+    } catch (err) {
+      return refuse(err.message);
+    }
+    saveState(state);
+    const language = resolveLanguage(options.language, { invocationText: argsString });
+    const scope = language === 'vi'
+      ? 'Phạm vi classify: chỉ đọc metadata (backbone.yml + số lượng tác giả commit của repo hiện tại) — không đọc nội dung lịch sử, không tính tiến cảnh (tiến cảnh cần `analyze`).'
+      : 'classify scope: metadata only (backbone.yml + a distinct commit-author count of the current repo) — no history content is read, and no progression is computed (progression needs `analyze`).';
+    return { code: 0, out: [scope, '', renderClassificationMarkdown(classification, language)] };
+  }
+
+  if (action === 'explain') {
+    if (options.metric && EXPLAIN[options.metric]) {
+      return { code: 0, out: [`A note from the Dao ledger — ${options.metric}: ${EXPLAIN[options.metric]}`] };
+    }
+    return { code: 0, out: [`The Dao ledger can explain: ${Object.keys(EXPLAIN).join(', ')} (pass metric=<name>).`] };
+  }
+
+  if (action === 'compare') {
+    const files = fs.existsSync(snapDir) ? fs.readdirSync(snapDir).filter((f) => f.endsWith('.json')).sort() : [];
+    if (files.length < 2) return refuse('need at least two snapshots to compare; run analyze snapshot=true first.');
+    const load = (f) => JSON.parse(fs.readFileSync(path.join(snapDir, f), 'utf8'));
+    const result = compareSnapshots(load(files[files.length - 2]), load(files[files.length - 1]));
+    return {
+      code: 0,
+      out: ['Two cultivation records rest beneath the same lamp; the figures below show only what changed.', JSON.stringify(result, null, 2)]
+    };
+  }
+
+  if (action === 'analyze') {
+    const token = scopeToken(options.sources, options.range);
+    if (!options.approve) {
+      return refuse('analysis requires explicit approval: run preview, then pass the approve=<token> it printed.');
+    }
+    if (options.approve !== token || state.pendingApproval !== token) {
+      return refuse('approval token does not match the previewed scope; run preview again and approve that exact scope.');
+    }
+    delete state.pendingApproval;
+
+    const analysis = analyze(classifySources(options.sources));
+    let prior = null;
+    try {
+      const files = fs.readdirSync(snapDir).filter((f) => f.endsWith('.json')).sort();
+      if (files.length) prior = JSON.parse(fs.readFileSync(path.join(snapDir, files[files.length - 1]), 'utf8'));
+    } catch {}
+
+    const language = resolveLanguage(options.language, { invocationText: argsString });
+    let profile = null;
+    try {
+      profile = repoProfile(options);
+    } catch {}
+    const { model, markdown } = renderReport(analysis, {
+      ...options,
+      language,
+      profile,
+      progressionSalt: path.basename(root),
+      priorProgression: prior?.progression ?? null,
+      priorVillains: prior?.villainState ?? []
+    });
+
+    const out = [];
+    if (options.snapshot) {
+      fs.mkdirSync(snapDir, { recursive: true });
+      const createdAt = new Date().toISOString();
+      const snap = buildSnapshot(analysis, {
+        projectId: path.basename(root),
+        window: options.range,
+        createdAt,
+        prevVillainState: prior?.villainState ?? [],
+        shownVillains: model.villainCards,
+        canGamify: !model.suppressGamification,
+        policyState: model.policyState,
+        progression: model.cultivation?.progression ?? null,
+        classification: model.cultivation
+          ? { faction: model.cultivation.classification.faction.id, paths: model.cultivation.classification.paths.map((p) => p.id) }
+          : null
+      });
+      const file = path.join(snapDir, `${createdAt.replace(/[:.]/g, '-')}.json`);
+      fs.writeFileSync(file, `${JSON.stringify(snap, null, 2)}\n`);
+      out.push(`snapshot written: ${path.relative(root, file)}`);
+      const prune = snapshotsToPrune(fs.readdirSync(snapDir).filter((f) => f.endsWith('.json')), 20);
+      if (prune.length) {
+        out.push(`retention: remove old snapshots with: trash ${prune.map((f) => path.relative(root, path.join(snapDir, f))).join(' ')}`);
+      }
+    }
+    fs.mkdirSync(reportDir, { recursive: true });
+    fs.writeFileSync(path.join(reportDir, 'latest.md'), `${markdown}\n`);
+    saveState(state);
+    return { code: 0, out: [...out, markdown] };
+  }
+
+  return refuse(`unknown action "${action}"`);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const res = run(process.argv.slice(2).join(' '));
+  for (const line of res.out) console.log(line);
+  process.exit(res.code);
+}

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

@@ -0,0 +1,97 @@
+// Deterministic scoring: analysis JSON -> dimension scores -> realm.
+// No randomness, no wall clock. High token usage never raises the score;
+// necessary iteration is not punished; penalties are capped so one hard task
+// cannot erase a long history.
+
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+const round3 = (x) => Math.round(x * 1000) / 1000;
+
+export const DIMENSIONS = [
+  { key: 'delivery', weight: 0.3 },
+  { key: 'validation', weight: 0.25 },
+  { key: 'clarity', weight: 0.15 },
+  { key: 'recovery', weight: 0.15 },
+  { key: 'safety', weight: 0.1 },
+  { key: 'automation', weight: 0.05 }
+];
+
+export const REALMS = [
+  { min: 0, max: 14, name: 'Phàm Nhân Nhập Môn', gloss: 'Mortal Initiate' },
+  { min: 15, max: 29, name: 'Luyện Khí', gloss: 'Qi Refining' },
+  { min: 30, max: 44, name: 'Trúc Cơ', gloss: 'Foundation Establishment' },
+  { min: 45, max: 59, name: 'Kết Đan', gloss: 'Core Formation' },
+  { min: 60, max: 69, name: 'Nguyên Anh', gloss: 'Nascent Soul' },
+  { min: 70, max: 79, name: 'Hóa Thần', gloss: 'Spirit Transformation' },
+  { min: 80, max: 87, name: 'Luyện Hư', gloss: 'Void Refinement' },
+  { min: 88, max: 93, name: 'Hợp Thể', gloss: 'Body Integration' },
+  { min: 94, max: 97, name: 'Đại Thừa', gloss: 'Great Vehicle' },
+  { min: 98, max: 100, name: 'Độ Kiếp / Phi Thăng', gloss: 'Tribulation / Ascension' }
+];
+
+// Fraction of assistant turns with known (reported or estimated) usage.
+// Below 0.60 the run does not have enough evidence ("thiên cơ") to score.
+export function coverageFraction(analysis) {
+  const tc = analysis.coverage?.tokenCoverage ?? {};
+  return clamp01((tc.reportedTurnsPct ?? 0) + (tc.estimatedTurnsPct ?? 0));
+}
+
+export function scoreDimensions(analysis) {
+  const issues = analysis.issues ?? {};
+  const passes = issues.passes ?? 0;
+  const failures = (issues.failures ?? []).length;
+  const recoveries = (issues.recoveries ?? []).length;
+  const commits = analysis.coverage?.commits ?? 0;
+  const userPrompts = analysis.coverage?.userPrompts ?? 0;
+  const validationEvents = passes + failures;
+  const rep = analysis.repetition ?? {};
+  const retryPrompts = (rep.retryLoopCandidates ?? []).reduce((n, l) => n + l.count, 0);
+  const conflicts = (analysis.conflicts ?? []).length;
+
+  // delivery: verified completion vs failed attempts, plus committed output.
+  const delivery = validationEvents + commits === 0
+    ? 0.3
+    : clamp01((passes + recoveries + Math.min(commits, 5) * 0.3) / (passes + failures + 1));
+
+  // validation discipline: presence and density of validation evidence.
+  const validation = validationEvents === 0
+    ? 0.2
+    : clamp01(0.55 + 0.1 * recoveries + 0.05 * passes);
+
+  // clarity: 1 - avoidable-repeat rate (capped penalty).
+  const clarity = clamp01(1 - Math.min(0.6, userPrompts ? retryPrompts / userPrompts : 0));
+
+  // recovery from failure.
+  const recovery = failures === 0 ? 0.7 : clamp01(recoveries / failures);
+
+  // safety / rule alignment: high baseline, capped penalty per conflict.
+  const safety = clamp01(0.9 - Math.min(0.4, conflicts * 0.15));
+
+  // reusable automation: not inferable from history alone in V1 (neutral).
+  const automation = 0.4;
+
+  const scores = { delivery, validation, clarity, recovery, safety, automation };
+  for (const k of Object.keys(scores)) scores[k] = round3(scores[k]);
+  return scores;
+}
+
+export function realmFor(score) {
+  return REALMS.find((r) => score >= r.min && score <= r.max) ?? REALMS[0];
+}
+
+export function scoreReport(analysis, { coverageGate = 0.6 } = {}) {
+  const coverage = round3(coverageFraction(analysis));
+  const dimensions = scoreDimensions(analysis);
+  if (coverage < coverageGate) {
+    return {
+      enoughEvidence: false,
+      coverage,
+      dimensions,
+      score: null,
+      realm: { name: 'Chưa đủ thiên cơ', gloss: 'Not enough evidence yet' },
+      missing: ['token usage coverage below 60%; supply provider usage metadata to compute a realm']
+    };
+  }
+  const weighted = DIMENSIONS.reduce((sum, d) => sum + dimensions[d.key] * d.weight, 0);
+  const score = Math.round(weighted * 100);
+  return { enoughEvidence: true, coverage, dimensions, score, realm: realmFor(score), missing: [] };
+}

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

@@ -0,0 +1,76 @@
+// Phase 4 persistence. A snapshot is an AGGREGATE only: metric counts,
+// coverage, token totals, score/realm, thresholds, adapter versions, villain
+// cooldown state, and SALTED event-id digests. It never stores raw prompts,
+// URLs, secrets, or file contents. Snapshots live under the git-ignored
+// .vibekit/reports/tutien/ tree; deletion follows the repo safe-delete policy
+// (prefer `trash`, never silent `rm`).
+
+import crypto from 'node:crypto';
+import { scoreReport } from './score.mjs';
+import { detectProblems } from './catalog.mjs';
+import { advanceVillainState } from './villains.mjs';
+
+export const SNAPSHOT_SCHEMA = 1;
+const PEPPER = 'tutien-snapshot-v1';
+
+const sha16 = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+// Salt is stable per project (so trends line up) but not reversible to raw ids.
+const saltFor = (projectId) => sha16(`${PEPPER}:${projectId}`);
+
+export function buildSnapshot(analysis, options = {}) {
+  const { projectId = 'repo', window = 'all', createdAt = null, thresholds = {}, adapterVersions = {}, prevVillainState = [] } = options;
+  const salt = saltFor(projectId);
+  const score = scoreReport(analysis);
+  const problems = detectProblems(analysis);
+
+  // Provenance without content: only salted digests of evidence event ids.
+  const provenance = [
+    ...new Set(problems.flatMap((p) => p.evidence.eventIds ?? []))
+  ].sort().map((id) => sha16(`${salt}:${id}`));
+
+  const rep = analysis.repetition ?? {};
+  const issues = analysis.issues ?? {};
+
+  const shown = options.shownVillains ?? [];
+  // A suppressed policy (declared-stop / needs-review / authorization-required)
+  // must not persist a score, realm, or dimensions — the same fail-closed
+  // projection the renderer uses. Only Nghiệp Lực survives in progression.
+  const suppressed = options.canGamify === false;
+  return {
+    snapshotSchema: SNAPSHOT_SCHEMA,
+    createdAt,
+    projectId,
+    window,
+    coverage: analysis.coverage ?? {},
+    tokens: analysis.tokens ?? {},
+    counts: {
+      exactRepeats: (rep.exactRepeats ?? []).length,
+      nearRepeats: (rep.nearRepeats ?? []).length,
+      retryLoops: (rep.retryLoopCandidates ?? []).length,
+      conflicts: (analysis.conflicts ?? []).length,
+      failures: (issues.failures ?? []).length,
+      recoveries: (issues.recoveries ?? []).length,
+      passes: issues.passes ?? 0
+    },
+    score: suppressed ? null : score.score,
+    realm: suppressed ? null : score.realm,
+    dimensions: suppressed ? null : score.dimensions,
+    thresholds,
+    adapterVersions,
+    villainState: advanceVillainState(prevVillainState, shown),
+    // Cultivation accumulators and classification are aggregate slugs only:
+    // metric counters, the salted seen-ledger, and faction/path ids — never
+    // rationale text, raw prompts, or authorization values.
+    progression: options.progression ?? null,
+    classification: options.classification ?? null,
+    policyState: options.policyState ?? null,
+    provenance
+  };
+}
+
+// Retention is a pure decision; the caller performs the actual removal with
+// `trash` per safe-delete rules. Returns the oldest files beyond `keep`.
+export function snapshotsToPrune(files, keep = 20) {
+  const sorted = [...files].sort();
+  return sorted.slice(0, Math.max(0, sorted.length - keep));
+}

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 Lỗi Ma 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 Lỗi Ma 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 Lỗi Ma 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 Lỗi Ma đã 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 task 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 task 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 prompt thay cột mốc; đã đến lúc đổi chiếc vòng kế tiếp thành một tiêu chí “xong”.', en: 'The Ninefold Loop Heart-Shadow is counting prompts instead of checkpoints; turn the next circle into a done-criterion.' },
+      { vi: 'Prompt 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ô Kiể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ô Kiể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ô Kiể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ô Kiể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 commit 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 validation 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.