minimal-vibe-coding-kit 0.4.1 → 0.5.0

package/.vibekit/skills/tutien/references/lore-sources.md

@@ -0,0 +1,15 @@
+# tutien cultural source notes
+
+The report borrows xianxia/xiuxian genre vocabulary as a creative theme. It distinguishes historical/philosophical ideas from modern fictional/game progression, and does **not** present a fictional realm ladder as religious or historical fact.
+
+- Daoism's "the Way/path", learning, change, and self-correcting practice inform the broad framing — not a software achievement ladder: Stanford Encyclopedia of Philosophy, *Daoism* (`https://plato.stanford.edu/entries/daoism/`).
+- The distinction between `xiuzhen`, `xiuxian`, and `xianxia`, and how cultivation is translated into game systems and levels: "Cultivation games and cosmotechnics" (`https://journals.sagepub.com/doi/pdf/10.1177/20594364251364733`).
+- Xianxia as fiction grounded in Daoist cultivation philosophy and mythology, centered on growth and struggle: Wuxiaworld genre introduction (`https://www.wuxiaworld.com/page/introduction-to-chinese-webnovel-genres-xianxia`) and general glossary (`https://www.wuxiaworld.com/page/general-glossary-of-terms`).
+
+These sources justify the theme and terminology only. The realm names, score bands, achievement mappings, villain archetypes, and jokes in tutien are an original project design and are documented as such.
+
+## Tone contract
+
+- The villain is always the failure mode, never the person.
+- Banned in every mode (including `spicy`): attacks involving identity, intelligence, mental health, disability, religion, gender, race, finances; threats, profanity, humiliation. `tẩu hỏa nhập ma` is not used as a label for a person.
+- Sensitive or emergency contexts force neutral, villain-free output.

package/.vibekit/skills/tutien/references/privacy.md

@@ -0,0 +1,33 @@
+# tutien privacy model
+
+## What is read
+
+- **Git metadata** in the current repo (read-only `git log`): commit hashes, subjects, timestamps, revert flags. No working-tree contents.
+- **Explicitly supplied export files** the user passes by exact path (`sources=…`): `tutien-generic-v1` JSONL or plain transcripts.
+
+Never read: the home directory, global tool history, other repos, or any path the user did not name. `preview` shows the exact file list and date window before anything is read; nothing is read or written until the user approves that scope.
+
+## What is redacted (before anything else sees it)
+
+`scripts/redact.mjs` is the single choke point. On ingest it:
+
+- strips URL user-info (`user:pass@host`);
+- replaces sensitive query values (`token`, `key`, `secret`, `password`, `auth`, `signature`, `code`, and case/encoding variants) with `[REDACTED]`;
+- drops URL fragments;
+- masks bearer/authorization tokens and AWS-key-shaped strings in free text.
+
+Normalized events keep redacted text in memory for the run only. The analysis JSON references content solely through `eventId`, `textDigest`, and `phraseDigest` (16-hex SHA-256 prefixes).
+
+## What is persisted (only with approval)
+
+Aggregate snapshots under the git-ignored `.vibekit/reports/tutien/`:
+
+- coverage, disjoint reported/estimated/unknown token totals, metric counts, dimension scores, realm, thresholds, adapter versions, villain cooldown state, and **salted** evidence-id digests.
+
+Never persisted: raw prompts, URLs, secrets, file contents, or unsalted event IDs. `aggregate-only` is the default; excerpts are off by default and, if ever enabled, are redacted and capped to one line.
+
+## Deletion, retention, reset, export
+
+- **Retention:** keep the newest N snapshots; `snapshotsToPrune()` returns the rest as a list to remove.
+- **Delete/reset:** use the repo safe-delete policy — prefer `trash <path>`; never a silent `rm`. Deleting `.vibekit/reports/tutien/` resets all trend history.
+- **Export:** a snapshot is plain JSON; copy the file. It already contains no raw content.

package/.vibekit/skills/tutien/references/schema.md

@@ -0,0 +1,75 @@
+# `/tutien` normalized event and analysis schema (v1)
+
+## Generic input format `tutien-generic-v1`
+
+One JSON object per line (JSONL). An optional first line `{"schema":"tutien-generic-v1"}` pins the version; any other `schema` value fails closed. Comment lines start with `#`.
+
+The whole declared schema is validated on ingest and fails closed on: unknown `type`; invalid `role`, `outcome`, `usage.accuracy`; unparseable `ts`; non-string `session`/`task`/`label`/`text`/`usage.requestId`; negative, non-finite, or non-numeric usage numbers; non-boolean `usage.cumulative`; malformed `commit`; and the reserved fields `source`/`__source` (the event source is owned by the adapter, never by export content).
+
+Event object:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `type` | string | `message` \| `tool_call` \| `tool_result` \| `test` \| `approval` \| `commit`. Unknown types fail closed. |
+| `session` | string | Session/thread identifier. |
+| `task` | string? | Explicit task ID when the export has one (strongest grouping signal). |
+| `ts` | ISO-8601? | Timestamp; null allowed. |
+| `role` | string? | `user` \| `assistant` \| `tool` \| `git`. |
+| `text` | string? | Redacted on ingest; retained in memory only. |
+| `usage` | object? | `input`, `cachedInput`, `output`, `reasoning`, `total`, `accuracy` (`reported`\|`estimated`\|`unknown`), `requestId`, `cumulative`. |
+| `outcome` | string? | `pass` \| `fail` for `test`/`tool_result`. |
+| `label` | string? | Stable name used to pair a failure with its recovery. |
+| `commit` | object? | `{ hash, subject, isRevert }` for git events. |
+
+## Analysis output (schemaVersion 1)
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "eventsAnalyzed": 0,
+  "coverage": {
+    "sessions": 0, "userPrompts": 0, "commits": 0,
+    "window": { "start": null, "end": null },
+    "tokenCoverage": { "reportedTurnsPct": 0, "estimatedTurnsPct": 0, "unknownTurns": 0 },
+    "confidence": "low|medium|high"
+  },
+  "tokens": {
+    "reportedTotal": 0, "estimatedTotal": 0, "unknownTurns": 0,
+    "countedRequests": 0, "dedupedStreamUpdates": 0
+  },
+  "tasks": [ { "taskId": "", "sessionId": "", "grouping": "explicit|derived", "confidence": "high|medium", "eventCount": 0 } ],
+  "repetition": {
+    "exactRepeats":  [ { "taskId": "", "count": 2, "eventIds": [], "textDigest": "" } ],
+    "nearRepeats":   [ { "taskId": "", "eventIds": [], "similarity": 0.9 } ],
+    "retryLoopCandidates": [ { "taskId": "", "count": 3, "eventIds": [], "confidence": 0.6 } ]
+  },
+  "conflicts": [ { "category": "user-user", "taskId": "", "eventIds": [], "phraseDigest": "", "confidence": 0.6 } ],
+  "issues": {
+    "passes": 0,
+    "failures":   [ { "eventId": "", "label": "" } ],
+    "recoveries": [ { "issueEventId": "", "recoveryEventId": "" } ],
+    "revertCandidates": [ { "eventId": "", "hash": "", "confidence": 0.5 } ]
+  },
+  "notes": []
+}
+```
+
+## Phase 2 render model
+
+`render-report.mjs` builds a language-neutral model from the analysis (realm, dimension scores, disjoint token totals, evidence-bound problems, one if-then practice, one lesson) and renders it in `vi` or `en` — the same model feeds both, so counts are identical across languages by construction. `score.mjs` returns `Chưa đủ thiên cơ` (no realm) when known-token coverage is below 60%. `catalog.mjs` emits at most three problems, ranked by `impact × recurrence × confidence × fixability`, each carrying `evidence` (event IDs / counts), a counter-technique, a project-skill pointer, and a micro-quest. Lore never alters a count.
+
+## Privacy invariant
+
+`text` is redacted inside `normalize-events.mjs` and never emitted. **Metadata is digested too**: `session`, `task`, and `label` values become 16-hex SHA-256 prefixes before they reach normalized events, so task/session identifiers in analysis output (`tasks[].taskId`, `tasks[].sessionId`, `issues.failures[].label`) can never carry raw content. Timestamps are canonicalized to UTC ISO or dropped; commit subjects are dropped from the commit object (their redacted form travels only as event text). Analysis output references content solely through `eventId`, `textDigest`, and `phraseDigest`. No field carries raw prompt text, URL user-info, secret query values, or URL fragments.
+
+## Token-evidence invariant
+
+A usage record contributes to reported/estimated totals and coverage only when a **usable total** exists: a finite, positive `total`, or a positive sum of `input + output + reasoning`. A record claiming `accuracy=reported` with no numbers (or zero) is counted as `unknown` and cannot unlock a realm score. Only records marked `cumulative` are streaming counters (last value wins); independent chunks sharing a `requestId` are summed.
+
+## Runner state
+
+`scripts/run-tutien.mjs` executes the actions end-to-end. It stores the session mode and the pending single-use approval token in the git-ignored `.vibekit/reports/tutien/state.json`, snapshots under `snapshots/`, and the last report as `latest.md`. Preview inspects file existence/size only; analysis runs only with the matching `approve=<token>` for the identical scope. The runner never deletes files — retention prints a `trash` command for the user.
+
+## Determinism invariant
+
+Given the same inputs and options, `analyze()` returns byte-identical JSON. No randomness, no wall-clock reads, no ordering that depends on object insertion beyond the input order.

package/.vibekit/skills/tutien/references/scoring-and-realms.md

@@ -0,0 +1,37 @@
+# tutien scoring and realms
+
+Scoring is deterministic (`scripts/score.mjs`): the same analysis JSON always yields the same score. High token usage never raises the score; necessary iteration is not punished; penalties are capped so one hard task cannot erase a long history.
+
+## Coverage gate
+
+A realm is computed only when known-token coverage (reported + estimated turns) is at least **60%**. Below that the report shows `Cảnh giới: Chưa đủ thiên cơ` (not enough evidence) and lists what is missing — it never guesses a realm from thin data.
+
+## Dimensions (weights)
+
+| Dimension | Weight | Signal |
+|---|---:|---|
+| delivery | 30% | verified completions and recoveries vs failed attempts, plus committed output |
+| validation | 25% | presence and density of validation events |
+| clarity | 15% | 1 − avoidable-repeat rate (capped) |
+| recovery | 15% | recoveries ÷ failures |
+| safety | 10% | high baseline, capped penalty per conflict candidate |
+| automation | 5% | reusable automation (neutral in V1; refined once commit-subject signals are wired) |
+
+Score = round(Σ dimension × weight × 100).
+
+## Realm ladder (project-authored, humorous)
+
+| Band | Realm | Gloss |
+|---|---|---|
+| 0–14 | Phàm Nhân Nhập Môn | Mortal Initiate |
+| 15–29 | Luyện Khí | Qi Refining |
+| 30–44 | Trúc Cơ | Foundation Establishment |
+| 45–59 | Kết Đan | Core Formation |
+| 60–69 | Nguyên Anh | Nascent Soul |
+| 70–79 | Hóa Thần | Spirit Transformation |
+| 80–87 | Luyện Hư | Void Refinement |
+| 88–93 | Hợp Thể | Body Integration |
+| 94–97 | Đại Thừa | Great Vehicle |
+| 98–100 | Độ Kiếp / Phi Thăng | Tribulation / Ascension |
+
+The realm names, thresholds, dimension weights, and jokes are an original project design — a creative theme, not a claim that one authentic cultivation ladder exists. See `lore-sources.md`.

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

@@ -0,0 +1,44 @@
+# 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, and return one plain confirmation.
+- 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.
+
+1. Open with one or two atmospheric sentences.
+2. Present evidence and numbers in plain language.
+3. Use at most one playful image per finding.
+4. Target the workflow pattern, never the person.
+5. Offer one small, measurable next step.
+6. Close with calm encouragement and no pressure.
+
+Avoid dense archaic prose, melodrama, mockery, personal judgment, intimacy, diagnosis, treatment claims, or imported persona language. `serene` is the default. `spirited` may tease the 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.

package/.vibekit/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/.vibekit/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/.vibekit/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/.vibekit/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/.vibekit/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);
+}