@haposoft/cafekit 0.8.11 → 0.8.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.11",
+  "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/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

@@ -78,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",
@@ -86,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/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

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

@@ -1,7 +1,7 @@
 ---
 name: hapo:develop
-description: "Code execution engine: Reads specs and implements code end-to-end with automatic code review and self-healing."
-argument-hint: "[feature-name|specs-directory-path]"
+description: "Code execution engine: Reads specs and implements code end-to-end with automatic code review, self-healing, and visual implementation notes."
+argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--no-notes]"
 ---
 
 # Develop — Feature Implementation (Task-Orchestrated Build)
@@ -16,6 +16,9 @@ Reads the project specification (`hapo:specs`) and implements code through a dis
 /hapo:develop <feature name>
 /hapo:develop specs/<feature-name>
 /hapo:develop <feature name> <specific-task-file.md>
+/hapo:develop <feature name> --flash
+/hapo:develop <feature name> <specific-task-file.md> --flash
+/hapo:develop <feature name> --no-notes
 ```
 
 ## Execution Modes
@@ -25,7 +28,7 @@ Triggered by `/hapo:develop <feature> <task-file>`.
 
 - Load exactly one task file.
 - Implement only that task packet.
-- STOP immediately after the task is verified and synchronized.
+- STOP immediately after the task is verified and synchronized, or flash-synchronized when `--flash` is active.
 - Never auto-chain into the next task.
 
 ### 2. Full-Spec Mode
@@ -37,6 +40,28 @@ Triggered by `/hapo:develop <feature>` or `/hapo:develop specs/<feature>`.
 - Sync state.
 - Recompute the queue and continue.
 - STOP the overall run on the first blocked task, unresolved gate failure, or missing proof.
+- In `--flash` mode, missing full test proof does not stop the loop; record `FLASH_UNVERIFIED` and continue to the next unblocked task.
+
+### 3. Flash Mode
+Triggered by adding `--flash` to either specific-task or full-spec mode.
+
+- Optimize for fast implementation, not full verification.
+- Still load the approved spec, scout every task, obey scope, and implement real code.
+- Skip dedicated test suites, E2E/browser/manual QA loops, full task evidence execution, and code-review retry loops.
+- Run only cheap preflight checks when available and fast: syntax, typecheck, or build commands that do not require installing dependencies or starting external services.
+- Never weaken, delete, or rewrite tests to avoid running them.
+- Sync completed implementation with an explicit `FLASH_UNVERIFIED` receipt; do not claim production-ready quality.
+- Final output MUST recommend `/hapo:test <feature>` before merge, release, or publish.
+
+### 4. Implementation Notes
+Enabled by default for all develop modes. Disable only with `--no-notes`.
+
+- Maintain `specs/<feature-name>/implementation-notes.html`.
+- Use `references/implementation-notes-template.html` when the file does not exist.
+- Keep the file self-contained: inline CSS, no JS, no external fonts, no network assets.
+- Style notes as readable Claude Code-like blocks: compact cards, left accent bars, category badges, monospace file paths, and a task timeline.
+- Record decisions and caveats while implementing, not only at the end.
+- Do not use notes to justify scope changes that alter the approved contract. If the contract changes, stop and route back to `/hapo:specs update`.
 
 <HARD-GATE>
 DO NOT write implementation code until an approved spec exists.
@@ -46,6 +71,7 @@ DO NOT write implementation code until an approved spec exists.
 <DEFINITION-OF-DONE>
 A task is NOT done because code compiles or a placeholder renders.
 A task is done only when the task file's Completion Criteria AND Evidence section are satisfied with real execution proof. Existing specs may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`; treat those as the same contract.
+`--flash` is the only exception: it records fast implementation closeout with `FLASH_UNVERIFIED`, not full Definition of Done.
 </DEFINITION-OF-DONE>
 
 <CONTRACT-FIDELITY>
@@ -73,9 +99,13 @@ flowchart TD
     B -->|Missing| Z[Stop: Run /hapo:specs]
     B -->|Ready| C[Step 2: Task-Aware Scout (inspector)]
     C --> D[Step 3: Implement Code (god-developer)]
-    D --> E[Step 4: Quality Gate: Test + Spec Review + Code Review + Evidence]
-    E -->|Fail| D
-    E -->|Pass| F[Step 5: State Sync + Incremental Docs Sync]
+    D --> E{Flash Mode?}
+    E -->|No| Q[Step 4: Quality Gate: Test + Spec Review + Code Review + Evidence]
+    E -->|Yes| R[Step 4F: Flash Gate: Minimal Preflight + Scope Sanity]
+    Q -->|Fail| D
+    Q -->|Pass| F[Step 5: State Sync + Incremental Docs Sync]
+    R -->|Syntax/compile fail| D
+    R -->|Flash closeout| F
     F --> H{More tasks?}
     H -->|Yes| B
     H -->|No| G[Final Integration Scout + Report Completion]
@@ -85,6 +115,10 @@ flowchart TD
 - Identify input: Open `specs/<feature-name>/spec.json`.
 - Check `ready_for_implementation` status. If not ready, notify user.
 - Load `task_registry` and verify it matches the requested task file(s). If registry is missing or stale, route to `/hapo:sync audit <feature>` before coding.
+- Unless `--no-notes` is present, initialize or update `specs/<feature-name>/implementation-notes.html`:
+  - If missing, create it from `references/implementation-notes-template.html`.
+  - Replace template placeholders for feature name, spec path, creation timestamp, and current mode.
+  - If present, preserve existing note cards and update the summary/timeline/status fields.
 - **Task Scoping (CRITICAL):**
   - If the user specifies a particular task file (e.g., `task-R0-02...md`), load **ONLY** that specific file into working memory.
   - If no specific task is mentioned, DO NOT load all tasks into working memory. Resolve the next single unblocked `pending` task from `task_registry` and load only that task packet.
@@ -121,6 +155,14 @@ flowchart TD
 - Act as `god-developer` OR directly write code, executing tasks specified in the loaded Markdown file(s) sequentially.
 - **Important:** You may create and modify files directly, but must faithfully follow the design from the Spec.
 - You MUST use the Step 2 scout report as implementation context. If code reality contradicts the task packet, stop and reconcile the spec before coding.
+- Unless `--no-notes` is present, append a note card to `implementation-notes.html` whenever any of these occurs:
+  - `decision`: a necessary implementation choice not specified by the spec
+  - `spec-gap`: missing or ambiguous spec detail discovered during implementation
+  - `codebase-reality`: existing code requires a different integration path than the task implied
+  - `tradeoff`: a conscious simplicity, performance, UX, or maintainability tradeoff
+  - `scope-escape`: a file or behavior outside Related Files must be touched for reachability/compile/integration
+  - `risk`: known residual risk, edge case, or deferred follow-up
+  - `verification`: command result, skipped check, manual proof, or evidence caveat
 - Progress tracking: Temporarily change `[ ]` to `[/]` in Spec files while coding is in progress. Do NOT mark `[x]` before Step 4 passes.
 - **Task Boundary Protocol (CRITICAL):**
   - Default editable scope is `Related Files` from the task packet.
@@ -141,6 +183,8 @@ flowchart TD
 The moment you finish coding, DO NOT proceed further. Switch to `references/quality-gate.md` and run the automatic review loop.
 **Mantra:** Scope/spec compliance first, code quality second. All feedback from code-auditor must be addressed thoroughly: Score >= 9.5 & Zero Critical issues.
 
+If `--flash` is active, use **Step 4F: Flash Gate** instead of the full automatic review loop.
+
 - Passing Step 4 requires ALL of the following:
   1. Automated verification passes, including preflight compile/typecheck/build health and every exact command named in the task's `Evidence` section (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
   2. Spec compliance review passes: every scoped requirement and active task criterion is implemented, with no extras and no omissions
@@ -153,8 +197,28 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
 - If the implementation silently replaced a named contract choice or relies on cross-service process-local stand-ins, the task is still FAIL.
 - Only escalate to the user after 3 consecutive failed review rounds.
 
+### Step 4F: Flash Gate (`--flash` only)
+Flash mode is an explicit speed trade-off requested by the user.
+
+- Skip:
+  - dedicated test commands from task Evidence
+  - full test-runner delegation
+  - E2E/browser/manual QA loops
+  - full code-auditor retry loop
+  - screenshot, accessibility, performance, and visual verification unless the active task is purely visual and can be checked cheaply
+- Still perform:
+  - task-aware scout from Step 2
+  - active task scope sanity check against Completion Criteria
+  - reachability sanity check for runtime-facing files: imported, mounted, registered, routed, or invoked where applicable
+  - cheap compile/syntax/typecheck/build command when it is already available and expected to run quickly
+- If the cheap preflight fails, return to Step 3 and fix before syncing.
+- If no cheap preflight exists or it would require slow setup/external services, record `Preflight: skipped in --flash mode`.
+- Flash output MUST log: `⚡ Step 4 Flash Gate: tests skipped by --flash; preflight=<pass|skipped>; evidence=FLASH_UNVERIFIED`.
+- Flash output MUST NOT say `Test PASS`, `Evidence PASS`, `Auto-Approved`, or `production-ready`.
+
 ### Step 5: State Sync + Task-Level Docs Sync
 - Only after Step 4 passes may you mark task checkboxes completed and sync `spec.json` progress/timestamps/task_registry.
+- In `--flash` mode, Step 4F may sync the task only as a fast implementation closeout with an explicit `FLASH_UNVERIFIED` receipt.
 - If verification is partial or blocked by environment, keep the task in `pending` or `in_progress` and record the blocker instead of pretending completion.
 - A completed task MUST leave behind:
   - markdown `**Status:** done`
@@ -162,7 +226,14 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
   - `completed_at` + `last_updated_at`
   - synchronized top-level `updated_at`
   - a human-readable verification receipt inside the task's `Evidence` section showing which commands ran, their outcomes, and what proof was observed
+- In `--flash` mode, the receipt MUST include `Mode: --flash`, `Tests: skipped by user request`, `Evidence: FLASH_UNVERIFIED`, and `Next verification: /hapo:test <feature>`.
 - Verification receipts with `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation intentionally simplified a named contract MUST NOT be synchronized as `done`.
+- Exception: `FLASH_UNVERIFIED` is allowed only when `--flash` is explicitly present. It records fast implementation completion, not full verification completion.
+- Unless `--no-notes` is present, update `implementation-notes.html` before reporting the task:
+  - Mark the task block as `done`, `blocked`, or `flash_unverified`.
+  - Add a `verification` note with exact commands run or `Tests skipped by --flash`.
+  - If no implementation note was needed for the task, add a compact `decision` note: `No spec gaps, tradeoffs, scope escapes, or deferred risks recorded for this task.`
+  - Add `Next verification: /hapo:test <feature>` when any evidence is skipped, partial, or `FLASH_UNVERIFIED`.
 - After syncing the active task, run a **Task Closeout Docs Checkpoint**
 - Task Closeout Docs Checkpoint:
   - Evaluate `Docs impact: none | minor | major` based on real behavior changes from the just-completed task
@@ -183,3 +254,4 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
 ## Attached References
 - `references/quality-gate.md` - Rules for the Code Review loop.
 - `references/subagent-patterns.md` - Standard prompts for calling subagents.
+- `references/implementation-notes-template.html` - Self-contained visual implementation notes template.

package/src/claude/skills/develop/references/implementation-notes-template.html

@@ -0,0 +1,320 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Implementation Notes - {{FEATURE_NAME}}</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --bg: #f7faf9;
+      --panel: #ffffff;
+      --ink: #17211d;
+      --muted: #63736d;
+      --line: #dfe8e4;
+      --soft: #eef7f3;
+      --brand: #087a5a;
+      --brand-2: #0ea5a0;
+      --decision: #0f766e;
+      --spec-gap: #b45309;
+      --tradeoff: #7c3aed;
+      --scope: #be123c;
+      --risk: #dc2626;
+      --verify: #2563eb;
+      --codebase: #475569;
+      --flash: #c2410c;
+      --shadow: 0 12px 32px rgba(15, 23, 42, 0.08);
+    }
+
+    * { box-sizing: border-box; }
+
+    body {
+      margin: 0;
+      background:
+        radial-gradient(circle at top left, rgba(14, 165, 160, 0.16), transparent 34rem),
+        linear-gradient(180deg, #f8fffd 0%, var(--bg) 34%, #eef7f3 100%);
+      color: var(--ink);
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.55;
+    }
+
+    main {
+      width: min(1120px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 32px 0 56px;
+    }
+
+    .hero {
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      background: rgba(255, 255, 255, 0.9);
+      box-shadow: var(--shadow);
+      padding: 28px;
+      display: grid;
+      gap: 18px;
+    }
+
+    .eyebrow {
+      color: var(--brand);
+      font-size: 12px;
+      font-weight: 760;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+
+    h1, h2, h3 { margin: 0; line-height: 1.15; }
+    h1 { font-size: clamp(30px, 5vw, 52px); letter-spacing: 0; }
+    h2 { font-size: 22px; }
+    h3 { font-size: 16px; }
+
+    .summary {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 12px;
+    }
+
+    .metric {
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      background: var(--soft);
+      padding: 12px 14px;
+      min-height: 76px;
+    }
+
+    .metric span {
+      display: block;
+      color: var(--muted);
+      font-size: 12px;
+      margin-bottom: 6px;
+    }
+
+    .metric strong {
+      display: block;
+      font-size: 15px;
+      overflow-wrap: anywhere;
+    }
+
+    .layout {
+      display: grid;
+      grid-template-columns: 280px minmax(0, 1fr);
+      gap: 20px;
+      margin-top: 20px;
+      align-items: start;
+    }
+
+    aside, .content-panel {
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      background: rgba(255, 255, 255, 0.92);
+      box-shadow: var(--shadow);
+    }
+
+    aside {
+      padding: 18px;
+      position: sticky;
+      top: 18px;
+    }
+
+    .toc {
+      list-style: none;
+      padding: 0;
+      margin: 14px 0 0;
+      display: grid;
+      gap: 8px;
+    }
+
+    .toc a {
+      display: block;
+      color: var(--ink);
+      text-decoration: none;
+      border: 1px solid var(--line);
+      border-radius: 10px;
+      padding: 9px 10px;
+      background: #fbfefd;
+      font-size: 14px;
+    }
+
+    .toc a:hover { border-color: var(--brand-2); color: var(--brand); }
+
+    .content-panel {
+      padding: 20px;
+      display: grid;
+      gap: 16px;
+    }
+
+    .task-block {
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      overflow: hidden;
+      background: #fff;
+    }
+
+    .task-header {
+      display: flex;
+      justify-content: space-between;
+      gap: 14px;
+      align-items: flex-start;
+      padding: 16px 18px;
+      background: linear-gradient(90deg, rgba(8, 122, 90, 0.1), rgba(14, 165, 160, 0.04));
+      border-bottom: 1px solid var(--line);
+    }
+
+    .task-meta {
+      color: var(--muted);
+      font-size: 13px;
+      margin-top: 6px;
+    }
+
+    .status {
+      border-radius: 999px;
+      padding: 5px 10px;
+      background: #ecfdf5;
+      color: var(--brand);
+      border: 1px solid rgba(8, 122, 90, 0.22);
+      font-size: 12px;
+      font-weight: 720;
+      white-space: nowrap;
+    }
+
+    .notes {
+      padding: 16px;
+      display: grid;
+      gap: 12px;
+    }
+
+    .note {
+      border: 1px solid var(--line);
+      border-left: 5px solid var(--brand);
+      border-radius: 12px;
+      padding: 14px 14px 14px 16px;
+      background: #fbfefd;
+      display: grid;
+      gap: 10px;
+    }
+
+    .note.decision { border-left-color: var(--decision); }
+    .note.spec-gap { border-left-color: var(--spec-gap); }
+    .note.tradeoff { border-left-color: var(--tradeoff); }
+    .note.scope-escape { border-left-color: var(--scope); }
+    .note.risk { border-left-color: var(--risk); }
+    .note.verification { border-left-color: var(--verify); }
+    .note.codebase-reality { border-left-color: var(--codebase); }
+    .note.flash { border-left-color: var(--flash); }
+
+    .note-head {
+      display: flex;
+      justify-content: space-between;
+      gap: 10px;
+      align-items: center;
+    }
+
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      border-radius: 999px;
+      padding: 4px 9px;
+      font-size: 12px;
+      font-weight: 780;
+      background: #eef7f3;
+      color: var(--brand);
+      border: 1px solid var(--line);
+    }
+
+    .note time {
+      color: var(--muted);
+      font-size: 12px;
+    }
+
+    .note p { margin: 0; }
+
+    .details {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 10px;
+    }
+
+    .detail {
+      border-radius: 10px;
+      background: #f8fbfa;
+      border: 1px solid var(--line);
+      padding: 10px;
+      font-size: 13px;
+    }
+
+    .detail strong {
+      display: block;
+      color: var(--muted);
+      font-size: 11px;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      margin-bottom: 4px;
+    }
+
+    code {
+      font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+      font-size: 0.92em;
+      background: #eef7f3;
+      border: 1px solid var(--line);
+      border-radius: 6px;
+      padding: 1px 5px;
+    }
+
+    .empty {
+      color: var(--muted);
+      border: 1px dashed var(--line);
+      border-radius: 12px;
+      padding: 18px;
+      background: #fbfefd;
+    }
+
+    @media (max-width: 860px) {
+      main { width: min(100% - 20px, 1120px); padding-top: 18px; }
+      .summary, .layout, .details { grid-template-columns: 1fr; }
+      aside { position: static; }
+      .task-header, .note-head { flex-direction: column; align-items: flex-start; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <section class="hero">
+      <div class="eyebrow">CafeKit Implementation Notes</div>
+      <h1>{{FEATURE_NAME}}</h1>
+      <div class="summary">
+        <div class="metric"><span>Spec path</span><strong><code>{{SPEC_PATH}}</code></strong></div>
+        <div class="metric"><span>Mode</span><strong>{{MODE}}</strong></div>
+        <div class="metric"><span>Last updated</span><strong>{{UPDATED_AT}}</strong></div>
+        <div class="metric"><span>Verification</span><strong>{{VERIFICATION_STATUS}}</strong></div>
+      </div>
+    </section>
+
+    <div class="layout">
+      <aside>
+        <h2>Task Timeline</h2>
+        <ul class="toc">
+          <!-- TASK_TOC_START -->
+          <li><a href="#task-current">Current task</a></li>
+          <!-- TASK_TOC_END -->
+        </ul>
+      </aside>
+
+      <section class="content-panel">
+        <!-- NOTES_START -->
+        <article class="task-block" id="task-current">
+          <div class="task-header">
+            <div>
+              <h2>Current Task</h2>
+              <div class="task-meta">Add task id, title, and active task file here.</div>
+            </div>
+            <span class="status">in_progress</span>
+          </div>
+          <div class="notes">
+            <div class="empty">No implementation decisions recorded yet.</div>
+          </div>
+        </article>
+        <!-- NOTES_END -->
+      </section>
+    </div>
+  </main>
+</body>
+</html>

package/src/claude/skills/develop/references/quality-gate.md

@@ -8,6 +8,8 @@ Green tests are NOT enough. The gate requires four proofs:
 3. Code quality review
 4. Task evidence (completion criteria + runtime/artifact/reachability proof from the task file)
 
+`--flash` is the explicit fast path. It bypasses this full gate and uses the Flash Gate defined below.
+
 ## Automation Semantics
 
 - If the task names exact commands in `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`), those exact commands are mandatory and must run before any fallback repo defaults.
@@ -21,6 +23,29 @@ Green tests are NOT enough. The gate requires four proofs:
 - Scope fidelity is mandatory: missing scoped behavior, extra unapproved behavior, or task output that exists only as orphaned/unreachable code is a review failure even when build/tests pass.
 - Runtime-facing artifacts must be reachable from the real entrypoint/caller named by the task or the task-aware scout report.
 
+## Flash Gate (`--flash`)
+
+Use this only when `/hapo:develop ... --flash` is present.
+
+- Skip dedicated test commands, E2E/browser/manual QA, full task evidence execution, test-runner delegation, and code-auditor retry loops.
+- Do not report `Test PASS`, `Evidence PASS`, `Auto-Approved`, or `production-ready`.
+- Still perform a scope sanity check against active task Completion Criteria.
+- Still perform a reachability sanity check for runtime-facing files: imported, mounted, registered, routed, or invoked where applicable.
+- Run a cheap compile/syntax/typecheck/build command only when available and expected to complete quickly without dependency install or external services.
+- If the cheap preflight fails, return to implementation; do not sync.
+- If the cheap preflight is unavailable or too slow, record `Preflight: skipped in --flash mode`.
+- Sync only with receipt fields:
+  - `Mode: --flash`
+  - `Tests: skipped by user request`
+  - `Evidence: FLASH_UNVERIFIED`
+  - `Next verification: /hapo:test <feature>`
+
+Terminal log:
+
+```text
+⚡ Step 4 Flash Gate: tests skipped by --flash; preflight=<pass|skipped>; evidence=FLASH_UNVERIFIED
+```
+
 ## Quality Cycle
 
 Maximum retry counter: **3 attempts**. Exceeding 3 triggers a collapse warning.

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

@@ -11,11 +11,11 @@ Kill bugs systematically. No guessing. Evidence first, fix second.
 
 ## Arguments
 
-- `--quick` - Fast track for trivial issues (lint, type errors, syntax)
+- `--quick` - Reduced-depth path for trivial issues (lint, type errors, syntax); still scout-first
 - `--parallel` - Spawn multiple `god-developer` agents for independent issues
 - `--from-debug` - Start from an existing `hapo:debug` report and validate its root-cause contract
 
-Default: Autonomous mode — auto-approve when confidence is high.
+Default: deterministic scout-first hotfix. There is no initial mode selection step.
 
 <HARD-GATE>
 Do NOT propose or implement fixes before completing Steps 1-2 (Scout + `hapo:debug` diagnosis).
@@ -23,9 +23,36 @@ Symptom fixes are FAILURE. Find the root cause first.
 The exact root-cause contract is mandatory: symptom, reproduction, expected/actual, root cause file:line or config/env source, why now, evidence chain, blast radius.
 The side-effect gate is mandatory before completion.
 If 3+ fix attempts fail → STOP. Question the architecture. Discuss with user.
-Exception: `--quick` mode allows abbreviated scout→diagnose→fix for trivial issues.
+Exception: `--quick` mode only abbreviates depth; it never skips scout, pre-fix evidence, diagnosis, or before/after verification.
 </HARD-GATE>
 
+<HARD-GATE-SCOUT-FIRST>
+Hotfix ALWAYS scouts before asking broad clarification questions, forming hypotheses, or changing files.
+Collect these scout outputs first:
+1. Project type, language(s), framework(s), and package/test runner from repo files.
+2. Exact file(s) where the symptom surfaces and their direct callers/dependents.
+3. Related tests covering the affected area.
+4. Recent commits touching affected files: `git log --oneline -10 -- <affected-files>`.
+5. Existing patterns/conventions for this kind of fix.
+Then state a concise 3-6 bullet codebase-context summary before Step 2.
+</HARD-GATE-SCOUT-FIRST>
+
+<HARD-GATE-NO-SIDE-EFFECTS>
+The fix is not done until Step 5 proves:
+1. The original symptom no longer reproduces with the exact pre-fix command/user flow.
+2. Modified files and transitively affected modules still pass relevant tests.
+3. Blast-radius workflows have no business-logic regression.
+4. No new lint/type/build errors were introduced.
+5. Public contracts are unchanged unless intentionally called out: function signatures, exported types, response shapes, DB schemas, env vars.
+
+If verification reveals a side effect or regression, STOP and present 2-4 concrete options to the user:
+- Revert this fix and try a different root-cause angle.
+- Narrow the fix scope to remove the regression.
+- Keep the fix and update named dependent files/contracts.
+- Accept the behavior change intentionally.
+Do not silently patch around the regression.
+</HARD-GATE-NO-SIDE-EFFECTS>
+
 ## Anti-Rationalization
 
 | Thought | Reality |
@@ -35,6 +62,7 @@ Exception: `--quick` mode allows abbreviated scout→diagnose→fix for trivial
 | "Just try changing X" | Random fixes waste time and create new bugs. Diagnose first. |
 | "It's probably X" | "Probably" = guessing. Use structured diagnosis. |
 | "One more fix attempt" (after 2+) | 3+ failures = wrong approach. Question architecture. |
+| "Quick mode means skip process" | Quick mode only reduces depth. Scout, diagnosis, and before/after proof remain mandatory. |
 
 ## Process Flow
 
@@ -43,7 +71,7 @@ flowchart TD
     A[Issue Input] --> B[Step 1: Scout via hapo:inspect]
     B --> C[Step 2: Diagnose via hapo:debug]
     C --> D[Step 3: Classify Complexity]
-    D -->|Trivial| E[Quick Fix]
+    D -->|Trivial| E[Quick Fix after scout+diagnose]
     D -->|Standard| F[Standard Fix]
     D -->|Complex| G[Deep Fix + Subagents]
     D -->|Multiple Issues| H[Parallel Fix]
@@ -70,17 +98,22 @@ flowchart TD
 
 **Action:** Activate `hapo:inspect` skill to map the blast radius.
 
-| Mode | Scout Depth |
+Do not ask generic questions before this step unless there is no repo, no error text, and no observable artifact to inspect.
+
+| Path | Scout Depth |
 |------|-------------|
-| `--quick` | Minimal — locate affected file(s) and direct dependencies only |
-| Standard | Full — map module boundaries, test coverage, call chains |
+| `--quick` | Minimal — project type, affected file(s), direct callers/dependents, related tests, recent commits |
+| Standard | Full — project type, module boundaries, test coverage, call chains, recent changes, existing patterns |
 | `--parallel` | Per-issue independent scouts |
 
 **Checklist:**
+- [ ] Project type, language, framework, package manager, and test runner identified
 - [ ] Affected files identified
-- [ ] Direct dependencies mapped (imports/exports)
+- [ ] Direct callers/dependents mapped (imports/exports, route registrations, provider wiring, consumers)
 - [ ] Related tests located
 - [ ] Recent git changes checked: `git log --oneline -10 -- <affected-files>`
+- [ ] Existing local patterns for this code path identified
+- [ ] 3-6 bullet codebase-context summary reported before diagnosis
 
 **Output:** `✓ Step 1: Scouted — [N] files mapped, [M] dependencies, [K] tests found`
 
@@ -115,6 +148,8 @@ Use `hapo:debug` or validate an existing debug report when `--from-debug` is pro
 - Evidence chain: observations proving the cause
 - Blast radius: affected files, modules, tests, users, workflows, or release paths
 
+If any field is vague (`probably`, `maybe`, `I think`, or missing file:line/config/env evidence), keep diagnosing or ask the user for the specific missing artifact. Do not implement.
+
 **Output:** `✓ Step 2: Diagnosed — Root cause: [summary], Evidence: [brief], Scope: [N files]`
 
 ---
@@ -131,6 +166,7 @@ Use `hapo:debug` or validate an existing debug report when `--from-debug` is pro
 **Task Orchestration (Standard+ only):**
 - Use `TaskCreate` with dependencies to track fix phases
 - Skip for Trivial (overhead exceeds benefit)
+- If `TaskCreate` / `TaskUpdate` are unavailable, use a concise markdown checklist or `TodoWrite` fallback. Do not block the hotfix because structured task tools are missing.
 
 **Output:** `✓ Step 3: [Complexity] detected — [workflow] selected`
 
@@ -144,8 +180,9 @@ Use `hapo:debug` or validate an existing debug report when `--from-debug` is pro
 - One logical change per commit boundary.
 
 ### Quick Workflow
-1. Apply the obvious fix directly from diagnosis
-2. Run typecheck/lint immediately
+1. Apply the minimal fix directly from completed scout + diagnosis
+2. Run exact pre-fix command plus typecheck/lint immediately
+3. Report before/after proof
 
 ### Standard Workflow
 1. Implement fix targeting root cause
@@ -178,20 +215,27 @@ Use `hapo:debug` or validate an existing debug report when `--from-debug` is pro
 2. **Regression test:** The test MUST fail without the fix and pass with it.
 3. **Parallel verification:** Run typecheck + lint + build + test simultaneously via `Bash`. See `references/parallel-patterns.md` Pattern C.
 4. **Prevention guard (Standard+ only):** See `references/prevention-gate.md`.
-5. **Side-effect gate:** Run the sweep in `references/debugger/side-effect-gate.md`.
-6. **Code review:** Trigger `hapo:code-review` and handle results per `references/review-cycle.md` (autonomous auto-approve loop or HITL depending on fix criticality).
+5. **Side-effect gate:** Sweep the full blast radius identified in Step 2:
+   - Modified files and direct dependents pass relevant tests
+   - Affected user/API/CLI workflows still work
+   - Public contracts unchanged unless intentionally called out
+   - No new lint/type/build errors
+6. **Code review:** Trigger `hapo:code-review`; never auto-approve blocking security, auth, data-loss, resource-exhaustion, or public-contract issues.
 
 **If verification fails:**
 - < 3 attempts → Loop back to Step 2 (re-diagnose with new evidence)
 - 3+ attempts → STOP. Question architecture. Discuss with user.
 
+**If a side effect appears:**
+- STOP and present concrete options to the user. Do not silently broaden the fix.
+
 **Output:** `✓ Step 5: Verified + Prevented — [before/after comparison], [N] tests added`
 
 ---
 
 ## Step 6: Finalize (MANDATORY — never skip)
 
-1. **Report:** Confidence score, root cause, changes made, files affected, prevention measures
+1. **Report:** Confidence score, root cause, changes made, files affected, prevention measures, side-effect sweep result
 2. **Docs update:** If API/behavior changed → delegate to `docs-keeper` subagent
 3. **Task cleanup:** `TaskUpdate` → mark all tasks `completed` (skip if no tasks created)
 4. **Commit:** Ask user if ready to commit via `git-ops` subagent
@@ -227,16 +271,23 @@ Unified step markers (emit after each step):
 | `docs-keeper` | Update docs if behavior changed (Step 6) |
 | `god-developer` | Parallel independent issues (each gets own agent) |
 
+## Specialized Paths
+
+Use `references/workflow-specialized.md` as an overlay after Step 1 scout:
+- CI/CD failures
+- Test suite failures
+- TypeScript type errors
+- UI / visual issues
+- Application log errors
+
+Specialized paths do not replace the 6-step hotfix process.
+
 ## References
 
 Load as needed:
 - `references/diagnosis-protocol.md` — Structured root cause analysis methodology
 - `references/escalation-tactics.md` — What to do when hypotheses fail (Inversion, Scale Game)
 - `references/prevention-gate.md` — Defense-in-depth validation after fix
-- `references/review-cycle.md` — Autonomous approval loop + HITL review handling
+- `references/review-cycle.md` — Review handling and required user-pause conditions
 - `references/parallel-patterns.md` — Parallel Explore/Bash/Task coordination with code templates
 - `references/workflow-specialized.md` — CI/CD, test, TypeScript, UI-specific workflows
-- `references/debugger/frontend-verification.md` — Browser/UI evidence and visual verification
-- `references/debugger/performance-diagnostics.md` — Baseline-driven performance diagnosis
-- `references/debugger/condition-based-waiting.md` — Flaky async test diagnosis
-- `references/debugger/side-effect-gate.md` — Regression and blast-radius sweep

package/src/claude/skills/hotfix/references/prevention-gate.md

@@ -1,6 +1,6 @@
 # Prevention Gate
 
-After a fix is verified, apply defense-in-depth to prevent the same bug class from recurring. Prevention is not the same as side-effect safety; run `references/debugger/side-effect-gate.md` before claiming completion.
+After a fix is verified, apply defense-in-depth to prevent the same bug class from recurring. Prevention is not the same as side-effect safety; run the Step 5 side-effect sweep in `../SKILL.md` before claiming completion.
 
 ## Mandatory Prevention Checklist
 

package/src/claude/skills/hotfix/references/review-cycle.md

@@ -2,7 +2,7 @@
 
 How to handle code review results after a fix is implemented. Ensures quality without unnecessary friction.
 
-## Autonomous Mode (Default)
+## Default Review Handling
 
 The agent reviews its own fix using `hapo:code-review` and decides automatically:
 
@@ -32,9 +32,9 @@ LOOP:
        → Proceed to Step 6
 ```
 
-## Human-in-the-Loop Mode
+## Required User Pause
 
-When the fix touches production-critical code or the user explicitly requests review control:
+When the fix touches production-critical code, changes public contracts, introduces a behavior change, or the user explicitly requests review control:
 
 1. Run `hapo:code-review` → collect score + findings
 2. Present a structured summary to user:
@@ -52,15 +52,15 @@ When the fix touches production-critical code or the user explicitly requests re
    - If no critical issues → "Approve" | "Address warnings" | "Abort"
 4. Execute user's choice. Max 3 remediation cycles.
 
-## When to Use HITL vs Autonomous
+## When To Pause vs Continue
 
 | Situation | Mode |
 |-----------|------|
-| Type errors, lint, syntax fixes | Autonomous (always) |
-| Single-file logic bugs | Autonomous |
-| Multi-file changes touching auth/payments/data | HITL recommended |
-| Architecture-impacting changes | HITL required |
-| User said "review with me" or similar | HITL |
+| Type errors, lint, syntax fixes | Continue after passing verification |
+| Single-file logic bugs | Continue after passing verification |
+| Multi-file changes touching auth/payments/data | Pause recommended |
+| Architecture-impacting changes | Pause required |
+| User said "review with me" or similar | Pause required |
 
 ## Blocking Issues (Never Auto-Approve)
 

package/src/claude/skills/hotfix/references/workflow-specialized.md

@@ -27,7 +27,7 @@ When unit/integration/e2e tests are failing:
 2. **Check for pollution:** Does it pass alone but fail in suite? → Test order dependency or shared state leaking
 3. **Check for staleness:** Did the implementation change but the test assertions were not updated?
 4. **Snapshot drift:** If snapshot tests fail, review the diff carefully — is it an intentional change or a regression?
-5. **Flaky async:** Replace arbitrary sleeps with condition-based waits. See `references/debugger/condition-based-waiting.md`.
+5. **Flaky async:** Replace arbitrary sleeps with condition-based waits: wait for observable state, DOM condition, network completion, queue drain, or explicit event instead of fixed timeouts.
 
 ---
 
@@ -52,7 +52,7 @@ When the interface is broken, misaligned, or not rendering:
 1. **Capture visual evidence:** Use `pushd skills/chrome-devtools/scripts && node screenshot.js --url <url> && popd`
 2. **Check ARIA structure:** `pushd skills/chrome-devtools/scripts && node aria-snapshot.js --url <url> && popd` — reveals hidden overlays, z-index battles
 3. **Check console errors:** `pushd skills/chrome-devtools/scripts && node console.js --url <url> && popd` — catches JS crashes preventing render
-4. **Run frontend verification:** Follow `references/debugger/frontend-verification.md` for screenshot, console, network, accessibility, responsive, and interaction evidence.
+4. **Run frontend verification:** collect screenshot, console, network, accessibility, responsive, and interaction evidence before/after the fix.
 5. **Common traps:**
    - CSS specificity wars (use browser DevTools or ARIA snapshot to verify computed styles)
    - Hydration mismatch in SSR frameworks (server HTML differs from client render)