kenaz 0.3.3 → 0.3.5

package/core/dev/scripts/matrix/src/cli/commands/stats.ts.wip

@@ -1,168 +1,168 @@
-/**
- * stats command - Display statistics about .matrix file
- */
-
-import chalk from 'chalk';
-import { FileHandler } from '../utils/file-handler';
-import { MatrixParser } from '../../parser';
-import { TagIndexer } from '../../indexer/tag-indexer';
-import type { DataRecord } from '../../../types';
-
-interface StatsOptions {
-  verbose?: boolean;
-}
-
-export async function statsCommand(
-  file: string,
-  options: StatsOptions = {}
-): Promise<void> {
-  const filePath = FileHandler.ensureExtension(file);
-
-  // Read file
-  const content = FileHandler.read(filePath);
-  if (!content) {
-    process.exit(1);
-  }
-
-  // Parse file
-  const parser = new MatrixParser();
-  const result = parser.parse(content);
-
-  if (!result.success) {
-    console.error(chalk.red('Failed to parse file'));
-    process.exit(1);
-  }
-
-  const matrixFile = result.data!;
-
-  // Build tag index
-  const indexer = new TagIndexer();
-  indexer.buildIndex(matrixFile);
-
-  console.log(chalk.bold.cyan('\n📊 Matrix File Statistics\n'));
-  console.log(chalk.gray(`File: ${filePath}\n`));
-
-  // 1. Overview
-  console.log(chalk.bold('Overview:'));
-  console.log(`  Total Rules: ${chalk.green(matrixFile.data.records.length)}`);
-  console.log(`  Version: ${chalk.yellow(matrixFile.meta.v)}`);
-  console.log(`  Category: ${chalk.yellow(matrixFile.meta.cat)}\n`);
-
-  // 2. Priority Distribution
-  const priorityStats = groupBy(matrixFile.data.records, 'p');
-  console.log(chalk.bold('Priority Distribution:'));
-  printDistribution(priorityStats, ['P0', 'P1', 'P2', 'P3']);
-
-  // 3. Source Distribution
-  const sourceStats = groupBy(matrixFile.rules, 'source');
-  console.log(chalk.bold('\nSource Distribution:'));
-  printDistribution(sourceStats);
-
-  // 4. Category Distribution
-  const categoryStats = groupBy(matrixFile.rules, 'category');
-  if (Object.keys(categoryStats).length > 0) {
-    console.log(chalk.bold('\nCategory Distribution:'));
-    printDistribution(categoryStats);
-  }
-
-  // 5. Status Distribution
-  const statusStats = groupBy(matrixFile.rules, 'status');
-  if (Object.keys(statusStats).length > 0) {
-    console.log(chalk.bold('\nStatus Distribution:'));
-    printDistribution(statusStats, [
-      'pending',
-      'in_progress',
-      'completed',
-      'blocked',
-      'cancelled',
-    ]);
-  }
-
-  // 6. Domain Distribution
-  const domainStats = groupBy(matrixFile.rules, 'domain');
-  if (Object.keys(domainStats).length > 0) {
-    console.log(chalk.bold('\nDomain Distribution:'));
-    printDistribution(domainStats);
-  }
-
-  // 7. Tag Statistics
-  const tagStats = indexer.getTagStats();
-  if (tagStats.length > 0) {
-    console.log(chalk.bold('\nTop Tags:'));
-    const topTags = tagStats.slice(0, 10);
-    for (const stat of topTags) {
-      console.log(`  ${chalk.cyan(stat.tag)}: ${chalk.green(stat.count)}`);
-    }
-    if (tagStats.length > 10) {
-      console.log(chalk.gray(`  ... and ${tagStats.length - 10} more`));
-    }
-  }
-
-  // 8. Verbose mode: Show all rules
-  if (options.verbose) {
-    console.log(chalk.bold('\nAll Rules:'));
-    for (const rule of matrixFile.rules) {
-      console.log(`  ${chalk.cyan(rule.id)}: ${rule.title || '(no title)'}`);
-    }
-  }
-
-  console.log(); // Empty line at end
-}
-
-/**
- * Group rules by field
- */
-function groupBy(
-  rules: Rule[],
-  field: keyof Rule
-): Record<string, number> {
-  const result: Record<string, number> = {};
-
-  for (const rule of rules) {
-    const value = rule[field];
-    if (value) {
-      const key = String(value);
-      result[key] = (result[key] || 0) + 1;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Print distribution with bar chart
- */
-function printDistribution(
-  stats: Record<string, number>,
-  order?: string[]
-): void {
-  const entries = Object.entries(stats);
-
-  // Sort by order if provided, otherwise by count descending
-  if (order) {
-    entries.sort((a, b) => {
-      const aIndex = order.indexOf(a[0]);
-      const bIndex = order.indexOf(b[0]);
-      if (aIndex === -1 && bIndex === -1) return 0;
-      if (aIndex === -1) return 1;
-      if (bIndex === -1) return -1;
-      return aIndex - bIndex;
-    });
-  } else {
-    entries.sort((a, b) => b[1] - a[1]);
-  }
-
-  // Calculate max count for bar chart
-  const maxCount = Math.max(...entries.map(([, count]) => count));
-  const maxBarLength = 30;
-
-  for (const [key, count] of entries) {
-    const barLength = Math.ceil((count / maxCount) * maxBarLength);
-    const bar = '█'.repeat(barLength);
-    const percentage = ((count / entries.reduce((sum, [, c]) => sum + c, 0)) * 100).toFixed(1);
-
-    console.log(
-      `  ${chalk.yellow(key.padEnd(15))} ${chalk.green(bar)} ${chalk.cyan(count)} ${chalk.gray(`(${percentage}%)`)}`
-    );
-  }
-}
+/**
+ * stats command - Display statistics about .matrix file
+ */
+
+import chalk from 'chalk';
+import { FileHandler } from '../utils/file-handler';
+import { MatrixParser } from '../../parser';
+import { TagIndexer } from '../../indexer/tag-indexer';
+import type { DataRecord } from '../../../types';
+
+interface StatsOptions {
+  verbose?: boolean;
+}
+
+export async function statsCommand(
+  file: string,
+  options: StatsOptions = {}
+): Promise<void> {
+  const filePath = FileHandler.ensureExtension(file);
+
+  // Read file
+  const content = FileHandler.read(filePath);
+  if (!content) {
+    process.exit(1);
+  }
+
+  // Parse file
+  const parser = new MatrixParser();
+  const result = parser.parse(content);
+
+  if (!result.success) {
+    console.error(chalk.red('Failed to parse file'));
+    process.exit(1);
+  }
+
+  const matrixFile = result.data!;
+
+  // Build tag index
+  const indexer = new TagIndexer();
+  indexer.buildIndex(matrixFile);
+
+  console.log(chalk.bold.cyan('\n📊 Matrix File Statistics\n'));
+  console.log(chalk.gray(`File: ${filePath}\n`));
+
+  // 1. Overview
+  console.log(chalk.bold('Overview:'));
+  console.log(`  Total Rules: ${chalk.green(matrixFile.data.records.length)}`);
+  console.log(`  Version: ${chalk.yellow(matrixFile.meta.v)}`);
+  console.log(`  Category: ${chalk.yellow(matrixFile.meta.cat)}\n`);
+
+  // 2. Priority Distribution
+  const priorityStats = groupBy(matrixFile.data.records, 'p');
+  console.log(chalk.bold('Priority Distribution:'));
+  printDistribution(priorityStats, ['P0', 'P1', 'P2', 'P3']);
+
+  // 3. Source Distribution
+  const sourceStats = groupBy(matrixFile.rules, 'source');
+  console.log(chalk.bold('\nSource Distribution:'));
+  printDistribution(sourceStats);
+
+  // 4. Category Distribution
+  const categoryStats = groupBy(matrixFile.rules, 'category');
+  if (Object.keys(categoryStats).length > 0) {
+    console.log(chalk.bold('\nCategory Distribution:'));
+    printDistribution(categoryStats);
+  }
+
+  // 5. Status Distribution
+  const statusStats = groupBy(matrixFile.rules, 'status');
+  if (Object.keys(statusStats).length > 0) {
+    console.log(chalk.bold('\nStatus Distribution:'));
+    printDistribution(statusStats, [
+      'pending',
+      'in_progress',
+      'completed',
+      'blocked',
+      'cancelled',
+    ]);
+  }
+
+  // 6. Domain Distribution
+  const domainStats = groupBy(matrixFile.rules, 'domain');
+  if (Object.keys(domainStats).length > 0) {
+    console.log(chalk.bold('\nDomain Distribution:'));
+    printDistribution(domainStats);
+  }
+
+  // 7. Tag Statistics
+  const tagStats = indexer.getTagStats();
+  if (tagStats.length > 0) {
+    console.log(chalk.bold('\nTop Tags:'));
+    const topTags = tagStats.slice(0, 10);
+    for (const stat of topTags) {
+      console.log(`  ${chalk.cyan(stat.tag)}: ${chalk.green(stat.count)}`);
+    }
+    if (tagStats.length > 10) {
+      console.log(chalk.gray(`  ... and ${tagStats.length - 10} more`));
+    }
+  }
+
+  // 8. Verbose mode: Show all rules
+  if (options.verbose) {
+    console.log(chalk.bold('\nAll Rules:'));
+    for (const rule of matrixFile.rules) {
+      console.log(`  ${chalk.cyan(rule.id)}: ${rule.title || '(no title)'}`);
+    }
+  }
+
+  console.log(); // Empty line at end
+}
+
+/**
+ * Group rules by field
+ */
+function groupBy(
+  rules: Rule[],
+  field: keyof Rule
+): Record<string, number> {
+  const result: Record<string, number> = {};
+
+  for (const rule of rules) {
+    const value = rule[field];
+    if (value) {
+      const key = String(value);
+      result[key] = (result[key] || 0) + 1;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Print distribution with bar chart
+ */
+function printDistribution(
+  stats: Record<string, number>,
+  order?: string[]
+): void {
+  const entries = Object.entries(stats);
+
+  // Sort by order if provided, otherwise by count descending
+  if (order) {
+    entries.sort((a, b) => {
+      const aIndex = order.indexOf(a[0]);
+      const bIndex = order.indexOf(b[0]);
+      if (aIndex === -1 && bIndex === -1) return 0;
+      if (aIndex === -1) return 1;
+      if (bIndex === -1) return -1;
+      return aIndex - bIndex;
+    });
+  } else {
+    entries.sort((a, b) => b[1] - a[1]);
+  }
+
+  // Calculate max count for bar chart
+  const maxCount = Math.max(...entries.map(([, count]) => count));
+  const maxBarLength = 30;
+
+  for (const [key, count] of entries) {
+    const barLength = Math.ceil((count / maxCount) * maxBarLength);
+    const bar = '█'.repeat(barLength);
+    const percentage = ((count / entries.reduce((sum, [, c]) => sum + c, 0)) * 100).toFixed(1);
+
+    console.log(
+      `  ${chalk.yellow(key.padEnd(15))} ${chalk.green(bar)} ${chalk.cyan(count)} ${chalk.gray(`(${percentage}%)`)}`
+    );
+  }
+}

package/core/dev/scripts/matrix/src/cli/commands/tokens.ts.wip

@@ -1,126 +1,126 @@
-/**
- * tokens command - Calculate token count and compression ratio
- */
-
-import chalk from 'chalk';
-import * as fs from 'fs';
-import { resolveFilePath } from '../utils/file-handler';
-import { parseMatrixFile } from '../../parser';
-import { serializeMatrixFile } from '../../serializer';
-
-interface TokensOptions {
-  verbose?: boolean;
-}
-
-export async function tokensCommand(
-  file: string,
-  options: TokensOptions = {}
-): Promise<void> {
-  const filePath = resolveFilePath(file);
-
-  // Read original .matrix content
-  const matrixContent = fs.readFileSync(filePath, 'utf-8');
-
-  // Parse and convert to JSON
-  const matrixFile = parseMatrixFile(filePath);
-  const jsonContent = JSON.stringify(matrixFile, null, 2);
-
-  // Calculate token counts (using simple estimation)
-  const matrixTokens = estimateTokenCount(matrixContent);
-  const jsonTokens = estimateTokenCount(jsonContent);
-
-  // Calculate compression ratio
-  const compressionRatio = (jsonTokens / matrixTokens).toFixed(2);
-
-  // Calculate sizes
-  const matrixSize = Buffer.byteLength(matrixContent, 'utf-8');
-  const jsonSize = Buffer.byteLength(jsonContent, 'utf-8');
-  const sizeRatio = (jsonSize / matrixSize).toFixed(2);
-
-  console.log(chalk.bold.cyan('\n🔢 Token Analysis\n'));
-  console.log(chalk.gray(`File: ${filePath}\n`));
-
-  // Token counts
-  console.log(chalk.bold('Token Counts:'));
-  console.log(`  .matrix format:  ${chalk.green(matrixTokens.toLocaleString())} tokens`);
-  console.log(`  JSON format:     ${chalk.yellow(jsonTokens.toLocaleString())} tokens`);
-  console.log(`  Compression:     ${chalk.cyan(compressionRatio)}:1`);
-  console.log();
-
-  // File sizes
-  console.log(chalk.bold('File Sizes:'));
-  console.log(`  .matrix format:  ${chalk.green(formatBytes(matrixSize))}`);
-  console.log(`  JSON format:     ${chalk.yellow(formatBytes(jsonSize))}`);
-  console.log(`  Size ratio:      ${chalk.cyan(sizeRatio)}:1`);
-  console.log();
-
-  // Efficiency analysis
-  console.log(chalk.bold('Efficiency:'));
-  const tokenSavings = jsonTokens - matrixTokens;
-  const tokenSavingsPercent = ((tokenSavings / jsonTokens) * 100).toFixed(1);
-  console.log(`  Token savings:   ${chalk.green(`-${tokenSavings.toLocaleString()}`)} (${tokenSavingsPercent}%)`);
-
-  const sizeSavings = jsonSize - matrixSize;
-  const sizeSavingsPercent = ((sizeSavings / jsonSize) * 100).toFixed(1);
-  console.log(`  Size savings:    ${chalk.green(`-${formatBytes(sizeSavings)}`)} (${sizeSavingsPercent}%)`);
-  console.log();
-
-  // Verbose mode: Show rule breakdown
-  if (options.verbose) {
-    console.log(chalk.bold('Rule Breakdown:'));
-    console.log(`  Total rules:     ${chalk.cyan(matrixFile.rules.length)}`);
-    console.log(`  Avg tokens/rule: ${chalk.cyan(Math.round(matrixTokens / matrixFile.rules.length))}`);
-    console.log();
-  }
-
-  // Compression assessment
-  const compressionQuality = parseFloat(compressionRatio);
-  let assessment = '';
-  let assessmentColor = chalk.green;
-
-  if (compressionQuality >= 5) {
-    assessment = 'Excellent compression! (≥5:1 target met)';
-    assessmentColor = chalk.green.bold;
-  } else if (compressionQuality >= 3) {
-    assessment = 'Good compression (3-5:1)';
-    assessmentColor = chalk.yellow;
-  } else if (compressionQuality >= 2) {
-    assessment = 'Moderate compression (2-3:1)';
-    assessmentColor = chalk.yellow;
-  } else {
-    assessment = 'Low compression (<2:1)';
-    assessmentColor = chalk.red;
-  }
-
-  console.log(assessmentColor(`✓ ${assessment}`));
-  console.log();
-}
-
-/**
- * Estimate token count using simple heuristics
- * (Approximates GPT tokenization without needing tiktoken dependency)
- */
-function estimateTokenCount(text: string): number {
-  // Simple estimation: ~4 characters per token for English text
-  // This is a rough approximation; actual tokenization varies
-  // For more accuracy, use tiktoken library
-
-  // Remove whitespace for better estimation
-  const trimmedText = text.replace(/\s+/g, ' ').trim();
-
-  // Count words and punctuation as separate tokens
-  const words = trimmedText.split(/\s+/).length;
-  const punctuation = (trimmedText.match(/[.,;:!?()[\]{}'"]/g) || []).length;
-
-  // Estimate: words + punctuation + special chars
-  return Math.ceil((words + punctuation) * 1.3);
-}
-
-/**
- * Format bytes to human-readable string
- */
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
-}
+/**
+ * tokens command - Calculate token count and compression ratio
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { resolveFilePath } from '../utils/file-handler';
+import { parseMatrixFile } from '../../parser';
+import { serializeMatrixFile } from '../../serializer';
+
+interface TokensOptions {
+  verbose?: boolean;
+}
+
+export async function tokensCommand(
+  file: string,
+  options: TokensOptions = {}
+): Promise<void> {
+  const filePath = resolveFilePath(file);
+
+  // Read original .matrix content
+  const matrixContent = fs.readFileSync(filePath, 'utf-8');
+
+  // Parse and convert to JSON
+  const matrixFile = parseMatrixFile(filePath);
+  const jsonContent = JSON.stringify(matrixFile, null, 2);
+
+  // Calculate token counts (using simple estimation)
+  const matrixTokens = estimateTokenCount(matrixContent);
+  const jsonTokens = estimateTokenCount(jsonContent);
+
+  // Calculate compression ratio
+  const compressionRatio = (jsonTokens / matrixTokens).toFixed(2);
+
+  // Calculate sizes
+  const matrixSize = Buffer.byteLength(matrixContent, 'utf-8');
+  const jsonSize = Buffer.byteLength(jsonContent, 'utf-8');
+  const sizeRatio = (jsonSize / matrixSize).toFixed(2);
+
+  console.log(chalk.bold.cyan('\n🔢 Token Analysis\n'));
+  console.log(chalk.gray(`File: ${filePath}\n`));
+
+  // Token counts
+  console.log(chalk.bold('Token Counts:'));
+  console.log(`  .matrix format:  ${chalk.green(matrixTokens.toLocaleString())} tokens`);
+  console.log(`  JSON format:     ${chalk.yellow(jsonTokens.toLocaleString())} tokens`);
+  console.log(`  Compression:     ${chalk.cyan(compressionRatio)}:1`);
+  console.log();
+
+  // File sizes
+  console.log(chalk.bold('File Sizes:'));
+  console.log(`  .matrix format:  ${chalk.green(formatBytes(matrixSize))}`);
+  console.log(`  JSON format:     ${chalk.yellow(formatBytes(jsonSize))}`);
+  console.log(`  Size ratio:      ${chalk.cyan(sizeRatio)}:1`);
+  console.log();
+
+  // Efficiency analysis
+  console.log(chalk.bold('Efficiency:'));
+  const tokenSavings = jsonTokens - matrixTokens;
+  const tokenSavingsPercent = ((tokenSavings / jsonTokens) * 100).toFixed(1);
+  console.log(`  Token savings:   ${chalk.green(`-${tokenSavings.toLocaleString()}`)} (${tokenSavingsPercent}%)`);
+
+  const sizeSavings = jsonSize - matrixSize;
+  const sizeSavingsPercent = ((sizeSavings / jsonSize) * 100).toFixed(1);
+  console.log(`  Size savings:    ${chalk.green(`-${formatBytes(sizeSavings)}`)} (${sizeSavingsPercent}%)`);
+  console.log();
+
+  // Verbose mode: Show rule breakdown
+  if (options.verbose) {
+    console.log(chalk.bold('Rule Breakdown:'));
+    console.log(`  Total rules:     ${chalk.cyan(matrixFile.rules.length)}`);
+    console.log(`  Avg tokens/rule: ${chalk.cyan(Math.round(matrixTokens / matrixFile.rules.length))}`);
+    console.log();
+  }
+
+  // Compression assessment
+  const compressionQuality = parseFloat(compressionRatio);
+  let assessment = '';
+  let assessmentColor = chalk.green;
+
+  if (compressionQuality >= 5) {
+    assessment = 'Excellent compression! (≥5:1 target met)';
+    assessmentColor = chalk.green.bold;
+  } else if (compressionQuality >= 3) {
+    assessment = 'Good compression (3-5:1)';
+    assessmentColor = chalk.yellow;
+  } else if (compressionQuality >= 2) {
+    assessment = 'Moderate compression (2-3:1)';
+    assessmentColor = chalk.yellow;
+  } else {
+    assessment = 'Low compression (<2:1)';
+    assessmentColor = chalk.red;
+  }
+
+  console.log(assessmentColor(`✓ ${assessment}`));
+  console.log();
+}
+
+/**
+ * Estimate token count using simple heuristics
+ * (Approximates GPT tokenization without needing tiktoken dependency)
+ */
+function estimateTokenCount(text: string): number {
+  // Simple estimation: ~4 characters per token for English text
+  // This is a rough approximation; actual tokenization varies
+  // For more accuracy, use tiktoken library
+
+  // Remove whitespace for better estimation
+  const trimmedText = text.replace(/\s+/g, ' ').trim();
+
+  // Count words and punctuation as separate tokens
+  const words = trimmedText.split(/\s+/).length;
+  const punctuation = (trimmedText.match(/[.,;:!?()[\]{}'"]/g) || []).length;
+
+  // Estimate: words + punctuation + special chars
+  return Math.ceil((words + punctuation) * 1.3);
+}
+
+/**
+ * Format bytes to human-readable string
+ */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}

package/core/plugins/kenaz/commands/Amelia.md

@@ -2,4 +2,4 @@ Execute `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/tools/se
 
 IMPORTANT: Run this command **foreground** (not background) with timeout=120000. Do NOT use background mode + sleep polling — session.js completes in <5s under normal conditions.
 
-Fallback (if session.js fails): Read `.specialist/Amelia/rule.yaml`, load files listed in `files:` by `override_priority` order.
+Fallback (if session.js fails): Read `${CLAUDE_PLUGIN_ROOT}/../../.specialist/Amelia/rule.yaml`, load files listed in `files:` by `override_priority` order.

package/core/plugins/kenaz/commands/Ansuz.md

@@ -12,16 +12,28 @@ ARGUMENTS 含 `[專案: X]` 或 `--project-path X` → PROJECT_PATH = X，下方
 
 ## 每件工作的做法
 - **自己做**：小而明確的修正（約 30 行內、單一檔案或少數檔案）→ 直接改，跑最近的測試，提交。
-- **開卡派工**：中型、可平行、或高風險路徑的工作 → `task-api.js create` 寫清楚驗收條件，再派 subagent（細節讀 `.specialist/Ansuz/RULES.md` 的 Dispatch）。
+- **開卡派工**：中型、可平行、或高風險路徑的工作：
+  1. 用 `kenaz_task_create` 開卡（`projectPath` = 目前專案；寫清楚 requirements、acceptance criteria、scope paths）。查卡、改狀態用 `kenaz_task_list` / `kenaz_task_get` / `kenaz_task_update`。
+  2. 產生派工內容：`node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent`（加 `--project-path`；Codex 加 `--harness=codex`）。把輸出 JSON 的 `promptText` 交給 subagent，`agentParams` 照用（模型不要自己換）。
+  3. subagent 在 worktree 裡改完並 commit；你驗證後合併。
 - 開卡前先確認 scope 與驗收條件對準真正的問題，不要照著錯的假設派工。
 
 ## 驗證（合併前一定做，強度跟風險相稱）
 - 走**真實路徑**：實際執行會被使用者用到的那條路（真的安裝、真的啟動、真的收發訊息），不只看單元測試。
 - 有**對照組**：證明測試在舊程式上會失敗，或修改前後結果不同。
 - subagent 回報「未驗證」的項目，由你補驗或明講仍未驗證。
-- 合併用 `.specialist/Ansuz/tools/verify-and-land.js` 或 `git merge` 後跑相關測試；Rust 測試只走 `npm run test:rust` / `dev/scripts/rust-verify-worktree.js`。
+- 合併：`git merge` 後跑相關測試（或 `node "${CLAUDE_PLUGIN_ROOT}/hooks/core-resolve.js" .specialist/Ansuz/tools/verify-and-land.js`），用這個專案自己的測試指令。
+- 只在 Kenaz 核心 repo 本身：Rust 測試走 `npm run test:rust` / `dev/scripts/rust-verify-worktree.js`。
 
 ## 回報
 用用戶的語言。說清楚：做了什麼、怎麼驗證的、還有什麼沒驗證或需要用戶決定。不說「應該可以」。
 
-需要更多規則時（用戶授權自主、派工前、合併前）讀 `.specialist/Ansuz/RULES.md`。
+## Kenaz 本身出問題時：先回報再繞過（wish / field report）
+Kenaz 的工具、hook、安裝、peer 訊息、派工擋住或拖慢工作時（指令失敗、回傳錯的資料、少了能力、行為不如預期），**繞過之前**先呼叫 `kenaz_wish_create`。scope=kenaz 的 wish 會自動送到 Kenaz 團隊成為 field report。
+- `projectPath`：目前專案路徑；`scope`：`kenaz`（Kenaz 本身的問題）或 `project`（只跟這個專案有關）
+- `wish_type`：`bug`（壞了）／`feature`（缺能力，內容寫：需求、現在哪裡不夠、建議做法、還有誰受益）／`question`
+- `content`：一行重現步驟 + 預期 vs 實際 + 版本（`npx kenaz doctor` 那幾行）；附上 session id。不要貼金鑰或 token。
+- 一個問題只報一次；報完照常用替代做法把工作完成，並在回報裡告訴用戶已送出 wish。
+- 用戶直接說「回報這個問題」時也用同一個工具（`source`=`user`）。
+
+需要更多規則時（用戶授權自主、派工前、合併前）讀 `${CLAUDE_PLUGIN_ROOT}/../../.specialist/Ansuz/RULES.md`。