@haposoft/cafekit 0.8.10 → 0.8.12

package/README.md

@@ -2,7 +2,7 @@
 
 > Claude Code-first spec-driven workflow and runtime bundle for AI coding assistants.
 
-[![Version](https://img.shields.io/badge/version-0.8.10-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.8.11-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Primary-orange.svg)](https://claude.ai/code)
 
@@ -46,6 +46,7 @@ Claude Code install targets:
 
 ```text
 .claude/
+├── .gitignore
 ├── skills/
 ├── agents/
 ├── hooks/

package/bin/install.js

@@ -751,7 +751,8 @@ function copyClaudeRuntimeFiles(platformKey, results, options = {}) {
 
   manifest.runtime.files.forEach(relPath => {
     const srcPath = path.join(srcBase, relPath);
-    const targetPath = path.join(targetBase, relPath);
+    const targetRelPath = relPath === 'gitignore' ? '.gitignore' : relPath;
+    const targetPath = path.join(targetBase, targetRelPath);
 
     if (!fs.existsSync(srcPath)) {
       console.log(`  ⚠ Runtime file not found: ${relPath}`);
@@ -767,10 +768,10 @@ function copyClaudeRuntimeFiles(platformKey, results, options = {}) {
       fs.copyFileSync(srcPath, targetPath);
 
       if (targetExists) {
-        console.log(`  ↻ Runtime updated: ${relPath}`);
+        console.log(`  ↻ Runtime updated: ${targetRelPath}`);
         results.updated++;
       } else {
-        console.log(`  ✓ Runtime installed: ${relPath}`);
+        console.log(`  ✓ Runtime installed: ${targetRelPath}`);
         results.copied++;
       }
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/gitignore

@@ -7,10 +7,12 @@
 skills/.venv/
 .venv/
 venv/
+skills/**/node_modules/
 __pycache__/
 *.pyc
 
-# System generated or logs
+# System generated state, caches, and logs
+session-state/
 hooks/.logs/
 agent-memory/
 settings.bak.json

package/src/claude/hooks/lib/config.cjs

@@ -65,6 +65,7 @@ const DEFAULT_CONFIG = {
     'session-init': true,
     'subagent-init': true,
     'dev-rules-reminder': true,
+    'skill-router': true,
     'usage': true,
     'context-tracking': true,
     'scout-block': true,

package/src/claude/hooks/lib/skill-router-routes.cjs

@@ -0,0 +1,190 @@
+const MIN_SCORE = 4;
+const WEIGHTS = { strong: 6, medium: 3, weak: 1, negative: -5 };
+
+const ROUTES = [
+  route('hapo:hotfix', 'urgent fix or production regression', 100, {
+    strong: ['hotfix', 'fix bug', 'fix lỗi', 'fix loi', 'sửa lỗi', 'sua loi', 'production bug', 'prod bug', 'regression', 'lỗi production', 'loi production', 'sửa gấp', 'sua gap', 'バグ修正', '不具合修正', '本番障害', '本番バグ', '緊急修正', '至急修正', 'リグレッション'],
+    medium: ['khẩn cấp', 'khan cap', 'production', 'critical bug', 'rollback', '修正して', '直して', '緊急', '本番', '重大バグ', 'ロールバック', '障害対応'],
+    weak: ['fix', 'fixing', 'sửa', 'sua', 'urgent', 'emergency', 'release is broken', '修正', '直す', '至急', 'リリースが壊れた'],
+    negative: ['slide', 'pptx', 'spec', 'brainstorm'],
+  }),
+  route('hapo:debug', 'bug investigation or failure diagnosis', 90, {
+    strong: ['debug', 'root cause', 'diagnose', 'stack trace', 'không chạy', 'khong chay', 'デバッグ', '原因調査', '根本原因', 'スタックトレース', '動かない'],
+    medium: ['bug', 'error', 'exception', 'failing', 'failed', 'failure', 'broken', 'lỗi', 'loi', 'tại sao', 'tai sao', 'vì sao', 'vi sao', 'nguyên nhân', 'nguyen nhan', 'ci fail', 'build fail', 'バグ', 'エラー', '例外', '失敗', '壊れている', 'なぜ', '原因', 'ci失敗', 'ビルド失敗'],
+    weak: ['sai', 'fail', 'issue', 'problem', '問題', '不具合'],
+    negative: ['commit', 'push', 'slide', 'pptx'],
+  }),
+  route('hapo:specs', 'specification, requirements, design, tasks, or spec validation', 80, {
+    strong: ['spec', 'specs', 'requirements', 'acceptance criteria', 'task breakdown', 'đặc tả', 'dac ta', '仕様', '仕様書', '要件', '受け入れ条件', 'タスク分解', '仕様を作って', '仕様を作成'],
+    medium: ['requirement', 'ears', 'design doc', 'scope', '--validate', 'yêu cầu', 'yeu cau', 'phạm vi', 'pham vi', 'validate spec', 'kiểm tra spec', 'kiem tra spec', '要求', '設計書', 'スコープ', '検証', '仕様を確認'],
+    weak: ['tính năng mới', 'tinh nang moi', 'feature idea', 'user story', 'criteria', 'task list', '新機能', 'ユーザーストーリー', '基準', 'タスクリスト'],
+    negative: ['commit', 'push', 'bug', 'error', 'production', 'pptx', 'pdf'],
+  }),
+  route('hapo:develop', 'implementation from an approved spec or task list', 75, {
+    strong: ['develop', 'implement', 'implementation', 'theo spec', 'theo specs', 'approved spec', 'làm theo spec', 'lam theo spec', '実装', '開発', '仕様に沿って', '仕様どおり', '承認済み仕様'],
+    medium: ['build this', 'code this', 'start task', 'run task', 'thực hiện task', 'thuc hien task', 'phát triển', 'phat trien', 'bắt đầu implement', 'bat dau implement', 'vào code', 'vao code', '作って', 'コードを書いて', 'タスクを開始', 'タスクを実行', '開発して', '実装して'],
+    weak: ['triển khai', 'trien khai', 'đưa vào code', 'dua vao code', 'code feature', 'コード化', '機能を作る'],
+    negative: ['bug', 'debug', 'review', 'test only', 'commit'],
+  }),
+  route('hapo:test', 'test, verification, QA, or runtime validation', 70, {
+    strong: ['unit test', 'integration test', 'e2e', 'playwright', 'coverage', 'kiểm thử', 'kiem thu', '単体テスト', '結合テスト', 'カバレッジ', 'テストして'],
+    medium: ['test', 'tests', 'testing', 'qa', 'verify', 'verification', 'kiểm tra chạy', 'kiem tra chay', 'xác minh', 'xac minh', 'テスト', '検証', '確認', '動作確認'],
+    weak: ['assert', 'runtime proof', 'manual qa', 'end to end', 'smoke test', 'アサート', 'スモークテスト'],
+    negative: ['spec', 'requirements', 'commit', 'push'],
+  }),
+  route('hapo:code-review', 'code review, audit, security, or quality assessment', 68, {
+    strong: ['code review', 'security review', 'performance review', 'đánh giá code', 'danh gia code', 'コードレビュー', 'セキュリティレビュー', '性能レビュー'],
+    medium: ['review', 'audit', 'quality', 'đánh giá', 'danh gia', 'kiểm tra chất lượng', 'kiem tra chat luong', 'レビュー', '監査', '品質', '品質確認'],
+    weak: ['risk', 'maintainability', 'readability', 'vulnerability', 'lỗ hổng', 'lo hong', 'リスク', '保守性', '可読性', '脆弱性'],
+    negative: ['slide', 'pptx', 'commit and push'],
+  }),
+  route('hapo:git', 'git, commit, push, branch, tag, or pull request workflow', 65, {
+    strong: ['commit', 'push', 'pull request', 'git', 'đẩy lên', 'day len', 'コミット', 'プッシュ', 'プルリク', 'リリースして'],
+    medium: ['pr ', 'branch', 'tag', 'release', 'publish', 'merge', 'rebase', 'ブランチ', 'タグ', 'リリース', '公開', 'マージ', 'リベース'],
+    weak: ['origin', 'remote', 'checkout', 'stash', 'version bump', 'リモート', 'チェックアウト', 'スタッシュ', 'バージョン更新'],
+    negative: ['deploy', 'test', 'review only'],
+  }),
+  route('hapo:inspect', 'codebase discovery, file search, structure scan, or locating implementation areas', 64, {
+    strong: ['inspect', 'codebase scan', 'scan codebase', 'scan source', 'file discovery', 'find files', 'locate files', 'xem source', 'xem codebase', 'quét source', 'quet source', 'quét codebase', 'quet codebase', 'kiểm tra cấu trúc', 'kiem tra cau truc', 'コード構造', 'ソース確認', 'コードベース確認', 'ファイル探索', '構造を確認'],
+    medium: ['search files', 'find where', 'where is', 'project structure', 'code structure', 'repo structure', 'tìm file', 'tim file', 'tìm trong source', 'tim trong source', 'cấu trúc project', 'cau truc project', 'ở đâu', 'o dau', '関連ファイル', 'どこにある', 'プロジェクト構造', 'リポジトリ構造', '探して'],
+    weak: ['scan', 'inspect code', 'explore code', 'xem qua', 'xem giúp', '調べて', '確認して'],
+    negative: ['bug', 'error', 'lỗi', 'loi', 'fail', 'failure', 'production', 'hotfix', 'fix', 'sửa', 'sua', 'debug', 'develop', 'implement', 'test', 'commit', 'push', 'slide', 'pptx'],
+  }),
+  route('hapo:impact-analysis', 'impact analysis before changing existing behavior', 64, {
+    strong: ['impact analysis', 'blast radius', 'ảnh hưởng', 'anh huong', 'tác động', 'tac dong', '影響分析', '影響範囲', '影響', '副作用'],
+    medium: ['impact', 'liên quan những đâu', 'lien quan nhung dau', 'affected files', 'dependency impact', '関連箇所', '影響ファイル', '依存関係'],
+    weak: ['before changing', 'risk area', 'downstream', 'upstream', 'side effect', '変更前', 'リスク範囲', '下流', '上流'],
+    negative: ['slide', 'pptx'],
+  }),
+  route('hapo:frontend-design', 'UI/UX design, visual style, layout, or color system', 62, {
+    strong: ['ui design', 'visual style', 'color system', 'thiết kế giao diện', 'thiet ke giao dien', 'màu sắc', 'mau sac', 'uiデザイン', '画面デザイン', 'ビジュアルスタイル', '配色'],
+    medium: ['ux', 'layout', 'style', 'theme', 'responsive design', 'giao diện', 'giao dien', 'wireframe', 'レイアウト', 'スタイル', 'テーマ', 'レスポンシブデザイン', '画面', 'ワイヤーフレーム', '色'],
+    weak: ['palette', 'typography', 'spacing', 'polish ui', 'mockup', 'prototype', 'パレット', 'タイポグラフィ', '余白', 'モックアップ', 'プロトタイプ'],
+    negative: ['backend', 'api', 'database'],
+  }),
+  route('hapo:react-best-practices', 'React and Next.js performance patterns, rerender optimization, and Vercel best practices', 60, {
+    strong: ['react best practices', 'next.js best practices', 'vercel react best practices', 'react performance', 'next.js performance', 'optimize react', 'optimize next.js', 'tối ưu react', 'toi uu react', 'tối ưu next.js', 'toi uu next.js', 'reactベストプラクティス', 'next.jsベストプラクティス', 'react最適化', 'next.js最適化', 'react性能'],
+    medium: ['bundle optimization', 'bundle size', 'rerender optimization', 're-render optimization', 'data fetching', 'server component', 'client component', 'suspense', 'hydration', 'waterfall', 'usememo', 'usecallback', 'react cache', 'tối ưu rerender', 'toi uu rerender', 'tối ưu bundle', 'toi uu bundle', 'バンドル最適化', '再レンダー最適化', 'データ取得', 'サーバーコンポーネント', 'クライアントコンポーネント', 'ハイドレーション'],
+    weak: ['react', 'next.js', 'memo', 'rerender', 're-render', 'render performance', 'component performance', 'waterfalls', 'lazy state', 'dynamic import', 'react pattern', 'next.js pattern', 'レンダー性能', 'コンポーネント性能', '動的インポート'],
+    negative: ['backend', 'api', 'database', 'slide', 'pptx', 'commit', 'push'],
+  }),
+  route('hapo:frontend-development', 'frontend implementation work', 58, {
+    strong: ['react', 'next.js', 'vite', 'frontend', 'tailwind', 'web app', 'フロントエンド', 'webアプリ'],
+    medium: ['component', 'css', 'html', 'browser ui', 'client side', 'giao diện react', 'コンポーネント', 'ブラウザui', 'クライアント側', 'react画面'],
+    weak: ['state management', 'hook', 'form', 'table', 'dashboard ui', '状態管理', 'フック', 'フォーム', 'テーブル', 'ダッシュボードui'],
+    negative: ['best practices', 'performance', 'optimize', 'optimization', 'rerender', 're-render', 'tối ưu', 'toi uu', '再レンダー', '最適化', '性能', 'backend only', 'database only', 'slide', 'pptx'],
+  }),
+  route('hapo:backend-development', 'backend, API, database, or service implementation', 58, {
+    strong: ['backend', 'api', 'database', 'endpoint', 'server', 'service', 'バックエンド', 'データベース', 'エンドポイント', 'サーバー', 'サービス'],
+    medium: ['db', 'sql', 'postgres', 'mysql', 'migration', 'schema', 'worker', 'queue', 'マイグレーション', 'スキーマ', 'ワーカー', 'キュー'],
+    weak: ['controller', 'route handler', 'repository', 'model', 'auth service', 'コントローラ', 'ルートハンドラ', 'リポジトリ', 'モデル', '認証サービス'],
+    negative: ['frontend only', 'slide', 'pptx'],
+  }),
+  route('hapo:mobile-development', 'mobile app implementation', 56, {
+    strong: ['mobile', 'ios', 'android', 'react native', 'flutter', 'モバイル'],
+    medium: ['app store', 'play store', 'native app', 'mobile screen', 'アプリストア', 'playストア', 'ネイティブアプリ', 'モバイル画面'],
+    weak: ['gesture', 'push notification', 'offline sync', 'ジェスチャー', 'プッシュ通知', 'オフライン同期'],
+    negative: ['web only', 'desktop only'],
+  }),
+  route('hapo:devops', 'deployment, infrastructure, CI/CD, or operations work', 54, {
+    strong: ['deploy', 'deployment', 'docker', 'kubernetes', 'ci/cd', 'github actions', 'デプロイ', 'デプロイメント'],
+    medium: ['vercel', 'infra', 'infrastructure', 'devops', 'pipeline', 'environment variable', 'インフラ', 'パイプライン', '環境変数'],
+    weak: ['build server', 'container', 'helm', 'terraform', 'monitoring', 'ビルドサーバー', 'コンテナ', '監視'],
+    negative: ['slide', 'pptx', 'spec only'],
+  }),
+  route('hapo:generate-graph', 'diagram, graph, architecture map, or flow visualization', 52, {
+    strong: ['diagram', 'graph', 'mermaid', 'flowchart', 'architecture diagram', 'sơ đồ', 'so do', '図', '図解', 'ダイアグラム', 'グラフ', 'フローチャート', '構成図'],
+    medium: ['biểu đồ', 'bieu do', 'visualize', 'sequence diagram', 'data flow', '可視化', 'シーケンス図', 'データフロー'],
+    weak: ['mind map', 'dependency map', 'system map', 'マインドマップ', '依存関係図', 'システム図'],
+    negative: ['pptx', 'slide deck'],
+  }),
+  route('hapo:brainstorm', 'early ideation or unclear solution direction', 50, {
+    strong: ['brainstorm', 'ý tưởng', 'y tuong', 'phương án', 'phuong an', 'gợi ý', 'goi y', 'ブレスト', 'アイデア', '案', '提案して', '相談'],
+    medium: ['idea', 'ideas', 'approach', 'options', 'tradeoff', 'chủ đề', 'chu de', 'cần làm gì', 'can lam gi', 'アプローチ', '選択肢', 'トレードオフ', 'テーマ', '何をすれば'],
+    weak: ['proposal', 'strategy', 'plan options', 'explore', 'direction', 'seminar topic', '提案', '戦略', '方向性', '検討'],
+    negative: ['commit', 'push', 'bug', 'error'],
+  }),
+  route('hapo:research', 'technical research or best-practice lookup', 48, {
+    strong: ['research', 'best practice', 'tìm hiểu', 'tim hieu', 'nghiên cứu', 'nghien cuu', '調査', 'リサーチ', 'ベストプラクティス'],
+    medium: ['documentation', 'docs', 'compare tools', 'latest docs', 'official docs', 'ドキュメント', '比較', '最新ドキュメント', '公式ドキュメント'],
+    weak: ['investigate options', 'market scan', 'reference', 'source material', '選択肢を調べる', '参考資料', '資料'],
+    negative: ['commit', 'push'],
+  }),
+  route('hapo:pptx', 'presentation or PowerPoint work', 46, {
+    strong: ['pptx', 'powerpoint', 'slide deck', 'presentation deck', 'スライド資料', 'プレゼン資料'],
+    medium: ['slide', 'slides', 'deck', 'presentation', 'seminar slides', 'スライド', 'プレゼン', 'セミナー資料'],
+    weak: ['speaker notes', 'appendix', 'mục lục slide', 'muc luc slide', '発表ノート', '付録', '目次'],
+    negative: ['source code', 'api', 'database'],
+  }),
+  route('hapo:agent-browser', 'browser automation with snapshot refs, web interaction, recording, or Browserbase cloud browser workflows', 45, {
+    strong: ['agent-browser', 'browser automation', 'web automation', 'browserbase', 'cloud browser', 'snapshot refs', 'browser snapshot', 'automate browser', 'tự động trình duyệt', 'tu dong trinh duyet', 'tự động thao tác trình duyệt', 'tu dong thao tac trinh duyet', 'ブラウザ自動化', 'クラウドブラウザ', 'ブラウザ操作', 'ブラウザスナップショット'],
+    medium: ['open url', 'navigate site', 'click in browser', 'fill form in browser', 'record browser', 'browser session', 'multi tab', 'browser test session', 'mở website', 'mo website', 'truy cập website', 'truy cap website', 'click trên web', 'click tren web', 'điền form web', 'dien form web', 'サイトを開く', 'ブラウザで開く', 'フォーム入力', 'クリック操作', '録画'],
+    weak: ['click button', 'fill form', 'open site', 'web session', 'browser ref', 'viewport', 'cookies', 'localstorage', 'ボタンをクリック', 'ビューポート', 'クッキー'],
+    negative: ['attached screenshot', 'ảnh đính kèm', 'anh dinh kem', '画像添付', 'source code', 'codebase', 'commit', 'push', 'pptx', 'pdf'],
+  }),
+  route('hapo:pdf', 'PDF reading, extraction, or generation', 44, {
+    strong: ['pdf'], medium: ['export pdf', 'read pdf', 'extract pdf', 'pdf出力', 'pdfを読む', 'pdf抽出'], weak: ['page render', 'ページレンダー'], negative: [],
+  }),
+  route('hapo:docx', 'Word document work', 42, {
+    strong: ['docx', 'word document', 'word file', 'word文書', 'wordファイル'], medium: ['word'], weak: ['tracked changes', 'document file', '変更履歴', '文書ファイル'], negative: [],
+  }),
+  route('hapo:xlsx', 'spreadsheet or Excel work', 42, {
+    strong: ['xlsx', 'excel', 'spreadsheet', 'スプレッドシート'], medium: ['csv', 'sheet', 'workbook', 'シート', 'ワークブック'], weak: ['formula', 'pivot table', '数式', 'ピボットテーブル'], negative: [],
+  }),
+  route('hapo:ai-multimodal', 'image, video, audio, or multimodal artifact analysis', 40, {
+    strong: ['screenshot', 'video', 'audio', 'multimodal', 'ảnh', 'anh', 'hình', 'hinh', 'スクリーンショット', '動画', '音声', '画像', '写真'],
+    medium: ['image', 'screen capture', 'recording', 'file attached', 'イメージ', '画面キャプチャ', '録画', '添付ファイル'],
+    weak: ['visual', 'describe image', 'ocr', 'ビジュアル', '画像説明'],
+    negative: ['pptx', 'pdf export'],
+  }),
+];
+
+function route(skill, reason, priority, signals) {
+  return { skill, reason, priority, signals };
+}
+
+function normalize(value) {
+  return String(value || '')
+    .normalize('NFKC')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .normalize('NFC')
+    .toLowerCase();
+}
+
+function scoreRoute(prompt, routeItem) {
+  const normalized = normalize(prompt);
+  const matched = [];
+  let score = 0;
+  for (const [bucket, weight] of Object.entries(WEIGHTS)) {
+    for (const term of routeItem.signals[bucket] || []) {
+      if (!normalized.includes(normalize(term))) continue;
+      score += weight;
+      matched.push({ bucket, term, weight });
+    }
+  }
+  return { ...routeItem, score, matched, confidence: confidence(score) };
+}
+
+function confidence(score) {
+  if (score >= 12) return 'high';
+  if (score >= 7) return 'medium';
+  if (score >= MIN_SCORE) return 'low';
+  return 'none';
+}
+
+function findRoute(prompt) {
+  const candidates = ROUTES
+    .map((routeItem, index) => ({ ...scoreRoute(prompt, routeItem), index }))
+    .filter((routeItem) => routeItem.score >= MIN_SCORE)
+    .sort((a, b) => b.score - a.score || b.priority - a.priority || a.index - b.index);
+  return candidates[0] || null;
+}
+
+module.exports = {
+  MIN_SCORE,
+  ROUTES,
+  findRoute,
+  normalize,
+  scoreRoute,
+};

package/src/claude/hooks/skill-router.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * UserPromptSubmit Hook - skill-router.cjs
+ *
+ * Adds a deterministic CafeKit skill suggestion for natural-language prompts.
+ * It never overrides explicit slash commands; it only injects a short routing hint.
+ *
+ * Exit: 0 always (fail-open)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function logCrash(error) {
+  try {
+    const dir = path.join(__dirname, '.logs');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(
+      path.join(dir, 'hook-log.jsonl'),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: 'skill-router',
+        status: 'crash',
+        error: error.message,
+      }) + '\n'
+    );
+  } catch (_) {}
+}
+
+try {
+  const { isHookEnabled } = require('./lib/config.cjs');
+  const { findRoute } = require('./lib/skill-router-routes.cjs');
+
+  function isExplicitCommand(prompt) {
+    const trimmed = prompt.trim();
+    return trimmed.startsWith('/') || /^hapo:[a-z-]+/i.test(trimmed);
+  }
+
+  if (!isHookEnabled('skill-router')) process.exit(0);
+
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  if (!stdin) process.exit(0);
+
+  const payload = JSON.parse(stdin);
+  const prompt = payload.prompt || '';
+  if (!prompt || isExplicitCommand(prompt)) process.exit(0);
+
+  const route = findRoute(prompt);
+  if (!route) process.exit(0);
+
+  const skillDir = route.skill.replace(/^hapo:/, '');
+  const lines = [
+    '## CafeKit Skill Router',
+    `- Suggested skill: \`${route.skill}\``,
+    `- Why: ${route.reason}.`,
+    `- Confidence: ${route.confidence} (score ${route.score}).`,
+    `- Action: before acting, read \`.claude/skills/${skillDir}/SKILL.md\` and follow that workflow.`,
+    '- If the user explicitly names another workflow or asks for direct answering only, follow the user request.',
+  ];
+
+  console.log(lines.join('\n'));
+  process.exit(0);
+} catch (error) {
+  try { logCrash(error); } catch (_) {}
+  process.exit(0);
+}

package/src/claude/migration-manifest.json

@@ -68,6 +68,7 @@
   },
   "runtime": {
     "files": [
+      "gitignore",
       "runtime.json",
       "status.cjs",
       "hooks/session.cjs",
@@ -77,6 +78,7 @@
       "hooks/privacy-block.cjs",
       "hooks/inspect-block.cjs",
       "hooks/rules.cjs",
+      "hooks/skill-router.cjs",
       "hooks/spec-state.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
@@ -85,7 +87,8 @@
       "hooks/lib/git.cjs",
       "hooks/lib/config.cjs",
       "hooks/lib/context.cjs",
-      "hooks/lib/detect.cjs"
+      "hooks/lib/detect.cjs",
+      "hooks/lib/skill-router-routes.cjs"
     ]
   },
   "settings": {

package/src/claude/scripts/validate-spec-output.cjs

@@ -86,23 +86,31 @@ function extractRequirementIds(requirementsText) {
 }
 
 function validateTaskSections(taskPath, content, errors) {
-  const hasContext =
-    hasHeading(content, 'Context') ||
-    hasHeading(content, 'Objective') ||
-    hasHeading(content, 'Goal');
+  const hasContext = hasHeading(content, 'Context');
+  const hasConstraints = hasHeading(content, 'Constraints');
   const hasSteps =
     hasHeading(content, 'Steps') || hasHeading(content, 'Implementation Steps');
   const hasRequirements =
     hasHeading(content, 'Requirements') || /_Requirements:\s*[^_\n]+_/i.test(content);
+  const hasRelatedFiles = hasHeading(content, 'Related Files');
+  const hasCompletionCriteria = hasHeading(content, 'Completion Criteria');
   const hasEvidence =
     hasHeading(content, 'Evidence') ||
     hasHeading(content, 'Task Test Plan & Verification Evidence') ||
     hasHeading(content, 'Verification & Evidence');
+  const hasRiskAssessment = hasHeading(content, 'Risk Assessment');
 
-  if (!hasContext) errors.push(`${taskPath}: missing Context/Objective/Goal`);
+  if (!hasContext) errors.push(`${taskPath}: missing Context`);
+  if (!hasConstraints) errors.push(`${taskPath}: missing Constraints`);
   if (!hasSteps) errors.push(`${taskPath}: missing Steps/Implementation Steps`);
   if (!hasRequirements) errors.push(`${taskPath}: missing Requirements mapping`);
+  if (!hasRelatedFiles) errors.push(`${taskPath}: missing Related Files`);
+  if (!hasCompletionCriteria) errors.push(`${taskPath}: missing Completion Criteria`);
   if (!hasEvidence) errors.push(`${taskPath}: missing Evidence or task test plan`);
+  if (!hasRiskAssessment) errors.push(`${taskPath}: missing Risk Assessment`);
+  if (hasEvidence && !/Runtime reachability verification/i.test(content)) {
+    errors.push(`${taskPath}: missing Runtime reachability verification`);
+  }
 }
 
 function validateSpec(specDir) {
@@ -187,6 +195,28 @@ function validateSpec(specDir) {
     errors.push('tasks/: feature work cannot be entirely R0; reserve R0 for shared foundation tasks');
   }
 
+  const validationRecommended = spec.design_context?.validation_recommended === true;
+  if (taskFiles.length >= 5 && !validationRecommended) {
+    errors.push('spec.json.design_context.validation_recommended: must be true for specs with 5+ task files');
+  }
+  if (
+    (validationRecommended || taskFiles.length >= 5) &&
+    spec.ready_for_implementation === true &&
+    spec.validation?.status !== 'completed'
+  ) {
+    errors.push(
+      'spec.json.ready_for_implementation: cannot be true when validation is recommended but validation.status is not completed',
+    );
+  }
+  if (spec.validation?.status === 'completed') {
+    if (!spec.timestamps?.validation_done) {
+      errors.push('spec.json.timestamps.validation_done: required when validation.status is completed');
+    }
+    if (taskFiles.length >= 5 && !spec.timestamps?.review_done) {
+      errors.push('spec.json.timestamps.review_done: required for 5+ task specs after validation');
+    }
+  }
+
   const requirementsPath = path.join(specDir, 'requirements.md');
   const designPath = path.join(specDir, 'design.md');
   const researchPath = path.join(specDir, 'research.md');

package/src/claude/settings/settings.json

@@ -42,6 +42,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/rules.cjs\""
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-state.cjs\""

package/src/claude/skills/debug/SKILL.md

@@ -16,17 +16,37 @@ Debugging is diagnosis, not repair. Find the source of the failure before changi
 - `--frontend` - Include browser console, screenshot, accessibility tree, network, and responsive checks
 - `--perf` - Include baseline measurements, bottleneck layer, profiling, and before/after targets
 
-Default: systematic diagnosis with no product-code edits.
-
-<HARD-GATE>
-Do NOT implement a fix inside `hapo:debug`.
+Default: systematic diagnosis with no product-code edits, scout first.
+
+<DIAGNOSTIC-ONLY-GATE>
+`hapo:debug` is read-only for product code.
+Do NOT edit product code, apply fixes, create migrations, or add regression tests as implementation.
+Do NOT change config, dependency versions, generated assets, or test snapshots to make the failure disappear.
+Temporary instrumentation is allowed only when it is the minimal way to observe hidden state; record the file/line, capture the proof, remove it before finishing, and report `Temporary instrumentation: removed`.
+</DIAGNOSTIC-ONLY-GATE>
+
+<HARD-GATE-SCOUT-FIRST>
+Before hypotheses, inspect the actual codebase context.
+You must identify:
+- project type, language, framework, runtime, and test runner
+- affected files/modules and exact symptom location
+- direct callers, dependents, and data/config boundaries
+- related tests and reproduction commands
+- recent commits touching affected paths
+- adjacent known-good implementation patterns
+
+After scout, provide a 3-6 bullet codebase-context summary before evidence capture.
+Do not ask generic questions before this step unless the issue cannot be located from the prompt or repository.
+</HARD-GATE-SCOUT-FIRST>
+
+<ROOT-CAUSE-GATE>
 Do NOT recommend a fix until the root-cause contract is complete.
 Do NOT stop at the first plausible explanation. Test hypotheses against evidence.
 If 2+ hypotheses are refuted, change strategy before continuing.
-If evidence is insufficient, report `Root cause: unknown` with the missing evidence needed.
-</HARD-GATE>
+If evidence is insufficient, report `Root cause: unknown`, `Missing Evidence`, and `Next Diagnostic Action`; do not hand off to `hapo:hotfix` as ready.
+</ROOT-CAUSE-GATE>
 
-Temporary instrumentation is allowed only when it is the minimal way to observe hidden state. Remove it before finishing and report what was instrumented.
+If the user asks to fix while still inside `hapo:debug`, finish the debug report first. Then hand off only the completed root-cause contract to `hapo:hotfix`.
 
 ## Process Flow
 
@@ -53,15 +73,18 @@ flowchart TD
 Understand the affected code before forming hypotheses.
 
 **Action:** Activate `hapo:inspect` for the relevant scope.
+If `hapo:inspect` is unavailable, use direct read-only reconnaissance (`rg`, file reads, test discovery, and `git log`) and state that fallback.
 
 **Checklist:**
+- [ ] Project type, language, framework, runtime, and test runner identified
 - [ ] Affected files and modules identified
 - [ ] Direct dependencies and call paths mapped
+- [ ] Inputs/outputs, data boundaries, and config/env boundaries mapped
 - [ ] Related tests located
 - [ ] Recent changes checked: `git log --oneline -10 -- <affected-files>`
 - [ ] Existing working examples or adjacent patterns identified
 
-**Output:** `✓ Step 1: Scouted - [N] files, [M] deps, [K] tests`
+**Output:** `✓ Step 1: Scouted - [N] files, [M] deps, [K] tests` plus a 3-6 bullet context summary.
 
 ---
 
@@ -77,9 +100,9 @@ Create a baseline that can later prove whether the issue changed.
 - Environment facts: runtime, dependency versions, OS, browser, CI runner, config
 - Whether the issue reproduces consistently or intermittently
 
-For frontend issues, use `references/debugger/frontend-verification.md`.
-For CI/log issues, use `references/debugger/log-ci-analysis.md`.
-For performance issues, use `references/debugger/performance-diagnostics.md`.
+For frontend issues, use `.claude/references/debugger/frontend-verification.md`.
+For CI/log issues, use `.claude/references/debugger/log-ci-analysis.md`.
+For performance issues, use `.claude/references/debugger/performance-diagnostics.md`.
 
 **Output:** `✓ Step 2: Evidence captured - baseline command/symptom recorded`
 
@@ -115,7 +138,7 @@ Result: confirmed | refuted | inconclusive
 Rules:
 - Never batch unrelated changes as a test.
 - Prefer read-only evidence: logs, grep, stack traces, DB queries, browser traces.
-- For flaky async tests, use `references/debugger/condition-based-waiting.md`.
+- For flaky async tests, use `.claude/references/debugger/condition-based-waiting.md`.
 - If 2+ hypotheses are refuted, use inversion: ask what evidence would make the current explanation impossible.
 
 **Output:** `✓ Step 4: Hypotheses tested - [confirmed/refuted counts]`
@@ -156,7 +179,7 @@ Prepare the handoff to `hapo:hotfix` or the user.
 - Affected-module tests
 - Typecheck/lint/build commands when relevant
 - UI screenshot/console/network checks when relevant
-- Side-effect sweep from `references/debugger/side-effect-gate.md`
+- Side-effect sweep from `.claude/references/debugger/side-effect-gate.md`
 
 **Output:** `✓ Step 6: Verification planned - [commands/scenarios]`
 
@@ -189,9 +212,18 @@ Prepare the handoff to `hapo:hotfix` or the user.
 - Regression guard:
 - Side-effect sweep:
 
+### Temporary Instrumentation
+- none | removed: [file:line, purpose, proof captured]
+
 ### Recommended Fix Direction
 [Smallest root-cause fix, or "insufficient evidence"]
 
+### Missing Evidence
+- [Only when root cause is unknown]
+
+### Next Diagnostic Action
+- [Only when root cause is unknown]
+
 ### Unresolved Questions
 - [Only if any]
 ```
@@ -199,18 +231,19 @@ Prepare the handoff to `hapo:hotfix` or the user.
 ## Relationship To Hotfix
 
 - Use `hapo:debug` to determine what is wrong.
-- Use `hapo:hotfix` to change code after the root-cause contract is complete.
+- Use `hapo:hotfix` to change code only after the root-cause contract is complete.
+- A `Root cause: unknown` report is not ready for hotfix; continue diagnosis or ask for the missing artifact.
 - If `hapo:hotfix` verification fails, return to `hapo:debug` with the new evidence.
 
 ## References
 
 Load as needed:
-- `references/debugger/core-philosophy.md` - Anti-guessing discipline
-- `references/debugger/root-cause-tracing.md` - Backward trace to origin
-- `references/debugger/verification-protocol.md` - Fresh evidence requirements
-- `references/debugger/log-ci-analysis.md` - Logs and CI/CD failure analysis
-- `references/debugger/parallel-agent-hydration.md` - Parallel reconnaissance
-- `references/debugger/frontend-verification.md` - Browser/UI verification
-- `references/debugger/performance-diagnostics.md` - Performance investigation
-- `references/debugger/condition-based-waiting.md` - Flaky async test diagnosis
-- `references/debugger/side-effect-gate.md` - Regression and blast-radius checks
+- `.claude/references/debugger/core-philosophy.md` - Anti-guessing discipline
+- `.claude/references/debugger/root-cause-tracing.md` - Backward trace to origin
+- `.claude/references/debugger/verification-protocol.md` - Fresh evidence requirements
+- `.claude/references/debugger/log-ci-analysis.md` - Logs and CI/CD failure analysis
+- `.claude/references/debugger/parallel-agent-hydration.md` - Parallel reconnaissance
+- `.claude/references/debugger/frontend-verification.md` - Browser/UI verification
+- `.claude/references/debugger/performance-diagnostics.md` - Performance investigation
+- `.claude/references/debugger/condition-based-waiting.md` - Flaky async test diagnosis
+- `.claude/references/debugger/side-effect-gate.md` - Regression and blast-radius checks