karajan-code 1.17.0 → 1.19.0

package/package.json

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

package/src/agents/index.js

@@ -2,6 +2,7 @@ import { ClaudeAgent } from "./claude-agent.js";
 import { CodexAgent } from "./codex-agent.js";
 import { GeminiAgent } from "./gemini-agent.js";
 import { AiderAgent } from "./aider-agent.js";
+import { OpenCodeAgent } from "./opencode-agent.js";
 
 const agentRegistry = new Map();
 
@@ -38,3 +39,4 @@ registerAgent("claude", ClaudeAgent, { bin: "claude", installUrl: "https://docs.
 registerAgent("codex", CodexAgent, { bin: "codex", installUrl: "https://developers.openai.com/codex/cli" });
 registerAgent("gemini", GeminiAgent, { bin: "gemini", installUrl: "https://github.com/google-gemini/gemini-cli" });
 registerAgent("aider", AiderAgent, { bin: "aider", installUrl: "https://aider.chat/docs/install.html" });
+registerAgent("opencode", OpenCodeAgent, { bin: "opencode", installUrl: "https://opencode.ai" });

package/src/agents/model-registry.js

@@ -60,3 +60,4 @@ registerModel("gemini", { provider: "google", pricing: { input_per_million: 1.25
 registerModel("gemini/pro", { provider: "google", pricing: { input_per_million: 1.25, output_per_million: 5 } });
 registerModel("gemini/flash", { provider: "google", pricing: { input_per_million: 0.075, output_per_million: 0.3 } });
 registerModel("aider", { provider: "aider", pricing: { input_per_million: 3, output_per_million: 15 } });
+registerModel("opencode", { provider: "opencode", pricing: { input_per_million: 0, output_per_million: 0 } });

package/src/agents/opencode-agent.js

@@ -0,0 +1,33 @@
+import { BaseAgent } from "./base-agent.js";
+import { runCommand } from "../utils/process.js";
+import { resolveBin } from "./resolve-bin.js";
+
+export class OpenCodeAgent extends BaseAgent {
+  async runTask(task) {
+    const role = task.role || "coder";
+    const args = ["run"];
+    const model = this.getRoleModel(role);
+    if (model) args.push("--model", model);
+    args.push(task.prompt);
+    const res = await runCommand(resolveBin("opencode"), args, {
+      onOutput: task.onOutput,
+      silenceTimeoutMs: task.silenceTimeoutMs,
+      timeout: task.timeoutMs
+    });
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+  }
+
+  async reviewTask(task) {
+    const role = task.role || "reviewer";
+    const args = ["run", "--format", "json"];
+    const model = this.getRoleModel(role);
+    if (model) args.push("--model", model);
+    args.push(task.prompt);
+    const res = await runCommand(resolveBin("opencode"), args, {
+      onOutput: task.onOutput,
+      silenceTimeoutMs: task.silenceTimeoutMs,
+      timeout: task.timeoutMs
+    });
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+  }
+}

package/src/config.js

@@ -140,6 +140,25 @@ const DEFAULTS = {
     max_backoff_ms: 30000,
     backoff_multiplier: 2,
     jitter_factor: 0.1
+  },
+  guards: {
+    output: {
+      enabled: true,
+      patterns: [],
+      protected_files: [],
+      on_violation: "block"
+    },
+    perf: {
+      enabled: true,
+      patterns: [],
+      block_on_warning: false,
+      frontend_extensions: []
+    },
+    intent: {
+      enabled: false,
+      patterns: [],
+      confidence_threshold: 0.85
+    }
   }
 };
 

package/src/guards/intent-guard.js

@@ -0,0 +1,123 @@
+import { VALID_TASK_TYPES } from "./policy-resolver.js";
+
+/**
+ * Built-in intent patterns for deterministic pre-triage classification.
+ * Each pattern maps keywords/regex to a taskType + complexity level.
+ * Evaluated top-down; first match with confidence >= threshold wins.
+ */
+const INTENT_PATTERNS = [
+  // Documentation-only tasks
+  {
+    id: "doc-readme",
+    keywords: ["readme", "docs", "documentation", "jsdoc", "typedoc", "changelog"],
+    taskType: "doc",
+    level: "trivial",
+    confidence: 0.95,
+    message: "Documentation-only task detected",
+  },
+  // Test-only tasks
+  {
+    id: "add-tests",
+    keywords: ["add test", "write test", "missing test", "test coverage", "add spec", "write spec", "unit test", "integration test"],
+    taskType: "add-tests",
+    level: "simple",
+    confidence: 0.9,
+    message: "Test-addition task detected",
+  },
+  // Refactoring tasks
+  {
+    id: "refactor",
+    keywords: ["refactor", "rename", "extract method", "extract function", "clean up", "cleanup", "reorganize", "restructure", "simplify"],
+    taskType: "refactor",
+    level: "simple",
+    confidence: 0.85,
+    message: "Refactoring task detected",
+  },
+  // Infrastructure / DevOps tasks
+  {
+    id: "infra-devops",
+    keywords: ["ci/cd", "pipeline", "dockerfile", "docker-compose", "kubernetes", "k8s", "terraform", "deploy", "nginx", "github actions", "gitlab ci"],
+    taskType: "infra",
+    level: "simple",
+    confidence: 0.85,
+    message: "Infrastructure/DevOps task detected",
+  },
+  // Trivial fixes (typos, comments, formatting)
+  {
+    id: "trivial-fix",
+    keywords: ["typo", "fix typo", "spelling", "comment", "fix comment", "formatting", "lint", "fix lint", "whitespace"],
+    taskType: "sw",
+    level: "trivial",
+    confidence: 0.9,
+    message: "Trivial fix detected",
+  },
+];
+
+/**
+ * Compile custom intent patterns from config.guards.intent.patterns
+ * Custom patterns are evaluated BEFORE built-in ones.
+ */
+export function compileIntentPatterns(configGuards) {
+  const custom = Array.isArray(configGuards?.intent?.patterns)
+    ? configGuards.intent.patterns.map(p => ({
+        id: p.id || "custom-intent",
+        keywords: Array.isArray(p.keywords) ? p.keywords : [],
+        taskType: VALID_TASK_TYPES.has(p.taskType) ? p.taskType : "sw",
+        level: p.level || "simple",
+        confidence: typeof p.confidence === "number" ? p.confidence : 0.85,
+        message: p.message || "Custom intent pattern matched",
+      }))
+    : [];
+
+  return [...custom, ...INTENT_PATTERNS];
+}
+
+/**
+ * Check if a task description matches any of the keywords.
+ * Returns true if at least one keyword (case-insensitive substring) appears in the task.
+ */
+function matchesKeywords(task, keywords) {
+  const lower = task.toLowerCase();
+  for (const kw of keywords) {
+    if (lower.includes(kw.toLowerCase())) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Classify a task description using deterministic keyword patterns.
+ *
+ * Returns:
+ *   { classified: true, taskType, level, confidence, patternId, message }
+ *   or { classified: false } if no pattern matches above threshold
+ */
+export function classifyIntent(task, config = {}) {
+  if (!task || typeof task !== "string") {
+    return { classified: false };
+  }
+
+  const configGuards = config?.guards || {};
+  const threshold = configGuards?.intent?.confidence_threshold ?? 0.85;
+  const patterns = compileIntentPatterns(configGuards);
+
+  for (const pattern of patterns) {
+    if (!matchesKeywords(task, pattern.keywords)) continue;
+
+    if (pattern.confidence >= threshold) {
+      return {
+        classified: true,
+        taskType: pattern.taskType,
+        level: pattern.level,
+        confidence: pattern.confidence,
+        patternId: pattern.id,
+        message: pattern.message,
+      };
+    }
+  }
+
+  return { classified: false };
+}
+
+export { INTENT_PATTERNS };

package/src/guards/output-guard.js

@@ -0,0 +1,158 @@
+import { runCommand } from "../utils/process.js";
+
+// Built-in destructive patterns
+const DESTRUCTIVE_PATTERNS = [
+  { id: "rm-rf", pattern: /rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+|--force\s+)*-[a-zA-Z]*r/, severity: "critical", message: "Recursive file deletion detected" },
+  { id: "drop-table", pattern: /DROP\s+(TABLE|DATABASE|SCHEMA)/i, severity: "critical", message: "SQL destructive operation detected" },
+  { id: "git-reset-hard", pattern: /git\s+reset\s+--hard/i, severity: "critical", message: "Hard git reset detected" },
+  { id: "git-push-force", pattern: /git\s+push\s+.*--force/i, severity: "critical", message: "Force push detected" },
+  { id: "truncate-table", pattern: /TRUNCATE\s+TABLE/i, severity: "critical", message: "SQL truncate detected" },
+  { id: "format-disk", pattern: /mkfs\.|fdisk|dd\s+if=/, severity: "critical", message: "Disk format operation detected" },
+];
+
+// Built-in credential patterns
+const CREDENTIAL_PATTERNS = [
+  { id: "aws-key", pattern: /AKIA[0-9A-Z]{16}/, severity: "critical", message: "AWS access key exposed" },
+  { id: "private-key", pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/, severity: "critical", message: "Private key exposed" },
+  { id: "generic-secret", pattern: /(password|secret|token|api_key|apikey)\s*[:=]\s*["'][^"']{8,}["']/i, severity: "warning", message: "Potential secret/credential exposed" },
+  { id: "github-token", pattern: /gh[pousr]_[A-Za-z0-9_]{36,}/, severity: "critical", message: "GitHub token exposed" },
+  { id: "npm-token", pattern: /npm_[A-Za-z0-9]{36,}/, severity: "critical", message: "npm token exposed" },
+];
+
+// Default protected files (block if these appear in added/modified lines)
+const DEFAULT_PROTECTED_FILES = [
+  ".env",
+  ".env.local",
+  ".env.production",
+  "serviceAccountKey.json",
+  "credentials.json",
+];
+
+export function compilePatterns(configGuards) {
+  const customPatterns = Array.isArray(configGuards?.output?.patterns)
+    ? configGuards.output.patterns.map(p => ({
+        id: p.id || "custom",
+        pattern: typeof p.pattern === "string" ? new RegExp(p.pattern, p.flags || "") : p.pattern,
+        severity: p.severity || "warning",
+        message: p.message || "Custom pattern matched",
+      }))
+    : [];
+
+  return [...DESTRUCTIVE_PATTERNS, ...CREDENTIAL_PATTERNS, ...customPatterns];
+}
+
+export function compileProtectedFiles(configGuards) {
+  const custom = Array.isArray(configGuards?.output?.protected_files)
+    ? configGuards.output.protected_files
+    : [];
+  return [...new Set([...DEFAULT_PROTECTED_FILES, ...custom])];
+}
+
+/**
+ * Parse a unified diff to extract only added lines (lines starting with +, not ++)
+ */
+export function extractAddedLines(diff) {
+  if (!diff) return [];
+  const results = [];
+  let currentFile = null;
+  let lineNum = 0;
+
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("+++ b/")) {
+      currentFile = line.slice(6);
+      continue;
+    }
+    if (line.startsWith("@@ ")) {
+      const match = /@@ -\d+(?:,\d+)? \+(\d+)/.exec(line);
+      lineNum = match ? Number.parseInt(match[1], 10) - 1 : 0;
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      lineNum += 1;
+      results.push({ file: currentFile, line: lineNum, content: line.slice(1) });
+    } else if (!line.startsWith("-")) {
+      lineNum += 1;
+    }
+  }
+  return results;
+}
+
+/**
+ * Check if any modified files are in the protected list
+ */
+export function checkProtectedFiles(diff, protectedFiles) {
+  const violations = [];
+  const modifiedFiles = [];
+
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("+++ b/")) {
+      modifiedFiles.push(line.slice(6));
+    }
+  }
+
+  for (const file of modifiedFiles) {
+    const basename = file.split("/").pop();
+    if (protectedFiles.some(pf => file === pf || file.endsWith(`/${pf}`) || basename === pf)) {
+      violations.push({
+        id: "protected-file",
+        severity: "critical",
+        file,
+        line: 0,
+        message: `Protected file modified: ${file}`,
+        matchedContent: "",
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Scan a diff for pattern violations.
+ * Returns { pass: boolean, violations: Array<{id, severity, file, line, message, matchedContent}> }
+ */
+export function scanDiff(diff, config = {}) {
+  if (!diff || typeof diff !== "string") {
+    return { pass: true, violations: [] };
+  }
+
+  const configGuards = config?.guards || {};
+  const patterns = compilePatterns(configGuards);
+  const protectedFiles = compileProtectedFiles(configGuards);
+  const addedLines = extractAddedLines(diff);
+  const violations = [];
+
+  // Check patterns against added lines
+  for (const { file, line, content } of addedLines) {
+    for (const { id, pattern, severity, message } of patterns) {
+      if (pattern.test(content)) {
+        violations.push({ id, severity, file, line, message, matchedContent: content.trim().slice(0, 200) });
+      }
+    }
+  }
+
+  // Check protected files
+  violations.push(...checkProtectedFiles(diff, protectedFiles));
+
+  const hasCritical = violations.some(v => v.severity === "critical");
+  return { pass: !hasCritical, violations };
+}
+
+/**
+ * Run output guard on the current git diff.
+ * This is the main entry point for the pipeline integration.
+ */
+export async function runOutputGuard(config = {}, baseBranch = "main") {
+  const diffResult = await runCommand("git", ["diff", `origin/${baseBranch}...HEAD`]);
+  if (diffResult.exitCode !== 0) {
+    // Fallback: diff against HEAD~1
+    const fallback = await runCommand("git", ["diff", "HEAD~1"]);
+    if (fallback.exitCode !== 0) {
+      return { pass: true, violations: [], error: "Could not generate diff" };
+    }
+    return scanDiff(fallback.stdout, config);
+  }
+  return scanDiff(diffResult.stdout, config);
+}
+
+export { DESTRUCTIVE_PATTERNS, CREDENTIAL_PATTERNS, DEFAULT_PROTECTED_FILES };

package/src/guards/perf-guard.js

@@ -0,0 +1,126 @@
+const FRONTEND_EXTENSIONS = new Set([".html", ".htm", ".css", ".jsx", ".tsx", ".astro", ".vue", ".svelte"]);
+
+// Built-in perf anti-patterns (applied to added lines in frontend files)
+const PERF_PATTERNS = [
+  { id: "img-no-dimensions", pattern: /<img\b(?![^>]*\bwidth\b)(?![^>]*\bheight\b)[^>]*>/i, severity: "warning", message: "Image without width/height attributes (causes CLS)" },
+  { id: "img-no-lazy", pattern: /<img\b(?![^>]*\bloading\s*=)(?![^>]*\bfetchpriority\s*=)[^>]*>/i, severity: "info", message: "Image without loading=\"lazy\" or fetchpriority (consider lazy loading)" },
+  { id: "script-no-defer", pattern: /<script\b(?![^>]*\b(?:defer|async)\b)(?![^>]*type\s*=\s*["']module["'])[^>]*src\s*=/i, severity: "warning", message: "External script without defer/async (render-blocking)" },
+  { id: "font-no-display", pattern: /@font-face\s*\{(?![^}]*font-display)/i, severity: "warning", message: "@font-face without font-display (causes FOIT)" },
+  { id: "css-import", pattern: /@import\s+(?:url\()?["'](?!.*\.module\.)/i, severity: "info", message: "CSS @import (causes sequential loading, prefer <link>)" },
+  { id: "inline-style-large", pattern: /style\s*=\s*["'][^"']{200,}["']/i, severity: "warning", message: "Large inline style (>200 chars, consider external CSS)" },
+  { id: "document-write", pattern: /document\.write\s*\(/, severity: "warning", message: "document.write() blocks parsing and degrades performance" },
+];
+
+// Patterns for package.json changes (heavy dependencies added)
+const HEAVY_DEPS = [
+  { id: "heavy-moment", pattern: /"moment"/, severity: "info", message: "moment.js added (consider dayjs or date-fns for smaller bundle)" },
+  { id: "heavy-lodash", pattern: /"lodash"(?!\/)/, severity: "info", message: "Full lodash added (consider lodash-es or individual imports)" },
+  { id: "heavy-jquery", pattern: /"jquery"/, severity: "info", message: "jQuery added (consider native DOM APIs)" },
+];
+
+function getExtension(filePath) {
+  if (!filePath) return "";
+  const dot = filePath.lastIndexOf(".");
+  return dot >= 0 ? filePath.slice(dot).toLowerCase() : "";
+}
+
+/**
+ * Check if any modified file in the diff is a frontend file
+ */
+export function hasFrontendFiles(diff) {
+  if (!diff) return false;
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("+++ b/")) {
+      const ext = getExtension(line.slice(6));
+      if (FRONTEND_EXTENSIONS.has(ext)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Extract added lines grouped by file from a unified diff
+ */
+function extractAddedLinesByFile(diff) {
+  const results = [];
+  let currentFile = null;
+  let lineNum = 0;
+
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("+++ b/")) {
+      currentFile = line.slice(6);
+      continue;
+    }
+    if (line.startsWith("@@ ")) {
+      const match = /@@ -\d+(?:,\d+)? \+(\d+)/.exec(line);
+      lineNum = match ? Number.parseInt(match[1], 10) - 1 : 0;
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      lineNum += 1;
+      results.push({ file: currentFile, line: lineNum, content: line.slice(1) });
+    } else if (!line.startsWith("-")) {
+      lineNum += 1;
+    }
+  }
+  return results;
+}
+
+/**
+ * Scan diff for frontend performance anti-patterns.
+ * Returns { pass: boolean, violations: [...], skipped: boolean }
+ */
+export function scanPerfDiff(diff, config = {}) {
+  if (!diff || typeof diff !== "string") {
+    return { pass: true, violations: [], skipped: true };
+  }
+
+  if (!hasFrontendFiles(diff)) {
+    return { pass: true, violations: [], skipped: true };
+  }
+
+  const customPatterns = Array.isArray(config?.guards?.perf?.patterns)
+    ? config.guards.perf.patterns.map(p => ({
+        id: p.id || "custom-perf",
+        pattern: typeof p.pattern === "string" ? new RegExp(p.pattern, p.flags || "i") : p.pattern,
+        severity: p.severity || "warning",
+        message: p.message || "Custom perf pattern matched",
+      }))
+    : [];
+
+  const allPatterns = [...PERF_PATTERNS, ...customPatterns];
+  const addedLines = extractAddedLinesByFile(diff);
+  const violations = [];
+
+  for (const { file, line, content } of addedLines) {
+    const ext = getExtension(file);
+    const isFrontend = FRONTEND_EXTENSIONS.has(ext);
+    const isPackageJson = file?.endsWith("package.json");
+
+    if (isFrontend) {
+      for (const { id, pattern, severity, message } of allPatterns) {
+        if (pattern.test(content)) {
+          violations.push({ id, severity, file, line, message, matchedContent: content.trim().slice(0, 200) });
+        }
+      }
+    }
+
+    if (isPackageJson) {
+      for (const { id, pattern, severity, message } of HEAVY_DEPS) {
+        if (pattern.test(content)) {
+          violations.push({ id, severity, file, line, message, matchedContent: content.trim().slice(0, 200) });
+        }
+      }
+    }
+  }
+
+  // perf-guard is advisory by default — only blocks on critical (none built-in are critical)
+  const blockOnWarning = Boolean(config?.guards?.perf?.block_on_warning);
+  const hasCritical = violations.some(v => v.severity === "critical");
+  const hasWarning = violations.some(v => v.severity === "warning");
+  const pass = !hasCritical && !(blockOnWarning && hasWarning);
+
+  return { pass, violations, skipped: false };
+}
+
+export { PERF_PATTERNS, HEAVY_DEPS, FRONTEND_EXTENSIONS };

package/src/orchestrator.js

@@ -23,6 +23,9 @@ import {
 } from "./git/automation.js";
 import { resolveRoleMdPath, loadFirstExisting } from "./roles/base-role.js";
 import { applyPolicies } from "./guards/policy-resolver.js";
+import { scanDiff } from "./guards/output-guard.js";
+import { scanPerfDiff } from "./guards/perf-guard.js";
+import { classifyIntent } from "./guards/intent-guard.js";
 import { resolveReviewProfile } from "./review/profiles.js";
 import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
@@ -272,7 +275,7 @@ function applyFlagOverrides(pipelineFlags, flags) {
 
 function resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags }) {
   const resolvedPolicies = applyPolicies({
-    taskType: flags.taskType || config.taskType || stageResults.triage?.taskType || null,
+    taskType: flags.taskType || config.taskType || stageResults.triage?.taskType || stageResults.intent?.taskType || null,
     policies: config.policies,
   });
   session.resolved_policies = resolvedPolicies;
@@ -764,6 +767,18 @@ async function handleReviewerRetryAndSolomon({ config, session, emitter, eventBa
 
 
 async function runPreLoopStages({ config, logger, emitter, eventBase, session, flags, pipelineFlags, coderRole, trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults }) {
+  // --- Intent classifier (deterministic pre-triage, opt-in) ---
+  if (config.guards?.intent?.enabled) {
+    const intentResult = classifyIntent(task, config);
+    stageResults.intent = intentResult;
+    if (intentResult.classified) {
+      emitProgress(emitter, makeEvent("intent:classified", { ...eventBase, stage: "intent" }, {
+        message: `Intent classified: ${intentResult.taskType} (${intentResult.level}) — ${intentResult.message}`,
+        detail: intentResult
+      }));
+    }
+  }
+
   // --- Discover (pre-triage, opt-in) ---
   if (flags.enableDiscover !== undefined) pipelineFlags.discoverEnabled = Boolean(flags.enableDiscover);
   if (pipelineFlags.discoverEnabled) {
@@ -811,6 +826,72 @@ async function runCoderAndRefactorerStages({ coderRoleInstance, coderRole, refac
   return { action: "ok" };
 }
 
+async function runGuardStages({ config, logger, emitter, eventBase, session, iteration }) {
+  const outputEnabled = config.guards?.output?.enabled !== false;
+  const perfEnabled = config.guards?.perf?.enabled !== false;
+
+  if (!outputEnabled && !perfEnabled) return { action: "ok" };
+
+  const baseBranch = config.base_branch || "main";
+  let diff;
+  try {
+    const { generateDiff: genDiff, computeBaseRef: compBase } = await import("./review/diff-generator.js");
+    const baseRef = await compBase({ baseBranch });
+    diff = await genDiff({ baseRef });
+  } catch {
+    logger.warn("Guards: could not generate diff, skipping");
+    return { action: "ok" };
+  }
+
+  if (!diff) return { action: "ok" };
+
+  if (outputEnabled) {
+    const outputResult = scanDiff(diff, config);
+    if (outputResult.violations.length > 0) {
+      const critical = outputResult.violations.filter(v => v.severity === "critical");
+      const warnings = outputResult.violations.filter(v => v.severity === "warning");
+      emitProgress(emitter, makeEvent("guard:output", { ...eventBase, stage: "guard" }, {
+        message: `Output guard: ${critical.length} critical, ${warnings.length} warnings`,
+        detail: { violations: outputResult.violations }
+      }));
+      logger.info(`Output guard: ${outputResult.violations.length} violation(s) found`);
+      for (const v of outputResult.violations) {
+        logger.info(`  [${v.severity}] ${v.file}:${v.line} — ${v.message}`);
+      }
+      await addCheckpoint(session, { stage: "guard-output", iteration, pass: outputResult.pass, violations: outputResult.violations.length });
+
+      if (!outputResult.pass && config.guards.output.on_violation === "block") {
+        await markSessionStatus(session, "failed");
+        emitProgress(emitter, makeEvent("guard:blocked", { ...eventBase, stage: "guard" }, {
+          message: "Output guard blocked: critical violations detected",
+          detail: { violations: critical }
+        }));
+        return {
+          action: "return",
+          result: { approved: false, sessionId: session.id, reason: "guard_blocked", violations: critical }
+        };
+      }
+    }
+  }
+
+  if (perfEnabled) {
+    const perfResult = scanPerfDiff(diff, config);
+    if (!perfResult.skipped && perfResult.violations.length > 0) {
+      emitProgress(emitter, makeEvent("guard:perf", { ...eventBase, stage: "guard" }, {
+        message: `Perf guard: ${perfResult.violations.length} issue(s)`,
+        detail: { violations: perfResult.violations }
+      }));
+      logger.info(`Perf guard: ${perfResult.violations.length} issue(s) found`);
+      for (const v of perfResult.violations) {
+        logger.info(`  [${v.severity}] ${v.file}:${v.line} — ${v.message}`);
+      }
+      await addCheckpoint(session, { stage: "guard-perf", iteration, pass: perfResult.pass, violations: perfResult.violations.length });
+    }
+  }
+
+  return { action: "ok" };
+}
+
 async function runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults }) {
   const tddResult = await runTddCheckStage({ config, logger, emitter, eventBase, session, trackBudget, iteration: i, askQuestion });
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
@@ -947,6 +1028,9 @@ async function runSingleIteration(ctx) {
   const crResult = await runCoderAndRefactorerStages({ coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase, session, plannedTask, trackBudget, i });
   if (crResult.action === "return" || crResult.action === "retry") return crResult;
 
+  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 });
   if (qgResult.action === "return" || qgResult.action === "continue") return qgResult;
 

package/src/utils/agent-detect.js

@@ -5,7 +5,8 @@ const KNOWN_AGENTS = [
   { name: "claude", install: "npm install -g @anthropic-ai/claude-code" },
   { name: "codex", install: "npm install -g @openai/codex" },
   { name: "gemini", install: "npm install -g @anthropic-ai/gemini-code (or check Gemini CLI docs)" },
-  { name: "aider", install: "pip install aider-chat" }
+  { name: "aider", install: "pip install aider-chat" },
+  { name: "opencode", install: "curl -fsSL https://opencode.ai/install | bash (or see https://opencode.ai)" }
 ];
 
 export async function checkBinary(name, versionArg = "--version") {

package/templates/kj.config.yml

@@ -61,6 +61,39 @@ sonarqube:
       - "javascript:S1116"
       - "javascript:S3776"
 
+# Deterministic Guards
+guards:
+  output:
+    enabled: true
+    # Custom patterns (added to built-in destructive + credential patterns)
+    # patterns:
+    #   - id: custom-pattern
+    #     pattern: "DANGEROUS_FUNCTION"
+    #     severity: critical
+    #     message: "Custom dangerous pattern detected"
+    # Protected files (added to built-in: .env, serviceAccountKey.json, etc.)
+    # protected_files:
+    #   - secrets.yml
+    #   - .env.production
+    on_violation: block  # block | warn | skip
+  perf:
+    enabled: true
+    block_on_warning: false  # true to block on perf warnings (default: advisory only)
+    # Custom perf patterns (added to built-in frontend anti-patterns)
+    # patterns:
+    #   - id: custom-perf
+    #     pattern: "eval\\("
+    #     severity: warning
+    #     message: "eval() detected"
+  intent:
+    enabled: false  # enable for deterministic pre-triage classification
+    confidence_threshold: 0.85
+    # Custom intent patterns (evaluated before built-in)
+    # patterns:
+    #   - keywords: ["readme", "docs", "documentation"]
+    #     taskType: doc
+    #     confidence: 0.9
+
 # Git (post-approval)
 git:
   auto_commit: false