solidity-argus 0.2.0 → 0.3.0

package/skills/vulnerability-patterns/weird-tokens/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: weird-tokens
 description: Non-standard ERC20 behaviors, integration pitfalls, and token-handling safeguards.
+pattern_category: token-standard
+detection_rules:
+  - regex: 'IERC20\('
+    severity: Informational
+    confidence: Low
+    description: ERC20 integration point where non-standard token behavior may break assumptions
+  - regex: '\.approve\('
+    severity: Low
+    confidence: Low
+    description: approve usage requires allowance race and non-standard token handling checks
 ---
 <!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
 

package/skills/vulnerability-patterns/zero-address-misconfiguration/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: zero-address-misconfiguration
+description: "Critical addresses are set to address(0), causing hard reverts, fund loss paths, or permanently broken flows."
+category: vulnerability-pattern
+pattern_category: access-control
+source_url: "https://github.com/bailsec/BailSec"
+source_license: "CC0"
+imported_at: "2025-02-20T00:00:00Z"
+detection_rules:
+  - regex: "(set|update|initialize|constructor).*(address|receiver|collector|team).*=\\s*address\\(0\\)"
+    severity: "High"
+    description: "Administrative path allows writing a critical address to zero"
+  - regex: "transfer\\(address\\(0\\)|safeTransfer\\(address\\(0\\)"
+    severity: "Medium"
+    description: "Outbound transfer path can target zero address after misconfiguration"
+  - regex: 'address\(0\)'
+    severity: Medium
+    confidence: Low
+    description: Reference to zero address — potential missing zero-address validation
+---
+<!-- Source: BailSec audit reports (CC0) -->
+
+# Zero Address Misconfiguration Vulnerabilities
+
+## Overview
+Zero-address handling is an input validation and configuration integrity problem: critical system variables are set to `address(0)` even though downstream logic assumes a live recipient. In production this often appears in admin setters or constructor parameters for fee collectors, fallback receivers, team wallets, bridge modules, or reward sinks. The system usually works until one of these addresses is consumed by a transfer, mint, distribution, or callback path, then starts reverting in critical operations.
+
+This pattern is dangerous because it can be triggered accidentally (operator error), by weak deployment scripts, or after key compromise. It is also commonly missed in reviews because the setter itself may look harmless while the breakage happens in unrelated functions.
+
+## Common Patterns
+- Missing `require(newAddr != address(0))` in privileged setter functions.
+- Constructor checks differ from setter checks, so unsafe values are allowed in one path.
+- Protocol assumes a non-zero recipient in periodic distribution or epoch updates.
+- Emergency plans rely on setting an address to zero, but no explicit pause-mode logic exists.
+
+## Detection Heuristics
+- Trace every role-controlled address from write path to first transfer/mint usage.
+- Flag any critical address that can be set to zero without explicit documented semantics.
+- Check whether "zero means disabled" is consistently implemented across all read sites.
+- Verify deployment scripts and upgrade initializers enforce non-zero invariants.
+
+## Examples from Audits
+- Fee-aggregation routing where a primary aggregator could be set to zero, causing later fee forwarding to fail.
+- Fallback distribution receiver settable to zero, leading weekly distribution flow to revert.
+- Team emission address allowed to become zero, which can break epoch update and lock normal emissions.
+
+## Remediation
+Use strict non-zero validation in constructors, initializers, and all mutating setters for critical addresses. If zero has a valid "disabled" meaning, encode that explicitly with a separate boolean mode and guarded control flow; do not overload zero as a hidden state. Add invariant tests that assert all transfer sinks remain valid after governance actions and upgrades. During operations, enforce config guards in runbooks and monitoring so zero-address writes are blocked or alerted before they reach production.

package/src/agents/argus-prompt.ts

@@ -1,4 +1,3 @@
-
 export const ARGUS_PROMPT = `You are **Argus Panoptes**, the All-Seeing Guardian — an autonomous Solidity smart contract security auditor. You orchestrate a team of specialist subagents to conduct comprehensive security audits. Your mission is to identify vulnerabilities, logic flaws, and security risks in smart contracts with the precision and depth of a top-tier human auditor.
 
 ## IDENTITY & ROLE
@@ -23,6 +22,7 @@ Before analyzing code, understand the system.
   - Determine the "crown jewels" (e.g., user funds, admin privileges).
   - Map trust boundaries: Who is trusted? What external calls are made?
   - Define the scope: Which contracts are in scope? Which are out of scope?
+  - Use \`argus_proxy_detection\` to identify proxy/upgradeable patterns early.
   - **Key Questions**:
     - What is the intended business logic?
     - Who are the actors (users, admins, keepers)?
@@ -90,6 +90,8 @@ Prove the existence of vulnerabilities.
 - **Actions**:
   - Delegate to **@sentinel** to write and run reproduction tests using \`argus_forge_test\`.
   - If a function is complex or handles math/assets, delegate to **@sentinel** to run \`argus_forge_fuzz\`.
+  - Use \`argus_forge_coverage\` to measure test coverage gaps and prioritize untested code paths.
+  - Use \`argus_gas_analysis\` to identify gas-intensive hotspots that may indicate inefficient or vulnerable logic.
   - Verify that the fix (remediation) actually works.
   - Do not report a "Critical" or "High" issue without a Proof of Concept (PoC) or strong reasoning if a PoC is impossible.
   - **Techniques**:
@@ -181,14 +183,14 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
 - \`Task\` — for delegating to subagents
 
 **Only subagents can use (via Task delegation):**
-- \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\` → delegate to **sentinel**
-- \`argus_analyze_contract\`, \`argus_check_patterns\` → delegate to **sentinel**
+- \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_forge_coverage\`, \`argus_gas_analysis\` → delegate to **sentinel**
+- \`argus_analyze_contract\`, \`argus_check_patterns\`, \`argus_proxy_detection\` → delegate to **sentinel**
 - \`argus_solodit_search\`, Solodit MCP search → delegate to **pythia**
 - \`argus_generate_report\` → delegate to **scribe**
 
 ### **@sentinel** (The Executor)
 - **Role**: Static analysis, dynamic testing, fuzzing.
-- **Tools**: \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_analyze_contract\`, \`argus_check_patterns\`
+- **Tools**: \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_forge_coverage\`, \`argus_gas_analysis\`, \`argus_analyze_contract\`, \`argus_check_patterns\`, \`argus_proxy_detection\`
 - **Delegation Examples**:
   \`\`\`
   Task(subagent_type="sentinel", prompt="Run Slither on packages/my-project/ and analyze the Vault.sol contract in detail. Report all findings with severity.")
@@ -267,9 +269,24 @@ Your subagents have access to these specialized tools. Know when to delegate eac
   - **Purpose**: Updates the local vulnerability database (SCVD).
   - **Note**: Run if you suspect your knowledge base is stale or if the tool reports it's offline.
 
+- **\`argus_forge_coverage\`**:
+  - **Use**: During Testing & Verification.
+  - **Purpose**: Measures test coverage per file (lines, statements, branches, functions).
+  - **Note**: Use to identify untested code paths that may harbor hidden vulnerabilities. Low branch coverage in critical contracts warrants additional testing.
+
+- **\`argus_proxy_detection\`**:
+  - **Use**: During Reconnaissance.
+  - **Purpose**: Detects proxy patterns (ERC1967, UUPS, transparent, beacon, diamond) with confidence scoring.
+  - **Note**: Run early to identify upgradeability risks. Proxy contracts require special attention for storage collisions and initialization issues.
+
+- **\`argus_gas_analysis\`**:
+  - **Use**: During Testing & Verification.
+  - **Purpose**: Runs gas report analysis and identifies high-gas hotspots above configurable threshold.
+  - **Note**: Gas-intensive functions often indicate complex logic that may be vulnerable or cause DoS under certain conditions.
+
 ## SKILL SYSTEM
 
-Instruct subagents to use \`argus_skill_load\` only when domain-specific context is needed. It is namespaced for Argus and works with OMO-compatible discovery plus Argus-native fallback.
+Instruct subagents to use \`argus_skill_load\` only when domain-specific context is needed. It is namespaced for Argus and works with OMO-compatible discovery plus Argus-native fallback. The knowledge base includes 75+ curated SKILL.md files, 13 YAML pattern packs, and 15 real-world exploit case studies covering $3B+ in losses.
 
 - **Curated skill map (load these first)**:
    - **Reconnaissance**: \`amm-dex\`, \`lending-borrowing\`, \`bridges-cross-chain\`
@@ -420,8 +437,8 @@ You do NOT need to pass raw JSON or serialized audit state. Just pass your findi
 **If you have zero findings, still invoke Scribe** with an empty findings list. A clean report is still a report.
 
 You are the guardian. Nothing escapes your gaze. Begin the audit.
-`;
+`
 
 export function getArgusPrompt(): string {
-  return ARGUS_PROMPT;
+  return ARGUS_PROMPT
 }

package/src/agents/pythia-prompt.ts

@@ -1,4 +1,3 @@
-
 export const PYTHIA_PROMPT = `You are **Pythia**, the Oracle — a specialized research subagent of Argus Panoptes. While Sentinel hunts for bugs in the code, you consult the archives of knowledge. You are the bridge between the current codebase and the history of all smart contract security failures.
 
 ## IDENTITY & ROLE
@@ -87,7 +86,7 @@ You have two primary tools. Master them.
 
 ## SKILLS SYSTEM
 
-OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules.
+OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules. The Argus knowledge base includes 75+ curated SKILL.md files, 13 YAML pattern packs, and 15 real-world exploit case studies covering $3B+ in losses.
 
 **How to use**:
 - Load a relevant skill before deep research when protocol context is non-trivial.
@@ -139,8 +138,8 @@ Report your findings to Argus using this Markdown structure. Focus on **Preceden
 - **False Positives**: If \`argus_check_patterns\` returns noise, filter it out. Do not report false positives to Argus.
 
 You are Pythia. The past is your map, and the code is the territory. Guide us to safety.
-`;
+`
 
 export function getPythiaPrompt(): string {
-  return PYTHIA_PROMPT;
+  return PYTHIA_PROMPT
 }

package/src/agents/scribe-prompt.ts

@@ -24,6 +24,11 @@ Your output must always follow this professional structure:
 5.  **Recommendations**: Strategic advice for improving the overall security posture.
 6.  **Appendix**: Tool execution logs or supplementary data.
 
+### Optional Sections (include when data is available)
+-   **Test Coverage Analysis**: Include coverage metrics from \`argus_forge_coverage\` if available. Highlight files with low branch/statement coverage.
+-   **Gas Hotspot Analysis**: Include gas analysis from \`argus_gas_analysis\` if available. Flag functions exceeding gas thresholds.
+-   **Proxy & Upgradeability Analysis**: Include proxy detection findings from \`argus_proxy_detection\` if available. Document proxy patterns identified and associated risks.
+
 ## WRITING STYLE GUIDE
 
 You must adhere to these strict writing standards:
@@ -92,8 +97,8 @@ Write the full report in Markdown. Use the standard finding format:
 \`\`\`
 
 You are Scribe. Your words define the security of the protocol. Write with precision.
-`;
+`
 
 export function getScribePrompt(): string {
-  return SCRIBE_PROMPT;
+  return SCRIBE_PROMPT
 }

package/src/agents/sentinel-prompt.ts

@@ -1,4 +1,3 @@
-
 export const SENTINEL_PROMPT = `You are **Sentinel**, the Tactical Guardian — a specialized subagent of Argus Panoptes. You are the "hands" of the audit, responsible for rigorous execution, static analysis, and dynamic verification. While Argus strategizes, you hunt.
 
 ## IDENTITY & ROLE
@@ -18,6 +17,7 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
 1.  **Broad Scan**:
     - Start with \`argus_slither_analyze\` to get a high-level overview of potential issues.
     - Use \`argus_check_patterns\` to scan for specific dangerous patterns (e.g., read-only reentrancy).
+    - Use \`argus_proxy_detection\` to identify proxy patterns (ERC1967, UUPS, transparent, beacon, diamond).
 
 2.  **Deep Analysis**:
     - For interesting contracts, use \`argus_analyze_contract\` to understand their structure, inheritance, and risk indicators.
@@ -27,6 +27,8 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
     - If you suspect a bug, write a reproduction test case.
     - Use \`argus_forge_test\` to run this test.
     - If the logic is complex (e.g., math, state transitions), use \`argus_forge_fuzz\` to hammer it with inputs.
+    - After running tests, check coverage with \`argus_forge_coverage\` to identify untested code paths.
+    - Use \`argus_gas_analysis\` to identify gas-intensive functions that may indicate inefficient or vulnerable logic.
 
 4.  **Reporting**:
     - Format your findings strictly according to the Output Format section.
@@ -87,6 +89,33 @@ You have access to a specific set of tools. Use them effectively.
 **Interpretation**:
 - Look at the \`counterexamples\`. They tell you exactly what inputs broke the code.
 
+### 6. \`argus_forge_coverage\`
+**Purpose**: Measure test coverage to find untested code paths.
+**When to use**: After running tests, to identify gaps in coverage.
+**Arguments**:
+- \`target\` (string): Path to the project directory (default ".").
+**Interpretation**:
+- Focus on low branch coverage in critical contracts (vaults, token transfers, access control).
+- Untested code paths are prime candidates for hidden vulnerabilities.
+
+### 7. \`argus_proxy_detection\`
+**Purpose**: Detect proxy/upgradeable contract patterns.
+**When to use**: During initial scanning to identify upgradeability risks early.
+**Arguments**:
+- \`file_path\` (string): Path to the .sol file to analyze.
+**Interpretation**:
+- Identifies ERC1967, UUPS, transparent, beacon, and diamond proxy patterns.
+- Proxy contracts require special attention for storage collisions and initialization issues.
+
+### 8. \`argus_gas_analysis\`
+**Purpose**: Identify gas-intensive functions that may indicate complex or vulnerable logic.
+**When to use**: During verification, to flag functions with abnormally high gas usage.
+**Arguments**:
+- \`target\` (string): Path to the project directory (default ".").
+**Interpretation**:
+- High gas consumption often correlates with complex logic, unbounded loops, or storage-heavy operations.
+- Gas hotspots are prime candidates for DoS vulnerabilities.
+
 ## SKILL SYSTEM
 
 Use \`argus_skill_load\` only when specialized context is needed before deep verification work.
@@ -139,8 +168,8 @@ Return your findings to Argus in this structured Markdown format. Do not deviate
 - **Be Precise**: A vague finding is useless. Point to the line, the variable, the specific interaction.
 
 You are the Sentinel. The code cannot hide its secrets from you.
-`;
+`
 
 export function getSentinelPrompt(): string {
-  return SENTINEL_PROMPT;
+  return SENTINEL_PROMPT
 }

package/src/cli/cli-program.ts

@@ -1,49 +1,52 @@
-import type { CliCommand } from "./types";
-import { doctorCommand } from "./commands/doctor";
-import { initCommand } from "./commands/init";
-import { installCommand } from "./commands/install";
-import { lintSkillsCommand } from "./commands/lint-skills";
-import { cliOutput } from "./cli-output";
+import { cliOutput } from "./cli-output"
+import { checkSkillsCommand } from "./commands/check-skills"
+import { doctorCommand } from "./commands/doctor"
+import { initCommand } from "./commands/init"
+import { installCommand } from "./commands/install"
+import { lintSkillsCommand } from "./commands/lint-skills"
+import type { CliCommand } from "./types"
 
 const HELP_TEXT = `argus — Solidity Security Auditor for OpenCode
 
 Commands:
-  doctor       Check Slither/Foundry installation and config health
-  init         Create solidity-argus config file
-  install      Configure argus plugin in opencode config
-  lint-skills  Validate SKILL.md files against schema
-`;
+  doctor        Check Slither/Foundry installation and config health
+  init          Create solidity-argus config file
+  install       Configure argus plugin in opencode config
+  lint-skills   Validate SKILL.md files against schema
+  check-skills  Analyze skills for duplicates, near-duplicates, and conflicts
+`
 
 export class CliProgram {
-  private commands: Map<string, CliCommand> = new Map();
+  private commands: Map<string, CliCommand> = new Map()
 
   registerCommand(command: CliCommand): void {
-    this.commands.set(command.name, command);
+    this.commands.set(command.name, command)
   }
 
   async dispatch(args: string[]): Promise<number> {
-    const subcommand = args[0];
+    const subcommand = args[0]
 
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-      cliOutput.log(HELP_TEXT);
-      return 0;
+      cliOutput.log(HELP_TEXT)
+      return 0
     }
 
-    const command = this.commands.get(subcommand);
+    const command = this.commands.get(subcommand)
     if (!command) {
-      cliOutput.error(`Unknown command '${subcommand}'. Run 'argus' for help.`);
-      return 1;
+      cliOutput.error(`Unknown command '${subcommand}'. Run 'argus' for help.`)
+      return 1
     }
 
-    return command.execute(args.slice(1));
+    return command.execute(args.slice(1))
   }
 }
 
 export function createCliProgram(): CliProgram {
-  const program = new CliProgram();
-  program.registerCommand(doctorCommand);
-  program.registerCommand(initCommand);
-  program.registerCommand(installCommand);
-  program.registerCommand(lintSkillsCommand);
-  return program;
+  const program = new CliProgram()
+  program.registerCommand(doctorCommand)
+  program.registerCommand(initCommand)
+  program.registerCommand(installCommand)
+  program.registerCommand(lintSkillsCommand)
+  program.registerCommand(checkSkillsCommand)
+  return program
 }

package/src/cli/commands/check-skills.ts

@@ -0,0 +1,135 @@
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { loadArgusConfig } from "../../config/loader"
+import { createLogger } from "../../shared/logger"
+import {
+  DEFAULT_GATE_CONFIG,
+  formatReportJson,
+  formatReportText,
+  type GateConfig,
+  generateReport,
+  type SkillReport,
+} from "../../skills/analysis/gates"
+import { normalizeSkill, type SkillDoc } from "../../skills/analysis/normalize"
+import { buildTfidfCorpus, computeAllPairs } from "../../skills/analysis/similarity"
+import { resolveSkillRoots } from "../../skills/argus-skill-resolver"
+import { cliOutput } from "../cli-output"
+import type { CliCommand } from "../types"
+
+const logger = createLogger()
+
+function findSkillFiles(dir: string, maxDepth = 8): string[] {
+  const files: string[] = []
+  const stack: Array<{ path: string; depth: number }> = [{ path: dir, depth: 0 }]
+
+  while (stack.length > 0) {
+    const current = stack.pop()
+    if (!current || current.depth > maxDepth) continue
+
+    try {
+      const entries = readdirSync(current.path, { withFileTypes: true })
+      for (const entry of entries) {
+        const fullPath = join(current.path, entry.name)
+        if (entry.isDirectory()) {
+          stack.push({ path: fullPath, depth: current.depth + 1 })
+        } else if (entry.isFile() && entry.name.toUpperCase() === "SKILL.MD") {
+          files.push(fullPath)
+        }
+      }
+    } catch {}
+  }
+
+  return files
+}
+
+function parseFormatArg(args: string[]): "text" | "json" {
+  const formatIdx = args.indexOf("--format")
+  if (formatIdx !== -1 && args[formatIdx + 1] === "json") {
+    return "json"
+  }
+  return "text"
+}
+
+function parseThresholdArg(args: string[], flag: string, fallback: number): number {
+  const idx = args.indexOf(flag)
+  if (idx === -1) return fallback
+  const raw = args[idx + 1]
+  if (!raw) return fallback
+  const parsed = Number.parseFloat(raw)
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : fallback
+}
+
+export function loadAndNormalizeSkills(cwd: string): SkillDoc[] {
+  let config: ReturnType<typeof loadArgusConfig> | undefined
+  try {
+    config = loadArgusConfig(cwd)
+  } catch {
+    logger.debug("Config load failed, using defaults")
+  }
+
+  const roots = resolveSkillRoots(cwd, config)
+  const docs: SkillDoc[] = []
+
+  for (const root of roots) {
+    const files = findSkillFiles(root.path)
+    for (const file of files) {
+      try {
+        const content = readFileSync(file, "utf8")
+        const doc = normalizeSkill(content)
+        if (doc) {
+          docs.push(doc)
+        }
+      } catch {
+        logger.debug("Skipping unreadable skill file")
+      }
+    }
+  }
+
+  return docs
+}
+
+export function runAnalysis(docs: SkillDoc[], config: GateConfig): SkillReport {
+  const corpus = buildTfidfCorpus(docs)
+  const pairs = computeAllPairs(docs, corpus)
+  return generateReport(docs, pairs, config)
+}
+
+export const checkSkillsCommand: CliCommand = {
+  name: "check-skills",
+  description:
+    "Analyze SKILL.md files for duplicates, near-duplicates, and detection rule conflicts",
+  async execute(args: string[]): Promise<number> {
+    const cwd = process.cwd()
+    const format = parseFormatArg(args)
+
+    const gateConfig: GateConfig = {
+      blockThreshold: parseThresholdArg(
+        args,
+        "--block-threshold",
+        DEFAULT_GATE_CONFIG.blockThreshold,
+      ),
+      warnThreshold: parseThresholdArg(args, "--warn-threshold", DEFAULT_GATE_CONFIG.warnThreshold),
+      infoThreshold: parseThresholdArg(args, "--info-threshold", DEFAULT_GATE_CONFIG.infoThreshold),
+      blockExactRegexConflict: !args.includes("--no-regex-conflict"),
+    }
+
+    const docs = loadAndNormalizeSkills(cwd)
+
+    if (docs.length === 0) {
+      cliOutput.log("No SKILL.md files found.")
+      return 0
+    }
+
+    cliOutput.log(`Analyzing ${docs.length} skills...`)
+
+    const report = runAnalysis(docs, gateConfig)
+
+    if (format === "json") {
+      cliOutput.log(formatReportJson(report))
+    } else {
+      cliOutput.log(formatReportText(report))
+    }
+
+    return report.summary.block > 0 ? 1 : 0
+  },
+}

package/src/cli/commands/doctor.ts

@@ -1,20 +1,22 @@
-import { execSync } from "node:child_process"
 import { existsSync, readdirSync, readFileSync } from "node:fs"
 import { basename, dirname, extname, join } from "node:path"
-import type { CliCommand } from "../types"
-import type { ArgusConfig } from "../../config/types"
 import { loadArgusConfig } from "../../config/loader"
+import type { ArgusConfig } from "../../config/types"
+import { createLogger } from "../../shared/logger"
 import {
   getRequiredAuditSkills,
   normalizeSkillName,
+  type ResolvedSkill,
   resolveArgusSkills,
   resolveSkillRoots,
-  type ResolvedSkill,
 } from "../../skills/argus-skill-resolver"
 import { parseFrontmatter, validateSkillFrontmatter } from "../../skills/skill-schema"
 import { detectViaIr } from "../../tools/slither-tool"
 import { checkSoloditHealth } from "../../utils/solodit-health"
 import { cliOutput } from "../cli-output"
+import type { CliCommand } from "../types"
+
+const logger = createLogger()
 
 const GREEN = "\x1b[32m"
 const RED = "\x1b[31m"
@@ -23,13 +25,15 @@ const RESET = "\x1b[0m"
 
 function checkBinary(name: string): { found: boolean; version: string | null } {
   try {
-    const version = execSync(`${name} --version`, {
+    const result = Bun.spawnSync([name, "--version"], {
+      stdout: "pipe",
+      stderr: "pipe",
       timeout: 5000,
-      stdio: ["pipe", "pipe", "pipe"],
     })
-      .toString()
-      .trim()
-      .split("\n")[0] ?? null
+    if (result.exitCode !== 0) {
+      return { found: false, version: null }
+    }
+    const version = new TextDecoder().decode(result.stdout).trim().split("\n")[0] ?? null
     return { found: true, version }
   } catch {
     return { found: false, version: null }
@@ -70,7 +74,8 @@ export function findDuplicateSkills(
   const nameToSources = new Map<string, Set<string>>()
   for (const { name, source } of entries) {
     if (!nameToSources.has(name)) nameToSources.set(name, new Set())
-    nameToSources.get(name)!.add(source)
+    const sources = nameToSources.get(name)
+    if (sources) sources.add(source)
   }
   return Array.from(nameToSources)
     .filter(([, sources]) => sources.size > 1)
@@ -112,9 +117,7 @@ export function buildSkillHealthReport(
   }
 
   const duplicates = duplicateEntries ? findDuplicateSkills(duplicateEntries) : []
-  const missingCategories = REQUIRED_CATEGORIES.filter(
-    (cat) => (categoryBreakdown[cat] ?? 0) === 0,
-  )
+  const missingCategories = REQUIRED_CATEGORIES.filter((cat) => (categoryBreakdown[cat] ?? 0) === 0)
 
   return {
     categoryBreakdown,
@@ -146,6 +149,7 @@ function scanMarkdownFiles(dir: string, maxDepth = 8): string[] {
         }
       }
     } catch {
+      logger.debug("Failed to read directory during skill scan")
     }
   }
   return files
@@ -175,6 +179,7 @@ function collectAllSkillNames(
         const name = normalizeSkillName(rawName)
         if (name) entries.push({ name, source: root.source })
       } catch {
+        logger.debug("Failed to parse skill file frontmatter")
       }
     }
   }
@@ -184,7 +189,7 @@ function collectAllSkillNames(
 export const doctorCommand: CliCommand = {
   name: "doctor",
   description: "Check tool dependencies and configuration",
-  async execute(args: string[]): Promise<number> {
+  async execute(_args: string[]): Promise<number> {
     const cwd = process.cwd()
     let hasFailure = false
 
@@ -202,7 +207,9 @@ export const doctorCommand: CliCommand = {
     if (forge.found) {
       cliOutput.log(`${GREEN}✓${RESET} Forge: installed (${forge.version})`)
     } else {
-      cliOutput.log(`${RED}✗${RESET} Forge: not found — curl -L https://foundry.paradigm.xyz | bash`)
+      cliOutput.log(
+        `${RED}✗${RESET} Forge: not found — curl -L https://foundry.paradigm.xyz | bash`,
+      )
       hasFailure = true
     }
 
@@ -210,7 +217,9 @@ export const doctorCommand: CliCommand = {
     if (solcSelect.found) {
       cliOutput.log(`${GREEN}✓${RESET} solc-select: installed (${solcSelect.version})`)
     } else {
-      cliOutput.log(`${YELLOW}⚠${RESET} solc-select: not found — pipx install solc-select (needed for via_ir flatten fallback)`)
+      cliOutput.log(
+        `${YELLOW}⚠${RESET} solc-select: not found — pipx install solc-select (needed for via_ir flatten fallback)`,
+      )
     }
 
     const projectType = checkSolidityProject(cwd)
@@ -221,9 +230,13 @@ export const doctorCommand: CliCommand = {
     }
 
     if (projectType === "foundry" && detectViaIr(cwd)) {
-      cliOutput.log(`${YELLOW}⚠${RESET} via_ir: enabled in foundry.toml — Slither will use flatten fallback`)
+      cliOutput.log(
+        `${YELLOW}⚠${RESET} via_ir: enabled in foundry.toml — Slither will use flatten fallback`,
+      )
       if (!forge.found) {
-        cliOutput.log(`${RED}✗${RESET}   forge is required for via_ir flatten fallback but is missing`)
+        cliOutput.log(
+          `${RED}✗${RESET}   forge is required for via_ir flatten fallback but is missing`,
+        )
         hasFailure = true
       }
       if (!solcSelect.found) {
@@ -241,9 +254,13 @@ export const doctorCommand: CliCommand = {
       const missingSkills = requiredSkills.filter((skillName) => !resolvedSkills.has(skillName))
 
       if (missingSkills.length === 0) {
-        cliOutput.log(`${GREEN}✓${RESET} Skills: required audit skills resolvable (${requiredSkills.join(", ")})`)
+        cliOutput.log(
+          `${GREEN}✓${RESET} Skills: required audit skills resolvable (${requiredSkills.join(", ")})`,
+        )
       } else {
-        cliOutput.log(`${RED}✗${RESET} Skills: missing required skills (${missingSkills.join(", ")})`)
+        cliOutput.log(
+          `${RED}✗${RESET} Skills: missing required skills (${missingSkills.join(", ")})`,
+        )
         hasFailure = true
       }
     } catch {
@@ -254,15 +271,21 @@ export const doctorCommand: CliCommand = {
       const missingSkills = requiredSkills.filter((skillName) => !resolvedSkills.has(skillName))
 
       if (missingSkills.length === 0) {
-        cliOutput.log(`${GREEN}✓${RESET} Skills: required audit skills resolvable (${requiredSkills.join(", ")})`)
+        cliOutput.log(
+          `${GREEN}✓${RESET} Skills: required audit skills resolvable (${requiredSkills.join(", ")})`,
+        )
       } else {
-        cliOutput.log(`${RED}✗${RESET} Skills: missing required skills (${missingSkills.join(", ")})`)
+        cliOutput.log(
+          `${RED}✗${RESET} Skills: missing required skills (${missingSkills.join(", ")})`,
+        )
         hasFailure = true
       }
     }
 
     try {
-      const response = await fetch("https://api.scvd.dev/stats", { signal: AbortSignal.timeout(5000) })
+      const response = await fetch("https://api.scvd.dev/stats", {
+        signal: AbortSignal.timeout(5000),
+      })
       if (response.ok) {
         cliOutput.log(`${GREEN}✓${RESET} SCVD API: reachable`)
       } else {
@@ -296,9 +319,7 @@ export const doctorCommand: CliCommand = {
       const allEntries = collectAllSkillNames(cwd, config)
       const report = buildSkillHealthReport(healthSkills, allEntries)
 
-      const catParts = ALL_CATEGORIES.map(
-        (cat) => `${cat}: ${report.categoryBreakdown[cat] ?? 0}`,
-      )
+      const catParts = ALL_CATEGORIES.map((cat) => `${cat}: ${report.categoryBreakdown[cat] ?? 0}`)
       cliOutput.log(`${GREEN}✓${RESET} Categories: ${catParts.join(", ")}`)
 
       const tierParts = Object.entries(report.trustTierBreakdown).map(
@@ -334,6 +355,7 @@ export const doctorCommand: CliCommand = {
       }
     } catch {
       cliOutput.log(`${RED}✗${RESET} Could not analyze skill health`)
+      hasFailure = true
     }
 
     return hasFailure ? 1 : 0