minimal-vibe-coding-kit 0.5.0 → 0.5.2

package/.grok/skills/tutien/scripts/story-ledger.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// Deterministic storage helpers for the agent-authored living chronicle.
+// This module never generates story prose. It only builds an aggregate-only
+// evidence packet and validates the plot/chapter ledger written by the agent.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+export const STORY_SCHEMA = 1;
+export const STORY_CONTEXT_SCHEMA = 'tutien-story-context-v1';
+export const STORY_STATE_SCHEMA = 'tutien-story-state-v1';
+export const STORY_CHAPTER_SCHEMA = 'tutien-story-chapter-v1';
+
+const sha16 = (value) => crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, 16);
+
+export function storyPaths(root = process.cwd()) {
+  const base = path.join(path.resolve(root), '.vibekit', 'reports', 'tutien', 'story');
+  return {
+    base,
+    plot: path.join(base, 'plot.md'),
+    state: path.join(base, 'story-state.json'),
+    context: path.join(base, 'latest-context.json'),
+    chapters: path.join(base, 'chapters')
+  };
+}
+
+// Preserve letters from every language, including Han characters. Latin
+// scripts are normalized so Vietnamese titles remain readable in filenames.
+export function slugifyChapterTitle(title) {
+  const raw = String(title ?? '').trim();
+  if (!raw) throw new Error('chapter title is required');
+  const slug = raw
+    .normalize('NFD')
+    .replace(/\p{M}+/gu, '')
+    .toLocaleLowerCase('und')
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80)
+    .replace(/-+$/g, '');
+  if (!slug || slug === '.' || slug === '..') throw new Error('chapter title does not produce a safe filename');
+  return slug;
+}
+
+export function chapterFilename(number, title) {
+  if (!Number.isInteger(number) || number < 1 || number > 9999) {
+    throw new Error('chapter number must be an integer from 1 to 9999');
+  }
+  return `${String(number).padStart(4, '0')}-${slugifyChapterTitle(title)}.md`;
+}
+
+export function listChapters(root = process.cwd()) {
+  const dir = storyPaths(root).chapters;
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((file) => /^\d{4}-[\p{L}\p{N}][\p{L}\p{N}-]*\.md$/u.test(file))
+    .map((file) => ({ file, number: Number(file.slice(0, 4)), path: path.join(dir, file) }))
+    .sort((a, b) => a.number - b.number || a.file.localeCompare(b.file));
+}
+
+export function nextChapterNumber(root = process.cwd()) {
+  const chapters = listChapters(root);
+  return chapters.length ? chapters[chapters.length - 1].number + 1 : 1;
+}
+
+export function resolveStoryLanguage(requested = 'auto', invocationText = '', fallback = 'en') {
+  const explicit = String(requested).toLowerCase();
+  if (['vi', 'en', 'zh'].includes(explicit)) return explicit;
+  if (/\p{Script=Han}/u.test(invocationText)) return 'zh';
+  if (/[À-ỹĐđ]/u.test(invocationText) || /\b(hãy|giúp|của|và|không|chương|tu tiên)\b/iu.test(invocationText)) return 'vi';
+  return ['vi', 'en', 'zh'].includes(fallback) ? fallback : 'en';
+}
+
+function safeSlug(value, fallback = null) {
+  const text = String(value ?? '');
+  return /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(text) ? text : fallback;
+}
+
+function safeValidationCommand(value) {
+  const text = String(value ?? '');
+  return /^(?:npm run|yarn|pnpm|bun run) [A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/.test(text) ? text : null;
+}
+
+function storyFacts(model, profile = {}) {
+  const cultivation = model.cultivation ?? null;
+  const progression = cultivation?.progression ?? null;
+  return {
+    project: {
+      id: safeSlug(profile.projectId, 'repo'),
+      type: safeSlug(profile.projectType),
+      primaryLanguage: safeSlug(profile.primaryLanguage),
+      domains: (profile.domains ?? []).map((v) => safeSlug(v)).filter(Boolean).slice(0, 12),
+      stack: (profile.stack ?? []).map((v) => safeSlug(v)).filter(Boolean).slice(0, 12),
+      validationCommands: (profile.validationCommands ?? []).map((v) => safeValidationCommand(v)).filter(Boolean).slice(0, 3),
+      metadataSources: (profile.metadataSources ?? []).map((v) => safeSlug(String(v).replace(/\.[^.]+$/, ''))).filter(Boolean).slice(0, 12),
+      authorsCount: Number.isInteger(profile.authorsCount) && profile.authorsCount >= 0 ? profile.authorsCount : null
+    },
+    evidence: {
+      window: model.coverage?.window ?? { start: null, end: null },
+      sessions: model.coverage?.sessions ?? 0,
+      prompts: model.coverage?.userPrompts ?? 0,
+      commits: model.coverage?.commits ?? 0,
+      confidence: model.coverage?.confidence ?? 'low',
+      tokens: {
+        reported: model.tokens?.reportedTotal ?? 0,
+        estimated: model.tokens?.estimatedTotal ?? 0,
+        unknownTurns: model.tokens?.unknownTurns ?? 0
+      },
+      realm: model.realm ? { name: model.realm.name, score: model.score } : null,
+      problems: (model.problems ?? []).map((p) => ({
+        type: p.problemType,
+        confidence: p.confidence,
+        priority: p.priority
+      })),
+      classification: cultivation ? {
+        faction: cultivation.classification?.faction?.id ?? null,
+        affiliation: cultivation.classification?.affiliation?.id ?? null,
+        paths: (cultivation.classification?.paths ?? []).map((p) => p.id)
+      } : null,
+      progression: progression ? {
+        tuVi: progression.tuVi?.window ?? 0,
+        congDuc: progression.congDuc?.window ?? 0,
+        nghiepLuc: progression.nghiepLuc?.window ?? 0,
+        daoHanhWindows: progression.daoHanh?.windows ?? 0,
+        overlap: progression.overlap ?? 0
+      } : null
+    }
+  };
+}
+
+export function buildStoryContext(model, options = {}) {
+  const facts = storyFacts(model, options.profile ?? {});
+  const evidenceKey = sha16(JSON.stringify({
+    storySchema: STORY_SCHEMA,
+    project: facts.project.id,
+    range: options.range ?? 'all',
+    evidence: facts.evidence
+  }));
+  return {
+    schema: STORY_CONTEXT_SCHEMA,
+    storySchema: STORY_SCHEMA,
+    evidenceKey,
+    language: resolveStoryLanguage(options.language, options.invocationText, options.conversationLanguage),
+    style: safeSlug(options.style, 'auto'),
+    focus: safeSlug(options.focus, 'balanced'),
+    policyState: model.policyState ?? 'clear',
+    canWriteChapter: model.suppressGamification !== true,
+    ...facts
+  };
+}
+
+export function writeStoryContext(root, context) {
+  if (context?.schema !== STORY_CONTEXT_SCHEMA) throw new Error(`story context must use ${STORY_CONTEXT_SCHEMA}`);
+  const paths = storyPaths(root);
+  fs.mkdirSync(paths.base, { recursive: true });
+  fs.writeFileSync(paths.context, `${JSON.stringify(context, null, 2)}\n`);
+  return paths.context;
+}
+
+function chapterFrontmatter(text) {
+  const match = String(text).match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return null;
+  const get = (key) => match[1].match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim().replace(/^['"]|['"]$/g, '') ?? null;
+  return {
+    schema: get('schema'),
+    chapter: Number(get('chapter')),
+    title: get('title'),
+    evidenceKey: get('evidence_key')
+  };
+}
+
+export function validateStoryTree(root = process.cwd()) {
+  const paths = storyPaths(root);
+  const chapters = listChapters(root);
+  const errors = [];
+  if (chapters.length && !fs.existsSync(paths.plot)) errors.push('plot.md is required when chapters exist');
+
+  let state = null;
+  if (fs.existsSync(paths.state)) {
+    try {
+      state = JSON.parse(fs.readFileSync(paths.state, 'utf8'));
+      if (state.schema !== STORY_STATE_SCHEMA) errors.push(`story-state.json must use ${STORY_STATE_SCHEMA}`);
+    } catch {
+      errors.push('story-state.json must contain valid JSON');
+    }
+  } else if (chapters.length) {
+    errors.push('story-state.json is required when chapters exist');
+  }
+
+  const evidenceKeys = new Set();
+  for (let i = 0; i < chapters.length; i += 1) {
+    const expected = i + 1;
+    const item = chapters[i];
+    if (item.number !== expected) errors.push(`chapter sequence must be contiguous: expected ${expected}, found ${item.number}`);
+    const fm = chapterFrontmatter(fs.readFileSync(item.path, 'utf8'));
+    if (!fm) {
+      errors.push(`${item.file} is missing YAML frontmatter`);
+      continue;
+    }
+    if (fm.schema !== STORY_CHAPTER_SCHEMA) errors.push(`${item.file} must use ${STORY_CHAPTER_SCHEMA}`);
+    if (fm.chapter !== item.number) errors.push(`${item.file} frontmatter chapter must equal ${item.number}`);
+    if (!fm.title) errors.push(`${item.file} requires a title`);
+    if (!fm.evidenceKey || !/^[0-9a-f]{16}$/.test(fm.evidenceKey)) errors.push(`${item.file} requires a 16-hex evidence_key`);
+    else if (evidenceKeys.has(fm.evidenceKey)) errors.push(`${item.file} repeats evidence_key ${fm.evidenceKey}`);
+    else evidenceKeys.add(fm.evidenceKey);
+  }
+
+  if (state) {
+    if (state.lastChapter !== chapters.length) errors.push(`story-state.json lastChapter must equal ${chapters.length}`);
+    const consumed = state.consumedEvidenceKeys ?? [];
+    if (!Array.isArray(consumed) || consumed.some((key) => !/^[0-9a-f]{16}$/.test(key))) {
+      errors.push('story-state.json consumedEvidenceKeys must be an array of 16-hex keys');
+    }
+    for (const key of evidenceKeys) {
+      if (!consumed.includes(key)) errors.push(`story-state.json is missing consumed evidence key ${key}`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    chapters: chapters.length,
+    nextChapter: chapters.length + 1,
+    paths: Object.fromEntries(Object.entries(paths).map(([key, value]) => [key, path.relative(path.resolve(root), value)]))
+  };
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const command = process.argv[2] ?? 'status';
+  const root = path.resolve(process.argv[3] ?? process.cwd());
+  if (!['status', 'validate'].includes(command)) {
+    console.error('usage: story-ledger.mjs [status|validate] [repo-root]');
+    process.exit(2);
+  }
+  const result = validateStoryTree(root);
+  console.log(JSON.stringify(result, null, 2));
+  if (command === 'validate' && !result.ok) process.exit(1);
+}

package/.grok/skills/tutien/scripts/villains.mjs

@@ -60,22 +60,22 @@ export function sanitizeContext(ctx = {}) {
 const LINES = {
   'repeated-failure': {
     serene: [
-      { vi: 'Giữa làn sương mỏng, Luân Hồi Lỗi Ma hiện bóng khi lỗi cũ quay thêm một vòng.', en: 'In the thin mountain mist, the Error-Cycle Wraith appears as the old error completes another circle.' },
-      { vi: 'Một lần thử giống hệt khẽ lay chuông, gọi Luân Hồi Lỗi Ma trở lại đạo lộ.', en: 'One unchanged retry stirs the bell that calls the Error-Cycle Wraith back to the path.' }
+      { vi: 'Giữa làn sương mỏng, Luân Hồi Ma Ảnh hiện bóng khi lỗi cũ quay thêm một vòng.', en: 'In the thin mountain mist, the Error-Cycle Wraith appears as the old error completes another circle.' },
+      { vi: 'Một lần thử giống hệt khẽ lay chuông, gọi Luân Hồi Ma Ảnh trở lại đạo lộ.', en: 'One unchanged retry stirs the bell that calls the Error-Cycle Wraith back to the path.' }
     ],
     spirited: [
-      { vi: 'Luân Hồi Lỗi Ma lại gõ chuông: “Không đổi giả thuyết, sao đổi được kết cục?”', en: 'The Error-Cycle Wraith rings its bell again: “Without a new hypothesis, what new ending could appear?”' },
-      { vi: 'Vòng lặp cũ vừa khép, Luân Hồi Lỗi Ma đã bày sẵn bàn trà chờ vòng kế tiếp.', en: 'The old loop has barely closed, and the Error-Cycle Wraith has already set tea for the next.' }
+      { vi: 'Luân Hồi Ma Ảnh lại gõ chuông: “Không đổi giả thuyết, sao đổi được kết cục?”', en: 'The Error-Cycle Wraith rings its bell again: “Without a new hypothesis, what new ending could appear?”' },
+      { vi: 'Vòng lặp cũ vừa khép, Luân Hồi Ma Ảnh đã bày sẵn bàn trà chờ vòng kế tiếp.', en: 'The old loop has barely closed, and the Error-Cycle Wraith has already set tea for the next.' }
     ]
   },
   'too-many-prompts': {
     serene: [
-      { vi: 'Cửu Hoàn Tâm Ma dệt một task thành nhiều vòng sương khi cột mốc chưa hiện rõ.', en: 'The Ninefold Loop Heart-Shadow weaves one task into rings of mist when its checkpoints remain unclear.' },
-      { vi: 'Nơi ranh giới task nhạt dần, Cửu Hoàn Tâm Ma lặng lẽ nối thêm một vòng.', en: 'Where a task boundary fades, the Ninefold Loop Heart-Shadow quietly adds another circle.' }
+      { vi: 'Cửu Hoàn Tâm Ma dệt một nhiệm vụ thành nhiều vòng sương khi cột mốc chưa hiện rõ.', en: 'The Ninefold Loop Heart-Shadow weaves one task into rings of mist when its checkpoints remain unclear.' },
+      { vi: 'Nơi ranh giới nhiệm vụ nhạt dần, Cửu Hoàn Tâm Ma lặng lẽ nối thêm một vòng.', en: 'Where a task boundary fades, the Ninefold Loop Heart-Shadow quietly adds another circle.' }
     ],
     spirited: [
-      { vi: 'Cửu Hoàn Tâm Ma đếm prompt thay cột mốc; đã đến lúc đổi chiếc vòng kế tiếp thành một tiêu chí “xong”.', en: 'The Ninefold Loop Heart-Shadow is counting prompts instead of checkpoints; turn the next circle into a done-criterion.' },
-      { vi: 'Prompt càng tản như lá thu, Cửu Hoàn Tâm Ma càng dễ giấu mất lối ra.', en: 'The more prompts scatter like autumn leaves, the easier the Ninefold Loop Heart-Shadow hides the exit.' }
+      { vi: 'Cửu Hoàn Tâm Ma đếm lượt yêu cầu thay cột mốc; đã đến lúc đổi chiếc vòng kế tiếp thành một tiêu chí hoàn thành.', en: 'The Ninefold Loop Heart-Shadow is counting prompts instead of checkpoints; turn the next circle into a done-criterion.' },
+      { vi: 'Lượt yêu cầu càng tản như lá thu, Cửu Hoàn Tâm Ma càng dễ giấu mất lối ra.', en: 'The more prompts scatter like autumn leaves, the easier the Ninefold Loop Heart-Shadow hides the exit.' }
     ]
   },
   'conflicting-instructions': {
@@ -90,21 +90,21 @@ const LINES = {
   },
   'unrecovered-failure': {
     serene: [
-      { vi: 'Vô Kiểm Ảnh Quân ẩn sau một thất bại chưa được soi lại bằng lần kiểm chứng mới.', en: 'The Unverified Trial Wraith rests behind a failure that has not yet met a fresh validation.' },
-      { vi: 'Một lỗi bị bỏ lại làm bóng Vô Kiểm Ảnh Quân dài thêm trên bậc đá.', en: 'A failure left behind lengthens the Unverified Trial Wraith’s shadow across the stone steps.' }
+      { vi: 'Vô Nghiệm Ảnh Quân ẩn sau một thất bại chưa được soi lại bằng lần kiểm chứng mới.', en: 'The Unverified Trial Wraith rests behind a failure that has not yet met a fresh validation.' },
+      { vi: 'Một lỗi bị bỏ lại làm bóng Vô Nghiệm Ảnh Quân dài thêm trên bậc đá.', en: 'A failure left behind lengthens the Unverified Trial Wraith’s shadow across the stone steps.' }
     ],
     spirited: [
-      { vi: 'Vô Kiểm Ảnh Quân phủi bụi trên ghế đá: một lần kiểm chứng thành công là đủ để mời nó rời đi.', en: 'The Unverified Trial Wraith dusts its stone seat; one passing validation is enough to send it on its way.' },
-      { vi: 'Chưa có lần chạy lại, Vô Kiểm Ảnh Quân vẫn ung dung giữ chỗ bên cổng hoàn thành.', en: 'Without a rerun, the Unverified Trial Wraith calmly keeps its seat beside the completion gate.' }
+      { vi: 'Vô Nghiệm Ảnh Quân phủi bụi trên ghế đá: một lần kiểm chứng thành công là đủ để mời nó rời đi.', en: 'The Unverified Trial Wraith dusts its stone seat; one passing validation is enough to send it on its way.' },
+      { vi: 'Chưa có lần chạy lại, Vô Nghiệm Ảnh Quân vẫn ung dung giữ chỗ bên cổng hoàn thành.', en: 'Without a rerun, the Unverified Trial Wraith calmly keeps its seat beside the completion gate.' }
     ]
   },
   'work-without-proof': {
     serene: [
       { vi: 'Vô Chứng Đan Ảnh lảng vảng bên lò luyện khi lời tuyên bố hoàn thành chưa có bằng chứng đi cùng.', en: 'The Proofless Elixir Shade lingers by the furnace when a claim of completion carries no evidence.' },
-      { vi: 'Một commit thiếu kết quả kiểm chứng để lại làn khói mỏng cho Vô Chứng Đan Ảnh nương thân.', en: 'A commit without validation leaves a thread of smoke where the Proofless Elixir Shade can dwell.' }
+      { vi: 'Một bản ghi Git thiếu kết quả kiểm chứng để lại làn khói mỏng cho Vô Chứng Đan Ảnh nương thân.', en: 'A commit without validation leaves a thread of smoke where the Proofless Elixir Shade can dwell.' }
     ],
     spirited: [
-      { vi: 'Vô Chứng Đan Ảnh nâng chén trà bên viên đan chưa thử; một dòng validation sẽ làm màn khói tan ngay.', en: 'The Proofless Elixir Shade raises tea beside an untested pill; one validation line will clear the smoke.' },
+      { vi: 'Vô Chứng Đan Ảnh nâng chén trà bên viên đan chưa thử; một dòng kiểm chứng sẽ làm màn khói tan ngay.', en: 'The Proofless Elixir Shade raises tea beside an untested pill; one validation line will clear the smoke.' },
       { vi: 'Không có biên nhận kiểm chứng, Vô Chứng Đan Ảnh cứ ngỡ lò luyện thuộc về mình.', en: 'Without a validation receipt, the Proofless Elixir Shade starts to think the furnace is its own.' }
     ]
   }

package/.vibekit/docs/INSTALL.md

@@ -127,10 +127,11 @@ The installer also includes `visual-design-loop` for Claude, Codex, and Grok sur
 
 ## User-invoked utility skills
 
-Five user-invoked skills install across Claude, Codex, Cursor, and Grok surfaces:
+Six user-invoked skills install across Claude, Codex, Cursor, and Grok surfaces:
 
 - `memento`: write a `MEMENTO.md` working note before closing a multi-day task (`/memento`), then resume from it in the next session (`/memento resume`).
 - `coding-level`: set the explanation register from 0 (ELI5) to 5 (expert peer) with `/coding-level N`; stays active until reinvoked.
 - `prompt-sharpener`: sharpen a rough prompt into a precise one with `/prompt-sharpener <rough prompt>`, then execute the sharpened version immediately in the same turn.
 - `claim`: vet a request to bring something new into the repo with `/claim <request>` — validate URLs and references against official sources, check fit with existing rules and skills, confirm anything unclear, then integrate and document it.
 - `tutien`: turn Git history and explicitly supplied AI-chat exports into a private, funny xianxia "cultivation" report with `/tutien` (realm, token use, workflow habits, evidence-bound suggestions); read-only, aggregate-only by default, and `/tutien off` disables the mode.
+- `mermaid`: generate styled diagrams across 31 Mermaid types, adapt density to `/coding-level`, and optionally visualize multi-step documentation or debugging flows.

package/.vibekit/docs/SECURITY_MODEL.md

@@ -21,9 +21,12 @@ node .vibekit/scripts/agentshield-probe.mjs .
 Full scanner when available:
 
 ```bash
-npx ecc-agentshield scan --path . --format text --min-severity medium
+npx ecc-agentshield@1.4.0 scan --path . --format text --min-severity medium
 ```
 
+If the package is not already installed, request approval before fetching and executing this
+exact version. Otherwise use the repository probe plus the manual review checklist.
+
 ## Findings labels
 
 - `scanner-backed`: comes from AgentShield or deterministic probe output.

package/.vibekit/scripts/init-backbone.mjs

@@ -553,7 +553,7 @@ function detectContext() {
 function render(data) {
   const cmd = data.commands;
   const rules = data.conventions;
-  return `# Minimal Vibe Coding Kit backbone. See .vibekit/docs/BACKBONE_REFERENCE.md for details.\nversion: 2\nmeta:\n  template_status: initialized\n  initialized_at: ${yamlString(data.initializedAt)}\n  template_source: minimal-vibe-coding-kit\n  schema_version: 3\n  init_runbook: .vibekit/init/FIRST_TIME_INIT.md\n  init_done_marker: .vibekit/INIT_DONE\n\nproject:\n  name: ${yamlString(data.name)}\n  description: ${yamlString(data.description)}\n  type: ${data.type}\n  primary_language: ${data.language}\n  package_manager: ${data.packageManager}\n  mode: ${data.mode}\n  prd: ${yamlString(data.prd)}\n  context: ${yamlString(data.context)}\n\npaths:\n  root: .\n  apps:${yamlList(data.appPaths, 4)}\n  source: ${JSON.stringify(data.sourcePaths)}\n  tests: ${JSON.stringify(data.testPaths)}\n  docs: [README.md, .vibekit/docs/]\n  generated: [node_modules/, dist/, build/, coverage/]\n\nconventions:\n  review_required_before_write: true\n  scope: ${yamlString(rules.scope)}\n  naming:\n    files: ${yamlString(rules.naming.files)}\n    directories: ${yamlString(rules.naming.directories)}\n    symbols: follow existing language and framework conventions in nearby code\n    evidence:${yamlList(rules.naming.evidence, 6)}\n  architecture:\n    detected:${yamlList(rules.architecture.detected, 6)}\n    rule: ${yamlString(rules.architecture.rule)}\n  resources:\n    detected_asset_roots:${yamlList(rules.resources.assetRoots, 6)}\n    detected_registries:${yamlList(rules.resources.registries, 6)}\n    rule: ${yamlString(rules.resources.rule)}\n  localization:\n    detected_catalogs:${yamlList(rules.localization.catalogs, 6)}\n    detected_accessors:${yamlList(rules.localization.accessors, 6)}\n    rule: ${yamlString(rules.localization.rule)}\n  custom_rules:\n    - Add team-specific rules here during init review; future agents must follow them.\n\ncommands:\n  install: ${yamlString(cmd.install)}\n  test: ${yamlString(cmd.test)}\n  lint: ${yamlString(cmd.lint)}\n  typecheck: ${yamlString(cmd.typecheck)}\n  build: ${yamlString(cmd.build)}\n  validate: ${yamlString(cmd.validate)}\n\npolicy:\n  default_branch: main\n  branch_naming: "feat/<short-topic>"\n  commit_style: conventional\n  editable_paths: [.]\n  protected_paths:\n    - .git/\n    - .env*\n    - "**/*secret*"\n    - "**/*token*"\n    - "**/migrations/**"\n    - "**/node_modules/**"\n    - "**/dist/**"\n    - "**/build/**"\n    - "**/coverage/**"\n    - "**/*lock*"\n\nagent_surfaces:\n  claude: .claude/\n  cursor: .cursor/\n  codex: .agents/\n  codex_plugin: .codex-plugin/plugin.json\n  shared_skills: .vibekit/skills/\n  shared_commands: .vibekit/commands/\n\nautomation:\n  autoresearch:\n    results_file: results.tsv\n    logs_dir: .autoresearch/logs\n    default_budget: 3\n    default_timeout_seconds: 600\n  daily_enhance:\n    report_dir: .vibekit/reports\n    write_mode: propose_only\n  finalize:\n    cleanup_dir: _vibekit-cleanup\n    marker: .vibekit/FINALIZE_DONE\n    one_time_files: [.vibekit/init/FIRST_TIME_INIT.md, .vibekit/init/FIRST_PROMPT.md, .vibekit/init/PUSH_TO_GITHUB.md, .vibekit/init/CLAUDE-template.md]\n  security:\n    probe: node .vibekit/scripts/agentshield-probe.mjs .\n    scan: npx ecc-agentshield scan --path . --format text --min-severity medium\n`;
+  return `# Minimal Vibe Coding Kit backbone. See .vibekit/docs/BACKBONE_REFERENCE.md for details.\nversion: 2\nmeta:\n  template_status: initialized\n  initialized_at: ${yamlString(data.initializedAt)}\n  template_source: minimal-vibe-coding-kit\n  schema_version: 3\n  init_runbook: .vibekit/init/FIRST_TIME_INIT.md\n  init_done_marker: .vibekit/INIT_DONE\n\nproject:\n  name: ${yamlString(data.name)}\n  description: ${yamlString(data.description)}\n  type: ${data.type}\n  primary_language: ${data.language}\n  package_manager: ${data.packageManager}\n  mode: ${data.mode}\n  prd: ${yamlString(data.prd)}\n  context: ${yamlString(data.context)}\n\npaths:\n  root: .\n  apps:${yamlList(data.appPaths, 4)}\n  source: ${JSON.stringify(data.sourcePaths)}\n  tests: ${JSON.stringify(data.testPaths)}\n  docs: [README.md, .vibekit/docs/]\n  generated: [node_modules/, dist/, build/, coverage/]\n\nconventions:\n  review_required_before_write: true\n  scope: ${yamlString(rules.scope)}\n  naming:\n    files: ${yamlString(rules.naming.files)}\n    directories: ${yamlString(rules.naming.directories)}\n    symbols: follow existing language and framework conventions in nearby code\n    evidence:${yamlList(rules.naming.evidence, 6)}\n  architecture:\n    detected:${yamlList(rules.architecture.detected, 6)}\n    rule: ${yamlString(rules.architecture.rule)}\n  resources:\n    detected_asset_roots:${yamlList(rules.resources.assetRoots, 6)}\n    detected_registries:${yamlList(rules.resources.registries, 6)}\n    rule: ${yamlString(rules.resources.rule)}\n  localization:\n    detected_catalogs:${yamlList(rules.localization.catalogs, 6)}\n    detected_accessors:${yamlList(rules.localization.accessors, 6)}\n    rule: ${yamlString(rules.localization.rule)}\n  custom_rules:\n    - Add team-specific rules here during init review; future agents must follow them.\n\ncommands:\n  install: ${yamlString(cmd.install)}\n  test: ${yamlString(cmd.test)}\n  lint: ${yamlString(cmd.lint)}\n  typecheck: ${yamlString(cmd.typecheck)}\n  build: ${yamlString(cmd.build)}\n  validate: ${yamlString(cmd.validate)}\n\npolicy:\n  default_branch: main\n  branch_naming: "feat/<short-topic>"\n  commit_style: conventional\n  editable_paths: [.]\n  protected_paths:\n    - .git/\n    - .env*\n    - "**/*secret*"\n    - "**/*token*"\n    - "**/migrations/**"\n    - "**/node_modules/**"\n    - "**/dist/**"\n    - "**/build/**"\n    - "**/coverage/**"\n    - "**/*lock*"\n\nagent_surfaces:\n  claude: .claude/\n  cursor: .cursor/\n  codex: .agents/\n  codex_plugin: .codex-plugin/plugin.json\n  shared_skills: .vibekit/skills/\n  shared_commands: .vibekit/commands/\n\nautomation:\n  autoresearch:\n    results_file: results.tsv\n    logs_dir: .autoresearch/logs\n    default_budget: 3\n    default_timeout_seconds: 600\n  daily_enhance:\n    report_dir: .vibekit/reports\n    write_mode: propose_only\n  finalize:\n    cleanup_dir: _vibekit-cleanup\n    marker: .vibekit/FINALIZE_DONE\n    one_time_files: [.vibekit/init/FIRST_TIME_INIT.md, .vibekit/init/FIRST_PROMPT.md, .vibekit/init/PUSH_TO_GITHUB.md, .vibekit/init/CLAUDE-template.md]\n  security:\n    probe: node .vibekit/scripts/agentshield-probe.mjs .\n    scan: npx ecc-agentshield@1.4.0 scan --path . --format text --min-severity medium\n`;
 }
 
 function inferPaths(files) {

package/.vibekit/scripts/validate-kit.mjs

@@ -32,6 +32,41 @@ function listFiles(rel) {
   try { inner(base); } catch {}
   return out.sort();
 }
+function markdownTargets(text) {
+  const withoutCode = text
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/~~~[\s\S]*?~~~/g, '')
+    .replace(/`[^`\n]*`/g, '');
+  return [...withoutCode.matchAll(/!?\[[^\]\n]*\]\(([^)\n]+)\)/g)].map((match) => match[1].trim());
+}
+function markdownPathPart(rawTarget) {
+  const target = rawTarget.startsWith('<')
+    ? rawTarget.slice(1, rawTarget.indexOf('>'))
+    : rawTarget.split(/\s+["']/)[0];
+  return target.split(/[?#]/, 1)[0];
+}
+function validateCanonicalSkillLinks() {
+  const base = '.vibekit/skills';
+  let checked = 0;
+  let broken = 0;
+  for (const file of listFiles(base).filter((entry) => entry.endsWith('.md'))) {
+    const rel = `${base}/${file}`;
+    for (const rawTarget of markdownTargets(read(rel))) {
+      const target = markdownPathPart(rawTarget);
+      if (!target || target.startsWith('#') || target.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(target)) continue;
+      checked += 1;
+      let decoded = target;
+      try { decoded = decodeURIComponent(target); } catch {}
+      const resolved = target.startsWith('/')
+        ? path.join(root, target)
+        : path.resolve(path.dirname(path.join(root, rel)), decoded);
+      if (fs.existsSync(resolved)) continue;
+      broken += 1;
+      fail(`broken local Markdown link ${rel} -> ${rawTarget}`);
+    }
+  }
+  if (broken === 0) ok(`canonical skill Markdown links resolve (${checked} local targets)`);
+}
 
 // Surface presence: end-user repos may install only some profiles, so
 // per-surface files are required only when that surface is installed.
@@ -109,6 +144,7 @@ const reasoningSkillResources = {
     'references/output-schema.md',
     'references/parameters.md',
     'references/patterns.md',
+    'references/advanced-techniques.md',
     'examples/linear-reasoning.md',
     'examples/revision-pattern.md',
     'examples/branching-exploration.md',
@@ -119,6 +155,17 @@ const reasoningSkillResources = {
   ],
   'path-sensitive-shell-safety': [
     'references/workflow.md'
+  ],
+  'mermaid': [
+    'UPSTREAM-NOTICE.md',
+    'references/kit-examples.md',
+    'references/preview.html',
+    'references/styling-preset.md',
+    'references/coding-level-charts.md',
+    'references/debug-heatmap.md',
+    'references/flowchart.md',
+    'references/sequenceDiagram.md',
+    'references/config-theming.md'
   ]
 };
 
@@ -134,6 +181,7 @@ for (const surface of reasoningSurfaceDirs) {
 }
 
 for (const rel of required) exists(rel) ? ok(`required file ${rel}`) : fail(`missing required file ${rel}`);
+validateCanonicalSkillLinks();
 if (exists('README.md')) ok('optional README.md present');
 else console.log('INFO optional README.md not present in target project');
 
@@ -150,6 +198,9 @@ requireText('.github/workflows/vibekit-validate.yml', 'npm run pack:dry-run', 'C
 requireText('.vibekit/docs/AUTORESEARCH_LEDGER.md', 'node .vibekit/scripts/validate-kit.mjs .', 'autoresearch ledger documents validation command');
 requireText('.cursor/rules/020-security-agentshield.mdc', 'node .vibekit/scripts/agentshield-probe.mjs .', 'Cursor security rule uses Node AgentShield probe wrapper');
 requireText('.vibekit/scripts/doctor.mjs', '.vibekit/scripts/agentshield-probe.mjs', 'doctor uses Node AgentShield probe wrapper');
+requireText('.vibekit/skills/agentshield-security-review/SKILL.md', 'ecc-agentshield@1.4.0', 'AgentShield workflow pins the reviewed scanner version');
+requireText('.vibekit/skills/agentshield-security-review/SKILL.md', 'npm ls ecc-agentshield --depth=0 --ignore-scripts', 'AgentShield workflow checks for a local scanner without lifecycle scripts');
+requireText('.vibekit/scripts/init-backbone.mjs', 'npx ecc-agentshield@1.4.0 scan', 'generated backbone pins the AgentShield scanner version');
 
 if (exists('.vibekit/docs/AUTORESEARCH_LEDGER.md')) {
   const ledgerText = read('.vibekit/docs/AUTORESEARCH_LEDGER.md');
@@ -213,6 +264,119 @@ for (const [skill, mirrors] of Object.entries(skillMirrors)) {
   }
 }
 
+function validateSequentialThinkingContract() {
+  const base = '.vibekit/skills/sequential-thinking';
+  if (!exists(`${base}/SKILL.md`)) return;
+  const skill = read(`${base}/SKILL.md`);
+  const markdown = listFiles(base)
+    .filter((file) => file.endsWith('.md'))
+    .map((file) => read(`${base}/${file}`))
+    .join('\n');
+
+  const markers = ['REVISION', 'BRANCH', 'HYPOTHESIS', 'VERIFICATION', 'CONVERGENCE', 'META', 'FINAL'];
+  const missingMarkers = markers.filter((marker) => !skill.includes(`[${marker}`));
+  missingMarkers.length
+    ? fail(`sequential-thinking marker allowlist missing: ${missingMarkers.join(', ')}`)
+    : ok(`sequential-thinking closed marker allowlist (${markers.length} markers)`);
+
+  if (skill.includes('Keep private chain-of-thought private.')
+      && skill.includes('Complexity alone does not authorize more detailed reasoning.')
+      && skill.includes('Implicit (default)')) {
+    ok('sequential-thinking uses public checkpoints with explicit-only visible reasoning');
+  } else {
+    fail('sequential-thinking public-checkpoint or explicit-mode contract drifted');
+  }
+
+  const banned = ['thoughtContent', 'recentThoughts', 'sessionContext', 'remainingThoughts', 'Unlike MCP', 'Zod Layer', 'Response Prefix', 'PREFIX_LABEL'];
+  const leaked = banned.filter((term) => markdown.includes(term));
+  leaked.length
+    ? fail(`sequential-thinking contains rejected pseudo-runtime/plugin terms: ${leaked.join(', ')}`)
+    : ok('sequential-thinking rejects pseudo-runtime and foreign-plugin contracts');
+
+  const jsonBlocks = [];
+  for (const pattern of [/```json\s*\n([\s\S]*?)\n```/g, /~~~json\s*\n([\s\S]*?)\n~~~/g]) {
+    let match;
+    while ((match = pattern.exec(markdown))) jsonBlocks.push(match[1]);
+  }
+  let invalidJson = 0;
+  for (const block of jsonBlocks) {
+    try { JSON.parse(block); } catch { invalidJson += 1; }
+  }
+  if (jsonBlocks.length > 0 && invalidJson === 0) ok(`sequential-thinking JSON examples parse (${jsonBlocks.length} blocks)`);
+  else fail(`sequential-thinking JSON examples invalid or missing (${invalidJson} invalid, ${jsonBlocks.length} total)`);
+}
+
+function validateMermaidContract() {
+  const base = '.vibekit/skills/mermaid';
+  if (!exists(`${base}/SKILL.md`)) return;
+  const skill = read(`${base}/SKILL.md`);
+  const examples = read(`${base}/references/kit-examples.md`);
+  const preview = read(`${base}/references/preview.html`);
+  const notice = read(`${base}/UPSTREAM-NOTICE.md`);
+  const debug = read(`${base}/references/debug-heatmap.md`);
+  const styling = read(`${base}/references/styling-preset.md`);
+  const imported = listFiles(`${base}/references`)
+    .filter((file) => file.endsWith('.md'))
+    .map((file) => read(`${base}/references/${file}`))
+    .join('\n');
+
+  const diagrams = [...examples.matchAll(/```mermaid\s*\n([\s\S]*?)\n```/g)].map((match) => match[1]);
+  const distinctCases = ['Safe configuration promotion', 'Repository safety evolution', 'Localization release board', 'Validation feedback time', 'Duplicate webhook investigation'];
+  if (diagrams.length === 5
+      && diagrams.every((diagram) => diagram.includes('securityLevel: strict'))
+      && distinctCases.every((name) => examples.toLowerCase().includes(name.toLowerCase()))) {
+    ok('Mermaid maintains five strict kit-native examples');
+  } else {
+    fail('Mermaid kit-native example set, strict security, or distinct cases drifted');
+  }
+
+  if (preview.includes('mermaid@11.16.0/dist/mermaid.esm.min.mjs')
+      && preview.includes('mermaid-zenuml@0.2.2/dist/mermaid-zenuml.esm.min.mjs')
+      && preview.includes("securityLevel: 'strict'")
+      && skill.includes('isolated profile with no secrets or user data')) {
+    ok('Mermaid executable preview is pinned, strict, and isolated by policy');
+  } else {
+    fail('Mermaid executable preview pin, strict mode, or isolation warning drifted');
+  }
+
+  if (notice.includes('Copyright (c) 2014 - 2022 Knut Sveidqvist')
+      && notice.includes('The MIT License (MIT)')
+      && notice.includes('unavailable')) {
+    ok('Mermaid upstream ownership, MIT license, and version boundary are preserved');
+  } else {
+    fail('Mermaid upstream notice or preserved license is incomplete');
+  }
+
+  const staleTokens = ['MERMAID_RELEASE_VERSION', '/blob/develop/', 'Please edit the corresponding file', 'THIS IS AN AUTOGENERATED FILE'];
+  const stale = staleTokens.filter((token) => imported.includes(token));
+  stale.length
+    ? fail(`Mermaid imported references contain stale or operational tokens: ${stale.join(', ')}`)
+    : ok('Mermaid references remove development placeholders and imported operational directives');
+
+  const unavailableCount = (imported.match(/unreleased upstream; unavailable in Mermaid 11\.16\.0/g) || []).length;
+  unavailableCount === 3
+    ? ok('Mermaid marks three development-only syntaxes unavailable for 11.16.0')
+    : fail(`Mermaid expected 3 development-only boundary warnings, found ${unavailableCount}`);
+
+  if (styling.includes('first Kanban column to `section-1`')
+      && styling.includes('maps `section-1` to `cScale2`')
+      && examples.includes('cScale2: "#339AF0"')
+      && examples.includes('cScale5: "#9775FA"')) {
+    ok('Mermaid 11.16 Kanban compatibility mapping is documented and exercised');
+  } else {
+    fail('Mermaid 11.16 Kanban compatibility mapping drifted');
+  }
+
+  if (debug.includes('fill:#FA5252,stroke:#444444,stroke-width:2px,color:#111111')) {
+    ok('Mermaid debug heat map uses accessible ink on strong red');
+  } else {
+    fail('Mermaid debug heat-map strong-red text contrast drifted');
+  }
+}
+
+validateSequentialThinkingContract();
+validateMermaidContract();
+
 function parseFrontmatter(text) {
   const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!match) return null;
@@ -328,7 +492,7 @@ for (const [rel, settings] of [['.claude/settings.json', claudeSettings], ['.cur
   piped.length === 0
     ? ok(`${rel} deny rules avoid pipe-spanning patterns (subcommands are matched independently)`)
     : fail(`${rel} deny rules span a pipe and never match: ${piped.join(', ')}`);
-  const yesFirst = deny.some((rule) => rule.startsWith('Bash(npx --yes') || rule.startsWith('Bash(npx -y'));
+  const yesFirst = deny.some((rule) => rule.startsWith('Bash(npx --yes') || rule.startsWith('Bash(npx ' + '-y'));
   yesFirst
     ? ok(`${rel} denies leading npx --yes/-y forms`)
     : fail(`${rel} missing deny for leading npx --yes/-y forms`);
@@ -491,14 +655,26 @@ function walk(item) {
   return out;
 }
 
-for (const file of scanDirs.flatMap(walk)) {
-  if (!/\.(md|mdc|json|toml|yml|yaml|js|mjs|py|sh)$/i.test(file)) continue;
+const agentSurfaceFiles = scanDirs.flatMap(walk);
+for (const file of agentSurfaceFiles) {
+  if (!/\.(md|mdc|json|toml|yml|yaml|js|mjs|cjs|ts|tsx|py|sh|ps1|html|htm)$/i.test(file)) continue;
   const text = fs.readFileSync(file, 'utf8');
   for (const r of riskyPatterns) {
     if (text.includes(r.pattern)) warn(`${path.relative(root, file)} contains ${r.message}`);
   }
 }
 
+const unpinnedScanner = 'npx' + ' ecc-agentshield ';
+const unpinnedScannerFiles = agentSurfaceFiles
+  .filter((file) => /\.(md|mdc|json|toml|yml|yaml|js|mjs|py|sh|ps1|html)$/i.test(file))
+  .filter((file) => fs.readFileSync(file, 'utf8').includes(unpinnedScanner));
+unpinnedScannerFiles.length === 0
+  ? ok('agent surfaces avoid unpinned ecc-agentshield npx execution')
+  : fail(`agent surfaces contain unpinned ecc-agentshield npx execution: ${unpinnedScannerFiles.map((file) => path.relative(root, file)).join(', ')}`);
+
+requireText('.vibekit/skills/agentshield-security-review/scripts/agentshield_repo_probe.py', '".html"', 'AgentShield probe scans executable HTML surfaces');
+requireText('.vibekit/skills/agentshield-security-review/scripts/agentshield_repo_probe.py', '"npx" + " ecc-agentshield "', 'AgentShield probe flags unpinned scanner execution');
+
 const probe = path.join(root, '.vibekit/scripts/agentshield-probe.mjs');
 if (fs.existsSync(probe)) {
   const result = spawnSync(process.execPath, [probe, root, '--json'], { encoding: 'utf8' });

package/.vibekit/skills/agentshield-security-review/SKILL.md

@@ -15,20 +15,27 @@ Do not invent findings. Prefer deterministic scanner output when available, then
 
 1. Identify the repo root and active harness surfaces.
 2. Run `node .vibekit/scripts/agentshield-probe.mjs .` to inventory Claude, Codex, shared skills, hooks, MCP, commands, and repo instruction files.
-3. If Node/npm is available, run AgentShield from the repo root:
+3. Check whether the scanner is already installed locally:
    ```bash
-   npx ecc-agentshield scan --path . --format text
+   npm ls ecc-agentshield --depth=0 --ignore-scripts
    ```
-4. If JSON is needed for CI or automation, run:
+   If it is unavailable, use the fallback manual review by default. Fetching and executing a
+   package is a separate trust decision; request approval before using the exact reviewed version.
+4. With a local install or explicit approval, run the version-pinned scanner from the repo root:
    ```bash
-   npx ecc-agentshield scan --path . --format json
+   npx ecc-agentshield@1.4.0 scan --path . --format text
    ```
-5. If safe auto-fixes are requested, first summarize the proposed edits, then run:
+5. If JSON is needed for CI or automation, run:
    ```bash
-   npx ecc-agentshield scan --path . --fix
+   npx ecc-agentshield@1.4.0 scan --path . --format json
    ```
-6. Re-run the scan after fixes and report before/after score, severity counts, and changed files.
-7. If AgentShield is unavailable, perform the fallback manual review in `references/review-checklist.md`.
+6. If safe auto-fixes are requested, first summarize the proposed edits, then run:
+   ```bash
+   npx ecc-agentshield@1.4.0 scan --path . --fix
+   ```
+7. Re-run the scan after fixes and report before/after score, severity counts, and changed files.
+8. If AgentShield is unavailable or package execution is not approved, perform the fallback
+   manual review in `references/review-checklist.md`.
 
 ## Harness-native layout
 
@@ -71,5 +78,6 @@ Use `references/report-template.md` for the preferred report format.
 
 - Never print full secrets. Show only the file path and key name or a redacted prefix/suffix.
 - Do not run untrusted hook scripts, MCP server commands, package scripts, or installer scripts just to inspect them.
+- Do not replace the pinned `ecc-agentshield@1.4.0` command with an unpinned `npx` invocation.
 - Do not apply `--fix` without first stating the planned edit types.
 - Treat wildcard shell permissions, unpinned `npx`, shell-running MCP servers, prompt-injection instructions, and silent hook failures as high-risk until proven otherwise.