karajan-code 2.15.0 → 2.17.0

package/README.md

@@ -23,7 +23,11 @@
 
 ---
 
-> **v2.15.0 released** — Minor. Three epics, 30+ commits, ~4 000 LOC. (1) **Brain Recovery** (KJC-PCS-0044): universal error classifier with 7 rich classes (rate_limit_short, quota_daily, quota_monthly, api_down, auth_failed, network_timeout, silenced, unknown_fatal), `withBrainRecovery` wrapper wired into ALL agent invocations (no silent failures), persistent hibernation in `~/.kj/standby/<id>.json` with event-driven scheduler (no polling), `kj standby list` + `kj standby resume`, board reconcile at startup, **fallback chain** when quota exhausted with `retryAfter > 12h` (Claude → Codex → OpenCode → Aider, configurable per role via `kj init`). (2) **Model Routing + Undo** (KJC-PCS-0043): each HU gets `coder_model` + `reviewer_model` with cross-provider review by default (claude↔codex), per-HU override from board modal, OpenCode + Aider as first-class providers, ⏪ Undo button restores files via git snapshots. (3) **Self-Healing Plan** (KJC-PCS-0042): structural integrity pass breaks cycles + cleans orphan refs, smart convergence guard for self-fix loop, `kj plan fix [planId] [--prompt]` for iterating without regenerating, skip Sonar for SPIKE/DOC/RESEARCH HUs, eliminate Failed kanban column. 4 835/4 835 tests passing across 400 files. Safe upgrade from 2.14.3.
+> **v2.17.0 released** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
+>
+> **v2.16.0** — Minor. Quality-focused release: **deterministic Sonar false-positive filter** (KJC-TSK-0416), wire universal de Brain Recovery completado en `semantic-detector` (TSK-0413 step D), codemod `replace(/regex/g, …)` → `replaceAll(/regex/g, …)` en 41 sitios, y limpieza de hallazgos del propio `kj audit` v2.15.0. The Sonar filter combines two mechanisms: (1) **static rules** `{ rule, filePattern, reason }` from a built-in catalog (covering common false positives like `javascript:S2699` on `tests/architecture/`) plus extensible via `config.sonar.false_positives`; (2) **inline ignores** with `// karajan-sonar-ignore: <ruleId>` on the issue line. Result: the coder stops burning tokens "fixing" non-broken assertions. Brain Recovery now wraps **every** AI call in the pipeline — `semantic-detector` was the last legacy caller. 4 846/4 846 tests passing across 401 files. Safe upgrade from 2.15.0.
+>
+> **v2.15.0** — Minor. Three epics, 30+ commits, ~4 000 LOC. (1) **Brain Recovery** (KJC-PCS-0044): universal error classifier with 7 rich classes (rate_limit_short, quota_daily, quota_monthly, api_down, auth_failed, network_timeout, silenced, unknown_fatal), `withBrainRecovery` wrapper wired into ALL agent invocations (no silent failures), persistent hibernation in `~/.kj/standby/<id>.json` with event-driven scheduler (no polling), `kj standby list` + `kj standby resume`, board reconcile at startup, **fallback chain** when quota exhausted with `retryAfter > 12h` (Claude → Codex → OpenCode → Aider, configurable per role via `kj init`). (2) **Model Routing + Undo** (KJC-PCS-0043): each HU gets `coder_model` + `reviewer_model` with cross-provider review by default (claude↔codex), per-HU override from board modal, OpenCode + Aider as first-class providers, ⏪ Undo button restores files via git snapshots. (3) **Self-Healing Plan** (KJC-PCS-0042): structural integrity pass breaks cycles + cleans orphan refs, smart convergence guard for self-fix loop, `kj plan fix [planId] [--prompt]` for iterating without regenerating, skip Sonar for SPIKE/DOC/RESEARCH HUs, eliminate Failed kanban column. 4 835/4 835 tests passing across 400 files. Safe upgrade from 2.14.3.
 >
 > **v2.14.2** — Patch. More dogfooding fallout from GRETA Plan 2 v2.14.1: the **▶ Run button** on the HU Board appeared on every `pending` card regardless of `blocked_by` (you could launch a HU whose deps don't exist yet — the user caught it instantly), and titles on the board lost their **`[EPICA]` prefix** at some point in v2.14.x evolution, making it impossible to tell at a glance which area of the plan a card belonged to. Fixes: `canRunHu` now requires `blockedBy.length === 0` before showing ▶; the planner prompt now demands `description: "[EPICA] one-sentence description"` with INFRA/SHARED fallbacks. Plus a new doc `docs/task-templates/spec-conventions.md` collecting the 6 SPEC conventions the planner v2.14.x understands (épicas, scope exclusions, transversal deps, reuse, async observers, explicit deps), so users don't have to rediscover them by dogfooding. 2 PRs (#687, #688). 4584/4584 tests passing. Safe upgrade from 2.14.1.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -24,7 +24,7 @@
     "cli"
   ],
   "engines": {
-    "node": ">=20.10.0"
+    "node": ">=20.19.0"
   },
   "imports": {
     "#utils/*": "./src/utils/*",
@@ -70,6 +70,8 @@
     "commander": "^14.0.0",
     "execa": "^9.6.0",
     "js-yaml": "^4.1.0",
+    "knip": "^6.14.1",
+    "madge": "^8.0.0",
     "valibot": "^1.3.1"
   },
   "devDependencies": {

package/scripts/esbuild-sea.config.mjs

@@ -153,7 +153,22 @@ export const seaBuildOptions = {
   // this `external` entry is belt-and-braces — if any other dependency
   // pulls better-sqlite3 in we want a clear "not bundled" error, not a
   // silent half-bundle.
-  external: ["better-sqlite3"],
+  //
+  // madge (KJC-TSK v2.17): pulled in by src/audit/circular-deps.js via a
+  // dynamic import. Madge transitively depends on @vue/compiler-sfc which
+  // optionally requires ~20 template engines (velocityjs, dustjs-linkedin,
+  // twig, …) that are not installed — esbuild fails the bundle if it
+  // tries to walk those. Marking madge external keeps `kj audit` working
+  // in npm-installed Karajan (madge is in node_modules) and degrades
+  // gracefully in the SEA binary (the dynamic import fails → audit
+  // continues without circular-dep findings).
+  // knip (KJC-TSK v2.17): invoked as a subprocess by src/audit/dead-exports.js
+  // via `process.execPath knip-bin --reporter json`. Its native parser
+  // (oxc-parser, oxc-resolver) and CLI machinery must not be bundled. In SEA
+  // builds the createRequire(import.meta.url).resolve("knip/bin/knip.js")
+  // throws → collector returns available:false. npm installs get knip
+  // resolved normally from node_modules.
+  external: ["better-sqlite3", "madge", "knip", "oxc-parser", "oxc-resolver"],
   plugins: [seaTransformPlugin, huBoardStubPlugin],
   logLevel: "info",
 };

package/src/agents/claude-agent.js

@@ -156,7 +156,7 @@ function summarizeToolCall(name, input = {}) {
     case "Glob": return `Glob ${input.pattern || ""}`.trim();
     case "Grep": return `Grep "${(input.pattern || "").slice(0, 60)}"${input.path ? ` in ${rel(input.path)}` : ""}`;
     case "Bash": {
-      const cmd = String(input.command || "").replace(/\s+/g, " ").slice(0, 100);
+      const cmd = String(input.command || "").replaceAll(/\s+/g, " ").slice(0, 100);
       return `Bash $ ${cmd}`;
     }
     case "TodoWrite": return `Todo ${(input.todos || []).length} items`;
@@ -259,7 +259,7 @@ export function createStreamJsonFilter(onOutput) {
         } else if (block.type === "tool_use") {
           onOutput({ stream, line: summarizeToolCall(block.name, block.input), kind: "tool" });
         } else if (block.type === "thinking" && block.thinking) {
-          onOutput({ stream, line: `thinking: ${block.thinking.slice(0, 80).replace(/\s+/g, " ")}…`, kind: "thinking" });
+          onOutput({ stream, line: `thinking: ${block.thinking.slice(0, 80).replaceAll(/\s+/g, " ")}…`, kind: "thinking" });
         }
       }
       return;

package/src/agents/codex-agent.js

@@ -11,7 +11,7 @@ import { resolveBin } from "./resolve-bin.js";
 function extractCodexTokens(stdout) {
   const match = (stdout || "").match(/tokens?\s+used\s*\n\s*([\d,]+)/i);
   if (!match) return null;
-  const total = Number(match[1].replace(/,/g, ""));
+  const total = Number(match[1].replaceAll(/,/g, ""));
   if (!Number.isFinite(total) || total <= 0) return null;
   return { tokens_in: 0, tokens_out: total };
 }

package/src/audit/agent-readiness.js

@@ -178,7 +178,7 @@ function safeRead(p) {
  * line counts keeps later byte-offset checks stable.
  */
 function stripFencedCodeBlocks(text) {
-  return text.replace(/^([ \t]*)(```|~~~)[^\n]*\n([\s\S]*?)\n\1\2[^\n]*$/gm, (match) => {
+  return text.replaceAll(/^([ \t]*)(```|~~~)[^\n]*\n([\s\S]*?)\n\1\2[^\n]*$/gm, (match) => {
     const lineCount = match.split("\n").length;
     return "\n".repeat(lineCount - 1);
   });

package/src/audit/basal-cost.js

@@ -18,7 +18,7 @@ const EXCLUDE_DIRS = new Set([
 ]);
 
 function slugify(projectDir) {
-  return path.basename(projectDir).replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.basename(projectDir).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
 }
 
 async function walkSourceFiles(dir) {
@@ -144,9 +144,9 @@ function resolveImportSpecifier(fromFile, specifier) {
 // need the actual path inside the quotes to resolve the target module.
 function stripStringLiterals(content) {
   return content
-    .replace(/`[^`]*`/g, "``")
-    .replace(/"(?:\\.|[^"\\])*"/g, '""')
-    .replace(/'(?:\\.|[^'\\])*'/g, "''");
+    .replaceAll(/`[^`]*`/g, "``")
+    .replaceAll(/"(?:\\.|[^"\\])*"/g, '""')
+    .replaceAll(/'(?:\\.|[^'\\])*'/g, "''");
 }
 
 async function findDeadExports(sourceFiles) {

package/src/audit/circular-deps.js

@@ -0,0 +1,144 @@
+// Circular import-deps collector for `kj audit` (KJC-TSK — v2.17).
+//
+// Deterministic, stack-aware. Uses madge programmatically; activates only
+// when the project's stack has JS/TS sources. Anything else returns
+// { available: false, reason }.
+//
+// Same best-effort shape as sonar-findings / osv-findings / semgrep-findings:
+//   - missing dep or timeout returns { available: false, reason }
+//   - findings are passed through audit/issue-filter.js so the user can
+//     suppress known cycles via config.audit.false_positives or inline
+//     `// karajan-audit-ignore: madge:circular-import` markers.
+
+import path from "node:path";
+import fs from "node:fs/promises";
+import { filterFalsePositives } from "./issue-filter.js";
+
+// madge is loaded dynamically: in the SEA standalone binary it is excluded
+// from the bundle (see scripts/esbuild-sea.config.mjs) and a require()
+// failure here cleanly degrades to available:false, while npm installs work
+// normally. Keeping the import inside collectCircularDeps() also avoids
+// paying the load cost for non-JS projects.
+
+const SCAN_TIMEOUT_MS = 60_000;
+const MAX_CYCLES_REPORTED = 50;
+
+// Extensions madge will follow. Python/Go/etc. are not supported and we
+// short-circuit on stack detection — listing only JS/TS variants here is a
+// safety net so we never accidentally scan unrelated files.
+const JS_TS_EXTENSIONS = ["js", "mjs", "cjs", "jsx", "ts", "tsx"];
+
+function hasJsTsStack(stack) {
+  if (!stack) return false;
+  const lang = (stack.language || "").toLowerCase();
+  if (lang === "javascript" || lang === "typescript") return true;
+  const langs = Array.isArray(stack.languages) ? stack.languages : [];
+  return langs.some((l) => /^(javascript|typescript|jsx?|tsx?)$/i.test(String(l)));
+}
+
+async function findTsConfig(projectDir) {
+  for (const name of ["tsconfig.json", "jsconfig.json"]) {
+    const p = path.join(projectDir, name);
+    try { await fs.access(p); return p; } catch { /* not present */ }
+  }
+  return undefined;
+}
+
+function pickEntrypoint(projectDir) {
+  // madge needs an entrypoint. We prefer common conventions; if none
+  // exists we fall back to scanning `src/` which covers ~95% of JS/TS
+  // projects we've seen.
+  return path.join(projectDir, "src");
+}
+
+/**
+ * Collect circular-import findings for a project.
+ *
+ * @param {string} projectDir
+ * @param {object} stack - shape returned by detectProjectStack()
+ * @param {object} [config] - kj config (for config.audit.false_positives)
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, cycles?: object[], suppressed?: object[]}>}
+ */
+export async function collectCircularDeps(projectDir, stack, config = {}, logger = null) {
+  if (!hasJsTsStack(stack)) {
+    return { available: false, reason: "no JS/TS sources detected — circular-dep scan skipped" };
+  }
+
+  const entry = pickEntrypoint(projectDir);
+  try { await fs.access(entry); } catch {
+    return { available: false, reason: `entrypoint ${path.relative(projectDir, entry)} not found` };
+  }
+
+  let madge;
+  try {
+    ({ default: madge } = await import("madge"));
+  } catch (err) {
+    return { available: false, reason: `madge not loadable (${err?.message || err}). In the SEA binary install karajan-code via npm to enable.` };
+  }
+
+  const tsConfig = await findTsConfig(projectDir);
+  const opts = {
+    fileExtensions: JS_TS_EXTENSIONS,
+    excludeRegExp: [/node_modules/, /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /dist\//, /build\//, /coverage\//],
+    detectiveOptions: { es6: { mixedImports: true } },
+  };
+  if (tsConfig) opts.tsConfig = tsConfig;
+
+  let cycles;
+  try {
+    const scan = await Promise.race([
+      madge(entry, opts),
+      new Promise((_, rej) => setTimeout(() => rej(new Error("madge timeout")), SCAN_TIMEOUT_MS)),
+    ]);
+    cycles = scan.circular() || [];
+  } catch (err) {
+    logger?.warn?.(`audit/circular-deps: madge failed (${err?.message || err})`);
+    return { available: false, reason: `madge run failed: ${err?.message || err}` };
+  }
+
+  // madge returns paths relative to the entry dir; normalize to paths
+  // relative to projectDir so they match how the rest of the audit (Sonar,
+  // Semgrep) reports locations and so config.audit.false_positives can
+  // target them with familiar globs like "src/".
+  const relPrefix = path.relative(projectDir, entry);
+  const normalizedCycles = cycles.map((cycle) =>
+    cycle.map((p) => (relPrefix ? path.join(relPrefix, p) : p)),
+  );
+
+  const issues = normalizedCycles.slice(0, MAX_CYCLES_REPORTED).map((cycle, idx) => ({
+    tool: "madge",
+    rule: "circular-import",
+    component: cycle[0],
+    path: cycle[0],
+    line: 1,
+    severity: cycle.length >= 4 ? "MAJOR" : "MINOR",
+    message: `Circular import chain (${cycle.length} files): ${cycle.join(" → ")} → ${cycle[0]}`,
+    cycle,
+    index: idx,
+  }));
+
+  const extraRules = (config?.audit?.false_positives || []).filter((r) => r.tool === "madge");
+  const { kept, suppressed } = filterFalsePositives(issues, { extraRules, projectRoot: projectDir });
+
+  return {
+    available: true,
+    total: kept.length,
+    suppressedCount: suppressed.length,
+    cycles: kept,
+    suppressed,
+    truncated: normalizedCycles.length > MAX_CYCLES_REPORTED ? normalizedCycles.length - MAX_CYCLES_REPORTED : 0,
+  };
+}
+
+/**
+ * Group cycles by severity for the deterministic summary renderer.
+ */
+export function groupCyclesBySeverity(cycles) {
+  const groups = { MAJOR: [], MINOR: [] };
+  for (const c of cycles || []) {
+    const sev = c.severity || "MINOR";
+    if (groups[sev]) groups[sev].push(c);
+  }
+  return groups;
+}

package/src/audit/dead-exports.js

@@ -0,0 +1,186 @@
+// Dead exports collector for `kj audit` (KJC-TSK v2.17, code-quality dim).
+//
+// Wraps knip via subprocess. Reports unused exports + unused files —
+// findings consumed deterministically by the LLM phase so the coder
+// stops shipping new code without noticing dead code piling up.
+//
+// Same best-effort pattern as madge / semgrep / osv / sonar:
+//   - missing project signal (no package.json, no JS/TS) → available:false
+//   - missing knip binary → available:false (degrades cleanly in SEA)
+//   - timeout / parse error → available:false with reason
+//
+// Findings pass through audit/issue-filter.js so users can suppress
+// false positives via config.audit.false_positives (tool="knip") or
+// inline `// karajan-audit-ignore: knip:<ruleId>`.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createRequire } from "node:module";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { filterFalsePositives } from "./issue-filter.js";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 120_000;
+const MAX_DEAD_EXPORTS_REPORTED = 100;
+const MAX_UNUSED_FILES_REPORTED = 50;
+
+function hasJsTsStack(stack) {
+  if (!stack) return false;
+  const lang = (stack.language || "").toLowerCase();
+  if (lang === "javascript" || lang === "typescript") return true;
+  const langs = Array.isArray(stack.languages) ? stack.languages : [];
+  return langs.some((l) => /^(javascript|typescript|jsx?|tsx?)$/i.test(String(l)));
+}
+
+async function hasPackageJson(projectDir) {
+  try { await fs.access(path.join(projectDir, "package.json")); return true; } catch { return false; }
+}
+
+/**
+ * Resolve the knip binary path relative to this package's node_modules.
+ * In SEA builds knip is `external` and require.resolve throws — we let
+ * the caller catch it and return available:false.
+ *
+ * knip restricts its subpath exports to "." and "./session", so we can't
+ * directly resolve "knip/bin/knip.js" or even "knip/package.json".
+ * Instead we resolve "knip" (the main entry, dist/index.js), walk up to
+ * its package root, and locate bin/knip.js from there.
+ */
+function resolveKnipBin() {
+  const require = createRequire(import.meta.url);
+  const entry = require.resolve("knip"); // e.g. .../node_modules/knip/dist/index.js
+  // entry is .../node_modules/knip/dist/index.js — the package root is two levels up
+  const knipRoot = path.dirname(path.dirname(entry));
+  return path.join(knipRoot, "bin", "knip.js");
+}
+
+/**
+ * Collect dead-exports findings for a project.
+ *
+ * @param {string} projectDir
+ * @param {object} stack
+ * @param {object} [config]
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, exports?: object[], files?: object[], suppressed?: object[]}>}
+ */
+export async function collectDeadExports(projectDir, stack, config = {}, logger = null) {
+  if (!hasJsTsStack(stack)) {
+    return { available: false, reason: "no JS/TS sources detected — dead-export scan skipped" };
+  }
+  if (!(await hasPackageJson(projectDir))) {
+    return { available: false, reason: "no package.json found — knip needs one to detect entry points" };
+  }
+
+  let knipBin;
+  try { knipBin = resolveKnipBin(); } catch (err) {
+    return { available: false, reason: `knip binary not resolvable (${err?.message || err}). In the SEA binary install karajan-code via npm to enable.` };
+  }
+
+  let raw;
+  try {
+    const { stdout } = await execFileAsync(
+      process.execPath,
+      [knipBin, "--reporter", "json", "--no-progress", "--no-exit-code"],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 },
+    );
+    raw = stdout;
+  } catch (err) {
+    // knip exits non-zero when issues are found; with --no-exit-code that
+    // should not happen, but old configs might still trigger it. If the
+    // process produced JSON on stdout we still try to parse it.
+    raw = err?.stdout || "";
+    if (!raw) {
+      logger?.warn?.(`audit/dead-exports: knip failed (${err?.message || err})`);
+      return { available: false, reason: `knip run failed: ${err?.shortMessage || err?.message || err}` };
+    }
+  }
+
+  let report;
+  try {
+    report = JSON.parse(raw);
+  } catch (err) {
+    return { available: false, reason: `knip output not parseable as JSON (${err?.message || err})` };
+  }
+
+  // knip --reporter json shape: { files: [paths], issues: [{ file, exports?, types?, ... }], ... }
+  const unusedFiles = Array.isArray(report.files) ? report.files : [];
+  const fileIssues = Array.isArray(report.issues) ? report.issues : [];
+
+  const deadExportIssues = [];
+  for (const fi of fileIssues) {
+    const file = fi.file || fi.filePath || "";
+    if (!file) continue;
+    for (const ex of fi.exports || []) {
+      deadExportIssues.push({
+        tool: "knip",
+        rule: "unused-exports",
+        component: file,
+        path: file,
+        line: ex.line || 1,
+        col: ex.col,
+        name: ex.name,
+        severity: "MINOR",
+        message: `Unused export \`${ex.name}\` in ${file}`,
+      });
+    }
+    for (const t of fi.types || []) {
+      deadExportIssues.push({
+        tool: "knip",
+        rule: "unused-types",
+        component: file,
+        path: file,
+        line: t.line || 1,
+        name: t.name,
+        severity: "MINOR",
+        message: `Unused type \`${t.name}\` in ${file}`,
+      });
+    }
+  }
+
+  const unusedFileIssues = unusedFiles.map((f) => ({
+    tool: "knip",
+    rule: "unused-files",
+    component: f,
+    path: f,
+    line: 1,
+    severity: "MAJOR",
+    message: `Unused file: ${f}`,
+  }));
+
+  const allIssues = [
+    ...deadExportIssues.slice(0, MAX_DEAD_EXPORTS_REPORTED),
+    ...unusedFileIssues.slice(0, MAX_UNUSED_FILES_REPORTED),
+  ];
+  const extraRules = (config?.audit?.false_positives || []).filter((r) => r.tool === "knip");
+  const { kept, suppressed } = filterFalsePositives(allIssues, { extraRules, projectRoot: projectDir });
+
+  const keptExports = kept.filter((i) => i.rule === "unused-exports" || i.rule === "unused-types");
+  const keptFiles = kept.filter((i) => i.rule === "unused-files");
+
+  return {
+    available: true,
+    total: kept.length,
+    suppressedCount: suppressed.length,
+    exports: keptExports,
+    files: keptFiles,
+    suppressed,
+    truncated: {
+      exports: deadExportIssues.length > MAX_DEAD_EXPORTS_REPORTED ? deadExportIssues.length - MAX_DEAD_EXPORTS_REPORTED : 0,
+      files: unusedFiles.length > MAX_UNUSED_FILES_REPORTED ? unusedFiles.length - MAX_UNUSED_FILES_REPORTED : 0,
+    },
+  };
+}
+
+/**
+ * Group dead-export issues by severity for the deterministic summary.
+ */
+export function groupDeadExportsBySeverity(items) {
+  const groups = { MAJOR: [], MINOR: [] };
+  for (const i of items || []) {
+    const sev = i.severity || "MINOR";
+    if (groups[sev]) groups[sev].push(i);
+  }
+  return groups;
+}

package/src/audit/deterministic-summary.js

@@ -12,11 +12,15 @@
 import { groupIssuesBySeverity } from "./sonar-findings.js";
 import { groupVulnerabilitiesBySeverity } from "./osv-findings.js";
 import { groupFindingsBySeverity as groupSemgrepBySeverity } from "./semgrep-findings.js";
+import { groupCyclesBySeverity } from "./circular-deps.js";
+import { groupDeadExportsBySeverity } from "./dead-exports.js";
 
 const MAX_SAMPLE_DEAD_EXPORTS = 10;
 const MAX_SAMPLE_SONAR_PER_SEVERITY = 5;
 const MAX_SAMPLE_OSV_PER_SEVERITY = 5;
 const MAX_SAMPLE_SEMGREP_PER_SEVERITY = 5;
+const MAX_SAMPLE_CYCLES_PER_SEVERITY = 5;
+const MAX_SAMPLE_KNIP_PER_SEVERITY = 5;
 
 /**
  * @param {{basalCost?: object, growthDelta?: object, stack?: object, sonarFindings?: object, webperf?: object, osvFindings?: object}} ctx
@@ -32,11 +36,39 @@ export function formatDeterministicSummary(ctx) {
   if (ctx.sonarFindings) lines.push(...formatSonarBlock(ctx.sonarFindings));
   if (ctx.osvFindings) lines.push(...formatOsvBlock(ctx.osvFindings));
   if (ctx.semgrepFindings) lines.push(...formatSemgrepBlock(ctx.semgrepFindings));
+  if (ctx.circularDeps) lines.push(...formatCircularDepsBlock(ctx.circularDeps));
+  if (ctx.deadExports) lines.push(...formatDeadExportsBlock(ctx.deadExports));
   if (ctx.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
 
   return lines.join("\n");
 }
 
+function formatCircularDepsBlock(circularDeps) {
+  if (!circularDeps.available) {
+    return ["### Circular Dependencies (architecture)", `- Status: not available — ${circularDeps.reason || "madge not available"}`, ""];
+  }
+  const lines = ["### Circular Dependencies (architecture)"];
+  lines.push(`- Total cycles: ${circularDeps.total ?? 0}${circularDeps.suppressedCount ? ` (+${circularDeps.suppressedCount} suppressed)` : ""}`);
+  if ((circularDeps.total ?? 0) > 0) {
+    const groups = groupCyclesBySeverity(circularDeps.cycles || []);
+    for (const [severity, cycles] of Object.entries(groups)) {
+      if (cycles.length === 0) continue;
+      lines.push(`  - ${severity} (${cycles.length}):`);
+      for (const c of cycles.slice(0, MAX_SAMPLE_CYCLES_PER_SEVERITY)) {
+        const head = (c.cycle || [c.path]).slice(0, 3).join(" → ");
+        const more = (c.cycle?.length || 0) > 3 ? ` → … (${c.cycle.length} files)` : "";
+        lines.push(`    - ${head}${more}`);
+      }
+      if (cycles.length > MAX_SAMPLE_CYCLES_PER_SEVERITY) {
+        lines.push(`    - ... and ${cycles.length - MAX_SAMPLE_CYCLES_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+    if (circularDeps.truncated > 0) lines.push(`  - ... ${circularDeps.truncated} more cycles not shown`);
+  }
+  lines.push("");
+  return lines;
+}
+
 function formatSemgrepBlock(semgrepFindings) {
   if (!semgrepFindings.available) {
     return ["### Semgrep SAST", `- Status: not available — ${semgrepFindings.reason || "semgrep not installed"}`, ""];
@@ -86,6 +118,34 @@ function formatOsvBlock(osvFindings) {
   return lines;
 }
 
+function formatDeadExportsBlock(deadExports) {
+  if (!deadExports.available) {
+    return ["### Dead Code (knip)", `- Status: not available — ${deadExports.reason || "knip not available"}`, ""];
+  }
+  const lines = ["### Dead Code (knip)"];
+  const exportsTotal = (deadExports.exports || []).length;
+  const filesTotal = (deadExports.files || []).length;
+  lines.push(`- Unused exports/types: ${exportsTotal}`);
+  lines.push(`- Unused files: ${filesTotal}`);
+  if (deadExports.suppressedCount) lines.push(`- Suppressed (FP filter): ${deadExports.suppressedCount}`);
+  const allItems = [...(deadExports.exports || []), ...(deadExports.files || [])];
+  if (allItems.length > 0) {
+    const groups = groupDeadExportsBySeverity(allItems);
+    for (const [severity, items] of Object.entries(groups)) {
+      if (items.length === 0) continue;
+      lines.push(`  - ${severity} (${items.length}):`);
+      for (const item of items.slice(0, MAX_SAMPLE_KNIP_PER_SEVERITY)) {
+        lines.push(`    - ${item.path}${item.line ? `:${item.line}` : ""} [${item.rule}]${item.name ? ` \`${item.name}\`` : ""}`);
+      }
+      if (items.length > MAX_SAMPLE_KNIP_PER_SEVERITY) {
+        lines.push(`    - ... and ${items.length - MAX_SAMPLE_KNIP_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
 function formatStackBlock(stack) {
   if (!stack || (!stack.frameworks?.length && !stack.language && !stack.isFrontend && !stack.isBackend)) return [];
   const lines = ["### Project Stack"];
@@ -195,6 +255,8 @@ export function deterministicContextHasFindings(ctx) {
   if (ctx.sonarFindings?.qualityGate?.status === "ERROR") return true;
   if (ctx.osvFindings?.available && (ctx.osvFindings.total ?? 0) > 0) return true;
   if (ctx.semgrepFindings?.available && (ctx.semgrepFindings.total ?? 0) > 0) return true;
+  if (ctx.circularDeps?.available && (ctx.circularDeps.total ?? 0) > 0) return true;
+  if (ctx.deadExports?.available && (ctx.deadExports.total ?? 0) > 0) return true;
   if (ctx.growthDelta && (Math.abs(ctx.growthDelta.lines || 0) > 100 || Math.abs(ctx.growthDelta.deps || 0) > 0)) return true;
   return false;
 }

package/src/audit/issue-filter.js

@@ -0,0 +1,136 @@
+// Generalised deterministic false-positive filter for kj audit collectors.
+//
+// Originally introduced as `src/sonar/issue-filter.js` in v2.16.0 (KJC-TSK-0416)
+// for Sonar findings. Generalised here so every collector (sonar, knip, madge,
+// osv, semgrep, …) can reuse the same two mechanisms:
+//
+//   1. Static rules: { tool, rule, filePattern, reason }. Match by tool name
+//      + rule id + path pattern. Catalogue below + extensible per project via
+//      config.audit.false_positives. Legacy `config.sonar.false_positives` is
+//      honoured for backwards compatibility.
+//   2. Inline ignore: `// karajan-audit-ignore: <tool>:<ruleId>` on the issue
+//      line or the previous one. Legacy `// karajan-sonar-ignore: <ruleId>`
+//      keeps working when the issue's tool is "sonar".
+//
+// Issues filtered out are kept in the `suppressed` list with `_suppressedBy`
+// metadata for auditability — no silent dropping.
+
+import fs from "node:fs";
+
+export const DEFAULT_FALSE_POSITIVES = [
+  {
+    tool: "sonar",
+    rule: "javascript:S2699",
+    filePattern: /tests\/architecture\//,
+    reason: "Structural tests assert via expect(offenders, msg).toEqual([]) — Sonar misses the custom-message form",
+  },
+  // Knip — v2.17 audit/dead-exports collector.
+  {
+    tool: "knip",
+    rule: "unused-files",
+    filePattern: /(?:^|\/)tests\/fixtures\//,
+    reason: "Test fixtures are loaded by file path at runtime, not statically imported — knip can't see them",
+  },
+  {
+    tool: "knip",
+    rule: "unused-files",
+    filePattern: /(?:^|\/)examples\//,
+    reason: "Example projects are user-facing entry points, not consumed by the parent project's source",
+  },
+  {
+    tool: "knip",
+    rule: "unused-exports",
+    filePattern: /(?:^|\/)(?:index|main)\.(?:js|ts|mjs|cjs|jsx|tsx)$/,
+    reason: "Barrel re-exports in index.{js,ts} are legitimate public API surface even when no in-tree caller uses them",
+  },
+  // Madge — v2.17 audit/circular-deps collector.
+  {
+    tool: "madge",
+    rule: "circular-import",
+    filePattern: /node_modules\//,
+    reason: "Cycles inside node_modules are upstream's problem, not ours — defensive default since madge excludes node_modules by config",
+  },
+];
+
+export function hasInlineIgnore(filePath, line, ruleId, tool = "sonar") {
+  if (!filePath || !line || !ruleId) return false;
+  if (!fs.existsSync(filePath)) return false;
+  try {
+    const lines = fs.readFileSync(filePath, "utf8").split("\n");
+    const idx = line - 1;
+    const candidates = [lines[idx], lines[idx - 1]].filter(Boolean);
+    const escapedRule = escapeRegex(ruleId);
+    const escapedTool = escapeRegex(tool);
+    // New generalised marker + legacy sonar-only marker.
+    const reAudit = new RegExp(`karajan-audit-ignore\\s*:\\s*${escapedTool}:${escapedRule}\\b`);
+    const reLegacy = tool === "sonar"
+      ? new RegExp(`karajan-sonar-ignore\\s*:\\s*${escapedRule}\\b`)
+      : null;
+    return candidates.some((l) => reAudit.test(l) || (reLegacy && reLegacy.test(l)));
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegex(s) {
+  return String(s).replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Filter a list of normalised audit findings into kept + suppressed.
+ *
+ * @param {object[]} issues  Each issue must carry { tool, rule, component|path, line? }.
+ *                           `tool` defaults to "sonar" for backwards compat.
+ * @param {object} [opts]
+ * @param {object[]} [opts.extraRules]   Rules from config.audit.false_positives
+ *                                       (or legacy config.sonar.false_positives).
+ * @param {string} [opts.projectRoot]    Used to resolve component → absolute path.
+ * @returns {{ kept: object[], suppressed: object[] }}
+ */
+export function filterFalsePositives(issues, opts = {}) {
+  if (!Array.isArray(issues)) return { kept: [], suppressed: [] };
+  const rules = [...DEFAULT_FALSE_POSITIVES, ...(opts.extraRules || [])].map((r) => ({
+    tool: r.tool || "sonar",
+    rule: r.rule,
+    filePattern: r.filePattern instanceof RegExp ? r.filePattern : new RegExp(String(r.filePattern || ".*")),
+    reason: r.reason,
+  }));
+  const projectRoot = opts.projectRoot || process.cwd();
+  const kept = [];
+  const suppressed = [];
+
+  for (const issue of issues) {
+    const tool = issue.tool || "sonar";
+    const path = componentToPath(issue.component) || issue.path || "";
+    let matched = null;
+
+    // 1. Static rules.
+    for (const rule of rules) {
+      if (rule.tool === tool && issue.rule === rule.rule && rule.filePattern.test(path)) {
+        matched = { tool, rule: rule.rule, path, reason: rule.reason };
+        break;
+      }
+    }
+
+    // 2. Inline ignore (only checked if no static rule matched).
+    if (!matched && issue.rule && issue.line && path) {
+      const absPath = path.startsWith("/") ? path : `${projectRoot}/${path}`;
+      if (hasInlineIgnore(absPath, issue.line, issue.rule, tool)) {
+        matched = { tool, rule: issue.rule, path, reason: "inline `// karajan-audit-ignore`" };
+      }
+    }
+
+    if (matched) {
+      suppressed.push({ ...issue, _suppressedBy: matched });
+    } else {
+      kept.push(issue);
+    }
+  }
+  return { kept, suppressed };
+}
+
+function componentToPath(component) {
+  if (typeof component !== "string") return "";
+  const colonIdx = component.indexOf(":");
+  return colonIdx >= 0 ? component.slice(colonIdx + 1) : component;
+}

package/src/audit/webperf-input.js

@@ -39,7 +39,7 @@ function webperfHome() {
 }
 
 function projectSlug(projectDir) {
-  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
 }
 
 /**

package/src/brain/standby-store.js

@@ -34,7 +34,7 @@ export function standbyDoneDir() {
 
 function sanitizeId(sessionId) {
   if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId requerido");
-  return sessionId.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 120);
+  return sessionId.replaceAll(/[^a-zA-Z0-9._-]/g, "_").slice(0, 120);
 }
 
 /**

package/src/canvas/parse-md.js

@@ -218,7 +218,7 @@ function parseOperations(text) {
       if (testMatch && inAcceptance) {
         current.acceptance.push({
           type: testMatch[1].toLowerCase(),
-          content: testMatch[2].replace(/^`+|`+$/g, "").trim(),
+          content: testMatch[2].replaceAll(/^`+|`+$/g, "").trim(),
         });
       }
     }

package/src/commands/audit.js

@@ -157,7 +157,7 @@ async function resolveReportFilePath(flagValue, isJson) {
 
   let resolved;
   if (isDir) {
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const stamp = new Date().toISOString().replaceAll(/[:.]/g, "-");
     resolved = path.resolve(target, `audit-${stamp}.${ext}`);
   } else {
     resolved = path.resolve(target);

package/src/commands/plan/index.js

@@ -1,6 +1,4 @@
 // Barrel: re-export all plan sub-command handlers.
-import { planGenerateCommand } from "./generate.js";
-
 export { planGenerateCommand } from "./generate.js";
 export { planListCommand } from "./list.js";
 export { planShowCommand } from "./show.js";
@@ -11,6 +9,3 @@ export { planAddHuCommand } from "./add-hu.js";
 export { planRemoveHuCommand } from "./remove-hu.js";
 export { planMigrateResultCommand } from "./migrate-result.js";
 export { planFixCommand } from "./fix.js";
-
-// Keep backward compat — old callers import planCommand
-export const planCommand = planGenerateCommand;

package/src/commands/plan.js

@@ -12,5 +12,4 @@ export {
   planRemoveHuCommand,
   planMigrateResultCommand,
   planFixCommand,
-  planCommand,
 } from "./plan/index.js";

package/src/commands/webperf.js

@@ -26,7 +26,7 @@ function defaultReportDir() {
  * with audit history under ~/.karajan/.
  */
 function projectSlug(projectDir) {
-  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
 }
 
 function formatHumanReport(result) {

package/src/domains/domain-synthesizer.js

@@ -80,7 +80,7 @@ function buildKeywords(task, hints) {
 
   const taskWords = task
     .toLowerCase()
-    .replace(/[^a-z0-9\s-]/g, " ")
+    .replaceAll(/[^a-z0-9\s-]/g, " ")
     .split(/\s+/)
     .filter(w => w.length > 3 && !stopWords.has(w));
 

package/src/git/hu-automation.js

@@ -14,8 +14,8 @@ import { runCommand } from "../utils/process.js";
 export function buildHuBranchName(prefix, story) {
   const baseSlug = String(story.title || story.id || "hu")
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
+    .replaceAll(/[^a-z0-9]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
     .slice(0, 40);
   return `${prefix}${story.id}-${baseSlug}`;
 }

package/src/git/hu-snapshot.js

@@ -24,7 +24,7 @@ const REF_PREFIX = "refs/kj-snapshots/";
  */
 export function snapshotRefForHu(huId) {
   if (!huId) throw new Error("huId requerido");
-  const safe = String(huId).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
+  const safe = String(huId).replaceAll(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
   return REF_PREFIX + safe;
 }
 

package/src/hu/auto-generator.js

@@ -24,7 +24,7 @@ export function deriveProjectName(originalTask) {
   ]);
   const words = originalTask
     .toLowerCase()
-    .replace(/[^\p{L}\p{N}\s-]/gu, " ")
+    .replaceAll(/[^\p{L}\p{N}\s-]/gu, " ")
     .split(/\s+/)
     .filter(w => w && !STOPWORDS.has(w));
   const meaningful = words.slice(0, 6);

package/src/orchestrator/repair/repair-detector.js

@@ -50,9 +50,9 @@ const INFEASIBLE_SIGNATURES = [
 export function failureSignature(cmd, errorOutput) {
   const cmdNorm = String(cmd || "").trim().slice(0, 200);
   const errNorm = String(errorOutput || "")
-    .replace(/\s+/g, " ")        // collapse whitespace
-    .replace(/\d+/g, "N")          // numbers tend to drift; line numbers, counts
-    .replace(/\/[^\s]+/g, "/PATH") // absolute paths drift across runs
+    .replaceAll(/\s+/g, " ")        // collapse whitespace
+    .replaceAll(/\d+/g, "N")          // numbers tend to drift; line numbers, counts
+    .replaceAll(/\/[^\s]+/g, "/PATH") // absolute paths drift across runs
     .trim()
     .slice(0, 300);
   return `${cmdNorm}|||${errNorm}`;

package/src/plan/adr-generator.js

@@ -38,11 +38,11 @@ function slugifyTitle(title) {
     // Decompose accents (NFD) then strip combining marks so "versión"
     // → "version", keeping the ADR id ASCII-only and filesystem-safe.
     .normalize("NFD")
-    .replace(/[̀-ͯ]/g, "")
-    .replace(/[^a-z0-9\s-]/g, "")
-    .replace(/\s+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "")
+    .replaceAll(/[̀-ͯ]/g, "")
+    .replaceAll(/[^a-z0-9\s-]/g, "")
+    .replaceAll(/\s+/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-|-$/g, "")
     .slice(0, 80) || "untitled";
 }
 

package/src/plan/plan-id.js

@@ -8,7 +8,7 @@
  */
 export function generatePlanId() {
   const now = new Date();
-  const ts = now.toISOString().replace(/[-:T]/g, "").replace(/\.\d+Z$/, "");
+  const ts = now.toISOString().replaceAll(/[-:T]/g, "").replace(/\.\d+Z$/, "");
   const rand = Math.random().toString(36).slice(2, 6);
   return `plan-${ts}-${rand}`;
 }
@@ -36,10 +36,10 @@ export function normaliseAlias(name) {
   if (!name || typeof name !== "string") return null;
   const slug = name
     .normalize("NFKD")
-    .replace(/[̀-ͯ]/g, "")        // strip diacritics
+    .replaceAll(/[̀-ͯ]/g, "")        // strip diacritics
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")            // non-alphanum → guion
-    .replace(/^-+|-+$/g, "")                // trim guiones extremos
+    .replaceAll(/[^a-z0-9]+/g, "-")            // non-alphanum → guion
+    .replaceAll(/^-+|-+$/g, "")                // trim guiones extremos
     .slice(0, 60);
   return slug || null;
 }

package/src/plan/plan-store.js

@@ -50,7 +50,7 @@ export function projectSlug(projectDir) {
   return projectDir
     .replace(/^\//, "")
     .replace(/[/\\]/g, "_")
-    .replace(/[^a-zA-Z0-9_.-]/g, "")
+    .replaceAll(/[^a-zA-Z0-9_.-]/g, "")
     .slice(0, 120);
 }
 

package/src/plan/plan-structural-pass.js

@@ -31,7 +31,7 @@ export function removeOrphanRefs(plan) {
   return fixes;
 }
 
-export function breakCycles(plan) {
+function breakCycles(plan) {
   const fixes = [];
   let cycles = findCycles(plan.hus);
   let budget = plan.hus.length;

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/roles/perf-role.js

@@ -25,7 +25,7 @@ import { BaseRole } from "./base-role.js";
 import { runWebperfScan } from "../webperf/scanner.js";
 
 function projectSlug(projectDir) {
-  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
 }
 
 function defaultPersistDir() {

package/src/session/journal/decisions-writer.js

@@ -41,7 +41,7 @@ import { getSessionRoot } from "../../utils/paths.js";
  */
 
 function esc(text) {
-  return String(text ?? "").replace(/\|/g, "\\|");
+  return String(text ?? "").replaceAll(/\|/g, "\\|");
 }
 
 function formatConditions(conditions) {

package/src/session/journal/iteration-logger.js

@@ -28,7 +28,7 @@
  */
 
 function esc(text) {
-  return String(text ?? "").replace(/\|/g, "\\|");
+  return String(text ?? "").replaceAll(/\|/g, "\\|");
 }
 
 function formatDuration(ms) {

package/src/session/journal/summary-writer.js

@@ -33,7 +33,7 @@ import path from "node:path";
  */
 
 function esc(text) {
-  return String(text ?? "").replace(/\|/g, "\\|");
+  return String(text ?? "").replaceAll(/\|/g, "\\|");
 }
 
 function formatDuration(ms) {

package/src/skills/addyosmani-catalog.js

@@ -279,7 +279,7 @@ export async function listAvailableSlugs() {
  */
 export async function loadSkillBySlug(slug) {
   if (!slug || typeof slug !== "string") return null;
-  const safeSlug = slug.trim().replace(/[^A-Za-z0-9._-]/g, "");
+  const safeSlug = slug.trim().replaceAll(/[^A-Za-z0-9._-]/g, "");
   if (!safeSlug) return null;
 
   const skillPath = path.join(getSkillsRoot(), safeSlug, SKILL_FILE);

package/src/skills/semantic-detector.js

@@ -16,6 +16,7 @@
 
 import { createAgent } from "../agents/index.js";
 import { resolveRole } from "../config.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 /**
  * Curated catalog of skills the classifier is allowed to suggest. Keeping
@@ -106,15 +107,29 @@ export async function refineSkillsSemantically({ task, alreadyDetected = [], con
   }
 
   const prompt = PROMPT(task, SEMANTIC_CATALOG, alreadyDetected);
+  // KJC-TSK-0413 step D: wrap with Brain Recovery. semantic-detector usa
+  // signature legacy `runTask(prompt, opts)` — adapter normaliza al estándar
+  // `runTask({ prompt, timeoutMs })` que withBrainRecovery espera.
+  const adapter = {
+    provider: agent.provider,
+    runTask: (args) => agent.runTask(args.prompt, { timeoutMs: args.timeoutMs }),
+  };
   let res;
   try {
-    res = await agent.runTask(prompt, { timeoutMs: 30_000 });
+    res = await withBrainRecovery({
+      agent: adapter,
+      taskArgs: { prompt, timeoutMs: 30_000 },
+      role: "semantic-detector",
+      logger,
+    });
   } catch (err) {
     logger?.warn?.(`semantic-detector: classifier call failed (${err.message}) — skipping`);
     return [];
   }
   if (!res?.ok) {
-    logger?.debug?.("semantic-detector: classifier returned not-ok — skipping");
+    // En test env el sleep es no-op así que abort viene rápido. Skip-on-fail
+    // sigue siendo el comportamiento — semantic detection es best-effort.
+    logger?.debug?.(`semantic-detector: classifier returned not-ok (${res?.recovery?.class || "unknown"}) — skipping`);
     return [];
   }
 

package/src/skills/skills-cache.js

@@ -24,7 +24,7 @@ export function getCacheRoot() {
 
 function sanitize(name) {
   // Allow safe skill name characters, replace everything else with "_".
-  return String(name || "").replace(/[^A-Za-z0-9._-]/g, "_");
+  return String(name || "").replaceAll(/[^A-Za-z0-9._-]/g, "_");
 }
 
 function metaPath(name) {

package/src/sonar/api.js

@@ -2,6 +2,7 @@ import { runCommand } from "../utils/process.js";
 import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 import { resolveSonarToken } from "./config-resolver.js";
+import { filterFalsePositives } from "./issue-filter.js";
 
 class SonarApiError extends Error {
   constructor(message, { url, httpStatus, hint } = {}) {
@@ -83,10 +84,31 @@ export async function getOpenIssues(config, projectKey = null) {
   const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
   const body = await sonarFetch(config, `/api/issues/search?projectKeys=${effectiveProjectKey}&statuses=OPEN`);
 
+  let parsedIssues = [];
+  let parsedRaw = body;
   try {
     const parsed = JSON.parse(body);
-    return { total: parsed.total || 0, issues: parsed.issues || [], raw: parsed };
-  } catch { /* SonarQube response is not valid JSON */
-    return { total: 0, issues: [], raw: body };
-  }
+    parsedIssues = parsed.issues || [];
+    parsedRaw = parsed;
+  } catch { /* SonarQube response is not valid JSON */ }
+
+  // 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.
+  // 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,
+  });
+
+  return {
+    total: kept.length,
+    issues: kept,
+    suppressed,
+    raw: parsedRaw,
+  };
 }

package/src/sonar/config-resolver.js

@@ -16,7 +16,7 @@ const DEFAULT_HOST = "http://localhost:9000";
  */
 export function resolveSonarHost(rawHost) {
   const host = String(rawHost || DEFAULT_HOST)
-    .replace(/host\.docker\.internal/g, "localhost")
+    .replaceAll(/host\.docker\.internal/g, "localhost")
     .replace(/\/+$/, "");
   return host;
 }

package/src/sonar/issue-filter.js

@@ -0,0 +1,12 @@
+// @deprecated — moved to src/audit/issue-filter.js (v2.17.0). This shim
+// re-exports the generalised filter so existing imports keep working. All
+// Sonar-specific behaviour (default `tool="sonar"`, legacy
+// `// karajan-sonar-ignore: <rule>` markers) is preserved by the new module.
+//
+// New code should import from "../audit/issue-filter.js" directly.
+
+export {
+  filterFalsePositives,
+  hasInlineIgnore,
+  DEFAULT_FALSE_POSITIVES,
+} from "../audit/issue-filter.js";

package/src/sonar/scanner.js

@@ -164,7 +164,7 @@ async function ensureSonarProjectProperties(cwd = process.cwd()) {
     } catch {
       // no package.json or invalid JSON — use defaults
     }
-    const projectKey = (pkg.name || path.basename(cwd)).replace(/[^a-zA-Z0-9_.-]/g, "_");
+    const projectKey = (pkg.name || path.basename(cwd)).replaceAll(/[^a-zA-Z0-9_.-]/g, "_");
     const props = [
       `sonar.projectKey=${projectKey}`,
       `sonar.projectName=${pkg.name || path.basename(cwd)}`,

package/src/utils/derive-project-name-from-cwd.js

@@ -40,9 +40,9 @@ function prettifyName(raw) {
   if (!trimmed) return null;
   // Insert space at camelCase boundaries, then split on -/_/whitespace.
   const spaced = trimmed
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .replace(/[-_]+/g, " ")
-    .replace(/\s+/g, " ")
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replaceAll(/[-_]+/g, " ")
+    .replaceAll(/\s+/g, " ")
     .trim();
   if (!spaced) return null;
   return spaced

package/src/utils/injection-guard.js

@@ -178,7 +178,7 @@ export function scanDiff(diff, opts = {}) {
 function excerpt(text, index) {
   const start = Math.max(0, index - 20);
   const end = Math.min(text.length, index + 100);
-  return text.slice(start, end).replace(/\n/g, "\\n").slice(0, 120);
+  return text.slice(start, end).replaceAll(/\n/g, "\\n").slice(0, 120);
 }
 
 function lineAt(text, index) {

package/src/utils/messages.js

@@ -48,7 +48,7 @@ const MESSAGES = {
  */
 export function msg(key, lang = "en", params = {}) {
   const template = MESSAGES[lang]?.[key] || MESSAGES.en[key] || key;
-  return template.replace(/\{(\w+)\}/g, (_, k) => params[k] ?? `{${k}}`);
+  return template.replaceAll(/\{(\w+)\}/g, (_, k) => params[k] ?? `{${k}}`);
 }
 
 /**