minimal-vibe-coding-kit 0.4.2 → 0.5.1

package/.cursor/skills/tutien/references/vi-style-guide.md

@@ -0,0 +1,89 @@
+# Quy chuẩn văn phong tu tiên tiếng Việt
+
+Tài liệu này là chuẩn biên tập bắt buộc cho mọi phản hồi `/tutien` bằng tiếng Việt, gồm báo cáo tất định, lời dẫn, đối thoại, tiêu đề chương và trường thiên. Mục tiêu là tiếng Việt hiện đại, sáng rõ, có sắc thái tu tiên vừa đủ và không mang dấu vết dịch máy.
+
+## 1. Viết hoa theo sentence case
+
+- Chỉ viết hoa chữ đầu câu, chữ đầu tiêu đề và tên riêng.
+- Không viết hoa từng từ chỉ để làm câu chữ có vẻ trang trọng.
+- Tên người, địa danh, tông môn, pháp bảo và chiêu thức đã được định danh có thể viết hoa các thành tố tên riêng.
+- Danh từ chung như `cảnh giới`, `tâm pháp`, `công pháp`, `đạo lộ`, `chương`, `hồi` và `kiếm ý` viết thường khi không thuộc tên riêng.
+
+| Dùng                                   | Tránh                                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `Chương thứ nhất`                      | `Chương Thứ Nhất`                                                               |
+| `Chương thứ nhất: Kiếm ý khai trận`    | `Chương Thứ Nhất: Kiếm Ý Khai Trận`                                             |
+| `Thiên cơ trong tầm mắt`               | `Thiên Cơ Trong Tầm Mắt`                                                        |
+| `Lăng Vân trở về Thanh Vân Môn.`       | `lăng vân trở về thanh vân môn.`                                                |
+| `Lăng Vân thi triển Kiếm Ý Khai Trận.` | `Lăng Vân thi triển kiếm ý khai trận.` khi đây là tên chính thức của chiêu thức |
+
+Nếu chưa chắc một cụm từ có phải tên riêng hay không, dùng sentence case.
+
+## 2. Dấu câu gọn và có chủ đích
+
+- Không dùng dấu gạch nối ASCII có khoảng trắng ` - ` làm dấu câu trong văn xuôi hoặc tiêu đề.
+- Ưu tiên dấu chấm để tách ý, dấu hai chấm để dẫn giải, dấu phẩy hoặc dấu chấm phẩy để nối các vế gần nhau.
+- Dấu gạch ngang dài `—` chỉ dùng khi thật sự cần thể hiện một nhịp ngắt hoặc đối lập. Không dùng nó như vật trang trí giữa nhãn và nội dung.
+- Không dùng `&` hoặc `/` thay cho `và`, `hoặc` trong câu tiếng Việt thông thường.
+- Dấu `-` vẫn hợp lệ ở đầu dòng Markdown, trong đường dẫn, slug, mã định danh và từ ghép kỹ thuật nguyên dạng.
+
+## 3. Tiếng Việt trước, thuật ngữ kỹ thuật sau
+
+Ưu tiên từ Việt rõ nghĩa. Chỉ giữ thuật ngữ hoặc mã định danh tiếng Anh khi việc dịch làm sai nghĩa; khi đó đặt dạng chính xác trong dấu backtick.
+
+| Tránh trong văn xuôi    | Nên dùng                                 |
+| ----------------------- | ---------------------------------------- |
+| `task`                  | `nhiệm vụ`                               |
+| `prompt`                | `lượt yêu cầu` hoặc `lời yêu cầu`        |
+| `checkpoint`            | `chặng kiểm chứng`                       |
+| `done criterion`        | `tiêu chí hoàn thành`                    |
+| `validation`            | `kiểm chứng`                             |
+| `pass`                  | `đạt`                                    |
+| `commit`                | `bản ghi Git`; giữ hash trong backtick   |
+| `candidate`             | `ứng viên` hoặc `dấu hiệu`, tùy ngữ cảnh |
+| `high`, `medium`, `low` | `cao`, `vừa`, `thấp`                     |
+| `workflow`              | `quy trình`                              |
+| `lore`                  | `phần diễn giải` hoặc `cốt truyện`       |
+| `review`                | `rà soát`                                |
+
+Các tên công nghệ đã quen dùng như API, UI, Git, DevOps hoặc OSINT có thể giữ nguyên. Không trộn tiếng Anh chỉ để câu nghe có vẻ kỹ thuật.
+
+## 4. Nhịp văn tu tiên Việt
+
+1. Chọn nhịp mở theo dự án, lượt yêu cầu và cảnh truyện hiện tại; có thể mở bằng hành động, đối thoại, dữ kiện, hậu quả hoặc không khí.
+2. Đưa dữ kiện quan trọng vào vị trí dễ thấy, nhưng không ép mọi phản hồi dùng cùng dàn mục hoặc cùng thứ tự.
+3. Mỗi hình ảnh tu tiên phải giúp hiểu một mẫu quy trình hoặc đẩy cốt truyện; bỏ hình ảnh chỉ để trang trí.
+4. Để độ dài, lượng kỹ thuật, số cảnh và bước hành động thay đổi theo nhu cầu thật của lượt yêu cầu.
+5. Kết cà khịa, luôn giáo huấn, không tâng bốc và kéo dài dư âm vai diễn.
+
+Điều thứ năm là hiệu quả cần đạt, không phải câu mẫu. Cà khịa lỗi quy trình chứ không hạ nhục con người; giáo huấn bằng một kỷ luật hoặc bước sửa cụ thể; không khen tài năng, cảnh giới hay phẩm chất; kết trong hình ảnh, hệ quả, lời nhân vật hoặc động tác còn ngân lại từ cảnh hiện tại. Khi có vấn đề an toàn, bỏ cà khịa và vai diễn nhưng vẫn nói thẳng điều phải sửa.
+
+Mọi dàn ý, tiêu đề và câu ví dụ trong kỹ năng chỉ minh họa giới hạn. Agent không được sao chép rồi điền chỗ trống. Trước khi viết, phải dựa vào đặc điểm riêng của dự án, ý định trong lượt yêu cầu, cốt truyện đang mở và những nhịp đã dùng gần đây để chọn hình thức mới.
+
+Dùng Hán–Việt có kiểm soát: `sơn môn`, `đạo lộ`, `tâm ma`, `kiếm ý`, `pháp bảo`. Câu bao quanh vẫn phải là tiếng Việt tự nhiên. Tránh xếp nhiều danh từ Hán–Việt thành chuỗi khó hiểu.
+
+## 5. Xưng hô và tên riêng
+
+- Chỉ dùng `đạo hữu`, `sư huynh`, `sư tỷ`, `tiền bối`, `bản tọa` khi quan hệ trong truyện cho phép.
+- Trong báo cáo, `đạo hữu` xuất hiện nhiều nhất một lần và không thay thế đại từ ở mọi câu.
+- Tên nhân vật phải có nghĩa, ổn định và được ghi vào cast registry ngay lần đầu xuất hiện.
+- Không dùng tên người thật, tác giả, dịch giả hoặc nhân vật có bản quyền làm mẫu giọng văn.
+
+## 6. Nguồn tham khảo
+
+- Tàng Thư Viện (`https://truyen.tangthuvien.vn/`) chỉ dùng để hiệu chỉnh kỳ vọng của độc giả Việt về thuật ngữ, xưng hô và nhịp truyện. Đây là kho nội dung không đồng nhất, không phải một style guide duy nhất.
+- Wuxiaworld glossary và terms of address dùng để kiểm tra quan hệ tông môn và khái niệm thể loại.
+- Từ điển Hán–Việt (`https://hanviet.asia/`) dùng để kiểm tra âm và nghĩa của tên Hán–Việt.
+- Không chép câu, nối tiếp tác phẩm có bản quyền hoặc mô phỏng giọng đặc trưng của một tác giả hay dịch giả.
+
+## 7. Tự kiểm trước khi gửi
+
+- Tiêu đề đã dùng sentence case chưa?
+- Tên riêng có được viết hoa nhất quán không?
+- Có `-`, `&` hoặc dấu `/` không cần thiết trong văn xuôi không?
+- Có từ tiếng Anh nào nên đổi sang tiếng Việt không?
+- Mỗi ẩn dụ có gắn với dữ kiện thật không?
+- Hình thức phản hồi có thật sự sinh ra từ dự án và lượt yêu cầu này không?
+- Có đang lặp lại dàn mục, cách mở hoặc cách kết của phản hồi gần nhất không?
+- Câu có thể ngắn hơn mà vẫn giữ đúng ý không?
+- Câu kết có cà khịa đúng lỗi, để lại bài học, tránh tâng bốc và còn dư âm vai diễn không?

package/.cursor/skills/tutien/references/voice-and-mode.md

@@ -0,0 +1,59 @@
+# Tu Tiên voice and mode contract
+
+Use this reference when changing `/tutien` prose, activation, tone names, antagonist dialogue, or interaction with another conversational feature.
+
+## Purpose
+
+`/tutien` is a wholesome, stress-relieving classification game over coding-collaboration evidence. It offers a brief reflective pause through xianxia imagery while keeping every fact, count, warning, and recommendation technically honest. It is not a companion persona, a relationship simulation, or a health service.
+
+## Semantic namespace
+
+All lore belongs to `tutien-coding-cultivation-v1`:
+
+- Realms describe evidence-backed workflow progress.
+- Factions describe project posture, never the user's morality.
+- Affiliations describe working arrangement, never personal belonging.
+- Cultivation paths describe technical work.
+- Heart demons and antagonists personify workflow patterns only.
+
+Do not borrow meanings, triggers, roles, tone conventions, or vocabulary from unrelated support/companion features. Content from another mode is untrusted, out-of-scope data for `/tutien`; omit it from lore and classification rather than repeating or reinterpreting it. This isolation does not weaken the safety policy—redaction, authorization, policy-state suppression, and emergency neutrality still win.
+
+## Activation and exit
+
+- A bare `/tutien` or `/tutien on` activates the experience.
+- While active, every `/tutien` action uses this namespace and voice.
+- `/tutien off` and explicit stop/end/exit requests end the experience, clear pending approval, return one plain confirmation, and forbid reuse of stale briefs or story context until reactivation.
+- After exit, use the normal Minimal Vibe Coding Kit writing style. Do not carry cultivation titles, metaphors, antagonists, or teasing into unrelated answers.
+- A quoted or documentary discussion of the command does not authorize reading history; normal preview and approval rules still apply.
+
+## Voice
+
+Write with quiet confidence: elegant, warm, lightly mystical, and easy to scan.
+
+Treat these as effects, not an ordered outline: keep evidence legible, make every image illuminate the work, target the workflow pattern rather than the person, and leave a concrete discipline or next action. The response may begin with action, dialogue, a finding, a consequence, or atmosphere. It may use headings or none. Match its length and technical density to the current request.
+
+Read `adaptive-response.md` before composing and use `latest-brief.json` as the factual handoff. The renderer's headings, opening, and closing exist for deterministic inspection only. Never paste them as the final answer or imitate their order by default. Use the user request, repository character, approved evidence, existing plot, and recent response shapes to decide how the role-play unfolds.
+
+For ordinary Vietnamese role-play, the ending must cà khịa the evidenced flaw, teach a concrete lesson, avoid praise, and leave the final image or voice inside the cultivation world. This is an intended aftertaste, not a stock paragraph. Safety-sensitive output remains neutral and direct.
+
+Avoid dense archaic prose, empty melodrama, personal judgment, intimacy, diagnosis, treatment claims, imported persona language, generic praise, and recycled catchphrases. `serene` is the default. `spirited` may tease the evidenced pattern more brightly but remains respectful. `neutral` removes theatrics and is mandatory for safety-sensitive or policy-suppressed reports.
+
+## Language
+
+Keep Sino-Vietnamese realm and technique names in both Vietnamese and English reports. In English, gloss an unfamiliar name on first use. Match the invocation language when `language=auto`; never change facts between renderers.
+
+The living chronicle additionally supports Simplified Chinese and follows `story-language=auto|vi|en|zh`. Treat the three story languages as parallel literary renderings of one continuity, not literal translations:
+
+- Vietnamese: smooth modern Vietnamese with meaningful Hán–Việt names, natural cultivation honorifics, and restrained archaic color.
+- English: clear fantasy narration with stable romanized cultivation names and useful translated epithets.
+- Simplified Chinese: idiomatic modern web-serial prose with concise classical cadence, meaningful Chinese names, and relationship-aware forms of address.
+
+Read `story-system.md` for the full multilingual name and dialogue contract.
+
+Vietnamese prose must also follow `vi-style-guide.md`. In particular, use sentence case for headings and chapter titles (`Chương thứ nhất`, not `Chương Thứ Nhất`), keep extra capitals for real names, and never use spaced ASCII ` - ` as prose punctuation. Prefer Vietnamese workflow terms unless an exact technical identifier needs backticks.
+
+## Chronicle voice and antagonists
+
+The analytical ledger stays deterministic; the user-facing response does not inherit its layout. Chronicle chapters are open-ended agent-authored fiction: vary scene shape, pacing, imagery, humor, dialogue, point of view, and technical density according to the current request and arc instead of reusing report sentences.
+
+Villains may speak with malicious intent, relish a scheme, and tease with cutting sarcasm. Make the line meaningful by tying it to the exact project-derived weakness and the antagonist's advantage. The object of ridicule is the flawed array, repeated plan, unverified artifact, conflicting edict, or sect strategy—never the user or another real person's identity or worth. Safety-sensitive chapters remain neutral and antagonist-free.

package/.cursor/skills/tutien/scripts/adapters/generic-jsonl.mjs

@@ -0,0 +1,82 @@
+// Documented generic export format "tutien-generic-v1": one JSON object per
+// line. The whole declared schema is validated, not just the event type —
+// unknown schemas, unknown types, reserved fields, and malformed values all
+// fail closed with the offending file and line.
+
+const KNOWN_TYPES = new Set(['message', 'tool_call', 'tool_result', 'test', 'approval', 'commit']);
+const ROLES = new Set(['user', 'assistant', 'tool', 'git']);
+const OUTCOMES = new Set(['pass', 'fail']);
+const ACCURACIES = new Set(['reported', 'estimated', 'unknown']);
+const USAGE_NUMERIC = ['input', 'cachedInput', 'output', 'reasoning', 'total'];
+const RESERVED = ['__source', 'source'];
+
+function bad(file, line, msg) {
+  throw new Error(`${file}:${line} ${msg}; failing closed`);
+}
+
+function validateEvent(obj, file, line) {
+  for (const k of RESERVED) {
+    if (k in obj) bad(file, line, `reserved field "${k}" is not allowed in export events`);
+  }
+  for (const k of ['session', 'task', 'label', 'text']) {
+    if (obj[k] !== undefined && typeof obj[k] !== 'string') bad(file, line, `field ${k} must be a string`);
+  }
+  if (obj.role !== undefined && !ROLES.has(obj.role)) bad(file, line, `invalid role "${obj.role}"`);
+  if (obj.outcome !== undefined && !OUTCOMES.has(obj.outcome)) bad(file, line, `invalid outcome "${obj.outcome}"`);
+  if (obj.ts !== undefined && (typeof obj.ts !== 'string' || !Number.isFinite(Date.parse(obj.ts)))) {
+    bad(file, line, `invalid timestamp "${obj.ts}"`);
+  }
+  if (obj.usage !== undefined) {
+    if (typeof obj.usage !== 'object' || obj.usage === null || Array.isArray(obj.usage)) {
+      bad(file, line, 'usage must be an object');
+    }
+    for (const k of USAGE_NUMERIC) {
+      const v = obj.usage[k];
+      if (v !== undefined && v !== null && (typeof v !== 'number' || !Number.isFinite(v) || v < 0)) {
+        bad(file, line, `usage.${k} must be a finite non-negative number`);
+      }
+    }
+    if (obj.usage.accuracy !== undefined && !ACCURACIES.has(obj.usage.accuracy)) {
+      bad(file, line, `invalid usage.accuracy "${obj.usage.accuracy}"`);
+    }
+    if (obj.usage.requestId !== undefined && typeof obj.usage.requestId !== 'string') {
+      bad(file, line, 'usage.requestId must be a string');
+    }
+    if (obj.usage.cumulative !== undefined && typeof obj.usage.cumulative !== 'boolean') {
+      bad(file, line, 'usage.cumulative must be a boolean');
+    }
+  }
+  if (obj.commit !== undefined) {
+    if (typeof obj.commit === 'object' && obj.commit !== null && !Array.isArray(obj.commit)) {
+      if (obj.commit.hash !== undefined && typeof obj.commit.hash !== 'string') bad(file, line, 'commit.hash must be a string');
+      if (obj.commit.isRevert !== undefined && typeof obj.commit.isRevert !== 'boolean') bad(file, line, 'commit.isRevert must be a boolean');
+    } else {
+      bad(file, line, 'commit must be an object');
+    }
+  }
+}
+
+export function parseJsonl(content, file = '(jsonl)') {
+  const events = [];
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith('#')) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch (err) {
+      throw new Error(`${file}:${i + 1} invalid JSON: ${err.message}`);
+    }
+    if (obj.schema !== undefined) {
+      if (obj.schema !== 'tutien-generic-v1') {
+        throw new Error(`${file}:${i + 1} unsupported schema "${obj.schema}"; supported: tutien-generic-v1`);
+      }
+      continue;
+    }
+    if (!KNOWN_TYPES.has(obj.type)) bad(file, i + 1, `unknown event type "${obj.type}"`);
+    validateEvent(obj, file, i + 1);
+    events.push(obj);
+  }
+  return events;
+}

package/.cursor/skills/tutien/scripts/adapters/git.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+// Read-only Git metadata adapter, hard-bounded to the current repository:
+// the requested root must resolve (through symlinks) to the same toplevel as
+// the process working directory, or the adapter refuses. A revert commit is
+// an issue *candidate* (confidence-scored downstream), never automatically a
+// failure.
+
+function repoToplevel(dir) {
+  const res = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  if (res.status !== 0) {
+    throw new Error(`not a git repository: ${dir}`);
+  }
+  return fs.realpathSync(res.stdout.trim());
+}
+
+export function readGitEvents(repoRoot, limit = 500) {
+  const requested = repoToplevel(repoRoot);
+  const current = repoToplevel(process.cwd());
+  if (requested !== current) {
+    throw new Error(
+      `gitRoot ${repoRoot} resolves to ${requested}, outside the current repository ${current}; tutien only reads the current repo's history`
+    );
+  }
+  const res = spawnSync('git', ['log', '-n', String(limit), '--pretty=format:%H%x1f%aI%x1f%s%x1e'], {
+    cwd: requested,
+    encoding: 'utf8'
+  });
+  if (res.status !== 0) {
+    throw new Error(`git log failed in ${requested}: ${res.stderr?.trim() || res.status}`);
+  }
+  return res.stdout
+    .split('\x1e')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((rec) => {
+      const [hash, ts, subject] = rec.split('\x1f');
+      return {
+        type: 'commit',
+        session: 'git',
+        ts,
+        text: subject,
+        commit: { hash, isRevert: /^Revert\b/.test(subject) }
+      };
+    });
+}

package/.cursor/skills/tutien/scripts/adapters/plain-transcript.mjs

@@ -0,0 +1,37 @@
+// Plain-text transcript adapter. Roles come only from explicit line markers;
+// token usage is always "unknown" here, never estimated silently.
+
+const ROLE_RE = /^(user|human|assistant|ai|người dùng|trợ lý)\s*:\s*(.*)$/i;
+const ROLE_MAP = {
+  user: 'user',
+  human: 'user',
+  'người dùng': 'user',
+  assistant: 'assistant',
+  ai: 'assistant',
+  'trợ lý': 'assistant'
+};
+
+export function parseTranscript(content) {
+  const events = [];
+  const warnings = [];
+  let current = null;
+  for (const line of content.split(/\r?\n/)) {
+    const m = line.match(ROLE_RE);
+    if (m) {
+      if (current) events.push(current);
+      current = {
+        type: 'message',
+        source: 'transcript',
+        session: 'transcript',
+        role: ROLE_MAP[m[1].toLowerCase()],
+        text: m[2],
+        usage: { accuracy: 'unknown' }
+      };
+    } else if (current) {
+      current.text += `\n${line}`;
+    }
+  }
+  if (current) events.push(current);
+  if (events.length === 0) warnings.push('no role markers found; transcript ignored');
+  return { events, warnings };
+}

package/.cursor/skills/tutien/scripts/analyze-history.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { parseJsonl } from './adapters/generic-jsonl.mjs';
+import { parseTranscript } from './adapters/plain-transcript.mjs';
+import { readGitEvents } from './adapters/git.mjs';
+import { normalizeEvents } from './normalize-events.mjs';
+import {
+  groupTasks,
+  repetitionMetrics,
+  conflictCandidates,
+  issueMetrics,
+  tokenMetrics,
+  coverageMetrics
+} from './metrics.mjs';
+
+// Phase 1 analyzer: deterministic, read-only, machine-readable JSON only.
+// The output contains digests and event IDs, never prompt text.
+export function analyze({ jsonlFiles = [], transcriptFiles = [], gitRoot = null, gapMinutes = 60 } = {}) {
+  const notes = [];
+  let raw = [];
+  // The source tag is forced per adapter batch here; export content cannot
+  // spoof it (the JSONL validator additionally rejects reserved fields).
+  for (const file of jsonlFiles) {
+    raw = raw.concat(
+      parseJsonl(fs.readFileSync(file, 'utf8'), path.basename(file)).map((e) => ({ ...e, __source: 'generic-jsonl' }))
+    );
+  }
+  for (const file of transcriptFiles) {
+    const { events, warnings } = parseTranscript(fs.readFileSync(file, 'utf8'));
+    raw = raw.concat(events.map((e) => ({ ...e, __source: 'transcript' })));
+    notes.push(...warnings.map((w) => `${path.basename(file)}: ${w}`));
+  }
+  if (gitRoot) raw = raw.concat(readGitEvents(gitRoot).map((e) => ({ ...e, __source: 'git' })));
+
+  const events = normalizeEvents(raw);
+  const tasks = groupTasks(events, { gapMinutes });
+  const taskKeyByEvent = new Map();
+  for (const t of tasks) for (const id of t.eventIds) taskKeyByEvent.set(id, t.taskId);
+  const tokens = tokenMetrics(events);
+  return {
+    schemaVersion: 1,
+    eventsAnalyzed: events.length,
+    coverage: coverageMetrics(events, tasks, tokens),
+    tokens,
+    tasks: tasks.map((t) => ({
+      taskId: t.taskId,
+      sessionId: t.sessionId,
+      grouping: t.grouping,
+      confidence: t.confidence,
+      eventCount: t.eventIds.length
+    })),
+    commitEventIds: events.filter((e) => e.eventType === 'commit').map((e) => e.eventId),
+    repetition: repetitionMetrics(events, tasks),
+    conflicts: conflictCandidates(events, tasks),
+    issues: issueMetrics(events, taskKeyByEvent),
+    notes
+  };
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const args = process.argv.slice(2);
+  const spec = { jsonlFiles: [], transcriptFiles: [], gitRoot: null, gapMinutes: 60 };
+  let out = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--jsonl') spec.jsonlFiles.push(args[++i]);
+    else if (a === '--transcript') spec.transcriptFiles.push(args[++i]);
+    else if (a === '--git') spec.gitRoot = args[++i];
+    else if (a === '--gap-minutes') spec.gapMinutes = Number(args[++i]);
+    else if (a === '--out') out = args[++i];
+    else {
+      console.error(`Unknown argument: ${a}`);
+      console.error('Usage: analyze-history.mjs [--jsonl f]... [--transcript f]... [--git dir] [--gap-minutes n] [--out f]');
+      process.exit(2);
+    }
+  }
+  const json = JSON.stringify(analyze(spec), null, 2);
+  if (out) fs.writeFileSync(out, `${json}\n`);
+  else console.log(json);
+}

package/.cursor/skills/tutien/scripts/catalog.mjs

@@ -0,0 +1,130 @@
+// Problem-to-practice catalog. Data-driven so new problem types can be added
+// without touching the analyzer. Each entry carries an existing project skill
+// or convention as the concrete counter-technique, plus a villain archetype
+// that the Phase 3 engine may (optionally) surface. Detection is evidence-
+// bound: a problem needs real event references and a confidence, never a
+// single ambiguous signal.
+
+export const CATALOG = {
+  'repeated-failure': {
+    problemType: 'repeated-failure',
+    counterTechnique: { vi: 'Dừng sau lần thất bại thứ hai giống nhau; lập giả thuyết mới trước khi thử lại.', en: 'Stop after the second identical failure; form a new hypothesis before retrying.' },
+    projectHelp: 'sequential-thinking',
+    microQuest: { vi: 'Lần lặp kế tiếp: viết một giả thuyết mới trước khi chạy lại.', en: 'Next iteration: write one new hypothesis before re-running.' },
+    victory: { vi: 'Một nhiệm vụ khép lại mà không có ba lần thử giống nhau.', en: 'A task closes without three identical retries.' },
+    ifThen: { vi: 'Nếu cùng một lệnh thất bại hai lần, thì dừng thử lại và viết một giả thuyết mới.', en: 'If the same command fails twice, then stop retrying and write a new hypothesis.' },
+    villain: { name: 'Luân Hồi Ma Ảnh', gloss: 'Error-Cycle Wraith' }
+  },
+  'too-many-prompts': {
+    problemType: 'too-many-prompts',
+    counterTechnique: { vi: 'Chia nhiệm vụ thành các chặng kiểm chứng; mỗi chặng có một kết quả rõ ràng.', en: 'Split the task into checkpoints with a validation result at each boundary.' },
+    projectHelp: 'clearthought',
+    microQuest: { vi: 'Nhiệm vụ tới: xác định hai chặng kiểm chứng có tiêu chí hoàn thành.', en: 'Next task: define 2 checkpoints each with a done-criterion.' },
+    victory: { vi: 'Nhiệm vụ hoàn thành với số lượt yêu cầu thấp hơn ngưỡng lịch sử.', en: 'A task completes under the historical prompt threshold.' },
+    ifThen: { vi: 'Nếu gửi lượt yêu cầu thứ ba cho cùng một nhiệm vụ, hãy đặt một chặng kiểm chứng có tiêu chí hoàn thành trước.', en: 'If you send a third prompt on one task, then define a checkpoint with a done-criterion first.' },
+    villain: { name: 'Cửu Hoàn Tâm Ma', gloss: 'Ninefold Loop Heart-Shadow' }
+  },
+  'conflicting-instructions': {
+    problemType: 'conflicting-instructions',
+    counterTechnique: { vi: 'Lập sổ ưu tiên và ràng buộc; nêu rõ chỉ thị nào thay thế chỉ thị nào.', en: 'Build a precedence and constraint ledger; state which instruction supersedes which.' },
+    projectHelp: 'claim',
+    microQuest: { vi: 'Trước khi sửa: ghi một dòng nêu rõ điều được phép và điều không được phép.', en: 'Before editing: write one allowed/forbidden line.' },
+    victory: { vi: 'Không còn cặp chỉ thị mâu thuẫn chưa giải quyết trong một nhiệm vụ.', en: 'No unresolved contradictory instruction pair remains in a task.' },
+    ifThen: { vi: 'Nếu chỉ thị mới mâu thuẫn với chỉ thị trước, thì nêu rõ chỉ thị nào thắng trước khi sửa.', en: 'If a new instruction contradicts an earlier one, then state which one wins before editing.' },
+    villain: { name: 'Nghịch Lệnh Ma Quân', gloss: 'Lord of Clashing Edicts' }
+  },
+  'unrecovered-failure': {
+    problemType: 'unrecovered-failure',
+    counterTechnique: { vi: 'Thêm cổng hoàn thành: chạy kiểm chứng và đính kèm kết quả.', en: 'Add a completion gate: run validation and attach a result receipt.' },
+    projectHelp: 'backbone.yml validate',
+    microQuest: { vi: 'Với mỗi lỗi còn treo: chạy lại đúng kiểm tra đó tới khi đạt.', en: 'For each open failure: re-run that exact check until it passes.' },
+    victory: { vi: 'Mỗi thất bại có một lần kiểm chứng đạt tương ứng về sau.', en: 'Every failure has a later matching pass.' },
+    ifThen: { vi: 'Nếu một kiểm tra thất bại, hãy chạy lại đúng kiểm tra đó tới khi đạt trước khi làm việc mới.', en: 'If a check fails, then re-run that exact check until it passes before starting new work.' },
+    villain: { name: 'Vô Nghiệm Ảnh Quân', gloss: 'Unverified Trial Wraith' }
+  },
+  'work-without-proof': {
+    problemType: 'work-without-proof',
+    counterTechnique: { vi: 'Chạy lệnh kiểm chứng của kho mã và gắn kết quả trước khi tuyên bố hoàn thành.', en: 'Run the repository validation and attach the result before declaring done.' },
+    projectHelp: 'backbone.yml validate',
+    microQuest: { vi: 'Bản ghi Git tiếp theo: kèm một dòng kết quả kiểm chứng.', en: 'Next commit: include one validation-result line.' },
+    victory: { vi: 'Mỗi vùng công việc có ít nhất một sự kiện kiểm chứng.', en: 'Every work window has at least one validation event.' },
+    ifThen: { vi: 'Nếu sắp tuyên bố hoàn thành, hãy chạy lệnh kiểm chứng của kho mã và đính kèm kết quả trước.', en: "If you are about to say 'done', then run the repo validation and attach the result first." },
+    villain: { name: 'Vô Chứng Đan Ảnh', gloss: 'Proofless Elixir Shade' }
+  }
+};
+
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+const round3 = (x) => Math.round(x * 1000) / 1000;
+
+// Returns ranked, actionable problems. priority = impact × recurrence ×
+// confidence × fixability. Only problems with confidence >= minConfidence and
+// priority >= minPriority survive; at most `top` are returned.
+export function detectProblems(analysis, { minConfidence = 0.5, minPriority = 0.12, top = 3 } = {}) {
+  const found = [];
+  const rep = analysis.repetition ?? {};
+  const issues = analysis.issues ?? {};
+  const failures = issues.failures ?? [];
+  const recoveries = issues.recoveries ?? [];
+
+  for (const loop of rep.retryLoopCandidates ?? []) {
+    // Only failures attributed to this loop's own task make it a failure loop;
+    // an unrelated failure elsewhere must not change the classification.
+    const isFailing = failures.some((f) => f.taskId != null && f.taskId === loop.taskId);
+    const id = isFailing ? 'repeated-failure' : 'too-many-prompts';
+    found.push({
+      problemId: id,
+      evidence: { taskId: loop.taskId, repeatCount: loop.count, eventIds: loop.eventIds },
+      confidence: loop.confidence,
+      impact: isFailing ? 0.7 : 0.5,
+      recurrence: clamp01(loop.count / 4),
+      fixability: 0.8
+    });
+  }
+
+  const conflicts = analysis.conflicts ?? [];
+  if (conflicts.length > 0) {
+    found.push({
+      problemId: 'conflicting-instructions',
+      evidence: { count: conflicts.length, eventIds: conflicts.flatMap((c) => c.eventIds) },
+      confidence: Math.max(...conflicts.map((c) => c.confidence)),
+      impact: 0.7,
+      recurrence: clamp01(conflicts.length / 2),
+      fixability: 0.7
+    });
+  }
+
+  const unrecovered = failures.filter((f) => !recoveries.some((r) => r.issueEventId === f.eventId));
+  if (unrecovered.length > 0) {
+    found.push({
+      problemId: 'unrecovered-failure',
+      evidence: { count: unrecovered.length, eventIds: unrecovered.map((f) => f.eventId) },
+      confidence: 0.7,
+      impact: 0.8,
+      recurrence: clamp01(unrecovered.length / 3),
+      fixability: 0.6
+    });
+  }
+
+  const commits = analysis.coverage?.commits ?? 0;
+  const validationEvents = (issues.passes ?? 0) + failures.length;
+  if (commits > 0 && validationEvents === 0) {
+    found.push({
+      problemId: 'work-without-proof',
+      evidence: { commits, validationEvents: 0 },
+      confidence: 0.6,
+      impact: 0.6,
+      recurrence: clamp01(commits / 5),
+      fixability: 0.7
+    });
+  }
+
+  return found
+    .map((p) => {
+      const meta = CATALOG[p.problemId];
+      const priority = round3(p.impact * p.recurrence * p.confidence * p.fixability);
+      return { ...p, priority, confidence: round3(p.confidence), meta };
+    })
+    .filter((p) => p.confidence >= minConfidence && p.priority >= minPriority)
+    .sort((a, b) => b.priority - a.priority || a.problemId.localeCompare(b.problemId))
+    .slice(0, top);
+}