karajan-code 1.22.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli.js

@@ -75,6 +75,7 @@ program
   .option("--enable-researcher")
   .option("--enable-tester")
   .option("--enable-security")
+  .option("--enable-impeccable")
   .option("--enable-triage")
   .option("--enable-discover")
   .option("--enable-architect")

package/src/commands/init.js

@@ -204,6 +204,56 @@ async function scaffoldBecariaGateway(config, flags, logger) {
   logger.info("  4. Push the workflow files and enable 'kj run --enable-becaria'");
 }
 
+async function installSkills(logger, interactive) {
+  const projectDir = process.cwd();
+  const commandsDir = path.join(projectDir, ".claude", "commands");
+  const skillsTemplateDir = path.resolve(import.meta.dirname, "../../templates/skills");
+
+  let doInstall = true;
+  if (interactive) {
+    const wizard = createWizard();
+    try {
+      doInstall = await wizard.confirm("Install Karajan skills as slash commands (/kj-code, /kj-review, etc.)?", true);
+    } finally {
+      wizard.close();
+    }
+  }
+
+  if (!doInstall) {
+    logger.info("Skills installation skipped.");
+    return;
+  }
+
+  await ensureDir(commandsDir);
+
+  let installed = 0;
+  try {
+    const files = await fs.readdir(skillsTemplateDir);
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      const src = path.join(skillsTemplateDir, file);
+      const dest = path.join(commandsDir, file);
+      if (await exists(dest)) {
+        logger.info(`  ${file} already exists — skipping`);
+        continue;
+      }
+      const content = await fs.readFile(src, "utf8");
+      await fs.writeFile(dest, content, "utf8");
+      installed += 1;
+    }
+  } catch (err) {
+    logger.warn(`Could not install skills: ${err.message}`);
+    return;
+  }
+
+  if (installed > 0) {
+    logger.info(`Installed ${installed} Karajan skill(s) in .claude/commands/`);
+    logger.info("Available as slash commands: /kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar");
+  } else {
+    logger.info("All skills already installed.");
+  }
+}
+
 export async function initCommand({ logger, flags = {} }) {
   const karajanHome = getKarajanHome();
   await ensureDir(karajanHome);
@@ -219,6 +269,7 @@ export async function initCommand({ logger, flags = {} }) {
   await handleConfigSetup({ config, configExists, interactive, configPath, logger });
   await ensureReviewRules(reviewRulesPath, logger);
   await ensureCoderRules(coderRulesPath, logger);
+  await installSkills(logger, interactive);
   await setupSonarQube(config, logger);
   await scaffoldBecariaGateway(config, flags, logger);
 }

package/src/commands/run.js

@@ -7,6 +7,12 @@ import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 
 export async function runCommandHandler({ task, config, logger, flags }) {
+  // Best-effort session cleanup before starting
+  try {
+    const { cleanupExpiredSessions } = await import("../session-cleanup.js");
+    await cleanupExpiredSessions({ logger });
+  } catch { /* non-blocking */ }
+
   const requiredProviders = [
     resolveRole(config, "coder").provider,
     config.reviewer_options?.fallback_reviewer

package/src/config.js

@@ -16,6 +16,7 @@ const DEFAULTS = {
     researcher: { provider: null, model: null },
     tester: { provider: null, model: null },
     security: { provider: null, model: null },
+    impeccable: { provider: null, model: null },
     triage: { provider: null, model: null },
     discover: { provider: null, model: null },
     architect: { provider: null, model: null }
@@ -27,6 +28,7 @@ const DEFAULTS = {
     researcher: { enabled: false },
     tester: { enabled: true },
     security: { enabled: true },
+    impeccable: { enabled: false },
     triage: { enabled: true },
     discover: { enabled: false },
     architect: { enabled: false }
@@ -276,7 +278,7 @@ const ROLE_MODEL_FLAGS = [
 const PIPELINE_ENABLE_FLAGS = [
   ["enablePlanner", "planner"], ["enableRefactorer", "refactorer"],
   ["enableSolomon", "solomon"], ["enableResearcher", "researcher"],
-  ["enableTester", "tester"], ["enableSecurity", "security"],
+  ["enableTester", "tester"], ["enableSecurity", "security"], ["enableImpeccable", "impeccable"],
   ["enableTriage", "triage"], ["enableDiscover", "discover"],
   ["enableArchitect", "architect"]
 ];
@@ -408,14 +410,14 @@ export function resolveRole(config, role) {
   let provider = roleConfig.provider ?? null;
   if (!provider && role === "coder") provider = legacyCoder;
   if (!provider && role === "reviewer") provider = legacyReviewer;
-  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage" || role === "discover" || role === "architect")) {
+  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect")) {
     provider = roles.coder?.provider || legacyCoder;
   }
 
   let model = roleConfig.model ?? null;
   if (!model && role === "coder") model = config?.coder_options?.model ?? null;
   if (!model && role === "reviewer") model = config?.reviewer_options?.model ?? null;
-  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage" || role === "discover" || role === "architect")) {
+  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect")) {
     model = config?.coder_options?.model ?? null;
   }
 
@@ -426,7 +428,7 @@ export function resolveRole(config, role) {
 const RUN_PIPELINE_ROLES = [
   ["reviewer", "reviewer"], ["triage", "triage"], ["planner", "planner"],
   ["refactorer", "refactorer"], ["researcher", "researcher"],
-  ["tester", "tester"], ["security", "security"]
+  ["tester", "tester"], ["security", "security"], ["impeccable", "impeccable"]
 ];
 
 // Direct command-to-role mapping for non-"run" commands

package/src/guards/intent-guard.js

@@ -51,6 +51,16 @@ const INTENT_PATTERNS = [
     confidence: 0.9,
     message: "Trivial fix detected",
   },
+  // Frontend / UI tasks (sets hasFrontend flag for impeccable role activation)
+  {
+    id: "frontend-ui",
+    keywords: ["html", "css", "ui", "landing", "component", "responsive", "accessibility", "a11y", "frontend", "design", "layout", "styling", "dark mode", "animation"],
+    taskType: "sw",
+    level: "simple",
+    confidence: 0.8,
+    message: "Frontend/UI task detected",
+    hasFrontend: true,
+  },
 ];
 
 /**
@@ -106,7 +116,7 @@ export function classifyIntent(task, config = {}) {
     if (!matchesKeywords(task, pattern.keywords)) continue;
 
     if (pattern.confidence >= threshold) {
-      return {
+      const result = {
         classified: true,
         taskType: pattern.taskType,
         level: pattern.level,
@@ -114,6 +124,8 @@ export function classifyIntent(task, config = {}) {
         patternId: pattern.id,
         message: pattern.message,
       };
+      if (pattern.hasFrontend) result.hasFrontend = true;
+      return result;
     }
   }
 

package/src/mcp/run-kj.js

@@ -42,6 +42,7 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   normalizeBoolFlag(options.enableResearcher, "--enable-researcher", args);
   normalizeBoolFlag(options.enableTester, "--enable-tester", args);
   normalizeBoolFlag(options.enableSecurity, "--enable-security", args);
+  normalizeBoolFlag(options.enableImpeccable, "--enable-impeccable", args);
   normalizeBoolFlag(options.enableTriage, "--enable-triage", args);
   normalizeBoolFlag(options.enableDiscover, "--enable-discover", args);
   normalizeBoolFlag(options.enableArchitect, "--enable-architect", args);

package/src/mcp/server-handlers.js

@@ -239,6 +239,12 @@ export async function handleRunDirect(a, server, extra) {
   await assertNotOnBaseBranch(config);
   const logger = createLogger(config.output.log_level, "mcp");
 
+  // Best-effort session cleanup before starting
+  try {
+    const { cleanupExpiredSessions } = await import("../session-cleanup.js");
+    await cleanupExpiredSessions({ logger });
+  } catch { /* non-blocking */ }
+
   const requiredProviders = [
     resolveRole(config, "coder").provider,
     config.reviewer_options?.fallback_reviewer
@@ -821,6 +827,7 @@ async function handleResume(a, server, extra) {
   if (!a.sessionId) {
     return failPayload("Missing required field: sessionId");
   }
+  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable"]);
   return handleResumeDirect(a, server, extra);
 }
 
@@ -837,7 +844,7 @@ async function handleRun(a, server, extra) {
   if (!isPreflightAcked()) {
     return buildPreflightRequiredResponse("kj_run");
   }
-  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity"]);
+  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable"]);
   return handleRunDirect(a, server, extra);
 }
 

package/src/mcp/tools.js

@@ -69,6 +69,7 @@ export const tools = [
         enableResearcher: { type: "boolean" },
         enableTester: { type: "boolean" },
         enableSecurity: { type: "boolean" },
+        enableImpeccable: { type: "boolean" },
         enableTriage: { type: "boolean" },
         enableDiscover: { type: "boolean" },
         enableArchitect: { type: "boolean" },

package/src/orchestrator/post-loop-stages.js

@@ -1,5 +1,6 @@
 import { TesterRole } from "../roles/tester-role.js";
 import { SecurityRole } from "../roles/security-role.js";
+import { ImpeccableRole } from "../roles/impeccable-role.js";
 import { addCheckpoint, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { invokeSolomon } from "./solomon-escalation.js";
@@ -163,3 +164,53 @@ export async function runSecurityStage({ config, logger, emitter, eventBase, ses
   session.security_retry_count = 0;
   return { action: "ok", stageResult: { ok: true, summary: securityOutput.summary || "No vulnerabilities found" } };
 }
+
+export async function runImpeccableStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff }) {
+  logger.setContext({ iteration, stage: "impeccable" });
+  emitProgress(
+    emitter,
+    makeEvent("impeccable:start", { ...eventBase, stage: "impeccable" }, {
+      message: "Impeccable auditing frontend design quality"
+    })
+  );
+
+  const impeccable = new ImpeccableRole({ config, logger, emitter });
+  await impeccable.init({ task, iteration });
+  const impeccableStart = Date.now();
+  let impeccableOutput;
+  try {
+    impeccableOutput = await impeccable.run({ task, diff });
+  } catch (err) {
+    logger.warn(`Impeccable threw: ${err.message}`);
+    impeccableOutput = { ok: false, summary: `Impeccable error: ${err.message}`, result: { error: err.message } };
+  }
+  trackBudget({
+    role: "impeccable",
+    provider: config?.roles?.impeccable?.provider || coderRole.provider,
+    model: config?.roles?.impeccable?.model || coderRole.model,
+    result: impeccableOutput,
+    duration_ms: Date.now() - impeccableStart
+  });
+
+  await addCheckpoint(session, {
+    stage: "impeccable",
+    iteration,
+    ok: impeccableOutput.ok,
+    provider: config?.roles?.impeccable?.provider || coderRole.provider,
+    model: config?.roles?.impeccable?.model || coderRole.model || null
+  });
+
+  const verdict = impeccableOutput.result?.verdict || "APPROVED";
+  emitProgress(
+    emitter,
+    makeEvent("impeccable:end", { ...eventBase, stage: "impeccable" }, {
+      status: impeccableOutput.ok ? "ok" : "fail",
+      message: impeccableOutput.ok
+        ? (verdict === "IMPROVED" ? "Impeccable applied design fixes" : "Impeccable audit passed")
+        : `Impeccable: ${impeccableOutput.summary}`
+    })
+  );
+
+  // Impeccable is advisory — failures do not block the pipeline
+  return { action: "ok", stageResult: { ok: impeccableOutput.ok, verdict, summary: impeccableOutput.summary || "No frontend design issues found" } };
+}

package/src/orchestrator/pre-loop-stages.js

@@ -11,7 +11,7 @@ import { parsePlannerOutput } from "../prompts/planner.js";
 import { selectModelsForRoles } from "../utils/model-selector.js";
 import { createStallDetector } from "../utils/stall-detector.js";
 
-const ROLE_NAMES = ["planner", "researcher", "architect", "refactorer", "reviewer", "tester", "security"];
+const ROLE_NAMES = ["planner", "researcher", "architect", "refactorer", "reviewer", "tester", "security", "impeccable"];
 
 function buildRoleOverrides(recommendedRoles, pipelineConfig) {
   const overrides = {};

package/src/orchestrator.js

@@ -31,7 +31,7 @@ import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage } from "./orchestrator/pre-loop-stages.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
-import { runTesterStage, runSecurityStage } from "./orchestrator/post-loop-stages.js";
+import { runTesterStage, runSecurityStage, runImpeccableStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 
 
@@ -44,6 +44,7 @@ function resolvePipelineFlags(config) {
     researcherEnabled: Boolean(config.pipeline?.researcher?.enabled),
     testerEnabled: Boolean(config.pipeline?.tester?.enabled),
     securityEnabled: Boolean(config.pipeline?.security?.enabled),
+    impeccableEnabled: Boolean(config.pipeline?.impeccable?.enabled),
     reviewerEnabled: config.pipeline?.reviewer?.enabled !== false,
     discoverEnabled: Boolean(config.pipeline?.discover?.enabled),
     architectEnabled: Boolean(config.pipeline?.architect?.enabled),
@@ -51,7 +52,7 @@ function resolvePipelineFlags(config) {
 }
 
 async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
-  const { plannerEnabled, refactorerEnabled, researcherEnabled, testerEnabled, securityEnabled, reviewerEnabled, discoverEnabled, architectEnabled } = pipelineFlags;
+  const { plannerEnabled, refactorerEnabled, researcherEnabled, testerEnabled, securityEnabled, impeccableEnabled, reviewerEnabled, discoverEnabled, architectEnabled } = pipelineFlags;
   const plannerRole = resolveRole(config, "planner");
   const coderRole = resolveRole(config, "coder");
   const reviewerRole = resolveRole(config, "reviewer");
@@ -84,6 +85,7 @@ async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
       researcher_enabled: researcherEnabled,
       tester_enabled: testerEnabled,
       security_enabled: securityEnabled,
+      impeccable_enabled: impeccableEnabled,
       solomon_enabled: Boolean(config.pipeline?.solomon?.enabled)
     },
     limits: {
@@ -203,7 +205,7 @@ async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
 }
 
 function applyTriageOverrides(pipelineFlags, roleOverrides) {
-  const keys = ["plannerEnabled", "researcherEnabled", "architectEnabled", "refactorerEnabled", "reviewerEnabled", "testerEnabled", "securityEnabled"];
+  const keys = ["plannerEnabled", "researcherEnabled", "architectEnabled", "refactorerEnabled", "reviewerEnabled", "testerEnabled", "securityEnabled", "impeccableEnabled"];
   for (const key of keys) {
     if (roleOverrides[key] !== undefined) {
       pipelineFlags[key] = roleOverrides[key];
@@ -271,6 +273,7 @@ function applyFlagOverrides(pipelineFlags, flags) {
   if (flags.enableReviewer !== undefined) pipelineFlags.reviewerEnabled = Boolean(flags.enableReviewer);
   if (flags.enableTester !== undefined) pipelineFlags.testerEnabled = Boolean(flags.enableTester);
   if (flags.enableSecurity !== undefined) pipelineFlags.securityEnabled = Boolean(flags.enableSecurity);
+  if (flags.enableImpeccable !== undefined) pipelineFlags.impeccableEnabled = Boolean(flags.enableImpeccable);
 }
 
 function resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags }) {
@@ -892,7 +895,7 @@ async function runGuardStages({ config, logger, emitter, eventBase, session, ite
   return { action: "ok" };
 }
 
-async function runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults }) {
+async function runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults, coderRole, pipelineFlags }) {
   const tddResult = await runTddCheckStage({ config, logger, emitter, eventBase, session, trackBudget, iteration: i, askQuestion });
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
   if (tddResult.action === "continue") return { action: "continue" };
@@ -919,6 +922,17 @@ async function runQualityGateStages({ config, logger, emitter, eventBase, sessio
     }
   }
 
+  if (pipelineFlags?.impeccableEnabled) {
+    const diff = await generateDiff({ baseRef: session.session_start_sha });
+    const impeccableResult = await runImpeccableStage({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget,
+      iteration: i, task, diff
+    });
+    if (impeccableResult.stageResult) {
+      stageResults.impeccable = impeccableResult.stageResult;
+    }
+  }
+
   return { action: "ok" };
 }
 
@@ -1071,7 +1085,7 @@ async function runSingleIteration(ctx) {
   const guardResult = await runGuardStages({ config, logger, emitter, eventBase, session, iteration: i });
   if (guardResult.action === "return") return guardResult;
 
-  const qgResult = await runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults });
+  const qgResult = await runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults, coderRole, pipelineFlags });
   if (qgResult.action === "return" || qgResult.action === "continue") return qgResult;
 
   await handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i });

package/src/roles/impeccable-role.js

@@ -0,0 +1,121 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on auditing frontend/UI code for design quality."
+].join(" ");
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.impeccable?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function buildPrompt({ task, diff, instructions }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push(
+    `## Task\n${task}`
+  );
+
+  if (diff) {
+    sections.push(`## Git diff to audit\n${diff}`);
+  }
+
+  return sections.join("\n\n");
+}
+
+function parseImpeccableOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = /\{[\s\S]*\}/.exec(text);
+  if (!jsonMatch) return null;
+  return JSON.parse(jsonMatch[0]);
+}
+
+function buildSummary(parsed) {
+  const verdict = parsed.verdict || "APPROVED";
+  const found = parsed.issuesFound || 0;
+  const fixed = parsed.issuesFixed || 0;
+
+  if (verdict === "APPROVED" || found === 0) {
+    return `Verdict: APPROVED; No frontend design issues found`;
+  }
+
+  const cats = parsed.categories || {};
+  const parts = Object.entries(cats)
+    .filter(([, count]) => count > 0)
+    .map(([cat, count]) => `${count} ${cat}`);
+
+  return `Verdict: ${verdict}; ${found} issue(s) found, ${fixed} fixed (${parts.join(", ")})`;
+}
+
+export class ImpeccableRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "impeccable", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const { task, diff } = typeof input === "string"
+      ? { task: input, diff: null }
+      : { task: input?.task || this.context?.task || "", diff: input?.diff || null };
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildPrompt({ task, diff, instructions: this.instructions });
+    const result = await agent.runTask({ prompt, role: "impeccable" });
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || "Impeccable audit failed",
+          provider
+        },
+        summary: `Impeccable audit failed: ${result.error || "unknown error"}`
+      };
+    }
+
+    try {
+      const parsed = parseImpeccableOutput(result.output);
+      if (!parsed) {
+        return {
+          ok: false,
+          result: { error: "Failed to parse impeccable output: no JSON found", provider },
+          summary: "Impeccable output parse error: no JSON found"
+        };
+      }
+
+      const verdict = parsed.verdict || (parsed.issuesFound > 0 ? "IMPROVED" : "APPROVED");
+      const ok = verdict === "APPROVED" || verdict === "IMPROVED";
+
+      return {
+        ok,
+        result: {
+          verdict,
+          issuesFound: parsed.issuesFound || 0,
+          issuesFixed: parsed.issuesFixed || 0,
+          categories: parsed.categories || {},
+          changes: parsed.changes || [],
+          provider
+        },
+        summary: buildSummary({ ...parsed, verdict })
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        result: { error: `Failed to parse impeccable output: ${err.message}`, provider },
+        summary: `Impeccable output parse error: ${err.message}`
+      };
+    }
+  }
+}

package/src/roles/triage-role.js

@@ -4,7 +4,7 @@ import { buildTriagePrompt } from "../prompts/triage.js";
 import { VALID_TASK_TYPES } from "../guards/policy-resolver.js";
 
 const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
-const VALID_ROLES = new Set(["planner", "researcher", "refactorer", "reviewer", "tester", "security"]);
+const VALID_ROLES = new Set(["planner", "researcher", "refactorer", "reviewer", "tester", "security", "impeccable"]);
 const FALLBACK_TASK_TYPE = "sw";
 
 function resolveProvider(config) {

package/src/session-cleanup.js

@@ -1,48 +1,72 @@
 /**
  * Automatic cleanup of expired sessions.
- * Removes session directories older than session.expiry_days (default: 30).
+ *
+ * Policy (by status):
+ * - failed / stopped: removed after 1 day
+ * - approved: removed after 7 days
+ * - running (stale): marked failed + removed after 1 day (crash without cleanup)
+ * - paused: kept (user may want to resume)
+ *
+ * Runs automatically at the start of every kj_run (best-effort, non-blocking).
  */
 
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getSessionRoot } from "./utils/paths.js";
 
-const DEFAULT_EXPIRY_DAYS = 30;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
 
-async function tryRemoveOrphan({ sessionDir, dirName, cutoff, removed, errors, logger }) {
-  const stat = await fs.stat(sessionDir).catch(() => null);
-  if (!stat || stat.mtimeMs >= cutoff) return;
-  try {
-    await fs.rm(sessionDir, { recursive: true, force: true });
-    removed.push(dirName);
-    logger?.debug?.(`Orphan session dir removed: ${dirName}`);
-  } catch (error_) {
-    errors.push({ session: dirName, error: error_.message });
-  }
+const POLICY = {
+  failed:   { expiryMs: ONE_DAY_MS },
+  stopped:  { expiryMs: ONE_DAY_MS },
+  running:  { expiryMs: ONE_DAY_MS },   // stale — crashed without marking failed
+  approved: { expiryMs: 7 * ONE_DAY_MS },
+  paused:   null                          // never auto-delete
+};
+
+function shouldRemove(session) {
+  const status = session.status || "unknown";
+  const policy = POLICY[status];
+  if (!policy) return false;
+
+  const updatedAt = new Date(session.updated_at || session.created_at).getTime();
+  return Date.now() - updatedAt > policy.expiryMs;
 }
 
-async function tryCleanupSession({ sessionDir, dirName, cutoff, removed, errors, logger }) {
+async function tryCleanupSession({ sessionDir, dirName, removed, errors, logger }) {
   const sessionFile = path.join(sessionDir, "session.json");
+  let session;
   try {
     const raw = await fs.readFile(sessionFile, "utf8");
-    const session = JSON.parse(raw);
-    const updatedAt = new Date(session.updated_at || session.created_at).getTime();
-    if (updatedAt < cutoff) {
-      await fs.rm(sessionDir, { recursive: true, force: true });
-      removed.push(dirName);
-      logger?.debug?.(`Session expired and removed: ${dirName}`);
-    }
+    session = JSON.parse(raw);
   } catch {
-    await tryRemoveOrphan({ sessionDir, dirName, cutoff, removed, errors, logger });
+    // Orphan dir without valid session.json — remove if older than 1 day
+    const stat = await fs.stat(sessionDir).catch(() => null);
+    if (stat && Date.now() - stat.mtimeMs > ONE_DAY_MS) {
+      try {
+        await fs.rm(sessionDir, { recursive: true, force: true });
+        removed.push(dirName);
+        logger?.debug?.(`Orphan session dir removed: ${dirName}`);
+      } catch (err) {
+        errors.push({ session: dirName, error: err.message });
+      }
+    }
+    return;
   }
-}
 
-export async function cleanupExpiredSessions({ config, logger } = {}) {
-  const expiryDays = config?.session?.expiry_days ?? DEFAULT_EXPIRY_DAYS;
-  if (expiryDays <= 0) return { removed: 0, errors: [] };
+  if (!shouldRemove(session)) return;
+
+  try {
+    await fs.rm(sessionDir, { recursive: true, force: true });
+    removed.push(dirName);
+    logger?.debug?.(`Session cleaned up: ${dirName} (status: ${session.status})`);
+  } catch (err) {
+    errors.push({ session: dirName, error: err.message });
+  }
+}
 
+export async function cleanupExpiredSessions({ logger } = {}) {
   const sessionRoot = getSessionRoot();
-  const cutoff = Date.now() - expiryDays * 24 * 60 * 60 * 1000;
 
   let entries;
   try {
@@ -57,7 +81,7 @@ export async function cleanupExpiredSessions({ config, logger } = {}) {
 
   for (const dir of dirs) {
     const sessionDir = path.join(sessionRoot, dir.name);
-    await tryCleanupSession({ sessionDir, dirName: dir.name, cutoff, removed, errors, logger });
+    await tryCleanupSession({ sessionDir, dirName: dir.name, removed, errors, logger });
   }
 
   if (removed.length > 0) {

package/templates/roles/impeccable.md

@@ -0,0 +1,125 @@
+# Impeccable Role
+
+You are the **Impeccable Design Auditor** in a multi-role AI pipeline. You run after SonarQube and before the reviewer. Your job is to audit changed UI/frontend files for design quality issues and apply fixes automatically.
+
+## Scope constraint
+
+- **ONLY audit and fix files present in the diff.** Do not touch files that were not changed.
+- If no frontend files (.html, .css, .astro, .jsx, .tsx, .vue, .svelte, .lit, .js with DOM manipulation) are in the diff, report APPROVED immediately with 0 issues.
+
+## Input
+
+- **Task**: {{task}}
+- **Diff**: {{diff}}
+- **Context**: {{context}}
+
+## Phase 1 — Audit
+
+Analyze all changed files in the diff that are frontend-related. Run these checks systematically:
+
+### 1. Accessibility (a11y)
+- Missing ARIA labels on interactive elements
+- No `focus-visible` styles on focusable elements
+- Missing `alt` text on images
+- Non-semantic HTML (e.g. `<div>` used as buttons instead of `<button>`)
+- Missing skip links for navigation
+- Keyboard traps (focus cannot leave a component)
+- Insufficient color contrast
+
+### 2. Performance
+- Render-blocking resources (synchronous scripts in `<head>`)
+- Missing `loading="lazy"` on below-fold images
+- Animating layout properties (`width`, `height`, `top`, `left`) instead of `transform`/`opacity`
+- Missing image dimensions (`width`/`height` attributes) causing CLS
+- No `prefers-reduced-motion` support for animations
+
+### 3. Theming
+- Hard-coded colors not using design tokens or CSS custom properties
+- Broken dark mode (elements invisible or unreadable in dark theme)
+- Inconsistent token usage across the same component
+
+### 4. Responsive
+- Fixed widths (`width: 500px`) that break on mobile viewports
+- Touch targets smaller than 44×44px
+- Horizontal scroll on narrow viewports (< 375px)
+- Text that does not scale with user font-size preferences
+
+### 5. Anti-patterns
+- AI slop tells: gratuitous gradient text, excessive card grids, bounce animations, glassmorphism overuse
+- Gray text on colored backgrounds (poor readability)
+- Deeply nested cards (card inside card inside card)
+- Generic fallback fonts without a proper font stack
+
+## Phase 2 — Fix
+
+For each issue found in Phase 1, apply the fix directly. Use the **Edit** tool for targeted changes — never use Write to overwrite entire files.
+
+### Priority order
+1. **Critical a11y** — keyboard accessibility, ARIA attributes, semantic HTML
+2. **Performance** — CLS fixes, render-blocking resources
+3. **Theming** — design token consistency, dark mode
+4. **Responsive** — viewport, touch targets, scaling
+5. **Anti-pattern cleanup** — slop removal, readability
+
+### Rules
+- Each fix must be minimal and targeted (Edit, not Write)
+- Only use Read, Edit, Grep, Glob, and Bash tools
+- Verify each fix with `git diff` to confirm only intended lines changed
+- If a fix would require changes outside the diff, skip it and note it in the report
+
+## Phase 3 — Report
+
+Output a strict JSON object:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "verdict": "APPROVED",
+    "issuesFound": 0,
+    "issuesFixed": 0,
+    "categories": {
+      "a11y": 0,
+      "performance": 0,
+      "theming": 0,
+      "responsive": 0,
+      "antiPatterns": 0
+    },
+    "changes": []
+  },
+  "summary": "No frontend design issues found"
+}
+```
+
+When issues are found and fixed:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "verdict": "IMPROVED",
+    "issuesFound": 3,
+    "issuesFixed": 3,
+    "categories": {
+      "a11y": 2,
+      "performance": 1,
+      "theming": 0,
+      "responsive": 0,
+      "antiPatterns": 0
+    },
+    "changes": [
+      {
+        "file": "src/components/Button.astro",
+        "issue": "Non-semantic div used as button",
+        "fix": "Replaced <div onclick> with <button>",
+        "category": "a11y"
+      }
+    ]
+  },
+  "summary": "3 design issues found and fixed (2 a11y, 1 performance)"
+}
+```
+
+### Verdict rules
+- **APPROVED** — No frontend design issues found (issuesFound === 0)
+- **IMPROVED** — Issues were found and fixes were applied (issuesFixed > 0)

package/templates/roles/triage.md

@@ -9,7 +9,7 @@ Return a single valid JSON object and nothing else:
 {
   "level": "trivial|simple|medium|complex",
   "taskType": "sw|infra|doc|add-tests|refactor",
-  "roles": ["planner", "researcher", "refactorer", "reviewer", "tester", "security"],
+  "roles": ["planner", "researcher", "refactorer", "reviewer", "tester", "security", "impeccable"],
   "reasoning": "brief practical justification",
   "shouldDecompose": false,
   "subtasks": []
@@ -41,6 +41,13 @@ When `shouldDecompose` is true, provide `subtasks`: an array of 2-5 short string
 
 When `shouldDecompose` is false, `subtasks` must be an empty array.
 
+## Frontend detection
+If the task involves frontend/UI work, include `"impeccable"` in `roles`. Detect frontend tasks by:
+- **File extensions**: .html, .css, .astro, .jsx, .tsx, .vue, .svelte
+- **Keywords in description**: UI, landing, component, responsive, accessibility, a11y, frontend, design, layout, styling, dark mode, animation, CSS, HTML
+
+The `impeccable` role audits and fixes frontend design quality (a11y, performance, theming, responsive, anti-patterns).
+
 ## Rules
 - Keep `reasoning` short.
 - Recommend only roles that add clear value.

package/templates/skills/kj-architect.md

@@ -0,0 +1,45 @@
+# kj-architect — Architecture Design
+
+Analyze the task and propose an architecture before implementation.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Read the task and understand the requirements
+2. Explore the existing codebase structure (`ls`, `find`, read key files)
+3. Identify the appropriate architectural approach
+4. Propose a design with tradeoffs
+
+## What to deliver
+
+### Architecture overview
+- Architecture type (layered, hexagonal, event-driven, etc.)
+- Key components/layers and their responsibilities
+- Data flow between components
+
+### API contracts (if applicable)
+- Endpoints with method, path, request/response schema
+- Error handling strategy
+
+### Data model changes (if applicable)
+- New entities/collections
+- Modified fields
+- Migration strategy
+
+### Tradeoffs
+- For each design decision: what was chosen, why, and what alternatives were considered
+- Constraints that influenced the design
+
+### Clarification questions
+- Any ambiguities that could affect the architecture
+- Decisions that need stakeholder input
+
+## Constraints
+
+- Follow existing patterns in the codebase — don't introduce a new architecture without justification
+- Keep it simple — the right amount of complexity is the minimum needed
+- Consider testability in every design decision
+- Do NOT start coding — this is design only

package/templates/skills/kj-code.md

@@ -0,0 +1,51 @@
+# kj-code — Coder with Guardrails
+
+Implement the task with TDD methodology and built-in quality checks.
+
+## Your task
+
+$ARGUMENTS
+
+## Methodology
+
+1. **Tests first**: Write or update tests BEFORE implementation
+2. **Implement**: Write minimal, focused code to pass the tests
+3. **Verify**: Run the test suite (`npm test` or project equivalent)
+4. **Check diff**: Run `git diff` and verify ONLY intended lines changed
+
+## Guardrails (MANDATORY)
+
+After writing code, verify ALL of these before reporting done:
+
+### Security check
+- [ ] No hardcoded credentials, API keys, or secrets in the diff
+- [ ] No `eval()`, `innerHTML` with user input, or SQL string concatenation
+- [ ] User input is validated/sanitized at system boundaries
+
+### Destructive operation check
+- [ ] No `rm -rf /`, `DROP TABLE`, `git push --force`, or similar in the diff
+- [ ] No `fs.rmSync` or `fs.rm` on paths derived from user input
+- [ ] No `process.exit()` in library code
+
+### Performance check
+- [ ] No synchronous file I/O (`readFileSync`, `writeFileSync`) in request handlers
+- [ ] No `document.write()` or layout thrashing patterns
+- [ ] No unbounded loops or missing pagination
+
+### TDD check
+- [ ] Source changes have corresponding test changes
+- [ ] Tests actually run and pass
+
+## File modification safety
+
+- NEVER overwrite existing files entirely — make targeted edits
+- After each edit, verify with `git diff` that ONLY intended lines changed
+- If unintended changes detected, revert immediately with `git checkout -- <file>`
+
+## Completeness check
+
+Before reporting done:
+- Re-read the task description
+- Check every requirement is addressed
+- Run the test suite
+- Verify no regressions

package/templates/skills/kj-discover.md

@@ -0,0 +1,24 @@
+# kj-discover — Gap Detection
+
+Analyze the task for gaps, ambiguities, and missing information BEFORE coding.
+
+## Your task
+
+$ARGUMENTS
+
+## What to do
+
+1. Read the task description carefully
+2. Identify gaps: missing requirements, implicit assumptions, ambiguities, contradictions
+3. Classify each gap: **critical** (blocks implementation), **major** (risks rework), **minor** (reasonable default exists)
+4. For each gap, suggest a specific question to resolve it
+5. Give a verdict: **ready** (no gaps) or **needs_validation** (gaps found)
+
+## Output
+
+Present findings clearly:
+- List each gap with severity and suggested question
+- Give your verdict at the end
+- If ready, say so and suggest proceeding to implementation
+
+Do NOT start coding. This is analysis only.

package/templates/skills/kj-review.md

@@ -0,0 +1,47 @@
+# kj-review — Code Review with Quality Gates
+
+Review the current changes against task requirements and quality standards.
+
+## Your task
+
+Review the changes in the current branch: $ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` (or appropriate base branch) to see all changes
+2. Review each changed file against the priorities below
+3. Report findings clearly
+
+## Review priorities (in order)
+
+1. **Security** — vulnerabilities, exposed secrets, injection vectors
+2. **Correctness** — logic errors, edge cases, broken tests
+3. **Tests** — adequate coverage, meaningful assertions
+4. **Architecture** — patterns, maintainability, SOLID principles
+5. **Style** — naming, formatting (only flag if egregious)
+
+## Scope constraint
+
+- **ONLY review files present in the diff** — do not flag issues in untouched files
+- Out-of-scope issues go as suggestions, never as blocking
+
+## Guardrails (auto-check)
+
+Flag as BLOCKING if any of these are detected in the diff:
+- [ ] Hardcoded credentials, API keys, or secrets
+- [ ] Entire file replaced (massive deletions + additions instead of targeted edits)
+- [ ] `eval()`, `innerHTML` with user input, SQL string concatenation
+- [ ] Missing test changes when source files changed (TDD violation)
+- [ ] `rm -rf`, `DROP TABLE`, `git push --force` or similar destructive operations
+
+## Output
+
+For each issue found:
+- **File and line** where the issue is
+- **Severity**: critical / major / minor
+- **Description**: what's wrong
+- **Suggested fix**: how to fix it
+
+End with a clear verdict:
+- **APPROVED** — no blocking issues found
+- **REQUEST_CHANGES** — blocking issues listed above must be fixed

package/templates/skills/kj-run.md

@@ -0,0 +1,69 @@
+# kj-run — Full Pipeline (Skills Mode)
+
+Execute the complete Karajan pipeline as sequential skills.
+
+## Your task
+
+$ARGUMENTS
+
+## Pipeline steps (execute in order)
+
+### Step 1 — Discover (optional but recommended)
+Analyze the task for gaps before coding:
+- Identify missing requirements, ambiguities, contradictions
+- If critical gaps found, STOP and ask the user before proceeding
+- If ready, continue
+
+### Step 2 — Code (with guardrails)
+Implement the task:
+1. **Tests first** (TDD): write/update tests before implementation
+2. **Implement**: minimal, focused code to fulfill the task
+3. **Verify**: run the test suite
+4. **Security check**: no hardcoded secrets, no injection vectors, no destructive ops in the diff
+5. **Diff check**: run `git diff` and verify only intended lines changed
+6. If any guardrail fails, fix before proceeding
+
+### Step 3 — Review (self-review)
+Review your own changes against quality standards:
+1. Run `git diff main...HEAD` (or base branch)
+2. Check: security, correctness, tests, architecture, style (in that order)
+3. Flag blocking issues:
+   - Hardcoded credentials or secrets
+   - Entire files overwritten instead of targeted edits
+   - Missing tests for new code
+   - SQL injection, XSS, command injection
+   - Destructive operations
+4. If blocking issues found, fix them and re-review
+5. If clean, proceed
+
+### Step 4 — Test audit
+Verify test quality:
+1. Every changed source file has corresponding tests
+2. Run `npm test` (or equivalent) — all must pass
+3. No skipped tests for changed code
+4. If tests fail, fix before proceeding
+
+### Step 5 — Security scan
+Quick security audit on the diff:
+1. Scan for OWASP top 10 in changed files
+2. Check for leaked secrets, injection vectors, missing auth
+3. If critical/high findings, fix before proceeding
+
+### Step 6 — Sonar (if available)
+If SonarQube is running (`docker ps | grep sonarqube`):
+1. Run `npx @sonar/scan`
+2. Check quality gate
+3. Fix blockers and critical issues
+
+### Step 7 — Commit
+If all steps pass:
+1. Stage changed files: `git add <specific files>`
+2. Commit with conventional commit message: `feat:`, `fix:`, `refactor:`, etc.
+3. Do NOT push unless the user explicitly asks
+
+## Important rules
+
+- **Never skip steps** — execute all applicable steps in order
+- **Fix before proceeding** — if a step finds issues, fix them before moving to the next
+- **Report progress** — after each step, briefly state what was done and the result
+- **Stop on critical** — if a critical security or correctness issue can't be fixed, stop and report

package/templates/skills/kj-security.md

@@ -0,0 +1,49 @@
+# kj-security — Security Audit
+
+Perform a security audit on the current changes.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` to see all changes
+2. Scan for each vulnerability category below
+3. Report findings with severity and remediation
+
+## Vulnerability categories
+
+### Critical
+- [ ] Hardcoded secrets (API keys, passwords, tokens, connection strings)
+- [ ] SQL injection (string concatenation in queries)
+- [ ] Command injection (`exec`, `spawn` with unsanitized input)
+- [ ] Path traversal (file operations with user-controlled paths)
+
+### High
+- [ ] XSS (Cross-Site Scripting) — `innerHTML`, `dangerouslySetInnerHTML` with user input
+- [ ] Missing authentication/authorization checks on new endpoints
+- [ ] Insecure deserialization
+- [ ] SSRF (Server-Side Request Forgery) — fetch/request with user-controlled URLs
+
+### Medium
+- [ ] Missing input validation at system boundaries
+- [ ] Verbose error messages that leak internal details
+- [ ] Missing CSRF protection on state-changing endpoints
+- [ ] Insecure random number generation for security purposes
+
+### Low
+- [ ] Missing security headers
+- [ ] Dependencies with known vulnerabilities (check `npm audit`)
+- [ ] Console.log with sensitive data
+
+## Output
+
+For each finding:
+- **Severity**: critical / high / medium / low
+- **File and line**: where the issue is
+- **Category**: which vulnerability type
+- **Description**: what's wrong
+- **Remediation**: specific fix
+
+End with a summary: total findings by severity, and whether the code is safe to ship.

package/templates/skills/kj-sonar.md

@@ -0,0 +1,41 @@
+# kj-sonar — Static Analysis
+
+Run SonarQube/SonarCloud analysis and fix any issues found.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Check if SonarQube is running: `docker ps | grep sonarqube`
+2. If running, execute scan:
+   ```bash
+   npx @sonar/scan -Dsonar.host.url=http://localhost:9000 -Dsonar.projectKey=<project-key>
+   ```
+3. Check quality gate status:
+   ```bash
+   curl -s -u admin:admin "http://localhost:9000/api/qualitygates/project_status?projectKey=<project-key>"
+   ```
+4. List issues:
+   ```bash
+   curl -s -u admin:admin "http://localhost:9000/api/issues/search?projectKeys=<project-key>&statuses=OPEN&ps=50"
+   ```
+
+## If SonarQube is not available
+
+Perform manual static analysis checks:
+- [ ] Cognitive complexity — functions over 15 should be refactored
+- [ ] Duplicated code blocks (3+ lines repeated)
+- [ ] Unused imports and variables
+- [ ] Empty catch blocks without comments
+- [ ] Nested ternary operations
+- [ ] `console.log` left in production code
+
+## Output
+
+Report:
+- Quality gate status (passed/failed)
+- Issues found by severity (blocker, critical, major, minor)
+- For each issue: file, line, rule, and suggested fix
+- Fix critical and blocker issues before proceeding

package/templates/skills/kj-test.md

@@ -0,0 +1,40 @@
+# kj-test — Test Quality Audit
+
+Evaluate test coverage and quality for the current changes.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` to identify changed source files
+2. For each changed source file, find the corresponding test file
+3. Run the test suite and check results
+4. Evaluate test quality
+
+## Checks
+
+### Coverage
+- [ ] Every changed source file has a corresponding test file
+- [ ] New functions/methods have at least one test
+- [ ] Edge cases are covered (null, empty, boundary values)
+
+### Quality
+- [ ] Tests have meaningful assertions (not just "no error thrown")
+- [ ] Test descriptions clearly state what is being tested
+- [ ] No tests that always pass (e.g., empty test body, `expect(true).toBe(true)`)
+- [ ] Mocks are minimal — prefer real implementations where feasible
+
+### Execution
+- [ ] Run `npm test` (or project equivalent) and report results
+- [ ] All tests pass
+- [ ] No skipped tests (`.skip`) for the changed code
+
+## Output
+
+Report:
+- Test files found/missing for each changed source file
+- Test execution results (pass/fail count)
+- Quality issues found
+- Suggestions for improving coverage