minimal-vibe-coding-kit 0.4.2 → 0.5.1

package/.agents/skills/tutien/references/story-system.md

@@ -0,0 +1,176 @@
+# Living chronicle system
+
+Read this reference whenever `/tutien` creates, continues, repairs, or discusses the repository-specific story.
+
+## Core contract
+
+The chronicle is an open-ended xianxia serial whose world grows from the current repository. Deterministic code supplies approved facts; the agent creates the plot, characters, names, dialogue, imagery, and chapter prose. Never select complete sentences from a fixed phrase bank, and never treat a report template as the story.
+
+Keep these layers separate:
+
+1. **Project truth:** approved Git aggregates, token totals when available, safe facts from the advertised root manifests, validation results, classifications, and facts already established in the current task.
+2. **Cultivation interpretation:** sects, realms, artifacts, tribulations, techniques, rivals, and geography derived from those facts.
+3. **Fictional invention:** scenes, dialogue, motivations, mysteries, and future hooks. These may dramatize project truth but may not change it.
+
+If evidence is missing, write uncertainty into the world as fog, an unopened seal, an unknown realm, or an unresolved rumor. Do not invent project events.
+
+## First activation in a repository
+
+After the first successful, approved `analyze` with `story=on`:
+
+1. Read `latest-context.json` and use only its aggregate facts plus repository metadata already authorized by the active task.
+2. Detect `vi`, `en`, or `zh` from `story-language`, then the invocation language. Ask only when the user explicitly wants another language or the signal is genuinely ambiguous.
+3. Choose a flexible style profile from `story-style`; `auto` selects from project shape:
+   - `classic-quest`: focused protagonist, trials, discoveries, and gradual realm advancement.
+   - `web-serial`: strong chapter hooks, layered sect politics, widening maps, and long arcs.
+   - `daily-life`: craft, maintenance, customs, relationships, and light comic reversals.
+   - `clan-epic`: the repository or team is the enduring protagonist across generations.
+   - `comic-adventure`: lively misunderstandings and reversals without turning evidence into a joke.
+   - Blend at most two profiles and record the blend in `plot.md`.
+4. Transform the project into a world using semantic relationships, not word substitution:
+   - project/repository → sect, clan, wandering pavilion, or hidden domain;
+   - architecture/modules → territories, peaks, halls, arrays, or lineages;
+   - tools/dependencies → artifacts, spirit beasts, manuals, or allied workshops;
+   - validation/tests → trials, sword arrays, alchemical inspections, or heavenly seals;
+   - bugs/retry loops/conflicts → tribulations, curses, enemy schemes, or heart-demon manifestations;
+   - commits/releases → completed techniques, expeditions, treaties, or breakthroughs;
+   - tokens → spent spiritual stones or divine-sense expenditure, always retaining the exact reported/estimated/unknown distinction.
+5. Create `plot.md`, `story-state.json`, and chapter 1 as one continuity transaction.
+
+## Local story layout
+
+Store all chronicle files under the git-ignored runtime directory:
+
+```text
+.vibekit/reports/tutien/story/
+├── plot.md
+├── story-state.json
+├── latest-context.json
+└── chapters/
+    ├── 0001-<cultivation-title>.md
+    └── 0002-<cultivation-title>.md
+```
+
+`plot.md` is the overall plot and world bible that future agents must read before continuing. Keep these sections current:
+
+- Story constitution: language, style blend, narrative distance, humor level.
+- Project truth map: real project facts and their stable cultivation counterparts.
+- World: sects/clans, regions, laws, resources, history, factions, and power balance.
+- Cultivation system: realms, paths, techniques, artifacts, costs, limits, and breakthrough rules.
+- Cast registry: stable names, localized display names, role, motivation, voice, relationships, and name meaning.
+- Overall plot: central conflict, current arc, planned horizons, and an explicitly open ending.
+- Open threads: mysteries, promises, rival plans, technical risks, and possible payoffs.
+- Chapter ledger: chapter number, title, evidence key, project change, fictional consequence, unresolved hook.
+
+`story-state.json` is machine-readable continuity only:
+
+```json
+{
+  "schema": "tutien-story-state-v1",
+  "language": "vi",
+  "style": "web-serial+daily-life",
+  "lastChapter": 1,
+  "consumedEvidenceKeys": ["0123456789abcdef"]
+}
+```
+
+Do not persist raw prompts, commit subjects, author identities, secrets, URLs, source-file contents, or conversation excerpts in any story file.
+
+## Chapter contract
+
+One save equals exactly one chapter file. Use the next contiguous four-digit number and a title that sounds like a real xianxia chapter, not a ticket name or generic label:
+
+```text
+0007-kiem-y-khai-tran.md
+0007-sword-intent-opens-the-array.md
+0007-剑意开阵.md
+```
+
+Every chapter begins with:
+
+```yaml
+---
+schema: tutien-story-chapter-v1
+chapter: 7
+title: "Localized xianxia chapter title"
+language: vi
+evidence_key: 0123456789abcdef
+---
+```
+
+The following are content obligations, not a scene order or six-slot template. Arrange, merge, imply, or foreground them according to the user's current request, the repository's distinctive evidence, and the open plot:
+
+1. a scene rooted in the previous hook;
+2. one or more meaningful project-derived developments;
+3. character choice and consequence, not a metrics dump;
+4. dialogue in the active language's xianxia register;
+5. an earned change in relationships, knowledge, risk, or cultivation posture;
+6. a forward hook that offers several plausible future paths.
+
+Do not force every chapter to open with scenery, introduce evidence at the same beat, stage an antagonist, or end with the same hook mechanism. Compare the recent chapters and vary at least two useful dimensions such as point of view, location, scene pressure, dialogue share, technical density, humor, or closing image. Use explicit user direction for focus and mood ephemerally; never persist the raw prompt.
+
+Never advance a realm solely because tokens increased. Never create a second chapter for an already consumed `evidence_key`. With no new evidence, continue discussion in chat or write an interlude only when the user explicitly asks; do not fabricate project progress.
+
+## Language, names, and voice parity
+
+Vietnamese, English, and Simplified Chinese use identical facts, continuity, and character intent, but each version must read naturally in its own literary register. Do not translate mechanically.
+
+### Vietnamese (`vi`)
+
+- Use fluent modern Vietnamese narration enriched with controlled Hán–Việt cultivation vocabulary.
+- Prefer meaningful two-to-four-syllable personal names and titles whose semantics fit origin, path, and temperament. Record the meaning in the cast registry.
+- Use natural address such as `đạo hữu`, `sư huynh`, `sư tỷ`, `tiền bối`, `bản tọa`, or role-specific titles only when relationships justify them.
+- Keep sentences smooth and readable; avoid piling archaic particles or mechanically converting English metaphors.
+- Follow `vi-style-guide.md` for every heading, title, sentence, and line of dialogue.
+- Use sentence case: `Chương thứ nhất: Kiếm ý khai trận`, not `Chương Thứ Nhất: Kiếm Ý Khai Trận`. A stable proper name such as `Lăng Vân`, `Thanh Vân Môn`, or the named technique `Kiếm Ý Khai Trận` may retain its capitals.
+- Never use spaced ASCII ` - ` as prose punctuation. Prefer a full stop, colon, comma, or semicolon; use an em dash only for a necessary rhetorical pause.
+- Prefer Vietnamese workflow terms. Preserve exact code, paths, commands, and identifiers in backticks.
+
+### English (`en`)
+
+- Use clear fantasy prose with measured xianxia terminology and gloss an unfamiliar localized term on first use.
+- Give characters a stable cultivation-style romanized name plus a meaningful English epithet when useful.
+- Use hierarchy and titles consistently; avoid faux-Elizabethan speech unless explicitly selected.
+
+### Simplified Chinese (`zh`)
+
+- Use concise, idiomatic modern Chinese web-serial narration with controlled classical cadence.
+- Use meaningful Chinese surnames, given names, Daoist titles, sect names, and technique names; avoid random character combinations.
+- Dialogue should respect seniority and relationship through address, rhythm, and omission rather than explanatory translation.
+
+For other user languages, keep narration and dialogue in that language while retaining one stable xianxia name and a localized epithet. Once a name is recorded, never silently rename or retranslate it.
+
+## Character and dialogue generation
+
+Use meaningful cultivation-style names. Create each important character from four linked facts: project role, cultivation path, personal desire, and contradiction. A name is valid only when its meaning reinforces at least two of those facts. Avoid names made from bare tool names, random grandiose nouns, or meaningless syllables.
+
+Every spoken line must do at least one job: reveal motive, change leverage, interpret evidence, sharpen conflict, set up a technique, or deliver a relevant joke. Remove dialogue that merely repeats metrics or generic cultivation slogans.
+
+Humor comes from character logic, hierarchy, technical irony, and timing. Keep serious failures serious; let the absurdity arise from the fictional response to the workflow pattern.
+
+Examples and mappings in this reference define possibilities and invariants only. They are not phrase banks, mandatory beats, or response templates.
+
+## Villains: sarcastic and maliciously teasing
+
+Villains may be genuinely malicious **inside the fiction**: they exploit the sect's demonstrated weakness, savor the inconvenience, mislead rivals, and tease with sharp sarcasm. Their dialogue should:
+
+1. point at the exact workflow weakness supported by evidence;
+2. reveal how the villain benefits from it;
+3. deliver a cutting but meaningful tease;
+4. leave room for the heroes to answer with the real counter-technique.
+
+Aim hostility at the failure mode, plan, array, artifact, or sect strategy—never at the user's identity, intelligence, health, worth, protected traits, or finances. No threats toward the user, humiliation, slurs, or abusive degradation. Safety-sensitive contexts remain neutral and villain-free.
+
+Generate antagonist names, titles, schemes, and lines from the current project, language, prior chapters, and evidence. Do not reuse the renderer's fixed villain sentence bank as chapter dialogue.
+
+## Save transaction
+
+For every new approved evidence key:
+
+1. Run `node .vibekit/skills/tutien/scripts/story-ledger.mjs status`.
+2. Read `plot.md`, `story-state.json`, `latest-context.json`, and only the last one to three chapters needed for continuity.
+3. Refuse chapter creation when `canWriteChapter=false`, policy state is not `clear`, or the evidence key is already consumed.
+4. Draft the chapter and update `plot.md` without closing the whole saga.
+5. Write exactly one numbered chapter and update `story-state.json` in the same task.
+6. Run `node .vibekit/skills/tutien/scripts/story-ledger.mjs validate`.
+7. If validation fails, repair the transaction before presenting the chapter.

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