karajan-code 2.16.0 → 2.17.1

package/src/checks/binaries.js

@@ -15,6 +15,7 @@
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 import { runCommand } from "../utils/process.js";
 import { withDocLink } from "../utils/doc-links.js";
+import { getInstallHint, appliesToStack } from "../utils/install-hints.js";
 import { STRATEGY } from "./types.js";
 
 /**
@@ -105,6 +106,56 @@ function createSerenaCheck() {
   };
 }
 
+/**
+ * Audit-side external tool (semgrep, osv-scanner, lighthouse) check.
+ *
+ * These are not blockers: `kj audit` and `kj webperf` degrade to
+ * available:false when missing. We surface them in `kj doctor` so the
+ * user can see at a glance which audit dimensions are active, and we
+ * point to `kj install-tools` for one-line remediation.
+ *
+ * `lighthouse` is stack-gated: only flagged when the project is
+ * frontend / fullstack. On backend-only projects the check is a no-op
+ * (returns ok:true with detail "n/a") to keep doctor output focused.
+ */
+function createAuditToolCheck(tool, { gatedByStack = false, label }) {
+  return {
+    name: `audit-tool:${tool}`,
+    label,
+    strategy: STRATEGY.MANUAL,
+    async detect({ config } = {}) {
+      if (gatedByStack) {
+        // Stack detection is best-effort — failing here just means we
+        // treat the project as backend-only (skip the check). Keeps the
+        // doctor pipeline resilient to weird repos.
+        let stack = null;
+        try {
+          const { detectProjectStack } = await import("../utils/stack-detect.js");
+          stack = await detectProjectStack(config?.projectDir || process.cwd());
+        } catch { /* ignore */ }
+        if (!appliesToStack(tool, stack)) {
+          return { ok: true, severity: "info", detail: "n/a (no frontend stack detected)" };
+        }
+      }
+      const result = await checkBinary(tool);
+      if (result.ok) {
+        return { ok: true, severity: "info", detail: result.version || "available" };
+      }
+      const hint = await getInstallHint(tool);
+      const fixLine = hint.command
+        ? `Run \`kj install-tools --only ${tool}\` or: ${hint.command}`
+        : `Run \`kj install-tools --only ${tool}\` or see ${hint.manualUrl}`;
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — `kj audit` dimension will degrade",
+        fix: fixLine,
+        extra: { tool, suggested: hint.command, manager: hint.manager, manualUrl: hint.manualUrl },
+      };
+    },
+  };
+}
+
 /**
  * Aggregate: all binary-related checks for the current config.
  * @returns {import("./types.js").Check[]}
@@ -119,5 +170,10 @@ export function getBinaryChecks() {
   }
   checks.push(createDockerCheck());
   checks.push(createSerenaCheck());
+  // KJC-TSK v2.18 — surface audit-side tools in doctor so the user knows
+  // which dimensions will work. lighthouse is gated to frontend stacks.
+  checks.push(createAuditToolCheck("semgrep", { label: "Semgrep (audit/security)" }));
+  checks.push(createAuditToolCheck("osv-scanner", { label: "OSV-Scanner (audit/security)" }));
+  checks.push(createAuditToolCheck("lighthouse", { label: "Lighthouse (webperf)", gatedByStack: true }));
   return checks;
 }

package/src/checks/runner.js

@@ -196,6 +196,10 @@ export async function runChecks(checks, ctx, options = {}) {
     detail: e.detail ?? "",
     fix: e.detectResult?.fix,
     runMs: e.runMs,
+    // Forward optional structured metadata so the doctor printer can
+    // surface per-tool remediation tips (KJC-TSK v2.18). Undefined when
+    // the check didn't set one — kept minimal so JSON output stays tight.
+    extra: e.detectResult?.extra,
   }));
 
   const summary = summarize(reports);

package/src/cli/register-pipeline.js

@@ -3,6 +3,7 @@ import { configCommand } from "../commands/config.js";
 import { codeCommand } from "../commands/code.js";
 import { reviewCommand } from "../commands/review.js";
 import { scanCommand } from "../commands/scan.js";
+import { installToolsCommand } from "../commands/install-tools.js";
 import { doctorCommand } from "../commands/doctor.js";
 import { reportCommand } from "../commands/report.js";
 import { runCommandHandler } from "../commands/run.js";
@@ -192,6 +193,26 @@ export function registerPipeline(program, { pkgVersion }) {
       if (Number.isInteger(exitCode)) process.exit(exitCode);
     });
 
+  program
+    .command("install-tools")
+    .description("Install external audit tools (semgrep, osv-scanner, lighthouse, docker, sonar) using the package manager available on your system")
+    .option("--only <tools>", "Comma-separated subset (e.g. \"semgrep,osv-scanner\"). Bypasses stack-gating.")
+    .option("-y, --yes", "Auto-accept all prompts (non-interactive)")
+    .option("--dry-run", "Show what would be installed without running anything")
+    .action(async (flags) => {
+      try {
+        const { exitCode } = await installToolsCommand({
+          only: flags.only,
+          yes: !!flags.yes,
+          dryRun: !!flags.dryRun,
+        });
+        if (Number.isInteger(exitCode)) process.exit(exitCode);
+      } catch (err) {
+        console.error(`kj install-tools: ${err?.message || err}`);
+        process.exit(1);
+      }
+    });
+
   program
     .command("status")
     .description("Show pipeline dashboard with HU progress")

package/src/commands/board.js

@@ -88,6 +88,40 @@ function buildBoardUrl(port, projectSlug) {
   return projectSlug ? `${base}/p/${projectSlug}` : base;
 }
 
+/**
+ * After spawning the board daemon, watch for an early exit. Resolves to
+ * an error string when the child dies within the window — a broken
+ * native module, a crash on boot, or the silent entry-point mismatch
+ * that made the daemon exit 0 without a trace — and to `null` when it
+ * survives. This is what stops `startBoard` from reporting `ok` for a
+ * daemon that died milliseconds after spawn. The window is overridable
+ * via KJ_BOARD_START_WINDOW_MS (tests set it low to stay fast).
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {string} logPath
+ * @returns {Promise<string|null>}
+ */
+export function waitForEarlyExit(child, logPath) {
+  const envWindow = Number(process.env.KJ_BOARD_START_WINDOW_MS);
+  const windowMs = Number.isFinite(envWindow) && envWindow >= 0 ? envWindow : 1500;
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+    const onExit = (code, signal) => {
+      const how = signal ? `signal ${signal}` : `exit code ${code}`;
+      finish(`HU Board daemon died on startup (${how}). See ${logPath} for the cause.`);
+    };
+    function finish(value) {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      child.removeListener("exit", onExit);
+      resolve(value);
+    }
+    child.once("exit", onExit);
+    timer = setTimeout(() => finish(null), windowMs);
+  });
+}
+
 export async function startBoard(desiredPort = 4000, opts = {}) {
   const { projectSlug = null, bind = "127.0.0.1" } = opts;
   const existingPid = readPid();
@@ -141,8 +175,11 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
 
   // Use process.execPath (absolute path to current node binary) instead of "node".
   // Fixes ENOENT on nvm setups where `node` is not in the spawned process's PATH.
+  // KJ_BOARD_DAEMON=1 tells server.js to run main() regardless of how
+  // its entry-point path compares — the symlink/Windows/space-in-path
+  // mismatch that used to make the daemon exit 0 in total silence.
   const child = spawn(process.execPath, [serverPath], {
-    env: { ...process.env, PORT: String(port), BIND_HOST: bind },
+    env: { ...process.env, PORT: String(port), BIND_HOST: bind, KJ_BOARD_DAEMON: "1" },
     detached: true,
     stdio: ["ignore", logFd, logFd],
     cwd: BOARD_DIR
@@ -154,6 +191,14 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   if (!child.pid) {
     throw new Error("Failed to spawn HU Board server");
   }
+  // Don't report success blindly: a crash on boot (e.g. broken
+  // better-sqlite3, or the silent entry-point mismatch) used to be
+  // reported as ok:true, leaving the user with a dead board and a log
+  // showing only the start line. Catch the early exit here.
+  const failure = await waitForEarlyExit(child, logPath);
+  if (failure) {
+    throw new Error(failure);
+  }
   fs.writeFileSync(PID_FILE, String(child.pid));
   // Detach for real: `detached: true` only sets up the new session;
   // without `unref()` the parent's event loop still holds a reference
@@ -289,7 +334,18 @@ export function renderBoardBanner({ url, status, projectName }) {
 export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger }) {
   switch (action) {
     case "start": {
-      const result = await startBoard(port, { bind });
+      let result;
+      try {
+        result = await startBoard(port, { bind });
+      } catch (err) {
+        // The daemon died on boot (broken native module, crash) or no
+        // free port was found. Surface it cleanly — the whole point of
+        // this fix is that `kj board start` never reports a phantom
+        // success while leaving a dead board behind.
+        logger.error(`HU Board failed to start: ${err.message}`);
+        process.exitCode = 1;
+        return { ok: false, error: err.message };
+      }
       if (result.alreadyRunning) {
         logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
       } else {

package/src/commands/doctor.js

@@ -171,4 +171,21 @@ function printHuman(report, { verbose }) {
   if (Object.keys(report.overrides).length > 0) {
     console.log(`Runtime overrides applied: ${JSON.stringify(report.overrides)}`);
   }
+
+  // KJC-TSK v2.18 — if any external audit tool (semgrep, osv-scanner,
+  // lighthouse) reported missing, surface the one-line remediation so
+  // the user doesn't have to dig the fix lines out of the wall of
+  // checks. The audit-tool checks emit names like "audit-tool:semgrep"
+  // and embed { tool, suggested } in `extra` (see binaries.js).
+  const installable = report.checks
+    .filter((c) => c.name?.startsWith("audit-tool:") && c.status === STATUS.WARN && c.extra?.tool)
+    .map((c) => c.extra.tool);
+  if (installable.length > 0) {
+    console.log();
+    const list = installable.join(", ");
+    const only = installable.length === 1 ? ` --only ${installable[0]}` : "";
+    console.log(`Tip: run \`kj install-tools${only}\` to install: ${list}.`);
+  }
 }
+
+export const __test = { printHuman };

package/src/commands/install-tools.js

@@ -0,0 +1,211 @@
+// `kj install-tools` — install the external audit tools that `kj audit`
+// and `kj webperf` rely on but does not bundle.
+//
+// Covers semgrep, osv-scanner, lighthouse, docker, sonar. Picks the
+// install command per tool from `getInstallHint` (HU1) so the command
+// matches the package manager available on the user's system.
+//
+// Lighthouse is stack-gated: by default we only prompt about it when
+// the project is frontend/fullstack. Pass `--only lighthouse` to bypass
+// the gate.
+//
+// Docker and sonar are special cases — see TOOL_HANDLERS below.
+
+import readline from "node:readline";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { checkBinary } from "../utils/agent-detect.js";
+import { getInstallHint, detectPackageManagers, appliesToStack } from "../utils/install-hints.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+
+const execFileAsync = promisify(execFile);
+
+const ALL_TOOLS = ["semgrep", "osv-scanner", "lighthouse", "docker", "sonar"];
+
+function parseOnlyList(raw) {
+  if (!raw) return null;
+  const wanted = String(raw).split(",").map((t) => t.trim()).filter(Boolean);
+  const invalid = wanted.filter((t) => !ALL_TOOLS.includes(t));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown tool(s) in --only: ${invalid.join(", ")}. Valid: ${ALL_TOOLS.join(", ")}`);
+  }
+  return wanted;
+}
+
+function promptYesNo(question, defaultYes = true) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) { resolve(defaultYes); return; } // non-TTY → assume default
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const hint = defaultYes ? "Y/n" : "y/N";
+    rl.question(`${question} [${hint}] `, (answer) => {
+      rl.close();
+      const a = (answer || "").trim().toLowerCase();
+      if (!a) return resolve(defaultYes);
+      resolve(a === "y" || a === "yes");
+    });
+  });
+}
+
+async function isInstalled(tool) {
+  // sonar is a Docker container, not a binary. We check it separately
+  // by looking at running containers via `docker ps`.
+  if (tool === "sonar") return checkSonarRunning();
+  if (tool === "lighthouse") return (await checkBinary("lighthouse")).ok;
+  if (tool === "docker") return (await checkBinary("docker")).ok;
+  return (await checkBinary(tool)).ok;
+}
+
+async function checkSonarRunning() {
+  try {
+    const { stdout } = await execFileAsync("docker", ["ps", "--format", "{{.Names}}", "--filter", "name=sonarqube"], { timeout: 5000 });
+    return stdout.trim().length > 0;
+  } catch { return false; }
+}
+
+async function runInstall(command) {
+  // Split on whitespace (commands here are simple, no nested quoting).
+  const [bin, ...args] = command.split(/\s+/);
+  try {
+    const { stdout, stderr } = await execFileAsync(bin, args, { timeout: 300_000, maxBuffer: 32 * 1024 * 1024 });
+    return { ok: true, stdout, stderr };
+  } catch (err) {
+    return { ok: false, error: err?.shortMessage || err?.message || String(err), stderr: err?.stderr };
+  }
+}
+
+/**
+ * Sonar handler: special case. Cannot install Sonar via package manager;
+ * the install is `docker compose -f <our-template> up -d` if Docker is
+ * available. Falls back to a manual URL otherwise.
+ */
+async function handleSonar({ available, dryRun }) {
+  if (!available.docker) {
+    return {
+      tool: "sonar",
+      action: "manual",
+      reason: "docker not available — sonar needs docker. Install docker first.",
+      manualUrl: "https://docs.docker.com/get-docker/",
+    };
+  }
+  const composePath = path.join(process.cwd(), "docker-compose.yml");
+  let composeExists = false;
+  try { await fs.access(composePath); composeExists = true; } catch { /* missing */ }
+  const command = composeExists
+    ? "docker compose up -d"
+    : "docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community";
+  return {
+    tool: "sonar",
+    action: dryRun ? "dry-run" : "ready",
+    command,
+    manualUrl: "https://docs.sonarsource.com/sonarqube-community-build/try-out-sonarqube/",
+  };
+}
+
+/**
+ * Docker handler: never auto-install (platform-specific, invasive).
+ * Always point at the official docs.
+ */
+function handleDocker(available) {
+  return {
+    tool: "docker",
+    action: "manual",
+    reason: "Docker install is platform-specific — see official docs.",
+    manualUrl: "https://docs.docker.com/get-docker/",
+    suggested: available.brew ? "brew install --cask docker" : null,
+  };
+}
+
+/**
+ * Plan + (optionally execute) the install of every requested tool.
+ *
+ * @param {Object} opts
+ * @param {string|null} [opts.only] - comma-separated subset
+ * @param {boolean} [opts.yes] - skip prompts
+ * @param {boolean} [opts.dryRun] - plan-only, no execution
+ * @param {Object} [opts.logger]
+ * @returns {Promise<{ results: Array<Object>, exitCode: number }>}
+ */
+export async function installToolsCommand(opts = {}) {
+  const only = parseOnlyList(opts.only);
+  const yes = !!opts.yes;
+  const dryRun = !!opts.dryRun;
+  const logger = opts.logger || console;
+
+  const targetTools = only || ALL_TOOLS;
+  const available = await detectPackageManagers();
+  const stack = await detectProjectStack(process.cwd()).catch(() => null);
+
+  const results = [];
+  for (const tool of targetTools) {
+    // Stack gating — lighthouse on backend-only projects is skipped
+    // UNLESS the user passed --only lighthouse explicitly.
+    if (tool === "lighthouse" && !only && !appliesToStack(tool, stack)) {
+      results.push({ tool, action: "skipped", reason: "no frontend stack detected" });
+      logger.info?.(`⊘ ${tool}: skipped (no frontend stack detected; use --only lighthouse to force)`);
+      continue;
+    }
+
+    if (await isInstalled(tool)) {
+      results.push({ tool, action: "already-installed" });
+      logger.info?.(`✓ ${tool}: already installed`);
+      continue;
+    }
+
+    if (tool === "sonar") {
+      const result = await handleSonar({ available, dryRun });
+      results.push(result);
+      logger.info?.(`▸ sonar: ${result.command || result.manualUrl}`);
+      if (!dryRun && result.action === "ready") {
+        const proceed = yes || await promptYesNo(`Start SonarQube with: ${result.command}?`);
+        if (proceed) {
+          const r = await runInstall(result.command);
+          result.action = r.ok ? "installed" : "failed";
+          if (!r.ok) result.error = r.error;
+        }
+      }
+      continue;
+    }
+
+    if (tool === "docker") {
+      const result = handleDocker(available);
+      results.push(result);
+      logger.info?.(`▸ docker: ${result.suggested || result.manualUrl}`);
+      continue;
+    }
+
+    // semgrep / osv-scanner / lighthouse — package-manager driven.
+    const hint = await getInstallHint(tool, available);
+    if (!hint.command || !hint.manager) {
+      results.push({ tool, action: "manual", reason: "no compatible package manager found", manualUrl: hint.manualUrl, suggested: hint.command });
+      logger.warn?.(`✗ ${tool}: no compatible package manager. Manual: ${hint.manualUrl}`);
+      continue;
+    }
+    if (dryRun) {
+      results.push({ tool, action: "dry-run", command: hint.command, manager: hint.manager });
+      logger.info?.(`▸ ${tool}: would run \`${hint.command}\` (manager: ${hint.manager})`);
+      continue;
+    }
+    const proceed = yes || await promptYesNo(`Install ${tool} with: ${hint.command}?`);
+    if (!proceed) {
+      results.push({ tool, action: "declined", command: hint.command });
+      logger.info?.(`⊘ ${tool}: declined`);
+      continue;
+    }
+    logger.info?.(`▸ ${tool}: running \`${hint.command}\`...`);
+    const r = await runInstall(hint.command);
+    if (r.ok) {
+      results.push({ tool, action: "installed", command: hint.command, manager: hint.manager });
+      logger.info?.(`✓ ${tool}: installed via ${hint.manager}`);
+    } else {
+      results.push({ tool, action: "failed", command: hint.command, error: r.error });
+      logger.warn?.(`✗ ${tool}: install failed (${r.error})`);
+    }
+  }
+
+  const failures = results.filter((r) => r.action === "failed").length;
+  return { results, exitCode: failures > 0 ? 1 : 0 };
+}
+
+export const __test = { parseOnlyList, isInstalled, ALL_TOOLS };

package/src/prompts/audit.js

@@ -28,7 +28,7 @@ const VALID_SCORES = new Set(["A", "B", "C", "D", "F"]);
 const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low"]);
 const VALID_IMPACT = new Set(["high", "medium", "low"]);
 
-export function buildAuditPrompt({ task, instructions, dimensions = null, context = null, basalCost = null, growthDelta = null, stack = null, sonarFindings = null, webperf = null, osvFindings = null, semgrepFindings = null }) {
+export function buildAuditPrompt({ task, instructions, dimensions = null, context = null, basalCost = null, growthDelta = null, stack = null, sonarFindings = null, webperf = null, osvFindings = null, semgrepFindings = null, circularDeps = null, deadExports = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -346,6 +346,41 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     sections.push(lines.join("\n"));
   }
 
+  // Knip dead-exports findings — KJC-TSK v2.17. Stack-aware, JS/TS only.
+  // Folds into the `codeQuality` dimension as MINOR for unused exports/types
+  // and MAJOR for unused files (likely real dead code).
+  if (deadExports?.available && deadExports.total > 0) {
+    const lines = ["## Dead Code (knip)"];
+    lines.push(`- Unused exports/types: ${(deadExports.exports || []).length}`);
+    lines.push(`- Unused files: ${(deadExports.files || []).length}`);
+    const allItems = [...(deadExports.exports || []), ...(deadExports.files || [])].slice(0, 40);
+    for (const item of allItems) {
+      const loc = `${item.path}${item.line ? `:${item.line}` : ""}`;
+      const name = item.name ? ` \`${item.name}\`` : "";
+      lines.push(`  - [${item.severity}] ${loc} [${item.rule}]${name}`);
+    }
+    lines.push("");
+    lines.push("These dead-code findings are GROUND TRUTH (deterministic, no LLM guessing). Fold them into the `codeQuality` dimension. Use the knip rule id (`knip:unused-exports`, `knip:unused-types`, `knip:unused-files`) verbatim in the `rule` field. Unused files at MAJOR severity are most likely real dead code; unused exports at MINOR may be public API surface kept for downstream consumers — flag but don't insist on deletion.");
+    sections.push(lines.join("\n"));
+  }
+
+  // Madge circular-import findings — KJC-TSK v2.17. Stack-aware, JS/TS only.
+  if (circularDeps?.available && circularDeps.total > 0) {
+    const lines = ["## Circular Import Cycles"];
+    lines.push(`- Total cycles: ${circularDeps.total}`);
+    const slice = (circularDeps.cycles || []).slice(0, 30);
+    for (const c of slice) {
+      const chain = (c.cycle || []).join(" → ");
+      lines.push(`  - [${c.severity}] ${chain} → ${c.cycle?.[0] || ""}`);
+    }
+    if (circularDeps.cycles?.length > slice.length) {
+      lines.push(`  - ... ${circularDeps.cycles.length - slice.length} more cycles`);
+    }
+    lines.push("");
+    lines.push("These cycles are GROUND TRUTH (deterministic, no LLM guessing). Fold them into the `architecture` dimension. Use `madge:circular-import` as the rule field. MAJOR severity = chain length ≥ 4 files; MINOR = shorter chains. Recommend the standard fix: extract a third module that both ends depend on, or break the cycle with a typeof/inline import.");
+    sections.push(lines.join("\n"));
+  }
+
   if (context) {
     sections.push(`## Context\n${context}`);
   }

package/src/roles/audit-role.js

@@ -6,6 +6,8 @@ import { collectSonarFindings } from "../audit/sonar-findings.js";
 import { collectWebPerfInput } from "../audit/webperf-input.js";
 import { collectOsvFindings } from "../audit/osv-findings.js";
 import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
+import { collectCircularDeps } from "../audit/circular-deps.js";
+import { collectDeadExports } from "../audit/dead-exports.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -47,6 +49,8 @@ export class AuditRole extends AgentRole {
     const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
     const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
     const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
+    const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
+    const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -55,6 +59,8 @@ export class AuditRole extends AgentRole {
     let webperf = null;
     let osvFindings = null;
     let semgrepFindings = null;
+    let circularDeps = null;
+    let deadExports = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
@@ -86,7 +92,23 @@ export class AuditRole extends AgentRole {
         semgrepFindings = await collectSemgrepFindings(projectDir, this.logger);
       } catch { /* semgrep is best-effort */ }
     }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings };
+    // Madge circular-import deps — KJC-TSK v2.17. Stack-aware: skipped for
+    // non-JS/TS projects. Best-effort: any failure returns available:false
+    // and the audit continues without the section.
+    if (!noMadge) {
+      try {
+        circularDeps = await collectCircularDeps(projectDir, stack, this.config, this.logger);
+      } catch { /* madge is best-effort */ }
+    }
+    // Knip dead-exports — KJC-TSK v2.17. Stack-aware, JS/TS only, needs
+    // package.json. Best-effort: any failure returns available:false and
+    // the audit continues without the section.
+    if (!noKnip) {
+      try {
+        deadExports = await collectDeadExports(projectDir, stack, this.config, this.logger);
+      } catch { /* knip is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports };
   }
 
   /**
@@ -102,11 +124,11 @@ export class AuditRole extends AgentRole {
     const context = typeof input === "object" ? input?.context || null : null;
     const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
 
-    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings } = deterministicCtx;
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports } = deterministicCtx;
 
     const provider = this.resolveProvider();
     const agent = this.createAgentInstance(provider);
-    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings });
+    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports });
     const runArgs = { prompt, role: "audit" };
     if (onOutput) runArgs.onOutput = onOutput;
     const startedAt = Date.now();
@@ -138,6 +160,8 @@ export class AuditRole extends AgentRole {
           webperf: webperf?.available ? webperf : undefined,
           osvFindings: osvFindings?.available ? osvFindings : undefined,
           semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
+          circularDeps: circularDeps?.available ? circularDeps : undefined,
+          deadExports: deadExports?.available ? deadExports : undefined,
           provider
         },
         summary: buildSummary(parsed),

package/src/sonar/api.js

@@ -95,9 +95,13 @@ export async function getOpenIssues(config, projectKey = null) {
   // KJC-TSK-0416: pre-filtro de falsos positivos antes de devolver al
   // caller. El coder, audit y scan consumen lo que pasa el filtro;
   // suppressed se devuelve aparte para observabilidad.
-  const extraRules = config?.sonar?.false_positives || [];
-  const { kept, suppressed } = filterFalsePositives(parsedIssues, {
-    extraRules,
+  // v2.17.0: accepts both legacy config.sonar.false_positives (no `tool`
+  // field, implicit "sonar") and the new generalised config.audit.false_positives.
+  const sonarLegacy = (config?.sonar?.false_positives || []).map((r) => ({ tool: "sonar", ...r }));
+  const auditRules = (config?.audit?.false_positives || []).filter((r) => (r.tool || "sonar") === "sonar");
+  const taggedIssues = parsedIssues.map((i) => ({ ...i, tool: "sonar" }));
+  const { kept, suppressed } = filterFalsePositives(taggedIssues, {
+    extraRules: [...sonarLegacy, ...auditRules],
     projectRoot: config?.projectDir,
   });