minimal-vibe-coding-kit 0.4.2 → 0.5.1

package/.grok/skills/tutien/references/adaptive-response.md

@@ -0,0 +1,68 @@
+# Adaptive response composition
+
+Use this reference for every user-facing `/tutien` answer. After `analyze`, read `latest-brief.json` first; consult `latest.md` only when more audit detail is needed. The deterministic renderer is an evidence ledger and fallback inspection view. It is not a response template, a required section order, or prose to paste unchanged.
+
+## Invariants and freedom
+
+Preserve these invariants:
+
+- exact counts, confidence, policy state, classifications, risks, and recommended action;
+- privacy, authorization, redaction, and neutral safety behavior;
+- established names, relationships, world laws, unresolved threads, and consumed evidence keys;
+- a clear distinction between project truth, cultivation interpretation, and fictional invention.
+
+Everything else is compositional freedom. Choose length, headings, order, narrative distance, scene, dialogue, humor, imagery, and amount of technical detail from the current context. A valid answer may be a terse field note, an in-scene exchange, a tribunal, a breakthrough scene, a technical diagnosis wrapped in lore, or a full chapter. These are possibilities, not named templates to cycle through.
+
+## Context-driven composition
+
+Before writing, privately identify four things:
+
+1. What the current user request is asking for, including desired depth, focus, and mood.
+2. What is distinctive about this repository, its current work, and the strongest approved evidence.
+3. What the living chronicle has already established and which open thread can move naturally.
+4. What shape, opening device, metaphor, and closing cadence were used recently and therefore should not be repeated without a reason.
+
+Let those answers determine the response. Do not expose this private planning as headings or a checklist.
+
+Treat the brief as a fact boundary, not a fill-in form. Its keys do not prescribe paragraph order. Project stack, package manager, and validation commands are anchors to make advice concrete; do not invent a missing tool or recommend a kit-only command when `kitInstalled` is false.
+
+- For a narrow question, answer narrowly and keep the role-play concentrated.
+- For a data-heavy analysis, make the decisive evidence easy to find, but do not dump every renderer section when a compact synthesis is clearer.
+- For new approved evidence with `story=on`, continue the chronicle and let the project change cause a fictional consequence.
+- With no new evidence, deepen interpretation or character tension without inventing project progress or consuming another evidence key.
+- Follow an explicit user request for scene focus, character focus, technical depth, brevity, or story emphasis when it does not conflict with safety or evidence.
+- Use the active user request only as ephemeral creative direction. Do not persist raw prompt text in story files.
+
+## Anti-template rule
+
+Never require all stock headings. Never preserve the renderer's section order merely because it is available. Never begin every answer with weather at the mountain gate, introduce every problem as a heart demon, or close every answer with the same encouragement.
+
+Across adjacent responses, vary at least two suitable dimensions when the context permits: opening position, point of view, scene location, amount of dialogue, technical density, antagonist presence, paragraph rhythm, heading use, or closing image. Do not force variation that harms clarity.
+
+Examples in this skill demonstrate constraints only. Do not copy their sentences, fill their slots, or treat them as canonical output.
+
+When mode is off, do not read this brief or continue its fiction. Return to the normal project voice until the user explicitly reactivates `/tutien`.
+
+## Vietnamese ending contract
+
+For ordinary Vietnamese role-play, preserve this exact editorial intent:
+
+> 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.
+
+Interpret it dynamically:
+
+- `cà khịa`: tease the evidenced flaw, evasive plan, brittle array, or antagonist strategy; never attack the user or a real person;
+- `giáo huấn`: leave a direct lesson or next discipline grounded in the evidence, not a generic motivational slogan;
+- `không tâng bốc`: do not praise intelligence, talent, destiny, rank, or worth;
+- `kéo dài dư âm vai diễn`: end inside the world through an image, consequence, warning, unfinished gesture, or character voice instead of stepping outside the role to summarize.
+
+This is an effect contract, not a four-line formula. The ending may be one sentence or several and should grow from the current scene. Neutral safety mode overrides sarcasm and role-play, but it still avoids flattery and states the required corrective action plainly.
+
+## Final check
+
+Before sending, ask:
+
+- Could this answer belong to a different repository after changing only a few nouns? If yes, make it more project-specific.
+- Does its shape repeat the previous answer? If yes, vary the form where useful.
+- Did any fictional claim overwrite or exaggerate project truth? If yes, repair it.
+- Does the ending satisfy the active language contract without becoming a stock catchphrase?

package/.grok/skills/tutien/references/classification.md

@@ -0,0 +1,64 @@
+# Tu Tiên classification and progression
+
+`scripts/classify.mjs` assigns a project's cultivation identity along three **orthogonal** axes, recommends knowledge, and derives seven progression metrics. It is deterministic and evidence-bound; classification comes from explicit declarations plus repo-profile keywords, each with a confidence and a rationale.
+
+Invoke it standalone with `/tutien classify` (or it is appended to a full `analyze` report when a project profile is available).
+
+```
+classify [faction=<id>] [affiliation=<id>] [paths=<id,id>] [domains=<kw,kw>] [authorization=<slug>] [language=vi|en]
+```
+
+## Policy state — the single fail-closed gate
+
+One `policy.state` governs the whole report, consumed identically by the renderer and the snapshot. **Only `clear` enables realm, score, villains, knowledge recommendations, and positive progression.** Under any other state those are set to **null (absent, not merely hidden)** and only Nghiệp Lực (risk) accrues.
+
+| state | trigger | effect |
+|---|---|---|
+| `clear` | lawful constructive work | full report |
+| `needs-review` | intent-to-harm signals in the description | faction **undetermined** (never Chính Đạo), no gamification, asks for human review |
+| `authorization-required` | Ma Đạo with no valid `authorization` slug | withholds gamification until a scope is recorded |
+| `declared-stop` | user declared Tà Đạo or the `ta` path | stop notice; no realm/score/knowledge; only Nghiệp Lực |
+
+## The safety rules (non-negotiable)
+
+1. **Tà Đạo and Tà Tu are never auto-assigned.** Intent to harm cannot be judged from keywords, and technical difficulty is not evil. They exist only as an explicit user declaration; `ta` cannot be combined with any other path (fails closed).
+2. **Harmful intent is never rewarded.** A harmful description does not become Chính Đạo — it becomes `needs-review` with an undetermined faction and no gamification. This is a refusal to classify, not an automatic Tà label.
+3. **A declared Tà Đạo suppresses all gamification.** No realm, score, villains, knowledge, Tu Vi, or Công Đức — only Nghiệp Lực and a stop-and-seek-review notice. Never a progression path.
+4. **Affiliation is orthogonal to ethics.** Tán Tu (independent) is an organizational status, not the opposite of Tà Tu. A solo red-teamer is Tán Tu + Ma Đạo.
+5. **Security/investigation/crypto/RE is legitimate.** Defensive work is Chính Đạo + Ảnh Tu; authorized adversarial engagement is Ma Đạo. Authorization is a **user-asserted reference slug** (`[A-Za-z0-9][A-Za-z0-9_-]{0,63}`), never verified; secret-shaped, markup, URL, or `key=value` values are rejected and never rendered. The Ảnh Tu / Huyền Cơ Tu paths always print a dual-use note.
+6. **Progression is idempotent.** Contributions are per-event with a salted seen-ledger; replaying the same evidence (e.g. `range=all` twice) adds zero Tu Vi/Công Đức/Đạo Hạnh. A window with one new validated event adds only that event's contribution; overlap is reported.
+
+## Axis 1 — Dao faction (project ethics/risk)
+
+| id | Faction | Meaning | Assignment |
+|---|---|---|---|
+| `chinh-dao` | Chính Đạo | lawful, transparent, constructive | default; no adversarial/experimental signals |
+| `bang-mon` | Bàng Môn / Kỳ Đạo | experimental, creative, specialized; not harmful | experimental/creative keywords |
+| `ma-dao` | Ma Đạo | high-risk/adversarial; needs authorization | adversarial-engagement keywords; records `authorization` |
+| `ta-dao` | Tà Đạo | intentionally harmful | **declaration only**; suppresses gamification |
+
+## Axis 2 — Cultivator affiliation (organizational)
+
+`tong-mon` (team/process) · `tan-tu` (independent) · `khach-khanh` (external/temporary) · `an-tu` (private long-term research). Author identifiers are read **transiently** (mailmap-collapsed `git log --use-mailmap`) and reduced immediately to a distinct **count**; no name or email is retained or emitted. The count is only a **low-confidence hint** (aliases, bots, and external contributors can inflate it) — declare `affiliation=` to set it authoritatively.
+
+## Axis 3 — Cultivation paths (technical, multi-select)
+
+`kiem` implementation · `tran` architecture/DevOps · `phu` prompts/automation · `khi` tools/libraries · `dan` data/optimization · `y` debugging/maintenance · `huyen` UI/UX/visual · `ngu-thu` AI-agent orchestration · `huyen-co` crypto/hard algorithms · `anh` authorized security/forensics/OSINT/RE · `ta` intentionally harmful methods (**declaration only**, never auto-assigned).
+
+## Knowledge taxonomy
+
+Recommended per the **primary path** (the first declared path, else the strongest detected one — never an alphabetical tie-break): **Tâm Pháp** (core mindset), **Công Pháp** (repeatable methods), **Thuật Pháp** (individual techniques — surfaced in the report's per-problem counter-techniques), **Bí Thuật** (rare/advanced), **Thần Thông** (mastered reusable abilities — rendered per path), **Pháp Bảo** (kit capabilities — existing skills *and* commands), **Bí Tịch / Đạo Điển** (playbooks/docs — this repo's `SKILL.md` files and `backbone.yml`).
+
+`classify` is a **metadata-only** action: it reads `backbone.yml` fields plus the transient author count, prints that exact data scope, and derives no progression (progression requires analyzed history via `analyze`). It is not gated behind the `analyze` preview/approval boundary because it reads no history content.
+
+## Progression metrics (deterministic; token-independent)
+
+Derived from analysis evidence plus prior-snapshot accumulators — token usage feeds none of them:
+
+- **Tu Vi** (per-window + lifetime): passes + recoveries + capped commits.
+- **Đạo Hạnh**: count of reporting windows (long-term practice).
+- **Ngộ Tính** [0–1]: recovery ratio minus avoidable-repeat rate.
+- **Độ Thuần Thục** [0–1]: overall mastery (per-path mastery needs path-tagged evidence — a V2 item).
+- **Tâm Cảnh** [0–1]: effectiveness under failure (recovery ÷ failure).
+- **Công Đức** (per-window + lifetime): verified positive output.
+- **Nghiệp Lực** (per-window + lifetime): unresolved failures ×2 + conflicts + loops. Under a suppressed (Tà Đạo) report, only Nghiệp Lực accrues; Tu Vi and Công Đức stay zero.

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

@@ -0,0 +1,43 @@
+# 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`).
+- Vietnamese reader register and community terminology: Tàng Thư Viện (`https://truyen.tangthuvien.vn/`). Treat it as a varied reader corpus containing translated, edited, and converted text, not as a single authoritative style or a source to copy.
+- Sino-Vietnamese name and term verification: Từ điển Hán–Việt (`https://hanviet.asia/`). Use it to check readings and meanings, not to manufacture dense archaic prose.
+
+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.
+
+## Source-backed story palette
+
+Use sources at the level of cultural concepts and genre craft. Never copy passages, continue a copyrighted work, or imitate the distinctive voice of a named living author.
+
+| Source family | Safe craft to borrow | Tutien application |
+| --- | --- | --- |
+| Daoist path and learning metaphors | A path offers changing possibilities; practice develops know-how through observation and correction. | Let the project encounter choices, feedback, and revised techniques instead of treating progression as a rigid moral ladder. |
+| Classical divine-and-demonic journey traditions, including *Journey to the West* and *Investiture of the Gods* as historical genre ancestors | Expansive worlds, trials, artifacts, rival powers, comic reversals, and travel between domains. | Turn new modules, releases, and architectural boundaries into newly opened regions without copying characters or plots. |
+| Modern cultivation-path serials | Sects and factions, long arcs, widening maps, breakthroughs, bottlenecks, and accumulated consequences. | Expand the world only when project scope expands; keep several future arcs possible. |
+| Daily-life cultivation | Craft work, maintenance, sect customs, relationships, lighter stakes, and humorous anti-tropes. | Give tests, refactors, documentation, and ordinary maintenance narrative weight instead of forcing every commit into combat. |
+| Clan or sect-centered cultivation | The organization persists while individual roles change; inheritance and institutions matter. | Treat the repository, team, or agent ecosystem as the long-lived protagonist when that fits the project. |
+| Cultivation-game procedural structure | Technical activity, progression rules, resources, and cosmology reinforce one another. | Make project architecture shape world laws and cultivation techniques, while real evidence remains authoritative. |
+
+The Wuxiaworld genre introduction identifies Daoist cultivation and mythology, growth and struggle, sect-rich worlds, map expansion, daily-life comedy, and clan-centered narratives as recurring xianxia patterns. Its glossary supports terminology for sect hierarchy, cultivation methods, breakthroughs, bottlenecks, and tribulations. The SAGE paper supports treating cultivation systems as procedural structures connected to technical activity. Stanford's Daoism entry supports the broader path, learning, change, and self-correction framing without turning fictional realm scores into philosophy or religion.
+
+## Reference verification ledger
+
+Verified on 2026-07-22:
+
+- `https://plato.stanford.edu/entries/daoism/` — official Stanford Encyclopedia of Philosophy entry; verified for path, practice, learning, change, and self-correction framing.
+- `https://www.wuxiaworld.com/page/introduction-to-chinese-webnovel-genres-xianxia` — Wuxiaworld's own editorial genre guide; verified for xianxia foundations and style families.
+- `https://www.wuxiaworld.com/page/general-glossary-of-terms` — Wuxiaworld's own glossary; verified for common genre terminology and sect/cultivation organization.
+- `https://journals.sagepub.com/doi/pdf/10.1177/20594364251364733` — SAGE-hosted academic paper; verified for cultivation narrative structures expressed through technical game systems.
+- `https://truyen.tangthuvien.vn/` — Tàng Thư Viện reader platform; verified as a varied Vietnamese cultivation-fiction corpus and terminology reference, not a unified style guide.
+- `https://hanviet.asia/` — structured Hán–Việt lookup with cited character sources; verified for name and term checking.
+
+## 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/.grok/skills/tutien/references/privacy.md

@@ -0,0 +1,45 @@
+# 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.
+- **Known root manifests** advertised during preview: `backbone.yml`, package/runtime manifests, lockfiles, and language config files from the fixed allowlist in `project-profile.mjs`. Symlinks and files above 1 MiB are ignored. Script bodies are never returned, persisted, or executed.
+
+Never read: the home directory, global tool history, other repos, arbitrary source files, or unadvertised paths. `preview` shows supplied evidence files, known manifest inventory, sizes, and date window before content is read; the approval token includes manifest size and modification time.
+
+## 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.
+
+`latest-brief.json` contains only aggregate evidence, safe project slugs, allowlisted stack names, generated validation commands based on script names, story pointers, and composition constraints. It never contains package script bodies, arbitrary manifest values, raw event IDs, or stock response prose.
+
+The optional living chronicle uses `.vibekit/reports/tutien/story/`:
+
+- `latest-context.json` contains only project slugs, aggregate coverage, disjoint token totals, realm/classification slugs, problem types, progression aggregates, and a 16-hex evidence key.
+- `plot.md` and `chapters/*.md` contain agent-authored fiction derived from approved aggregates and non-secret repository metadata already in task scope.
+- `story-state.json` contains the selected language/style, last chapter number, and consumed evidence keys.
+
+Story files must never contain raw prompts, conversation excerpts, commit subjects, author names/emails, raw event IDs, URLs, secret values, or source-file contents. Do not turn a real contributor into a character without explicit user permission. Fictional character names are locally generated and are not identity mappings.
+
+## 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.
+- **Story export:** copy `story/` only after reviewing the fictional prose for project-sensitive metaphors. The deterministic context remains aggregate-only, but the user's chosen plot may itself be private.

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

@@ -0,0 +1,106 @@
+# `/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 pending single-use approval token in `.vibekit/reports/tutien/state.json`, snapshots under `snapshots/`, the audit ledger as `latest.md`, and the agent handoff as `latest-brief.json`. Preview inspects existence, size, and modification time only; analysis runs only with the matching token for the identical evidence and manifest inventory. The runner never deletes files.
+
+`latest-brief.json` uses `tutien-response-brief-v1`. It carries policy state, safe project identity/stack/validation commands, aggregate evidence, classification/progression slugs, bounded findings without event IDs, an optional story pointer, and composition constraints. Its object shape is not a response layout.
+
+When `story=on`, runner state also stores the selected `storyLanguage`, `storyStyle`, and `storyFocus` for the current repository. A successful approved analysis writes `.vibekit/reports/tutien/story/latest-context.json`; it does not write creative prose.
+
+## Living chronicle schemas
+
+`latest-context.json` uses `tutien-story-context-v1` and contains:
+
+- a deterministic 16-hex `evidenceKey` derived from aggregate facts;
+- `language`, `style`, `focus`, `policyState`, and `canWriteChapter`;
+- safe project, stack, metadata-source, and generated validation-command slugs plus an aggregate author count;
+- coverage, reported/estimated/unknown token totals, realm/score, problem types, classification slugs, and progression aggregates.
+
+It never contains `text`, prompts, commit subjects, event IDs, author identities, file contents, URLs, or classification rationale.
+
+`story-state.json` uses `tutien-story-state-v1` with `language`, `style`, contiguous `lastChapter`, and unique `consumedEvidenceKeys`.
+
+Each `chapters/NNNN-<localized-xianxia-title>.md` uses YAML frontmatter:
+
+```yaml
+---
+schema: tutien-story-chapter-v1
+chapter: 1
+title: "Localized title"
+language: vi
+evidence_key: 0123456789abcdef
+---
+```
+
+Chapter numbers are contiguous and one evidence key may appear in at most one chapter. `scripts/story-ledger.mjs validate` checks these invariants plus the presence of `plot.md` and agreement with `story-state.json`.
+
+## 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/.grok/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/.grok/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.