@haposoft/cafekit 0.8.12 → 0.8.14

package/README.md

@@ -80,6 +80,7 @@ CafeKit ships many skills, but the main release surface is:
 - `/hapo:develop <feature-name>`: implement from approved spec artifacts
 - `/hapo:debug <issue>`: diagnose bugs, incidents, CI failures, flaky tests, UI regressions, and performance issues before fixing
 - `/hapo:hotfix <issue>`: fix diagnosed bugs with root-cause, verification, prevention, and side-effect gates
+- `/hapo:docs [init|update|summarize|reconstruct]`: create project docs or reconstruct as-is system documentation from source code
 - `/hapo:test [scope|--full]`: run verification and return a structured verdict
 - `/hapo:code-review [scope|--pending]`: adversarial review focused on correctness, regressions, and security
 - `/hapo:generate-graph <diagram request>`: generate technical SVG/PNG diagrams
@@ -125,6 +126,14 @@ Generate a diagram:
 /hapo:generate-graph Draw a sequence diagram for auth flow between browser, API, and database
 ```
 
+Reconstruct current-state docs for an existing or legacy system:
+
+```bash
+/hapo:docs reconstruct apps/legacy-admin
+```
+
+The reconstruct bundle includes as-is markdown/JSON evidence and a self-contained `overview.html` review dashboard before the approved docs are handed to `/hapo:specs`.
+
 ## Spec Artifacts
 
 CafeKit's current spec workflow writes artifacts under:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "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/docs-sync.cjs

@@ -15,13 +15,15 @@ try {
   const fs = require('fs');
   const path = require('path');
   const { execSync } = require('child_process');
+  const { loadConfig } = require('./lib/config.cjs');
 
   // Đọc stdin theo chuẩn hook
   const stdin = fs.readFileSync(0, 'utf8').trim();
   const payload = stdin ? JSON.parse(stdin) : {};
   const cwd = payload.cwd || process.cwd();
+  const config = loadConfig({ cwd, includeProject: false, includeAssertions: false, includeLocale: false });
 
-  const docsDir = path.join(cwd, 'docs');
+  const docsDir = path.join(cwd, config.paths?.docs || 'docs');
   
   // Xác định dự án đã có cốt lõi code hay chưa?
   const hasCode = fs.existsSync(path.join(cwd, 'src')) ||

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

@@ -16,14 +16,20 @@ const YELLOW = '\x1b[33m';
 const MAGENTA = '\x1b[35m';
 const CYAN = '\x1b[36m';
 
-// Detect color support at module load (cached)
-// Claude Code statusline runs via pipe but output displays in TTY - default to true
-const shouldUseColor = (() => {
+function detectColorDefault() {
   if (process.env.NO_COLOR) return false;
   if (process.env.FORCE_COLOR) return true;
   // Default true for statusline context (Claude Code handles TTY display)
   return true;
-})();
+}
+
+// Detect color support at module load (cached)
+// Claude Code statusline runs via pipe but output displays in TTY - default to true
+let shouldUseColor = detectColorDefault();
+
+function setColorEnabled(enabled) {
+  shouldUseColor = enabled === false ? false : detectColorDefault();
+}
 
 // Detect 256-color support via COLORTERM
 const has256Color = (() => {
@@ -90,6 +96,7 @@ module.exports = {
   dim,
   getContextColor,
   coloredBar,
-  shouldUseColor,
+  get shouldUseColor() { return shouldUseColor; },
+  setColorEnabled,
   has256Color
 };

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

@@ -9,11 +9,9 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const LOCAL_CONFIG_PATH = '.claude/.ck.json';
-const GLOBAL_CONFIG_PATH = path.join(os.homedir(), '.claude', '.ck.json');
+const RUNTIME_CONFIG_PATH = '.claude/runtime.json';
 
-// Legacy export for backward compatibility
-const CONFIG_PATH = LOCAL_CONFIG_PATH;
+const CONFIG_PATH = RUNTIME_CONFIG_PATH;
 
 const DEFAULT_CONFIG = {
   plan: {
@@ -61,6 +59,7 @@ const DEFAULT_CONFIG = {
   },
   assertions: [],
   statusline: 'full',
+  statuslineColors: true,
   hooks: {
     'session-init': true,
     'subagent-init': true,
@@ -81,8 +80,8 @@ const DEFAULT_CONFIG = {
  * Arrays are replaced entirely (not concatenated) to avoid duplicate entries
  *
  * IMPORTANT: Empty objects {} are treated as "inherit from parent", not "replace with empty".
- * This allows global config to set hooks.foo: false and have it persist even when
- * local config has hooks: {} (empty = inherit, not reset to defaults).
+ * This allows runtime config to leave hooks as {} (inherit defaults)
+ * without resetting all default hook toggles.
  *
  * @param {Object} target - Base object
  * @param {Object} source - Object to merge (takes precedence)
@@ -464,36 +463,39 @@ function sanitizeConfig(config, projectRoot) {
 }
 
 /**
- * Load config with cascading resolution: DEFAULT → global → local
+ * Load config with cascading resolution: DEFAULT → runtime
  *
  * Resolution order (each layer overrides the previous):
  *   1. DEFAULT_CONFIG (hardcoded defaults)
- *   2. Global config (~/.claude/.ck.json) - user preferences
- *   3. Local config (./.claude/.ck.json) - project-specific overrides
+ *   2. Runtime config (./.claude/runtime.json) - installed CafeKit runtime config
  *
  * @param {Object} options - Options for config loading
  * @param {boolean} options.includeProject - Include project section (default: true)
  * @param {boolean} options.includeAssertions - Include assertions (default: true)
  * @param {boolean} options.includeLocale - Include locale section (default: true)
+ * @param {string} options.cwd - Project root for local config lookup (default: process.cwd())
  */
 function loadConfig(options = {}) {
-  const { includeProject = true, includeAssertions = true, includeLocale = true } = options;
-  const projectRoot = process.cwd();
+  const {
+    includeProject = true,
+    includeAssertions = true,
+    includeLocale = true,
+    cwd = process.cwd()
+  } = options;
+  const projectRoot = cwd;
 
-  // Load configs from both locations
-  const globalConfig = loadConfigFromPath(GLOBAL_CONFIG_PATH);
-  const localConfig = loadConfigFromPath(LOCAL_CONFIG_PATH);
+  // Load config from the installed CafeKit runtime config.
+  const runtimeConfig = loadConfigFromPath(path.join(projectRoot, RUNTIME_CONFIG_PATH));
 
   // No config files found - use defaults
-  if (!globalConfig && !localConfig) {
+  if (!runtimeConfig) {
     return getDefaultConfig(includeProject, includeAssertions, includeLocale);
   }
 
   try {
-    // Deep merge: DEFAULT → global → local (local wins)
+    // Deep merge: DEFAULT → runtime (runtime wins)
     let merged = deepMerge({}, DEFAULT_CONFIG);
-    if (globalConfig) merged = deepMerge(merged, globalConfig);
-    if (localConfig) merged = deepMerge(merged, localConfig);
+    if (runtimeConfig) merged = deepMerge(merged, runtimeConfig);
 
     // Build result with optional sections
     const result = {
@@ -523,6 +525,7 @@ function loadConfig(options = {}) {
     result.hooks = merged.hooks || DEFAULT_CONFIG.hooks;
     // Statusline mode
     result.statusline = merged.statusline || 'full';
+    result.statuslineColors = merged.statuslineColors !== false;
 
     return sanitizeConfig(result, projectRoot);
   } catch (e) {
@@ -541,7 +544,8 @@ function getDefaultConfig(includeProject = true, includeAssertions = true, inclu
     codingLevel: -1,  // Default: disabled (no injection, saves tokens)
     skills: { ...DEFAULT_CONFIG.skills },
     hooks: { ...DEFAULT_CONFIG.hooks },
-    statusline: 'full'
+    statusline: 'full',
+    statuslineColors: true
   };
   if (includeLocale) {
     result.locale = { ...DEFAULT_CONFIG.locale };
@@ -790,8 +794,13 @@ function extractTaskListId(resolved) {
  * @param {string} hookName - Hook name (script basename without .cjs)
  * @returns {boolean} Whether hook is enabled
  */
-function isHookEnabled(hookName) {
-  const config = loadConfig({ includeProject: false, includeAssertions: false, includeLocale: false });
+function isHookEnabled(hookName, options = {}) {
+  const config = loadConfig({
+    includeProject: false,
+    includeAssertions: false,
+    includeLocale: false,
+    cwd: options.cwd
+  });
   const hooks = config.hooks || {};
   // Return true if undefined (default enabled), otherwise return the boolean value
   return hooks[hookName] !== false;
@@ -799,8 +808,7 @@ function isHookEnabled(hookName) {
 
 module.exports = {
   CONFIG_PATH,
-  LOCAL_CONFIG_PATH,
-  GLOBAL_CONFIG_PATH,
+  RUNTIME_CONFIG_PATH,
   DEFAULT_CONFIG,
   INVALID_FILENAME_CHARS,
   deepMerge,

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

@@ -18,7 +18,7 @@ const ROUTES = [
     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'],
+    negative: ['commit', 'push', 'bug', 'error', 'production', 'pptx', 'pdf', 'reconstruct requirements', 'as-is requirements', 'legacy system documentation', 'documentation from source code', 'docs from source code', 'ソースコードから'],
   }),
   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', '実装', '開発', '仕様に沿って', '仕様どおり', '承認済み仕様'],
@@ -27,8 +27,8 @@ const ROUTES = [
     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', 'テスト', '検証', '確認', '動作確認'],
+    strong: ['unit test', 'integration test', 'e2e', 'playwright', 'coverage', 'test all', 'run all tests', 'test toàn bộ', 'test toan bo', 'kiểm thử', 'kiem thu', 'kiểm tra toàn bộ', 'kiem tra toan bo', '単体テスト', '結合テスト', '全体テスト', 'カバレッジ', 'テストして'],
+    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'],
   }),
@@ -45,8 +45,8 @@ const ROUTES = [
     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', '関連ファイル', 'どこにある', 'プロジェクト構造', 'リポジトリ構造', '探して'],
+    strong: ['inspect', 'codebase scan', 'scan codebase', 'scan source', 'file discovery', 'find files', 'locate files', 'xem source', 'xem codebase', 'kiểm tra source', 'kiem tra source', 'kiểm tra source code', 'kiem tra source code', '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', 'source code', 'tìm file', 'tim file', 'tìm trong source', 'tim trong source', 'cấu trúc project', 'cau truc project', 'ở đâu', 'o dau', 'nằm đâu', 'nam 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'],
   }),
@@ -63,8 +63,8 @@ const ROUTES = [
     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', 'バンドル最適化', '再レンダー最適化', 'データ取得', 'サーバーコンポーネント', 'クライアントコンポーネント', 'ハイドレーション'],
+    strong: ['react best practices', 'next.js best practices', 'vercel react best practices', 'react performance', 'next.js performance', 'optimize react', 'optimize next.js', 'rerender nhiều', 'rerender nhieu', 'nhiều rerender', 'nhieu rerender', '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', 'optimize', 'optimization', 'tối ưu', 'toi uu', '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'],
   }),
@@ -98,6 +98,12 @@ const ROUTES = [
     weak: ['mind map', 'dependency map', 'system map', 'マインドマップ', '依存関係図', 'システム図'],
     negative: ['pptx', 'slide deck'],
   }),
+  route('hapo:docs', 'project documentation, codebase docs, or source-backed as-is reconstruction', 51, {
+    strong: ['hapo:docs', 'project docs', 'system docs', 'codebase docs', 'codebase documentation', 'documentation from source code', 'docs from source code', 'generate docs from codebase', 'dựng tài liệu từ source code', 'dung tai lieu tu source code', 'tài liệu hệ thống', 'tai lieu he thong', 'tài liệu hiện trạng', 'tai lieu hien trang', 'tạo tài liệu project', 'tao tai lieu project', 'legacy documentation', 'legacy system documentation', 'as-is documentation', 'as-is requirements', 'requirement reconstruction', 'reconstruct requirements', 'reconstruct requirements from legacy system', 'ソースコードから仕様書', 'ソースコードから仕様書を作成', 'ソースコードからドキュメント', '既存システムのドキュメント', '現行仕様書', 'as-isドキュメント'],
+    medium: ['create docs', 'update docs', 'refresh docs', 'summarize codebase', 'system documentation', 'source to docs', 'reverse documentation', 'current-state docs', 'existing system docs', 'legacy docs', 'legacy system', 'dựng docs', 'dung docs', 'tạo docs', 'tao docs', 'cập nhật docs', 'cap nhat docs', 'tóm tắt codebase', 'tom tat codebase', 'dựng lại tài liệu', 'dung lai tai lieu', '仕様書を作成', 'ドキュメント作成', 'ドキュメント更新', 'コードベース要約', '既存システム', 'レガシーシステム'],
+    weak: ['docs', 'documentation', 'document project', 'document codebase', 'as-is', 'reconstruct', 'hiện trạng', 'hien trang', 'tài liệu', 'tai lieu', 'ドキュメント', '資料化', '仕様化', '現状'],
+    negative: ['official docs', 'latest docs', 'library docs', 'framework docs', 'api docs lookup', 'context7', 'best practice', 'research', 'pptx', 'slide'],
+  }),
   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', 'アプローチ', '選択肢', 'トレードオフ', 'テーマ', '何をすれば'],
@@ -118,7 +124,7 @@ const ROUTES = [
   }),
   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', 'サイトを開く', 'ブラウザで開く', 'フォーム入力', 'クリック操作', '録画'],
+    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'],
   }),

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

@@ -38,13 +38,13 @@ try {
     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 cwd = payload.cwd || process.cwd();
   const prompt = payload.prompt || '';
+  if (!isHookEnabled('skill-router', { cwd })) process.exit(0);
   if (!prompt || isExplicitCommand(prompt)) process.exit(0);
 
   const route = findRoute(prompt);

package/src/claude/hooks/usage.cjs

@@ -21,14 +21,15 @@ try {
   const os = require("os");
   const { execSync } = require("child_process");
 
-  // Check if usage tracking is disabled in runtime.json
-  try {
-    const runtimePath = path.join(process.cwd(), '.claude', 'runtime.json');
-    if (fs.existsSync(runtimePath)) {
-      const runtime = JSON.parse(fs.readFileSync(runtimePath, 'utf-8'));
-      if (runtime.usage?.enabled === false) process.exit(0);
-    }
-  } catch { /* fail-open */ }
+  function readRuntime(cwd) {
+    try {
+      const runtimePath = path.join(cwd, '.claude', 'runtime.json');
+      if (fs.existsSync(runtimePath)) {
+        return JSON.parse(fs.readFileSync(runtimePath, 'utf-8'));
+      }
+    } catch { /* fail-open */ }
+    return {};
+  }
 
 // Cache configuration
 const USAGE_CACHE_FILE = path.join(os.tmpdir(), "ck-usage-limits-cache.json");
@@ -151,6 +152,12 @@ async function main() {
 		} catch {}
 
 		const input = JSON.parse(inputStr || "{}");
+		const cwd = input.cwd || process.cwd();
+		const runtime = readRuntime(cwd);
+		if (runtime.usage?.enabled === false) {
+			console.log(JSON.stringify(result));
+			return;
+		}
 
 		// Detect hook type
 		const isUserPrompt = typeof input.prompt === "string";

package/src/claude/migration-manifest.json

@@ -15,6 +15,7 @@
       "debug",
       "develop",
       "devops",
+      "docs",
       "docx",
       "frontend-design",
       "frontend-development",
@@ -56,6 +57,7 @@
   "scripts": {
     "required": [
       "validate-docs.cjs",
+      "validate-docs-reconstruct.cjs",
       "browser-tool.cjs",
       "validate-spec-output.cjs"
     ]

package/src/claude/scripts/validate-docs-reconstruct.cjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * CafeKit as-is reconstruction bundle validator.
+ *
+ * The docs workflow is LLM-authored, so the bundle shape and evidence links
+ * must be checked deterministically before it is handed to human review.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DOCUMENT_FILES = [
+  'overview.html',
+  'system-overview.md',
+  'requirements-as-is.md',
+  'roles-and-permissions.md',
+  'entities-and-statuses.md',
+  'business-rules.md',
+  'integrations.md',
+  'architecture-c4.md',
+  'constraints-risks-and-decisions.md',
+  'glossary.md',
+  'evidence-map.md',
+  'unknowns-and-assumptions.md',
+];
+const REQUIRED_FILES = ['reconstruction.json', ...DOCUMENT_FILES];
+const EVIDENCE_ID_RE = /\bE-[A-Z]+-\d{3}\b/g;
+
+function usage() {
+  console.error('Usage: node .claude/scripts/validate-docs-reconstruct.cjs docs/as-is/<scope>');
+}
+
+function readJson(filePath, errors) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    errors.push(`reconstruction.json: invalid JSON (${error.message})`);
+    return null;
+  }
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function uniqueMatches(text, pattern) {
+  return [...new Set(text.match(pattern) || [])].sort();
+}
+
+function validateMeta(bundle, meta, errors) {
+  for (const key of [
+    'scope',
+    'generated_at',
+    'status',
+    'docs_root',
+    'source_revision',
+    'source_branch',
+    'evidence_policy',
+    'review_gate',
+    'review_status',
+    'approved_for_specs',
+    'documents',
+    'counts',
+    'next_recommended_step',
+  ]) {
+    if (!(key in meta)) errors.push(`reconstruction.json.${key}: missing`);
+  }
+
+  for (const key of ['scope', 'generated_at', 'docs_root', 'source_revision', 'source_branch']) {
+    if (key in meta && (typeof meta[key] !== 'string' || meta[key].trim() === '')) {
+      errors.push(`reconstruction.json.${key}: must be a non-empty string`);
+    }
+  }
+  if (meta.approved_for_specs !== false && meta.review_status !== 'approved') {
+    errors.push('reconstruction.json.approved_for_specs: only approved review may set true');
+  }
+  if (!Array.isArray(meta.documents)) {
+    errors.push('reconstruction.json.documents: must be an array');
+    return;
+  }
+
+  const declared = [...meta.documents].sort();
+  const expected = [...DOCUMENT_FILES].sort();
+  if (JSON.stringify(declared) !== JSON.stringify(expected)) {
+    errors.push('reconstruction.json.documents: must exactly list the as-is document bundle');
+  }
+  if (typeof meta.docs_root === 'string' && !meta.docs_root.includes(path.basename(bundle))) {
+    errors.push('reconstruction.json.docs_root: must point at this scope bundle');
+  }
+}
+
+function requirementBlocks(text) {
+  const matches = [...text.matchAll(/^##\s+(R-ASIS-\d{3})\b[^\n]*$/gm)];
+  return matches.map((match, index) => ({
+    id: match[1],
+    text: text.slice(match.index, matches[index + 1]?.index ?? text.length),
+  }));
+}
+
+function validateRequirements(bundle, evidenceText, errors) {
+  const requirementPath = path.join(bundle, 'requirements-as-is.md');
+  const blocks = requirementBlocks(readText(requirementPath));
+  if (blocks.length === 0) {
+    errors.push('requirements-as-is.md: must contain at least one ## R-ASIS-### requirement');
+    return;
+  }
+
+  const ledgerIds = new Set(uniqueMatches(evidenceText, EVIDENCE_ID_RE));
+  for (const block of blocks) {
+    if (!/- Type:\s*(Observed|Inferred|Unknown)\b/.test(block.text)) {
+      errors.push(`requirements-as-is.md:${block.id}: missing Type`);
+    }
+    if (!/- Confidence:\s*(High|Medium|Low)\b/.test(block.text)) {
+      errors.push(`requirements-as-is.md:${block.id}: missing Confidence`);
+    }
+    if (!/^- Evidence:\s*$/m.test(block.text)) {
+      errors.push(`requirements-as-is.md:${block.id}: missing Evidence section`);
+    }
+
+    const evidenceIds = uniqueMatches(block.text, EVIDENCE_ID_RE);
+    if (evidenceIds.length === 0) {
+      errors.push(`requirements-as-is.md:${block.id}: must reference evidence IDs`);
+    }
+    for (const evidenceId of evidenceIds) {
+      if (!ledgerIds.has(evidenceId)) {
+        errors.push(`requirements-as-is.md:${block.id}: unknown evidence ID ${evidenceId}`);
+      }
+    }
+  }
+}
+
+function validateBundle(bundle) {
+  const errors = [];
+  if (!fs.existsSync(bundle)) return { errors: [`${bundle}: bundle directory does not exist`] };
+
+  for (const file of REQUIRED_FILES) {
+    if (!fs.existsSync(path.join(bundle, file))) errors.push(`${file}: missing`);
+  }
+  if (errors.length > 0) return { errors };
+
+  const meta = readJson(path.join(bundle, 'reconstruction.json'), errors);
+  if (meta) validateMeta(bundle, meta, errors);
+
+  const evidence = readText(path.join(bundle, 'evidence-map.md'));
+  if (uniqueMatches(evidence, EVIDENCE_ID_RE).length === 0) {
+    errors.push('evidence-map.md: must define evidence IDs');
+  }
+  validateRequirements(bundle, evidence, errors);
+
+  const overview = readText(path.join(bundle, 'overview.html'));
+  if (!overview.includes('data-reconstruct-overview')) {
+    errors.push('overview.html: must keep reconstruct overview marker');
+  }
+
+  return { errors };
+}
+
+function main() {
+  const input = process.argv[2];
+  if (!input) {
+    usage();
+    process.exit(2);
+  }
+
+  const bundle = path.resolve(process.cwd(), input);
+  const { errors } = validateBundle(bundle);
+  if (errors.length > 0) {
+    console.error(`FAIL ${path.relative(process.cwd(), bundle) || bundle}`);
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+
+  console.log(`PASS ${path.relative(process.cwd(), bundle) || bundle}`);
+}
+
+main();

package/src/claude/scripts/validate-docs.cjs

@@ -42,7 +42,8 @@ function checkBrokenLinks(docsDir) {
 }
 
 function main() {
-  const docsDir = path.resolve(process.cwd(), 'docs');
+  const docsArg = process.argv[2] || 'docs';
+  const docsDir = path.resolve(process.cwd(), docsArg);
   console.log(`[Docs Validator] Auditing bounds directory: ${docsDir}`);
   
   if (!fs.existsSync(docsDir)) {

package/src/claude/skills/ai-multimodal/SKILL.md

@@ -35,7 +35,7 @@ export GEMINI_API_KEY_2="key2"  # auto-rotates on rate limit
 
 **Verify setup**: `python scripts/check_setup.py`
 **Analyze media**: `python scripts/gemini_batch_process.py --files <file> --task <analyze|transcribe|extract>`
-  - TIP: When you're asked to analyze an image, check if `gemini` command is available, then use `echo "<prompt to analyze image>" | gemini -y -m <gemini.model>` command (read model from `$HOME/packages/spec/src/claude/.ck.json`: `gemini.model`). If `gemini` command is not available, use `python scripts/gemini_batch_process.py --files <file> --task analyze` command.
+  - TIP: When you're asked to analyze an image, check if `gemini` command is available, then use `echo "<prompt to analyze image>" | gemini -y -m <gemini.model>` command (read model from `.claude/runtime.json`: `gemini.model`). If `gemini` command is not available, use `python scripts/gemini_batch_process.py --files <file> --task analyze` command.
 
 > **Stdin support**: Pipe files via stdin for Gemini analysis (auto-detects PNG/JPG/PDF/WAV/MP3).