minimal-vibe-coding-kit 0.5.0 → 0.5.1

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

@@ -5,12 +5,21 @@ 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 {
+  normalizeStoryFocus,
+  normalizeStoryLanguage,
+  normalizeStoryStyle,
+  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';
+import { buildStoryContext, storyPaths, validateStoryTree, writeStoryContext } from './story-ledger.mjs';
+import { buildProjectProfile, inventoryProjectMetadata } from './project-profile.mjs';
+import { buildResponseBrief } from './response-brief.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
@@ -41,6 +50,20 @@ function saveState(state) {
   fs.writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`);
 }
 
+function resolveStoryPreferences(state, options, providedOptions = []) {
+  const provided = new Set(providedOptions);
+  const prior = state.storyPreferences ?? {};
+  const choose = (key, optionKey, fallback) => provided.has(key) ? options[optionKey] : (prior[optionKey] ?? options[optionKey] ?? fallback);
+  const preferences = {
+    story: choose('story', 'story', 'on') === 'off' ? 'off' : 'on',
+    storyLanguage: normalizeStoryLanguage(choose('story-language', 'storyLanguage', 'auto')),
+    storyStyle: normalizeStoryStyle(choose('story-style', 'storyStyle', 'auto')),
+    storyFocus: normalizeStoryFocus(choose('story-focus', 'storyFocus', 'balanced'))
+  };
+  state.storyPreferences = preferences;
+  return preferences;
+}
+
 function classifySources(sources) {
   const spec = { jsonlFiles: [], transcriptFiles: [], gitRoot: null };
   for (const s of sources) {
@@ -51,61 +74,60 @@ function classifySources(sources) {
   return spec;
 }
 
-const scopeToken = (sources, range) => sha16(JSON.stringify({ sources: [...sources].sort(), range }));
+const scopeToken = (sources, range, metadata = inventoryProjectMetadata(root)) => sha16(JSON.stringify({
+  sources: [...sources].sort(),
+  range,
+  metadata: metadata.map(({ path: file, size, mtimeMs }) => ({ path: file, size, mtimeMs }))
+}));
 
-// 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.
+// Project profile for classification: a bounded set of known manifests plus a
+// distinct-commit-author COUNT. Script bodies, names, emails, and file content
+// are never returned or persisted.
 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 {}
+  const profile = buildProjectProfile(root, options);
   // 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 }
-  };
+  return { ...profile, authorsCount };
 }
 
 // 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)');
+function previewLines(options, language = 'en') {
+  const vi = language === 'vi';
+  const metadata = inventoryProjectMetadata(root);
+  const lines = [vi
+    ? 'Xem trước phạm vi tu tiên: đài quan sát đã mở nhưng chưa đọc cuộn thư nào. Chỉ phân tích sau khi phạm vi chính xác này được phê duyệt.'
+    : '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(vi ? '- Chưa có nguồn. Hãy truyền `sources=git,/duong-dan/export.jsonl`.' : '- (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)`);
+      lines.push(vi ? `- Git: chỉ đọc siêu dữ liệu bản ghi của kho hiện tại tại ${root}.` : `- 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(size == null
+        ? (vi ? `- Tệp: ${s} (không tìm thấy)` : `- file: ${s} (NOT FOUND)`)
+        : (vi ? `- Tệp: ${s} (${size} byte)` : `- 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(',')}`);
+  if (metadata.length) {
+    lines.push(vi
+      ? `- Metadata dự án: ${metadata.map((item) => `${item.path} (${item.size} byte)`).join(', ')}; chỉ đọc nội dung sau khi phê duyệt.`
+      : `- project metadata: ${metadata.map((item) => `${item.path} (${item.size} bytes)`).join(', ')}; content is read only after approval.`);
+  } else {
+    lines.push(vi ? '- Metadata dự án: không tìm thấy manifest đã biết.' : '- project metadata: no known manifest found.');
+  }
+  lines.push(vi ? `- Phạm vi thời gian: ${options.range}` : `- range: ${options.range}`);
+  const token = scopeToken(options.sources, options.range, metadata);
+  lines.push(vi
+    ? `Để phê duyệt đúng phạm vi này: \`analyze approve=${token} sources=${options.sources.join(',')}\``
+    : `To approve exactly this scope: analyze approve=${token} sources=${options.sources.join(',')}`);
   return { lines, token };
 }
 
@@ -118,33 +140,50 @@ const EXPLAIN = {
   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ơ".'
 };
 
+const EXPLAIN_VI = {
+  reportedTotal: 'Tổng số token hợp lệ do nhà cung cấp báo cáo. Bản ghi luồng tích lũy có cùng `requestId` chỉ được tính một lần theo giá trị cuối; các đoạn độc lập được cộng riêng. Bản ghi không có tổng dương hợp lệ sẽ không được tính.',
+  estimatedTotal: 'Tổng số token hợp lệ được ước lượng cục bộ; không bao giờ gộp vào `reportedTotal`.',
+  unknownTurns: 'Số lượt trả lời của trợ lý không có dữ liệu sử dụng hoặc không có tổng hợp lệ. Tuyên bố độ chính xác mà thiếu số liệu vẫn được tính là chưa rõ.',
+  retryLoops: 'Chuỗi từ ba lời yêu cầu giống hoặc gần giống nhau trong cùng một nhiệm vụ, xen giữa bởi phản hồi của trợ lý hay công cụ; đây là các dấu hiệu có chấm mức tin cậy.',
+  conflicts: 'Một chỉ thị dạng “không bao giờ” hoặc “không làm X”, sau đó trong cùng nhiệm vụ xuất hiện lời yêu cầu làm X; cặp mã sự kiện có độ tin cậy 0,6.',
+  realm: 'Điểm có trọng số từ sáu chiều được ánh xạ vào thang cảnh giới. Cần ít nhất 60% độ phủ token đã biết; nếu thiếu sẽ trả về “Chưa đủ thiên cơ”.'
+};
+
 export function run(argsString = '') {
-  const { action, explicitAction, options } = parseInvocation(argsString);
+  const { action, explicitAction, options, providedOptions } = parseInvocation(argsString);
   const state = loadState();
+  const storyPreferences = resolveStoryPreferences(state, options, providedOptions);
+  const uiLanguage = resolveLanguage(options.language, { invocationText: argsString });
+  const say = (vi, en) => uiLanguage === 'vi' ? vi : en;
   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.'] };
+    return { code: 0, out: [say('Chế độ tu tiên đã tắt. Văn phong bình thường của bộ công cụ đã được khôi phục.', '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.'] };
+    return { code: 0, out: [say('Chế độ tu tiên đã bật. Sơn môn đã mở; hãy chạy `preview` để xem phạm vi chính xác trước khi phân tích.', '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;
+    const storyStatus = validateStoryTree(root);
     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}`
+        say(`chế độ: ${(state.mode ?? 'off') === 'on' ? 'bật' : 'tắt'}`, `mode: ${state.mode ?? 'off'}`),
+        say(`trải nghiệm: \`${TUTIEN_EXPERIENCE.kind}\``, `experience: ${TUTIEN_EXPERIENCE.kind}`),
+        say(`giọng văn: \`${TUTIEN_EXPERIENCE.narrativeStyle}\``, `voice: ${TUTIEN_EXPERIENCE.narrativeStyle}`),
+        say(`không gian ngữ nghĩa: \`${TUTIEN_EXPERIENCE.semanticNamespace}\``, `semantic namespace: ${TUTIEN_EXPERIENCE.semanticNamespace}`),
+        say(`phê duyệt đang chờ: ${state.pendingApproval ?? 'không có'}`, `pending approval: ${state.pendingApproval ?? 'none'}`),
+        say(`ảnh chụp tổng hợp: ${snaps}`, `snapshots: ${snaps}`),
+        say(`trường thiên: ${storyPreferences.story === 'on' ? 'bật' : 'tắt'} (${storyPreferences.storyLanguage}, ${storyPreferences.storyStyle}, ${storyPreferences.storyFocus})`, `story: ${storyPreferences.story} (${storyPreferences.storyLanguage}, ${storyPreferences.storyStyle}, ${storyPreferences.storyFocus})`),
+        say(`số chương: ${storyStatus.chapters}`, `story chapters: ${storyStatus.chapters}`),
+        say(`tổng cương: ${path.relative(root, storyPaths(root).plot)}`, `story plot: ${path.relative(root, storyPaths(root).plot)}`),
+        say(`sổ chương: ${storyStatus.ok ? 'hợp lệ' : `cần xem lại (${storyStatus.errors.length} lỗi)`}`, `story ledger: ${storyStatus.ok ? 'valid' : `needs attention (${storyStatus.errors.length})`}`)
       ]
     };
   }
@@ -152,21 +191,24 @@ export function run(argsString = '') {
   // 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.");
+    if (explicitAction) return refuse(say('Chế độ tu tiên đang tắt. Hãy chạy `on` hoặc gọi `/tutien` trước.', "tutien mode is off; run 'on' (or bare /tutien) first."));
     state.mode = 'on';
   }
 
   if (action === 'preview') {
-    const { lines, token } = previewLines(options);
+    const { lines, token } = previewLines(options, uiLanguage);
+    lines.push(say(
+      `- Trường thiên: ${storyPreferences.story === 'on' ? 'bật' : 'tắt'}; ngôn ngữ ${storyPreferences.storyLanguage}, phong cách ${storyPreferences.storyStyle}, trọng tâm ${storyPreferences.storyFocus}.`,
+      `- living chronicle: ${storyPreferences.story} (language=${storyPreferences.storyLanguage}, style=${storyPreferences.storyStyle}, focus=${storyPreferences.storyFocus})`
+    ));
     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.
+    // classify is a metadata-only action (no history content): it reads only
+    // the known manifests advertised below and a transient author count.
     let classification;
     try {
       classification = classifyProject(repoProfile(options));
@@ -175,37 +217,38 @@ export function run(argsString = '') {
     }
     saveState(state);
     const language = resolveLanguage(options.language, { invocationText: argsString });
+    const sources = inventoryProjectMetadata(root).map((item) => item.path).join(', ') || 'none';
     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`).';
+      ? `Phạm vi classify: chỉ đọc manifest đã biết (${sources}) và số lượng tác giả Git; 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: known manifests only (${sources}) plus a distinct Git-author count; 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: [say(`Ghi chú từ đạo ký về \`${options.metric}\`: ${EXPLAIN_VI[options.metric]}`, `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>).`] };
+    return { code: 0, out: [say(`Đạo ký có thể giải thích: ${Object.keys(EXPLAIN).map((key) => `\`${key}\``).join(', ')}. Hãy truyền \`metric=<tên>\`.`, `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.');
+    if (files.length < 2) return refuse(say('Cần ít nhất hai ảnh chụp tổng hợp để so sánh. Hãy chạy `analyze snapshot=true` trước.', '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)]
+      out: [say('Hai bản tu luyện cùng đặt dưới một ngọn đèn; số liệu dưới đây chỉ cho thấy phần đã thay đổi.', '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);
+    const token = scopeToken(options.sources, options.range, inventoryProjectMetadata(root));
     if (!options.approve) {
-      return refuse('analysis requires explicit approval: run preview, then pass the approve=<token> it printed.');
+      return refuse(say('Phân tích cần được phê duyệt rõ ràng. Hãy chạy `preview`, rồi truyền lại `approve=<token>` đã nhận.', '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.');
+      return refuse(say('Token phê duyệt không khớp phạm vi đã xem trước. Hãy chạy lại `preview` và phê duyệt đúng phạm vi đó.', 'approval token does not match the previewed scope; run preview again and approve that exact scope.'));
     }
     delete state.pendingApproval;
 
@@ -249,19 +292,54 @@ export function run(argsString = '') {
       });
       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)}`);
+      out.push(say(`Đã ghi ảnh chụp tổng hợp: ${path.relative(root, file)}`, `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(' ')}`);
+        out.push(say(`Lưu giữ: có thể chuyển các ảnh chụp cũ vào thùng rác bằng lệnh \`trash ${prune.map((f) => path.relative(root, path.join(snapDir, f))).join(' ')}\`.`, `retention: remove old snapshots with: trash ${prune.map((f) => path.relative(root, path.join(snapDir, f))).join(' ')}`));
+      }
+    }
+    let storyContext = null;
+    if (storyPreferences.story === 'on') {
+      if (model.suppressGamification) {
+        out.push(say(`Trường thiên tạm dừng: trạng thái chính sách \`${model.policyState}\` không cho phép viết cốt truyện.`, `living chronicle paused: policy state ${model.policyState} does not permit lore.`));
+      } else {
+        storyContext = buildStoryContext(model, {
+          profile,
+          range: options.range,
+          language: storyPreferences.storyLanguage,
+          invocationText: argsString,
+          conversationLanguage: language,
+          style: storyPreferences.storyStyle,
+          focus: storyPreferences.storyFocus
+        });
+        const contextFile = writeStoryContext(root, storyContext);
+        out.push(say(`Đã ghi ngữ cảnh trường thiên: ${path.relative(root, contextFile)}; bằng chứng \`${storyContext.evidenceKey}\`.`, `story context written: ${path.relative(root, contextFile)} (evidence ${storyContext.evidenceKey})`));
       }
     }
     fs.mkdirSync(reportDir, { recursive: true });
-    fs.writeFileSync(path.join(reportDir, 'latest.md'), `${markdown}\n`);
+    const ledgerFile = path.join(reportDir, 'latest.md');
+    const briefFile = path.join(reportDir, 'latest-brief.json');
+    fs.writeFileSync(ledgerFile, `${markdown}\n`);
+    const brief = buildResponseBrief(model, {
+      language,
+      profile,
+      storyContext,
+      ledgerPath: path.relative(root, ledgerFile)
+    });
+    fs.writeFileSync(briefFile, `${JSON.stringify(brief, null, 2)}\n`);
+    out.push(say(
+      `Đã ghi đạo ký chứng cứ: ${path.relative(root, ledgerFile)}.`,
+      `evidence ledger written: ${path.relative(root, ledgerFile)}.`
+    ));
+    out.push(say(
+      `Gói sáng tác đã sẵn sàng: ${path.relative(root, briefFile)}; hãy dùng dữ kiện này để viết phản hồi linh hoạt theo dự án, không sao chép bố cục đạo ký.`,
+      `response brief ready: ${path.relative(root, briefFile)}; compose adaptively from it instead of copying the ledger structure.`
+    ));
     saveState(state);
-    return { code: 0, out: [...out, markdown] };
+    return { code: 0, out: options.output === 'ledger' ? [...out, markdown] : out };
   }
 
-  return refuse(`unknown action "${action}"`);
+  return refuse(say(`Không nhận ra hành động "${action}".`, `unknown action "${action}"`));
 }
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

package/.claude/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/.claude/skills/tutien/scripts/villains.mjs

@@ -60,22 +60,22 @@ export function sanitizeContext(ctx = {}) {
 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.' }
+      { 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 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.' }
+      { 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 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.' }
+      { 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 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.' }
+      { 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': {
@@ -90,21 +90,21 @@ const LINES = {
   },
   '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.' }
+      { 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ô 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.' }
+      { 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 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.' }
+      { 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 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: '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.' }
     ]
   }