kenaz 0.0.0-stage → 0.3.2

package/core/.failure/tools/check_bom.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * BOM Checker Tool (for CI/CD and pre-commit hooks)
+ *
+ * Usage:
+ *   node check_bom.js <file_path>           # Check single file
+ *   node check_bom.js <dir_path> --recursive # Check all JSON files in directory
+ *
+ * Exit codes:
+ *   0 - No BOM found
+ *   1 - BOM detected in one or more files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const targetPath = args[0];
+const recursive = args.includes('--recursive');
+
+if (!targetPath) {
+  console.error('❌ Usage: node check_bom.js <file_path> [--recursive]');
+  process.exit(1);
+}
+
+let filesWithBOM = [];
+let filesChecked = 0;
+
+/**
+ * Check if a file has BOM
+ */
+function checkFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    filesChecked++;
+
+    if (content.charCodeAt(0) === 0xFEFF) {
+      filesWithBOM.push(filePath);
+      return true;
+    }
+    return false;
+  } catch (error) {
+    console.error(`⚠️  Error reading ${filePath}:`, error.message);
+    return false;
+  }
+}
+
+/**
+ * Recursively check all JSON files in a directory
+ */
+function checkDirectory(dirPath) {
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      if (recursive) {
+        // Skip node_modules, .git, etc.
+        if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          checkDirectory(fullPath);
+        }
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.json')) {
+      checkFile(fullPath);
+    }
+  }
+}
+
+// Main execution
+try {
+  const stats = fs.statSync(targetPath);
+
+  if (stats.isFile()) {
+    checkFile(targetPath);
+  } else if (stats.isDirectory()) {
+    checkDirectory(targetPath);
+  } else {
+    console.error('❌ Invalid path:', targetPath);
+    process.exit(1);
+  }
+
+  // Report results
+  console.log(`\n📊 Checked ${filesChecked} file(s)`);
+
+  if (filesWithBOM.length > 0) {
+    console.error(`\n❌ BOM detected in ${filesWithBOM.length} file(s):\n`);
+    filesWithBOM.forEach(file => {
+      console.error(`   - ${file}`);
+    });
+    console.error('\n💡 Fix with: node .failure/tools/remove_bom.js <file_path>');
+    process.exit(1);
+  } else {
+    console.log('\n✅ No BOM found in any files');
+    process.exit(0);
+  }
+} catch (error) {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+}

package/core/.failure/tools/check_failures.ps1

@@ -0,0 +1,387 @@
+# check_failures.ps1
+# 檢查當前任務是否匹配已知失敗模式的腳本
+
+<#
+.SYNOPSIS
+    檢查任務是否匹配已知的失敗模式
+
+.DESCRIPTION
+    此腳本根據任務類型、scope_paths 或關鍵詞搜尋相關失敗記錄，
+    輸出預防檢查清單和解決方案參考。
+
+.PARAMETER TaskID
+    任務 ID（如 TASK_077），會從 TASK_QUEUE.json 載入任務詳情
+
+.PARAMETER AgentType
+    Agent 類型（developer, backend, frontend, designer, qa, sre）
+
+.PARAMETER ScopePath
+    任務的 scope_paths（如 "dev/pipeline/"）
+
+.PARAMETER Keywords
+    搜尋關鍵詞（用逗號分隔）
+
+.PARAMETER Category
+    失敗分類過濾（agent_execution, code_quality, architecture, pipeline, data_integrity）
+
+.PARAMETER Severity
+    嚴重程度過濾（critical, high, medium, low）
+
+.PARAMETER Help
+    顯示幫助訊息
+
+.EXAMPLE
+    .\check_failures.ps1 -TaskID "TASK_077"
+    檢查特定任務的失敗模式
+
+.EXAMPLE
+    .\check_failures.ps1 -AgentType "developer" -ScopePath "dev/pipeline/"
+    檢查特定類型和路徑的失敗模式
+
+.EXAMPLE
+    .\check_failures.ps1 -Keywords "JSON,BOM,encoding"
+    根據關鍵詞搜尋失敗記錄
+#>
+
+param(
+    [Parameter(Mandatory=$false)]
+    [string]$TaskID,
+
+    [Parameter(Mandatory=$false)]
+    [ValidateSet("developer", "backend", "frontend", "designer", "qa", "sre", "architect")]
+    [string]$AgentType,
+
+    [Parameter(Mandatory=$false)]
+    [string]$ScopePath,
+
+    [Parameter(Mandatory=$false)]
+    [string]$Keywords,
+
+    [Parameter(Mandatory=$false)]
+    [ValidateSet("agent_execution", "code_quality", "architecture", "pipeline", "data_integrity")]
+    [string]$Category,
+
+    [Parameter(Mandatory=$false)]
+    [ValidateSet("critical", "high", "medium", "low")]
+    [string]$Severity,
+
+    [Parameter(Mandatory=$false)]
+    [switch]$Help
+)
+
+# ============================================================
+# 常量定義
+# ============================================================
+$FAILURE_ROOT = Join-Path (Split-Path $PSScriptRoot -Parent) ""
+$INDEX_FILE = Join-Path $FAILURE_ROOT "INDEX.yaml"
+$TASK_QUEUE_FILE = "dev/pipeline/TASK_QUEUE.json"
+
+$CATEGORY_PATHS = @{
+    "agent_execution" = "agent-execution"
+    "code_quality" = "code-quality"
+    "architecture" = "architecture"
+    "pipeline" = "pipeline"
+    "data_integrity" = "data-integrity"
+}
+
+$SEVERITY_ICONS = @{
+    "critical" = "🔴"
+    "high" = "🟠"
+    "medium" = "🟡"
+    "low" = "🟢"
+}
+
+# ============================================================
+# 函數定義
+# ============================================================
+
+function Show-Help {
+    Write-Host @"
+🔍 Failure Pattern Checker
+
+使用方式:
+  .\check_failures.ps1 -TaskID <id>              # 檢查特定任務
+  .\check_failures.ps1 -AgentType <type>         # 檢查特定 Agent 類型
+  .\check_failures.ps1 -ScopePath <path>         # 檢查特定路徑
+  .\check_failures.ps1 -Keywords <keywords>      # 關鍵詞搜尋
+
+參數:
+  -TaskID      任務 ID（會從 TASK_QUEUE.json 載入詳情）
+  -AgentType   Agent 類型 (developer, backend, frontend, designer, qa, sre)
+  -ScopePath   任務的 scope_paths（如 "dev/pipeline/"）
+  -Keywords    搜尋關鍵詞（用逗號分隔）
+  -Category    失敗分類過濾
+  -Severity    嚴重程度過濾
+  -Help        顯示此幫助訊息
+
+範例:
+  .\check_failures.ps1 -TaskID "TASK_077"
+  .\check_failures.ps1 -AgentType "developer" -ScopePath "dev/pipeline/"
+  .\check_failures.ps1 -Keywords "JSON,BOM"
+  .\check_failures.ps1 -Category "pipeline" -Severity "critical"
+
+相關資源:
+  - 失敗記錄索引: .failure/INDEX.yaml
+  - 任務佇列: dev/pipeline/TASK_QUEUE.json
+"@
+    exit 0
+}
+
+function Get-TaskDetails {
+    param([string]$TaskID)
+
+    if (-not (Test-Path $TASK_QUEUE_FILE)) {
+        Write-Warning "⚠️  TASK_QUEUE.json not found, using parameters only"
+        return $null
+    }
+
+    try {
+        $queue = Get-Content $TASK_QUEUE_FILE -Raw | ConvertFrom-Json
+        $task = $queue.tasks | Where-Object { $_.id -eq $TaskID }
+
+        if (-not $task) {
+            Write-Warning "⚠️  Task $TaskID not found in queue"
+            return $null
+        }
+
+        return $task
+    } catch {
+        Write-Warning "⚠️  Failed to parse TASK_QUEUE.json: $_"
+        return $null
+    }
+}
+
+function Get-FailureRecords {
+    if (-not (Test-Path $INDEX_FILE)) {
+        Write-Error "❌ INDEX.yaml not found at: $INDEX_FILE"
+        exit 1
+    }
+
+    $records = @()
+
+    # 遍歷所有分類目錄
+    foreach ($cat in $CATEGORY_PATHS.Keys) {
+        $categoryDir = Join-Path $FAILURE_ROOT $CATEGORY_PATHS[$cat]
+
+        if (-not (Test-Path $categoryDir)) {
+            continue
+        }
+
+        # 讀取所有 .yaml 文件
+        $yamlFiles = Get-ChildItem -Path $categoryDir -Filter "*.yaml" -File
+
+        foreach ($file in $yamlFiles) {
+            try {
+                $content = Get-Content $file.FullName -Raw
+
+                # 簡單解析 YAML（提取關鍵欄位）
+                $id = if ($content -match 'id:\s*"([^"]+)"') { $matches[1] } else { "" }
+                $category = if ($content -match 'category:\s*"([^"]+)"') { $matches[1] } else { $cat }
+                $severity = if ($content -match 'severity:\s*"([^"]+)"') { $matches[1] } else { "unknown" }
+                $title = if ($content -match '# \[([^\]]+)\] (.+)') { $matches[2] } else { $file.BaseName }
+
+                $records += [PSCustomObject]@{
+                    ID = $id
+                    Category = $category
+                    Severity = $severity
+                    Title = $title
+                    FilePath = $file.FullName
+                    Content = $content
+                }
+            } catch {
+                Write-Warning "⚠️  Failed to parse $($file.Name): $_"
+            }
+        }
+    }
+
+    return $records
+}
+
+function Test-FailureMatch {
+    param(
+        [object]$Record,
+        [hashtable]$Filters
+    )
+
+    # 分類過濾
+    if ($Filters.Category -and $Record.Category -ne $Filters.Category) {
+        return $false
+    }
+
+    # 嚴重程度過濾
+    if ($Filters.Severity -and $Record.Severity -ne $Filters.Severity) {
+        return $false
+    }
+
+    # Agent 類型匹配
+    if ($Filters.AgentType) {
+        # 檢查失敗記錄中是否提到該 agent_type
+        $agentMatch = $Record.Content -match $Filters.AgentType
+        if (-not $agentMatch) {
+            return $false
+        }
+    }
+
+    # Scope 路徑匹配
+    if ($Filters.ScopePath) {
+        # 檢查失敗記錄中是否提到該路徑
+        $pathMatch = $Record.Content -match [regex]::Escape($Filters.ScopePath)
+        if (-not $pathMatch) {
+            return $false
+        }
+    }
+
+    # 關鍵詞匹配
+    if ($Filters.Keywords) {
+        $keywordList = $Filters.Keywords -split ','
+        $matched = $false
+
+        foreach ($keyword in $keywordList) {
+            if ($Record.Content -match [regex]::Escape($keyword.Trim())) {
+                $matched = $true
+                break
+            }
+        }
+
+        if (-not $matched) {
+            return $false
+        }
+    }
+
+    return $true
+}
+
+function Show-FailureRecord {
+    param([object]$Record)
+
+    $icon = $SEVERITY_ICONS[$Record.Severity]
+    Write-Host "`n$icon [$($Record.ID)] $($Record.Title)" -ForegroundColor Cyan
+    Write-Host "   分類: $($Record.Category) | 嚴重程度: $($Record.Severity)" -ForegroundColor Gray
+
+    # 提取預防措施
+    if ($Record.Content -match '## 預防措施(.+?)(?=##|$)') {
+        $prevention = $matches[1].Trim()
+
+        # 提取檢查清單
+        if ($prevention -match '### 檢查清單(.+?)(?=###|$)') {
+            $checklist = $matches[1].Trim()
+            Write-Host "`n   📋 預防檢查清單:" -ForegroundColor Yellow
+            $checklistItems = $checklist -split "`n" | Where-Object { $_ -match '- \[' }
+            foreach ($item in $checklistItems) {
+                Write-Host "      $item" -ForegroundColor White
+            }
+        }
+    }
+
+    # 提取解決方案
+    if ($Record.Content -match '## 解決方案(.+?)(?=##|$)') {
+        $solution = $matches[1].Trim()
+        Write-Host "`n   💡 解決方案參考:" -ForegroundColor Yellow
+        $solutionLines = $solution -split "`n" | Select-Object -First 3
+        foreach ($line in $solutionLines) {
+            if ($line.Trim()) {
+                Write-Host "      $($line.Trim())" -ForegroundColor White
+            }
+        }
+        Write-Host "      （詳見: $($Record.FilePath)）" -ForegroundColor Gray
+    }
+}
+
+# ============================================================
+# 主程序
+# ============================================================
+
+if ($Help) {
+    Show-Help
+}
+
+Write-Host "🔍 Failure Pattern Checker" -ForegroundColor Cyan
+Write-Host "=========================`n" -ForegroundColor Cyan
+
+# 如果提供了 TaskID，載入任務詳情
+$task = $null
+if ($TaskID) {
+    Write-Host "📋 載入任務: $TaskID" -ForegroundColor Yellow
+    $task = Get-TaskDetails -TaskID $TaskID
+
+    if ($task) {
+        Write-Host "   Agent Type: $($task.agent_type)" -ForegroundColor Gray
+        Write-Host "   Scope Paths: $($task.scope_paths -join ', ')" -ForegroundColor Gray
+
+        # 自動填充參數
+        if (-not $AgentType) { $AgentType = $task.agent_type }
+        if (-not $ScopePath -and $task.scope_paths) { $ScopePath = $task.scope_paths[0] }
+    }
+}
+
+# 建立過濾器
+$filters = @{}
+if ($Category) { $filters.Category = $Category }
+if ($Severity) { $filters.Severity = $Severity }
+if ($AgentType) { $filters.AgentType = $AgentType }
+if ($ScopePath) { $filters.ScopePath = $ScopePath }
+if ($Keywords) { $filters.Keywords = $Keywords }
+
+# 顯示搜尋條件
+Write-Host "`n🔎 搜尋條件:" -ForegroundColor Yellow
+if ($filters.Count -eq 0) {
+    Write-Host "   （無過濾條件，顯示所有失敗記錄）" -ForegroundColor Gray
+} else {
+    foreach ($key in $filters.Keys) {
+        Write-Host "   $key`: $($filters[$key])" -ForegroundColor Gray
+    }
+}
+
+# 載入所有失敗記錄
+Write-Host "`n📂 載入失敗記錄..." -ForegroundColor Cyan
+$allRecords = Get-FailureRecords
+Write-Host "   找到 $($allRecords.Count) 筆失敗記錄" -ForegroundColor Gray
+
+# 過濾匹配的記錄
+$matchedRecords = @()
+foreach ($record in $allRecords) {
+    if (Test-FailureMatch -Record $record -Filters $filters) {
+        $matchedRecords += $record
+    }
+}
+
+# 顯示結果
+Write-Host "`n📊 匹配結果: $($matchedRecords.Count) 筆" -ForegroundColor Green
+
+if ($matchedRecords.Count -eq 0) {
+    Write-Host "`n✅ 未發現相關失敗模式" -ForegroundColor Green
+    Write-Host "   建議繼續進行任務，但保持警覺" -ForegroundColor Gray
+    exit 0
+}
+
+# 按嚴重程度排序
+$sortedRecords = $matchedRecords | Sort-Object @{Expression={
+    switch ($_.Severity) {
+        "critical" { 1 }
+        "high" { 2 }
+        "medium" { 3 }
+        "low" { 4 }
+        default { 5 }
+    }
+}}
+
+# 顯示匹配的失敗記錄
+Write-Host "`n⚠️  發現以下相關失敗模式，請注意預防:" -ForegroundColor Yellow
+
+foreach ($record in $sortedRecords) {
+    Show-FailureRecord -Record $record
+}
+
+# 總結建議
+Write-Host "`n" + ("="*60) -ForegroundColor Cyan
+Write-Host "📌 建議行動:" -ForegroundColor Yellow
+Write-Host "  1. 仔細閱讀上述失敗記錄的預防檢查清單" -ForegroundColor White
+Write-Host "  2. 在執行任務前完成所有相關檢查" -ForegroundColor White
+Write-Host "  3. 參考解決方案避免重複失敗" -ForegroundColor White
+Write-Host "  4. 如遇到新的失敗模式，執行 .\log_failure.ps1 記錄" -ForegroundColor White
+Write-Host "`n相關資源:" -ForegroundColor Yellow
+Write-Host "  - 規則系統: .rule/INDEX.yaml" -ForegroundColor Gray
+Write-Host "  - Agent 工作流程: .rule/general/agent-workflow.yaml" -ForegroundColor Gray
+Write-Host "  - 失敗記錄索引: .failure/INDEX.yaml" -ForegroundColor Gray
+
+exit 0

package/core/.failure/tools/fix_json.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * JSON Fixer Tool
+ *
+ * Usage: node fix_json.js <file_path>
+ *
+ * Removes BOM, validates JSON, and reformats the file.
+ * This is an all-in-one tool for fixing common JSON issues.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Get file path from command line arguments
+const filePath = process.argv[2];
+
+if (!filePath) {
+  console.error('❌ Usage: node fix_json.js <file_path>');
+  process.exit(1);
+}
+
+if (!fs.existsSync(filePath)) {
+  console.error(`❌ File not found: ${filePath}`);
+  process.exit(1);
+}
+
+try {
+  // Read file content
+  let content = fs.readFileSync(filePath, 'utf8');
+
+  // Check and remove BOM
+  if (content.charCodeAt(0) === 0xFEFF) {
+    content = content.slice(1);
+    console.log('⚠️  BOM detected and removed');
+  }
+
+  // Validate JSON
+  const parsed = JSON.parse(content);
+
+  // Reformat and write back (ensures consistent formatting)
+  const formatted = JSON.stringify(parsed, null, 2);
+  fs.writeFileSync(filePath, formatted, 'utf8');
+
+  console.log('✅ JSON fixed and validated:', filePath);
+} catch (error) {
+  console.error('❌ Failed to fix JSON:', filePath);
+  console.error('   Error:', error.message);
+
+  // Provide helpful hints
+  if (error.message.includes('position')) {
+    const position = error.message.match(/position (\d+)/);
+    if (position) {
+      console.error(`   Check characters around position ${position[1]}`);
+    }
+  }
+
+  process.exit(1);
+}