clckernel 1.2.13 → 1.2.18

package/tools/audit.js

@@ -2,7 +2,9 @@
 /**
  * Modular Audit Orchestrator — JS
  * Discovers check_*.js guard scripts at runtime, runs each with graceful
- * degradation, and generates an English audit report (05-audit-report.md).
+ * degradation, categorizes results into the 4 Canonical RDD Lenses,
+ * and generates both an English audit report (05-audit-report.md) and
+ * an immutable, machine-readable audit receipt (audit-receipt.json).
  * Self-contained: uses only Node.js built-ins.
  */
 
@@ -11,10 +13,59 @@ const path = require('path');
 
 const REPO_ROOT = path.resolve(__dirname, '..');
 
+// ── 4 Canonical RDD Lenses Mapping ──────────────────────────────────────────
+
+const LENS_MAP = {
+  // Correctness
+  verify_tdd: 'correctness',
+  check_scope: 'correctness',
+  check_a11y: 'correctness',
+  check_api_contracts: 'correctness',
+  check_openapi_drift: 'correctness',
+  pytest: 'correctness',
+  tsc: 'correctness',
+  lint: 'correctness',
+  ruff: 'correctness',
+  // Security
+  scan_secrets: 'security',
+  docker_guard: 'security',
+  redis_guard: 'security',
+  celery_guard: 'security',
+  postgres_guard: 'security',
+  // Architecture
+  check_architecture: 'architecture',
+  check_custom: 'architecture',
+  check_ui_reuse: 'architecture',
+  check_symlinks: 'architecture',
+  check_hitl: 'architecture',
+  check_domain_data: 'architecture',
+  check_migrations: 'architecture',
+  graphify: 'architecture',
+  gentle_ai_review: 'architecture',
+  // Performance
+  check_db_efficiency: 'performance',
+  check_performance: 'performance',
+  check_seo: 'performance',
+  check_responsive: 'performance',
+  check_storybook: 'performance',
+  check_test_calendar_sync: 'performance',
+  check_observability: 'performance',
+};
+
+function getLensForGuard(guardName) {
+  try {
+    const { lensFor } = require('../src/catalog');
+    const lens = lensFor(guardName);
+    if (lens) return lens;
+  } catch {}
+  return LENS_MAP[guardName] || 'architecture';
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function getActiveSddDir() {
-  const sddsDir = path.join(REPO_ROOT, 'sdds');
+function getActiveSddDir(baseDir) {
+  const root = baseDir || REPO_ROOT;
+  const sddsDir = path.join(root, 'sdds');
   if (!fs.existsSync(sddsDir)) {
     fs.mkdirSync(sddsDir, { recursive: true });
   }
@@ -25,7 +76,7 @@ function getActiveSddDir() {
   if (dirs.length > 0) {
     return path.join(sddsDir, dirs[0]);
   }
-  const defaultDir = path.join(sddsDir, 'frontend-audit');
+  const defaultDir = path.join(sddsDir, 'audit-run');
   fs.mkdirSync(defaultDir, { recursive: true });
   return defaultDir;
 }
@@ -34,8 +85,9 @@ function getActiveSddDir() {
  * Discover all check_*.js guard scripts in the tools/ directory.
  * Returns absolute paths sorted alphabetically for deterministic ordering.
  */
-function discoverGuards() {
-  const toolsDir = __dirname;
+function discoverGuards(toolsDirParam) {
+  const toolsDir = toolsDirParam || __dirname;
+  if (!fs.existsSync(toolsDir)) return [];
   return fs.readdirSync(toolsDir)
     .filter(f => (f.startsWith('check_') || f.startsWith('scan_')) && f.endsWith('.js') && f !== path.basename(__filename || 'audit.js'))
     .sort()
@@ -50,12 +102,13 @@ function discoverGuards() {
  */
 async function runGuard(guardPath, targetDir) {
   const guardName = path.basename(guardPath, '.js');
+  const lens = getLensForGuard(guardName);
   try {
     const mod = require(guardPath);
     const fn = typeof mod === 'function' ? mod : Object.values(mod)[0];
     if (typeof fn !== 'function') {
       return {
-        exitCode: 0, skipped: true, name: guardName,
+        exitCode: 0, skipped: true, name: guardName, lens,
         data: { message: `Guard ${guardName} does not export a function` },
       };
     }
@@ -65,11 +118,12 @@ async function runGuard(guardPath, targetDir) {
       exitCode: result.exitCode || 0,
       skipped: Boolean(result.skipped),
       name: result.name || guardName,
+      lens,
       data: result.data || result,
     };
   } catch (e) {
     return {
-      exitCode: 0, skipped: true, name: guardName,
+      exitCode: 0, skipped: true, name: guardName, lens,
       data: { message: `Guard unavailable: ${e.message}` },
     };
   }
@@ -84,8 +138,9 @@ function formatGuardSection(name, result) {
   const lines = [];
   const icon = result.skipped ? '⏭️' : result.exitCode === 0 ? '✅' : '❌';
   const status = result.skipped ? 'SKIPPED' : result.exitCode === 0 ? 'PASSED' : 'FAILED';
+  const lensBadge = (result.lens || 'architecture').toUpperCase();
 
-  lines.push(`### ${icon} ${name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase())} — ${status}`);
+  lines.push(`### ${icon} ${name.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase())} [${lensBadge}] — ${status}`);
   lines.push('');
 
   if (result.skipped) {
@@ -96,15 +151,21 @@ function formatGuardSection(name, result) {
     lines.push(`> ${result.data?.message || 'Issues found'}`);
     lines.push('');
     const violations = result.data?.violations || result.data?.findings || {};
-    const files = Object.keys(violations);
-    if (files.length > 0) {
-      for (const file of files) {
-        const items = violations[file];
-        for (const item of items) {
-          const loc = item.lineNo ? ` (line ${item.lineNo})` : '';
-          const label = item.label || item.rule || item.rule || item.module || '';
-          const msg = item.message || item.reason || '';
-          lines.push(`- \`${file}\`${loc}: ${label ? `[${label}] ` : ''}${msg}`);
+    if (Array.isArray(violations)) {
+      for (const item of violations) {
+        lines.push(`- ${item.file ? `\`${item.file}\`: ` : ''}${item.message || item.reason || JSON.stringify(item)}`);
+      }
+    } else {
+      const files = Object.keys(violations);
+      if (files.length > 0) {
+        for (const file of files) {
+          const items = violations[file];
+          for (const item of items) {
+            const loc = item.lineNo ? ` (line ${item.lineNo})` : '';
+            const label = item.label || item.rule || item.module || '';
+            const msg = item.message || item.reason || '';
+            lines.push(`- \`${file}\`${loc}: ${label ? `[${label}] ` : ''}${msg}`);
+          }
         }
       }
     }
@@ -127,8 +188,8 @@ function generateReport(results, sddDir) {
 
   sections.push(`# Code Audit Report: ${taskName}`);
   sections.push('');
-  sections.push('> **Note for reviewer:** This report summarizes security, architecture, accessibility,');
-  sections.push('> API contracts, performance, UI reuse, and testing coverage to facilitate review.');
+  sections.push('> **Review-Driven Development (RDD) Report:**');
+  sections.push('> Segmented across the 4 Canonical Review Lenses (Correctness, Security, Architecture, Performance).');
   sections.push('');
   sections.push('---');
   sections.push('');
@@ -144,9 +205,26 @@ function generateReport(results, sddDir) {
   sections.push('---');
   sections.push('');
 
-  for (const result of results) {
-    sections.push(formatGuardSection(result.name, result));
+  const lenses = ['correctness', 'security', 'architecture', 'performance'];
+  const lensHeaders = {
+    correctness: '## 🎯 Correctness Lens',
+    security: '## 🛡️ Security Lens',
+    architecture: '## 🏛️ Architecture Lens',
+    performance: '## ⚡ Performance Lens',
+  };
+
+  for (const lens of lenses) {
+    sections.push(lensHeaders[lens]);
     sections.push('');
+    const lensResults = results.filter(r => r.lens === lens);
+    if (lensResults.length === 0) {
+      sections.push('_No guards registered for this lens._\n');
+    } else {
+      for (const result of lensResults) {
+        sections.push(formatGuardSection(result.name, result));
+        sections.push('');
+      }
+    }
     sections.push('---');
     sections.push('');
   }
@@ -154,33 +232,107 @@ function generateReport(results, sddDir) {
   return sections.join('\n');
 }
 
+/**
+ * Generate an immutable machine-readable audit receipt (audit-receipt.json).
+ */
+function generateReceipt(results, targetDir) {
+  const lenses = ['correctness', 'security', 'architecture', 'performance'];
+  const lensSummary = {};
+
+  let hasFailure = false;
+  for (const lens of lenses) {
+    const lensResults = results.filter(r => r.lens === lens);
+    const passed = lensResults.filter(r => !r.skipped && r.exitCode === 0).length;
+    const failed = lensResults.filter(r => !r.skipped && r.exitCode !== 0).length;
+    const skipped = lensResults.filter(r => r.skipped).length;
+    if (failed > 0) hasFailure = true;
+
+    lensSummary[lens] = {
+      status: failed > 0 ? 'FAILED' : 'PASSED',
+      passed,
+      failed,
+      skipped,
+    };
+  }
+
+  let commitHash = 'UNKNOWN';
+  let gentleAiDetected = false;
+  try {
+    const { execSync } = require('child_process');
+    commitHash = execSync('git rev-parse HEAD', { cwd: targetDir, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }).trim();
+  } catch {}
+
+  try {
+    const { execSync } = require('child_process');
+    execSync('which gentle-ai', { stdio: 'ignore' });
+    gentleAiDetected = true;
+  } catch {}
+
+  return {
+    $schema: 'https://clckernel.dev/schemas/audit-receipt.v1.json',
+    contract: 'clckernel.audit-receipt/v1',
+    timestamp: new Date().toISOString(),
+    commitHash,
+    verdict: hasFailure ? 'FAILED' : 'PASSED',
+    lenses: lensSummary,
+    generator: 'clckernel',
+    gentle_ai: {
+      compatible: true,
+      rdd_ready: true,
+      cli_installed: gentleAiDetected,
+    },
+  };
+}
+
 // ── Console Summary ──────────────────────────────────────────────────────────
 
-function printSummary(results, reportPath) {
+function printSummary(results, reportPath, receiptPath) {
   console.log('\n=================================================================');
-  console.log('  CLC FORGE — EDUCATIONAL AUDIT SUMMARY');
+  console.log('  CLC KERNEL — 4-LENS RDD AUDIT SUMMARY');
   console.log('=================================================================\n');
 
-  for (const result of results) {
-    const icon = result.skipped ? '⏭️' : result.exitCode === 0 ? '✅' : '❌';
-    const label = result.name.replace(/_/g, ' ');
-    const msg = result.data?.message || '';
-    console.log(`  ${icon} ${label}: ${msg}`);
+  const lenses = ['correctness', 'security', 'architecture', 'performance'];
+  const lensLabels = {
+    correctness: '🎯 CORRECTNESS LENS',
+    security: '🛡️ SECURITY LENS',
+    architecture: '🏛️ ARCHITECTURE LENS',
+    performance: '⚡ PERFORMANCE LENS',
+  };
+
+  for (const lens of lenses) {
+    const lensResults = results.filter(r => r.lens === lens);
+    console.log(`  ${lensLabels[lens]}:`);
+    if (lensResults.length === 0) {
+      console.log('     — No guards active for this lens');
+    } else {
+      for (const result of lensResults) {
+        const icon = result.skipped ? '⏭️' : result.exitCode === 0 ? '✅' : '❌';
+        const label = result.name.replace(/_/g, ' ');
+        const msg = result.data?.message || (result.exitCode === 0 ? 'Passed' : 'Failed');
+        console.log(`     ${icon} ${label}: ${msg}`);
+      }
+    }
+    console.log('');
   }
 
-  console.log(`\n📄 Full report: ${reportPath}`);
+  console.log(`📄 Full report: ${reportPath}`);
+  if (receiptPath) {
+    console.log(`🧾 Audit receipt: ${receiptPath}`);
+  }
   console.log('=================================================================\n');
 }
 
 // ── Main ─────────────────────────────────────────────────────────────────────
 
 async function main(targetDir) {
-  const dir = targetDir || process.cwd();
-  const sddDir = getActiveSddDir();
+  const dir = targetDir ? path.resolve(targetDir) : process.cwd();
+  const sddDir = getActiveSddDir(dir);
 
-  console.log('\nRunning CLC Forge audit...\n');
+  console.log('\nRunning CLC Kernel audit...\n');
 
-  const guardPaths = discoverGuards();
+  const targetTools = path.join(dir, 'tools');
+  const toolsDir = fs.existsSync(targetTools) ? targetTools : __dirname;
+  const guardPaths = discoverGuards(toolsDir);
 
   if (guardPaths.length === 0) {
     console.log('No guard tools found in tools/. Nothing to audit.');
@@ -200,20 +352,27 @@ async function main(targetDir) {
   const reportPath = path.join(sddDir, '05-audit-report.md');
   fs.writeFileSync(reportPath, reportContent, 'utf-8');
 
+  // Generate receipt
+  const receipt = generateReceipt(results, dir);
+  const receiptPath = path.join(sddDir, 'audit-receipt.json');
+  fs.writeFileSync(receiptPath, JSON.stringify(receipt, null, 2) + '\n', 'utf-8');
+
   // Print summary
-  printSummary(results, reportPath);
+  printSummary(results, reportPath, receiptPath);
 
   // Exit with failure if any guard failed (not skipped)
   const hasFailure = results.some(r => !r.skipped && r.exitCode !== 0);
-  process.exit(hasFailure ? 1 : 0);
+  if (hasFailure) {
+    process.exit(1);
+  }
 }
 
 // Support both require() and direct execution
 if (require.main === module) {
   main(process.argv[2]).catch(err => {
     console.error(`Audit orchestrator error: ${err.message}`);
-    process.exit(0); // Graceful degradation
+    process.exit(1);
   });
 }
 
-module.exports = { main, getActiveSddDir, discoverGuards, runGuard };
+module.exports = { main, getActiveSddDir, discoverGuards, runGuard, generateReceipt };

package/tools/audit.py

@@ -17,6 +17,48 @@ import traceback
 
 REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
 
+# ── 4 Canonical RDD Lenses Mapping ──────────────────────────────────────────
+
+LENS_MAP = {
+    # Correctness
+    "verify_tdd": "correctness",
+    "check_scope": "correctness",
+    "check_a11y": "correctness",
+    "check_api_contracts": "correctness",
+    "check_openapi_drift": "correctness",
+    "pytest": "correctness",
+    "tsc": "correctness",
+    "lint": "correctness",
+    "ruff": "correctness",
+    # Security
+    "scan_secrets": "security",
+    "docker_guard": "security",
+    "redis_guard": "security",
+    "celery_guard": "security",
+    "postgres_guard": "security",
+    # Architecture
+    "check_architecture": "architecture",
+    "check_custom": "architecture",
+    "check_ui_reuse": "architecture",
+    "check_symlinks": "architecture",
+    "check_hitl": "architecture",
+    "check_domain_data": "architecture",
+    "check_migrations": "architecture",
+    "graphify": "architecture",
+    "gentle_ai_review": "architecture",
+    # Performance
+    "check_db_efficiency": "performance",
+    "check_performance": "performance",
+    "check_seo": "performance",
+    "check_responsive": "performance",
+    "check_storybook": "performance",
+    "check_test_calendar_sync": "performance",
+    "check_observability": "performance",
+}
+
+def get_lens(guard_name: str) -> str:
+    return LENS_MAP.get(guard_name, "architecture")
+
 
 # ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -87,12 +129,14 @@ def run_guard(guard_path: pathlib.Path, target_dir: str) -> dict:
             "exit_code": result.get("exit_code", 0),
             "skipped": bool(result.get("skipped", False)),
             "name": result.get("name", guard_name),
+            "lens": get_lens(guard_name),
             "data": result.get("data", result),
         }
 
     except Exception as exc:
         return {
             "exit_code": 0, "skipped": True, "name": guard_name,
+            "lens": get_lens(guard_name),
             "data": {"message": f"Guard unavailable: {exc}"},
         }
 
@@ -151,7 +195,7 @@ def _format_guard_section(name: str, result: dict) -> str:
 
 
 def generate_report(results: list[dict], sdd_dir: pathlib.Path) -> str:
-    """Generate the 05-audit-report.md from aggregated guard results."""
+    """Generate the 05-audit-report.md from aggregated guard results grouped by 4 RDD lenses."""
     task_name = sdd_dir.name
     passed = sum(1 for r in results if not r.get("skipped") and r.get("exit_code") == 0)
     failed = sum(1 for r in results if not r.get("skipped") and r.get("exit_code") != 0)
@@ -161,8 +205,8 @@ def generate_report(results: list[dict], sdd_dir: pathlib.Path) -> str:
     sections: list[str] = []
     sections.append(f"# Code Audit Report: {task_name}")
     sections.append("")
-    sections.append("> **Note for reviewer:** This report summarizes security, architecture,")
-    sections.append("> scope, migration safety, and TDD coverage to facilitate code review.")
+    sections.append("> **Review-Driven Development (RDD) Report:**")
+    sections.append("> Segmented across the 4 Canonical Review Lenses (Correctness, Security, Architecture, Performance).")
     sections.append("")
     sections.append("---")
     sections.append("")
@@ -178,39 +222,116 @@ def generate_report(results: list[dict], sdd_dir: pathlib.Path) -> str:
     sections.append("---")
     sections.append("")
 
-    for result in results:
-        sections.append(_format_guard_section(result.get("name", "unknown"), result))
+    lenses = ["correctness", "security", "architecture", "performance"]
+    headers = {
+        "correctness": "## 🎯 Correctness Lens",
+        "security": "## 🛡️ Security Lens",
+        "architecture": "## 🏛️ Architecture Lens",
+        "performance": "## ⚡ Performance Lens",
+    }
+
+    for lens in lenses:
+        sections.append(headers[lens])
         sections.append("")
+        lens_results = [r for r in results if r.get("lens") == lens]
+        if not lens_results:
+            sections.append("_No guards registered for this lens._\n")
+        else:
+            for result in lens_results:
+                sections.append(_format_guard_section(result.get("name", "unknown"), result))
+                sections.append("")
         sections.append("---")
         sections.append("")
 
     return "\n".join(sections)
 
 
+def generate_receipt(results: list[dict], target_dir: str) -> dict:
+    """Generate an immutable machine-readable audit receipt (audit-receipt.json)."""
+    import datetime
+
+    lenses = ["correctness", "security", "architecture", "performance"]
+    lens_summary = {}
+    has_failure = False
+
+    for lens in lenses:
+        lens_results = [r for r in results if r.get("lens") == lens]
+        passed = sum(1 for r in lens_results if not r.get("skipped") and r.get("exit_code") == 0)
+        failed = sum(1 for r in lens_results if not r.get("skipped") and r.get("exit_code") != 0)
+        skipped = sum(1 for r in lens_results if r.get("skipped"))
+        if failed > 0:
+            has_failure = True
+        lens_summary[lens] = {
+            "status": "FAILED" if failed > 0 else "PASSED",
+            "passed": passed,
+            "failed": failed,
+            "skipped": skipped,
+        }
+
+    commit_hash = "UNKNOWN"
+    try:
+        commit_hash = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"],
+            cwd=target_dir,
+            stderr=subprocess.DEVNULL,
+            encoding="utf-8"
+        ).strip()
+    except Exception:
+        pass
+
+    import shutil
+    gentle_ai_detected = shutil.which("gentle-ai") is not None
+
+    return {
+        "$schema": "https://clckernel.dev/schemas/audit-receipt.v1.json",
+        "contract": "clckernel.audit-receipt/v1",
+        "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "commitHash": commit_hash,
+        "verdict": "FAILED" if has_failure else "PASSED",
+        "lenses": lens_summary,
+        "generator": "clckernel",
+        "gentle_ai": {
+            "compatible": True,
+            "rdd_ready": True,
+            "cli_installed": gentle_ai_detected,
+        },
+    }
+
+
 # ── Console Summary ──────────────────────────────────────────────────────────
 
-def print_summary(results: list[dict], report_path: pathlib.Path) -> None:
+def print_summary(results: list[dict], report_path: pathlib.Path, receipt_path: pathlib.Path | None = None) -> None:
     """Print an educational summary to the terminal."""
     print("\n" + "=" * 65)
-    print("  CLC FORGE \u2014 EDUCATIONAL AUDIT SUMMARY")
+    print("  CLC KERNEL — 4-LENS RDD AUDIT SUMMARY")
     print("=" * 65 + "\n")
 
-    for result in results:
-        skipped = result.get("skipped", False)
-        exit_code = result.get("exit_code", 0)
-        name = result.get("name", "unknown").replace("_", " ")
-        msg = result.get("data", {}).get("message", "")
-
-        if skipped:
-            icon = "\u23ed\ufe0f"
-        elif exit_code == 0:
-            icon = "\u2705"
+    lenses = ["correctness", "security", "architecture", "performance"]
+    labels = {
+        "correctness": "🎯 CORRECTNESS LENS",
+        "security": "🛡️ SECURITY LENS",
+        "architecture": "🏛️ ARCHITECTURE LENS",
+        "performance": "⚡ PERFORMANCE LENS",
+    }
+
+    for lens in lenses:
+        lens_results = [r for r in results if r.get("lens") == lens]
+        print(f"  {labels[lens]}:")
+        if not lens_results:
+            print("     — No guards active for this lens")
         else:
-            icon = "\u274c"
-
-        print(f"  {icon} {name}: {msg}")
-
-    print(f"\n  Report: {report_path}")
+            for result in lens_results:
+                skipped = result.get("skipped", False)
+                exit_code = result.get("exit_code", 0)
+                name = result.get("name", "unknown").replace("_", " ")
+                msg = result.get("data", {}).get("message", "Passed" if exit_code == 0 else "Failed")
+                icon = "⏭️" if skipped else ("✅" if exit_code == 0 else "❌")
+                print(f"     {icon} {name}: {msg}")
+        print("")
+
+    print(f"📄 Full report: {report_path}")
+    if receipt_path:
+        print(f"🧾 Audit receipt: {receipt_path}")
     print("=" * 65 + "\n")
 
 
@@ -229,7 +350,7 @@ def main(target_dir: str | None = None) -> int:
         sdd_dir = sdds_dir / "audit-run"
         sdd_dir.mkdir(parents=True, exist_ok=True)
 
-    print(f"\nRunning CLC Forge audit for: {sdd_dir.name}\n")
+    print(f"\nRunning CLC Kernel audit for: {sdd_dir.name}\n")
 
     guard_paths = discover_guards(tools_dir)
 
@@ -253,8 +374,13 @@ def main(target_dir: str | None = None) -> int:
     report_path = sdd_dir / "05-audit-report.md"
     report_path.write_text(report_content, encoding="utf-8")
 
+    # Generate and write receipt
+    receipt = generate_receipt(results, dir_path)
+    receipt_path = sdd_dir / "audit-receipt.json"
+    receipt_path.write_text(json.dumps(receipt, indent=2) + "\n", encoding="utf-8")
+
     # Print summary
-    print_summary(results, report_path)
+    print_summary(results, report_path, receipt_path)
 
     # Exit with failure if any guard failed (not skipped)
     has_failure = any(
@@ -270,4 +396,4 @@ if __name__ == "__main__":
         sys.exit(main(target))
     except Exception:
         traceback.print_exc()
-        sys.exit(0)  # Graceful degradation
+        sys.exit(1)

package/tools/check_custom.js

@@ -7,7 +7,7 @@
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
-const { parseYaml, globToRegex } = require('../src/yaml.js');
+const { parseYaml, globToRegex } = require('./yaml.js');
 const check = async function checkCustom(targetDir) {
   const fs = require('fs');
   const path = require('path');

package/tools/check_hitl.js

@@ -22,10 +22,22 @@ const check = async function checkHitl(targetDir) {
   for (const sDir of searchDirs) {
     if (fs.existsSync(sDir)) {
       try {
-        const files = fs.readdirSync(sDir);
-        for (const file of files) {
-          if (file.endsWith('.md')) {
-            skillFiles.push(path.join(sDir, file));
+        const entries = fs.readdirSync(sDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isFile() && entry.name.endsWith('.md')) {
+            skillFiles.push(path.join(sDir, entry.name));
+          } else if (entry.isDirectory()) {
+            // Exclude framework CLI scaffolding and tool plugins
+            if (entry.name === 'clckernel_cli' || entry.name === 'clc_forge_cli' || entry.name === 'impeccable') {
+              continue;
+            }
+            const subDirPath = path.join(sDir, entry.name);
+            const subEntries = fs.readdirSync(subDirPath, { withFileTypes: true });
+            for (const sub of subEntries) {
+              if (sub.isFile() && sub.name.endsWith('.md')) {
+                skillFiles.push(path.join(subDirPath, sub.name));
+              }
+            }
           }
         }
       } catch {}