@karajan-family/code 4.21.0

package/src/webperf/devtools-detect.js

@@ -0,0 +1,112 @@
+// Chrome DevTools MCP detection and WebPerf skill auto-installation.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { isOpenSkillsAvailable, listSkills } from "../skills/openskills-client.js";
+
+/** Skill names relevant for WebPerf analysis. Already installed globally via openskills. */
+export const WEBPERF_SKILLS = [
+  "optimize",
+  "audit",
+  "polish"
+];
+
+/**
+ * Check whether Chrome DevTools MCP is configured and available.
+ * Checks: (1) config flag, (2) Claude MCP config (~/.claude.json), (3) VS Code MCP settings.
+ * @param {object} config - merged Karajan config
+ * @returns {boolean}
+ */
+export function isDevToolsMcpAvailable(config) {
+  // Explicit config flag takes priority
+  if (config?.webperf?.devtools_mcp === true) return true;
+  if (config?.webperf?.devtools_mcp === false) return false;
+
+  // Check cached detection result
+  if (_devToolsDetected !== null) return _devToolsDetected;
+
+  // Not yet detected - return false (async detection runs at init)
+  return false;
+}
+
+let _devToolsDetected = null;
+
+/**
+ * Auto-detect Chrome DevTools MCP from system configuration.
+ * Checks ~/.claude.json and VS Code MCP settings.
+ * Call once at pipeline init.
+ */
+export async function detectDevToolsMcp(logger) {
+  // Check Claude MCP config
+  const claudeConfigPath = path.join(os.homedir(), ".claude.json");
+  try {
+    const raw = await fs.readFile(claudeConfigPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const mcpServers = parsed?.mcpServers || parsed?.mcp_servers || {};
+    if (mcpServers["chrome-devtools"] || mcpServers["chrome_devtools"]) {
+      _devToolsDetected = true;
+      logger?.info?.("Chrome DevTools MCP detected in ~/.claude.json");
+      return true;
+    }
+  } catch { /* file not found or parse error */ }
+
+  // Check VS Code MCP settings
+  const vscodePaths = [
+    path.join(os.homedir(), ".vscode", "settings.json"),
+    path.join(process.cwd(), ".vscode", "settings.json")
+  ];
+  for (const vscPath of vscodePaths) {
+    try {
+      const raw = await fs.readFile(vscPath, "utf8");
+      if (raw.includes("chrome-devtools") || raw.includes("chrome_devtools")) {
+        _devToolsDetected = true;
+        logger?.info?.(`Chrome DevTools MCP detected in ${vscPath}`);
+        return true;
+      }
+    } catch { /* not found */ }
+  }
+
+  _devToolsDetected = false;
+  return false;
+}
+
+/**
+ * Ensure WebPerf skills are installed via OpenSkills.
+ * Installs any missing skills from WEBPERF_SKILLS.
+ * @param {string} projectDir - absolute path to the project root
+ * @param {object} [logger] - optional logger ({ info, warn })
+ * @returns {Promise<{ installed: string[], alreadyInstalled: string[], skipped: string[] }>}
+ */
+export async function ensureWebPerfSkills(projectDir, logger) {
+  const result = { installed: [], alreadyInstalled: [], skipped: [] };
+
+  const available = await isOpenSkillsAvailable();
+  if (!available) {
+    logger?.debug?.("OpenSkills CLI not available - WebPerf skills unavailable");
+    result.skipped = [...WEBPERF_SKILLS];
+    return result;
+  }
+
+  // List skills (includes global installs)
+  const listResult = await listSkills({ projectDir });
+  const installedNames = new Set(
+    (listResult.ok ? listResult.skills : []).map(s => s.name)
+  );
+
+  for (const skill of WEBPERF_SKILLS) {
+    if (installedNames.has(skill)) {
+      result.alreadyInstalled.push(skill);
+    } else {
+      // Skills should be installed globally via `openskills install owner/repo`
+      // Don't attempt auto-install with bare names — just note they're missing
+      result.skipped.push(skill);
+    }
+  }
+
+  if (result.alreadyInstalled.length > 0) {
+    logger?.info?.(`WebPerf skills available: ${result.alreadyInstalled.join(", ")}`);
+  }
+
+  return result;
+}

package/src/webperf/scanner.js

@@ -0,0 +1,209 @@
+/**
+ * Web performance scanner — KJC-TSK-0149.
+ *
+ * Wraps Google's Lighthouse CLI (`lighthouse`) to produce a structured
+ * Core Web Vitals + opportunity report against a local URL. Same
+ * pattern as sonar-findings.js, osv-findings.js, semgrep-findings.js:
+ * best-effort, missing binary returns {ok:false, reason}, all heavy
+ * lifting happens in an external tool the user installs themselves.
+ *
+ * Output shape is designed to feed two downstream consumers:
+ *   1. The CLI `kj webperf <url>` (KJC-TSK-0149) — print JSON or human
+ *      report, optionally persist to config.webperf.lastResult.
+ *   2. `kj audit` WebPerf section (KJC-TSK-0360) — the `cwv-result` mode
+ *      reads exactly this shape from `config.webperf.lastResult`.
+ *
+ * Lighthouse JSON schema reference:
+ *   https://github.com/GoogleChrome/lighthouse/blob/main/types/lhr/lhr.d.ts
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { evaluateCwv, CWV_THRESHOLDS } from "./cwv-gate.js";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 120_000;
+const MAX_OPPORTUNITIES = 20;
+
+/**
+ * Opportunity audits we extract from Lighthouse output. Each maps to a
+ * known render-perf issue with actionable fixes; we keep the list short
+ * to bound the payload size and keep the LLM prompt tight when this
+ * result feeds `kj audit`.
+ */
+const OPPORTUNITY_AUDITS = [
+  "render-blocking-resources",
+  "unused-css-rules",
+  "unused-javascript",
+  "unminified-css",
+  "unminified-javascript",
+  "modern-image-formats",
+  "uses-optimized-images",
+  "uses-text-compression",
+  "uses-responsive-images",
+  "uses-rel-preconnect",
+  "uses-rel-preload",
+  "font-display",
+  "preload-lcp-image",
+  "lcp-lazy-loaded",
+  "non-composited-animations",
+  "third-party-summary",
+  "bootup-time",
+  "mainthread-work-breakdown",
+];
+
+/**
+ * Run Lighthouse against a URL and return a structured result.
+ *
+ * @param {string} url - target URL (must be reachable from the runner)
+ * @param {object} [opts]
+ * @param {object} [opts.thresholds] - CWV thresholds override (passed to evaluateCwv)
+ * @param {object} [opts.logger]
+ * @param {string} [opts.preset] - "desktop" or "mobile" (default: desktop)
+ * @param {number} [opts.timeoutMs] - override the 120s default
+ * @returns {Promise<object>} scanner result (see module JSDoc)
+ */
+export async function runWebperfScan(url, opts = {}) {
+  if (!url || typeof url !== "string") {
+    return { ok: false, reason: "no URL provided" };
+  }
+
+  const logger = opts.logger || null;
+  const preset = opts.preset === "mobile" ? "mobile" : "desktop";
+  const timeoutMs = opts.timeoutMs || SCAN_TIMEOUT_MS;
+
+  const lighthouseArgs = [
+    url,
+    "--output=json",
+    "--quiet",
+    "--chrome-flags=--headless --no-sandbox --disable-gpu",
+    `--preset=${preset}`,
+    "--only-categories=performance",
+  ];
+
+  let stdout;
+  try {
+    const result = await execFileAsync("lighthouse", lighthouseArgs, {
+      timeout: timeoutMs,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    stdout = result.stdout;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("lighthouse not found in PATH — install via 'npm install -g lighthouse'");
+      return { ok: false, reason: "lighthouse not installed", url };
+    }
+    if (err.killed) {
+      return { ok: false, reason: `lighthouse timed out after ${timeoutMs}ms`, url };
+    }
+    if (typeof err.stdout === "string" && err.stdout.trim().startsWith("{")) {
+      stdout = err.stdout;
+    } else {
+      const stderr = (err.stderr || "").trim().split("\n").pop() || err.message;
+      // Lighthouse prints clear NO_DCHECK / NO_NAVSTART errors when the URL
+      // is unreachable. Surface that verbatim.
+      const reason = /failed to fetch|connection refused|net::|navigation_start_time/i.test(stderr)
+        ? `URL ${url} not reachable: ${stderr}`
+        : `lighthouse failed: ${stderr}`;
+      if (logger?.warn) logger.warn(reason);
+      return { ok: false, reason, url };
+    }
+  }
+
+  let report;
+  try {
+    report = JSON.parse(stdout);
+  } catch (err) {
+    return { ok: false, reason: `lighthouse output not parseable: ${err.message}`, url };
+  }
+
+  return parseLighthouseReport(report, { url, preset, thresholds: opts.thresholds });
+}
+
+/**
+ * Convert a raw Lighthouse JSON report into the scanner's flat output.
+ * Public so tests can drive parsing without spawning lighthouse.
+ *
+ * @param {object} report - parsed Lighthouse output (lhr)
+ * @param {{url: string, preset?: string, thresholds?: object}} ctx
+ */
+export function parseLighthouseReport(report, ctx = {}) {
+  const audits = report?.audits || {};
+  const metrics = extractMetrics(audits);
+  const issues = extractIssues(audits);
+  const cwv = evaluateCwv(metrics, ctx.thresholds || CWV_THRESHOLDS);
+
+  return {
+    ok: true,
+    url: ctx.url || report?.finalDisplayedUrl || report?.requestedUrl || null,
+    preset: ctx.preset || "desktop",
+    capturedAt: report?.fetchTime || new Date().toISOString(),
+    lighthouseVersion: report?.lighthouseVersion || null,
+    performanceScore: typeof report?.categories?.performance?.score === "number"
+      ? Math.round(report.categories.performance.score * 100)
+      : null,
+    metrics,
+    cwv,
+    issues,
+    thresholds: ctx.thresholds || CWV_THRESHOLDS,
+  };
+}
+
+/**
+ * Pull Core Web Vitals + supporting metrics out of the Lighthouse audit
+ * collection. `numericValue` is the raw measurement Google reports (ms
+ * for time-based metrics, score 0-1 for CLS).
+ */
+function extractMetrics(audits) {
+  const get = (id) => {
+    const v = audits[id]?.numericValue;
+    return typeof v === "number" ? v : null;
+  };
+  return {
+    // CWV — these three drive the cwv-gate verdict
+    lcp: get("largest-contentful-paint"),
+    cls: get("cumulative-layout-shift"),
+    inp: get("interaction-to-next-paint") ?? get("max-potential-fid"),
+    // Supporting (informational)
+    fcp: get("first-contentful-paint"),
+    tbt: get("total-blocking-time"),
+    si: get("speed-index"),
+    tti: get("interactive"),
+  };
+}
+
+/**
+ * Distil the Lighthouse opportunity audits into a flat `issues` array.
+ * Each issue carries the audit id, score, savings (when applicable) and
+ * a one-line description so consumers can prioritise without parsing
+ * the full lhr.
+ */
+function extractIssues(audits) {
+  const issues = [];
+  for (const id of OPPORTUNITY_AUDITS) {
+    const audit = audits[id];
+    if (!audit) continue;
+    // score === 1 means "passed" — skip clean audits
+    if (typeof audit.score === "number" && audit.score >= 1) continue;
+    if (audit.scoreDisplayMode === "notApplicable") continue;
+    issues.push({
+      id,
+      title: audit.title || id,
+      score: typeof audit.score === "number" ? audit.score : null,
+      savingsMs: audit.details?.overallSavingsMs ?? null,
+      savingsBytes: audit.details?.overallSavingsBytes ?? null,
+      severity: scoreToSeverity(audit.score),
+    });
+  }
+  return issues
+    .sort((a, b) => (b.savingsMs || 0) - (a.savingsMs || 0))
+    .slice(0, MAX_OPPORTUNITIES);
+}
+
+function scoreToSeverity(score) {
+  if (typeof score !== "number") return "info";
+  if (score < 0.5) return "high";
+  if (score < 0.9) return "medium";
+  return "low";
+}

package/src/webperf/webperf-role-integration.js

@@ -0,0 +1,66 @@
+/**
+ * Integration helpers that format CWV gate results for the
+ * impeccable prompt and for pipeline progress events.
+ */
+
+const RATING_ICONS = { good: "PASS", "needs-improvement": "WARN", poor: "FAIL" };
+
+/**
+ * Build a human-readable section for the impeccable prompt.
+ *
+ * @param {{ pass: boolean, scores: object, blocking: Array, advisory: Array }} cwvResult
+ * @returns {string}
+ */
+export function buildWebPerfSection(cwvResult) {
+  const lines = [];
+  const verdict = cwvResult.pass ? "PASSED" : "FAILED";
+  lines.push(`## WebPerf — Core Web Vitals (${verdict})`);
+  lines.push("");
+
+  for (const [metric, { value, rating }] of Object.entries(cwvResult.scores)) {
+    const icon = RATING_ICONS[rating] || rating;
+    const unit = metric === "cls" ? "" : "ms";
+    lines.push(`- **${metric.toUpperCase()}**: ${value}${unit} [${icon}]`);
+  }
+
+  if (cwvResult.blocking.length > 0) {
+    lines.push("");
+    lines.push("### Blocking issues");
+    for (const b of cwvResult.blocking) {
+      const unit = b.metric === "cls" ? "" : "ms";
+      lines.push(`- ${b.metric.toUpperCase()}: ${b.value}${unit} exceeds poor threshold (${b.threshold}${unit})`);
+    }
+  }
+
+  if (cwvResult.advisory.length > 0) {
+    lines.push("");
+    lines.push("### Advisory (needs improvement)");
+    for (const a of cwvResult.advisory) {
+      const unit = a.metric === "cls" ? "" : "ms";
+      lines.push(`- ${a.metric.toUpperCase()}: ${a.value}${unit} exceeds good threshold (${a.threshold}${unit})`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format CWV result for a pipeline progress event payload.
+ *
+ * @param {{ pass: boolean, scores: object, blocking: Array, advisory: Array }} cwvResult
+ * @returns {{ type: string, pass: boolean, metrics: object, blockingCount: number, advisoryCount: number }}
+ */
+export function formatCwvForEvent(cwvResult) {
+  const metrics = {};
+  for (const [metric, { value, rating }] of Object.entries(cwvResult.scores)) {
+    metrics[metric] = { value, rating };
+  }
+
+  return {
+    type: "webperf-cwv",
+    pass: cwvResult.pass,
+    metrics,
+    blockingCount: cwvResult.blocking.length,
+    advisoryCount: cwvResult.advisory.length
+  };
+}

package/templates/coder-rules.md

@@ -0,0 +1,45 @@
+# Coder Rules
+
+## File modification safety
+
+- NEVER overwrite existing files entirely. Always make targeted, minimal edits.
+- When adding new code to an existing file, insert only the new lines at the correct location.
+- After each edit, verify with `git diff` that ONLY the intended lines changed.
+- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+- Pay special attention to CSS, HTML, and config files where full rewrites destroy prior work (brand colors, layouts, styles).
+
+## Multi-agent / multi-developer environment
+
+- Multiple developers and AI agents may be committing and modifying code simultaneously.
+- ALWAYS run `git fetch origin main` and check recent commits before starting work.
+- Before pushing or merging, rebase on the latest main: `git rebase origin/main`.
+- If a commit or push fails, check whether someone else pushed in the meantime.
+- Never assume main is unchanged since the last check — always verify.
+- Create a dedicated branch per task (`feat/` or `fix/`) and merge via PR, never push directly to main.
+
+## General
+
+- Keep changes minimal and focused on the task.
+- Do not modify code unrelated to the task.
+- Follow existing code conventions and patterns in the repository.
+
+## Environment isolation (parallel runs)
+
+- Never hardcode ports, DB names, or docker project names — read them from env
+  vars, documenting each one in `.env.example`. When `KJ_LANE_SLOT` /
+  `KJ_PORT_OFFSET` exist in the env, derive per-task values from them so
+  parallel lanes never collide.
+- Never commit a real `.env` — only `.env.example` is versioned.
+
+## Tests location (MANDATORY)
+
+- Tests live in a top-level `tests/` directory mirroring `src/` (e.g. a function in
+  `src/services/foo.js` is tested by `tests/services/foo.test.js`).
+- DO NOT scatter `*.test.js` files inside `src/` unless the project's local
+  `.karajan/coder-rules.md` explicitly overrides this.
+- When generating a project from scratch:
+  - Create `tests/` and point the test runner at it (`include: ['tests/**/*.test.{js,ts}']`).
+  - Exclude `tests/` from the production bundle.
+  - If you write `sonar-project.properties`, set `sonar.tests=tests` AND make sure
+    that directory exists. Never declare a path that doesn't exist — Sonar will
+    refuse to scan and the run will fail every iteration with the same error.

package/templates/docker-compose.sonar.yml

@@ -0,0 +1,60 @@
+# SonarQube Community Edition + PostgreSQL
+# Karajan Code - Geniova Technologies
+#
+# Prerequisite (Linux):
+#   sudo sysctl -w vm.max_map_count=262144
+#   echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
+#
+# Usage:
+#   docker compose -f docker-compose.sonar.yml up -d
+#   Open http://localhost:9000 (admin/admin on first access)
+
+services:
+  sonarqube:
+    image: sonarqube:community
+    container_name: karajan-sonarqube
+    depends_on:
+      sonarqube-db:
+        condition: service_healthy
+    ports:
+      - "9000:9000"
+    environment:
+      - SONAR_JDBC_URL=jdbc:postgresql://sonarqube-db:5432/sonar
+      - SONAR_JDBC_USERNAME=sonar
+      - SONAR_JDBC_PASSWORD=sonar
+      - SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true
+    volumes:
+      - sonarqube_data:/opt/sonarqube/data
+      - sonarqube_extensions:/opt/sonarqube/extensions
+      - sonarqube_logs:/opt/sonarqube/logs
+    networks:
+      - sonarnet
+    restart: unless-stopped
+
+  sonarqube-db:
+    image: postgres:17
+    container_name: karajan-sonarqube-db
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U sonar"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    environment:
+      - POSTGRES_USER=sonar
+      - POSTGRES_PASSWORD=sonar
+      - POSTGRES_DB=sonar
+    volumes:
+      - postgresql_data:/var/lib/postgresql/data
+    networks:
+      - sonarnet
+    restart: unless-stopped
+
+volumes:
+  sonarqube_data:
+  sonarqube_extensions:
+  sonarqube_logs:
+  postgresql_data:
+
+networks:
+  sonarnet:
+    driver: bridge

package/templates/domains/example-dental.md

@@ -0,0 +1,57 @@
+---
+name: dental-clinical
+description: Clinical dental workflows, treatment types, and orthodontic terminology
+tags:
+  - dental
+  - clinical
+  - orthodontics
+  - treatments
+version: 1.0.0
+author: geniova
+visibility: private
+sources:
+  - type: manual
+    note: Created by Geniova dental team based on clinical protocols
+---
+
+# Dental Clinical Domain
+
+## Core Concepts
+
+Teeth are numbered using the FDI World Dental Federation notation system:
+- Upper right: 11-18, Upper left: 21-28
+- Lower left: 31-38, Lower right: 41-48
+
+Orthodontic treatment types:
+- **Fixed appliances**: brackets, archwires, bands
+- **Removable aligners**: transparent trays (e.g., Invisalign-type)
+- **Mixed**: combination of fixed and removable phases
+
+Treatment lifecycle: Diagnosis -> Planning -> Approval -> Manufacturing -> Delivery -> Follow-up
+
+## Terminology
+
+- **Malocclusion**: misalignment of teeth or incorrect relation between upper and lower dental arches
+- **Bracket**: small attachment bonded to the tooth surface to hold the archwire
+- **Archwire**: wire threaded through brackets that applies corrective force
+- **Aligner**: removable transparent tray that gradually moves teeth
+- **IPR (Interproximal Reduction)**: controlled removal of enamel between teeth to create space
+- **Attachment**: tooth-colored bump bonded to tooth to help aligners grip
+- **Overcorrection**: intentional over-movement to account for relapse tendency
+- **Staging**: the sequence and timing of tooth movements across aligner steps
+
+## Business Rules
+
+- Treatment plans must be approved by the lead clinician before manufacturing begins.
+- Maximum standard treatment duration is 36 months; extensions require clinical justification.
+- Each aligner step should move teeth no more than 0.25mm or 2 degrees of rotation.
+- Clinical photos and scans are mandatory at: initial diagnosis, mid-treatment, and completion.
+- Patient consent form must be signed before any irreversible procedure (e.g., IPR, extractions).
+
+## Common Edge Cases
+
+- **Mixed dentition**: pediatric patients with both primary and permanent teeth require special staging to account for natural tooth eruption during treatment.
+- **Missing teeth**: treatment plans must explicitly account for gaps, pontics, or implant spaces.
+- **Previous orthodontic treatment**: relapse cases need different force protocols than first-time treatments.
+- **TMJ disorders**: patients with temporomandibular joint issues may need movement limits per step.
+- **Pregnancy**: treatment may need to be paused; certain procedures (radiographs) are contraindicated.

package/templates/kj.config.yml

@@ -0,0 +1,128 @@
+# AI Agents
+coder: claude
+reviewer: codex
+
+# Review settings
+review_mode: standard
+max_iterations: 5
+review_rules: ./review-rules.md
+coder_rules: ./coder-rules.md
+base_branch: main
+
+# Coder settings
+coder_options:
+  model: null
+  auto_approve: true
+
+# Reviewer settings
+reviewer_options:
+  output_format: json
+  require_schema: true
+  model: null
+  deterministic: true
+  retries: 1
+  fallback_reviewer: codex
+
+# Development methodology
+development:
+  methodology: tdd
+  require_test_changes: true
+  test_file_patterns:
+    - /tests/
+    - /__tests__/
+    - .test.
+    - .spec.
+
+# SonarQube settings
+# Authentication: set token below, or KJ_SONAR_TOKEN env var,
+# or save admin credentials in ~/.karajan/sonar-credentials.json:
+#   {"user": "admin", "password": "your-password"}
+sonarqube:
+  enabled: true
+  host: http://localhost:9000
+  token: null
+  quality_gate: true
+  enforcement_profile: pragmatic
+  gate_block_on:
+    - new_reliability_rating=E
+    - new_security_rating=E
+    - new_maintainability_rating=E
+    - new_coverage<80
+    - new_duplicated_lines_density>5
+  fail_on:
+    - BLOCKER
+    - CRITICAL
+  ignore_on:
+    - INFO
+  max_scan_retries: 3
+  scanner:
+    sources: "src,public,lib"
+    exclusions: "**/node_modules/**,**/fake-apps/**,**/scripts/**,**/playground/**,**/dist/**,**/build/**,**/*.min.js"
+    test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
+    coverage_exclusions: "**/tests/**,**/__tests__/**,**/*.test.js,**/*.spec.js"
+    disabled_rules:
+      - "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
+  auto_push: false
+  auto_pr: false
+  auto_rebase: true
+  branch_prefix: feat/
+
+# Output
+output:
+  report_dir: ./.reviews
+  log_level: info
+
+# Session limits
+session:
+  max_iteration_minutes: 15
+  max_total_minutes: 120
+  # Hard per-run spend ceiling (USD-equivalent). The run stops with a summary
+  # when exceeded; resume with `kj resume`. Set to null to remove the cap.
+  max_budget_usd: 5
+  fail_fast_repeats: 2
+  # Per-lane setup for parallel runs (worktrees). Runs INSIDE the fresh
+  # worktree instead of the default `npm ci`. Each lane receives
+  # KJ_LANE_SLOT (0,1,2…) and KJ_PORT_OFFSET (slot-derived) in its env —
+  # derive ports, DB names and docker project names from them so lanes
+  # never collide. The coder never orchestrates git; isolation is declared
+  # here. Example:
+  #   worktree_setup: "npm ci && docker compose -p app_lane_$KJ_LANE_SLOT up -d db"
+  worktree_setup: null

package/templates/review-rules.md

@@ -0,0 +1,17 @@
+# Review Rules
+
+- Focus on security, correctness, and tests first.
+- Only raise blocking issues for concrete production risks.
+- Keep non-blocking suggestions separate.
+
+## Environment isolation
+
+- Reject changes that hardcode ports, DB names or service hostnames instead of
+  reading them from env vars, and any diff that adds a real `.env` (only
+  `.env.example` is versioned).
+
+## File overwrite detection (BLOCKING)
+
+- If the diff shows an entire file was replaced (massive deletions + additions instead of targeted edits), flag it as BLOCKING.
+- Check specifically for: reverted brand colors, lost CSS styles, removed existing functionality, overwritten config values.
+- A diff where most lines of a file are removed and re-added with minor changes is a sign of full-file overwrite.