minimal-vibe-coding-kit 0.4.1 → 0.5.0

package/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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 1 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 task khép lại mà không có 3 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 Lỗi Ma', gloss: 'Error-Cycle Wraith' }
+  },
+  'too-many-prompts': {
+    problemType: 'too-many-prompts',
+    counterTechnique: { vi: 'Chia task thành các checkpoint, mỗi ranh giới có một kết quả kiểm chứng.', en: 'Split the task into checkpoints with a validation result at each boundary.' },
+    projectHelp: 'clearthought',
+    microQuest: { vi: 'Task tới: định nghĩa 2 checkpoint có tiêu chí "done".', en: 'Next task: define 2 checkpoints each with a done-criterion.' },
+    victory: { vi: 'Task hoàn thành trong số prompt dưới ngưỡng lịch sử.', en: 'A task completes under the historical prompt threshold.' },
+    ifThen: { vi: 'Nếu gửi prompt thứ ba cho cùng một task, thì đặt một checkpoint có tiêu chí "done" 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 1 dòng "được phép / 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 task.', 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 validation và đính kèm biên nhận 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 pass.', 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 pass 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, thì chạy lại đúng kiểm tra đó cho tới khi pass 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ô Kiểm Ảnh Quân', gloss: 'Unverified Trial Wraith' }
+  },
+  'work-without-proof': {
+    problemType: 'work-without-proof',
+    counterTechnique: { vi: 'Chạy lệnh validation của repo và gắn kết quả trước khi tuyên bố xong.', en: 'Run the repository validation and attach the result before declaring done.' },
+    projectHelp: 'backbone.yml validate',
+    microQuest: { vi: 'Commit tới: kèm 1 dòng kết quả validation.', 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ố "xong", thì chạy validation của repo 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);
+}