karajan-code 2.9.0 → 2.10.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.9.0 released** — Audit overhaul release. `kj audit` becomes a stack-aware, two-phase analysis tool. Highlights: (1) **Two-phase mode**: deterministic findings (basalCost + Sonar + OSV + Semgrep + WebPerf) print first; you decide whether to spend tokens on the LLM analysis with `Continue with LLM analysis? [y/N]`. New `--deterministic-only` flag for zero-token runs. (2) **Three new deterministic security collectors**: SonarQube findings as ground truth in the prompt, OSV-Scanner for dependency CVEs (broader DB than `npm audit`), Semgrep for SAST (XSS, SQLi, taint flow, hardcoded secrets — equivalent to `snyk code` but free and local). (3) **Stack-aware prompt**: detects frontend/backend/fullstack and filters dimension heuristics — no more N+1 query nags on Astro projects, no more bundle-size nags on Express APIs. (4) **Accessibility dimension** auto-activates for frontend projects (WCAG 2.x: alt text, labels, ARIA, focus management, contrast hints). (5) **WebPerf section** with frontend perf hints (lazy loading, image format, render-blocking, font-display, critical CSS) plus optional Core Web Vitals verdict integration. (6) **`--report-file` flag** persists audits to `.md` or `.json` with reproducibility header (timestamp, branch, commit, flags). `$KJ_AUDIT_REPORT_DIR` env var for CI. (7) **Token/cost transparency**: every audit ends with provider + model + tokens + estimated USD cost. (8) **CLI/MCP parity bug fixed** — CLI now drives `AuditRole` like MCP does; both paths produce identical prompt content. Plus repo health: 228 dead exports → 3 in 5 atomic PRs, and the `kj audit` detector itself now matches knip ground truth (166 → 4 false positives, 99.7% reduction). 13 audit PRs + 5 dead-export PRs + 106 new tests; full suite 4305/4305 passing. See [CHANGELOG.md](./CHANGELOG.md) for the full punch list.
+> **v2.10.0 released** — Agent-readiness release. Karajan is now the first orchestrator with a full agent-readability surface: an `llms.txt` index at the root, a `SKILL.md` per CLI command under `docs/agents/`, and a static auditor that scores any third-party repo against the same shape. Highlights: (1) **`kj audit --agent-readiness`** scores any repo 0–100 across seven checks (llms.txt, robots AI-bot allowlist, page token budgets ≤ 32 KB, heading hierarchy, agents/README, SKILL.md coverage). LLM-free, deterministic, JSON-able. Karajan-on-Karajan: **100/100**. (2) **Six new SKILL.md files** (`kj doctor / init / board / review / resume / clean`) under `docs/agents/`, all with the same `What it does · Inputs · Outputs · Side effects · Failure modes · Example` contract; CI guards every link in `llms.txt` resolves. (3) **Webperf quality gate inside the iteration loop** (`pipeline.perf.enabled`): PASS continues, FAIL pushes blocking-metric feedback to the coder, scanner-missing skips best-effort. (4) **HU Board hardening**: binds 127.0.0.1 by default, opt-in `--bind 0.0.0.0` enforces an auto-generated token, helmet headers, rate limiting at 300 req/min — "safe by default on a coffee-shop WiFi". (5) **a11y skills auto-route**: tasks mentioning `accessibility / WCAG / ARIA / screen reader / keyboard nav` automatically pull the `frontend-ui-engineering` skill. (6) **Asciinema demo scripts** under `docs/demos/` so the recordings re-record per release instead of rotting. 5 PRs merged (#605–#609 + #610), 4358/4358 tests passing. See [CHANGELOG.md](./CHANGELOG.md) for the full punch list.
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -113,6 +113,19 @@ cd wrappers/python && pip install .
 
 That's it. `kj init` auto-detects your installed agents and installs RTK for token optimization.
 
+### Optional scanners for `kj audit` + `kj webperf`
+
+Karajan auto-skips any scanner that isn't installed. Add the ones that match your projects:
+
+| Tool | Install | What you get |
+|------|---------|--------------|
+| **SonarQube** | `docker compose -f ~/sonarqube/docker-compose.yml up -d` | Code quality + security rules with line-precision in `kj audit` |
+| **OSV-Scanner** | `go install github.com/google/osv-scanner@latest` | Dependency CVE coverage broader than `npm audit` |
+| **Semgrep** | `pipx install semgrep` | SAST: XSS, SQLi, taint flow, secrets — equivalent to `snyk code`, free for OSS |
+| **Lighthouse** | `npm install -g lighthouse` | Core Web Vitals + opportunities for `kj webperf` (auto-feeds `kj audit`) |
+
+Skip any per-run with `--no-sonar`, `--no-osv`, `--no-semgrep`. See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md#optional-scanners--kj-audit--kj-webperf) for full table.
+
 ## Three ways to use Karajan
 
 Karajan installs **three commands**: `kj`, `kj-tail`, and `karajan-mcp`.

package/package.json

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

package/src/audit/agent-readiness.js

@@ -104,10 +104,15 @@ const CHECKS = [
       if (!fs.existsSync(docsDir)) return { ok: true, hint: null, details: { docsDirPresent: false } };
       const violations = [];
       for (const f of listMarkdownFiles(docsDir)) {
-        const text = safeRead(f);
-        const h1Count = (text.match(/^#\s+/gm) || []).length;
+        const text = stripFencedCodeBlocks(safeRead(f));
+        // Count BOTH markdown `# ` and HTML `<h1>` headings — bilingual
+        // README-style files often use a centered `<h1 align="center">`
+        // banner, which is still semantically the document's H1.
+        const mdH1Count = (text.match(/^#\s+/gm) || []).length;
+        const htmlH1Count = (text.match(/<h1[\s>]/gi) || []).length;
+        const h1Count = mdH1Count + htmlH1Count;
         if (h1Count !== 1) {
-          violations.push({ file: path.relative(rootDir, f), h1Count });
+          violations.push({ file: path.relative(rootDir, f), h1Count, mdH1Count, htmlH1Count });
           continue;
         }
         // Check for skipped levels (#### without preceding ###, etc.)
@@ -166,6 +171,19 @@ function safeRead(p) {
   try { return fs.readFileSync(p, "utf8"); } catch { return ""; }
 }
 
+/**
+ * Replace every fenced code block (```…``` or ~~~…~~~) with blank lines
+ * of the same line count so heading regexes don't accidentally match
+ * shell comments inside bash code blocks (`# install foo`). Preserving
+ * line counts keeps later byte-offset checks stable.
+ */
+function stripFencedCodeBlocks(text) {
+  return text.replace(/^([ \t]*)(```|~~~)[^\n]*\n([\s\S]*?)\n\1\2[^\n]*$/gm, (match) => {
+    const lineCount = match.split("\n").length;
+    return "\n".repeat(lineCount - 1);
+  });
+}
+
 function listMarkdownFiles(dir, out = []) {
   for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
     if (e.name.startsWith(".") || e.name === "node_modules") continue;

package/src/audit/webperf-input.js

@@ -7,22 +7,67 @@
  *     source (bundle bloat, render-blocking, image opt, lazy loading).
  *     This is the common path because `kj audit` runs against a code
  *     tree, not a live preview server.
- *   - "cwv-result": a Core Web Vitals measurement was supplied (either
- *     via config.webperf.lastResult, or in the future via a `kj webperf`
- *     command that drives Chrome DevTools MCP). evaluateCwv from
- *     src/webperf/cwv-gate.js produces a structured verdict the prompt
- *     renders verbatim.
+ *   - "cwv-result": a Core Web Vitals measurement was supplied. Three
+ *     possible sources, in priority order:
+ *       1. `config.webperf.lastResult` — inline {metrics, thresholds, ...}
+ *          (rare; legacy / programmatic injection)
+ *       2. `config.webperf.lastResultPath` — file path written by
+ *          `kj webperf` (KJC-TSK-0149). This is the standard wiring.
+ *       3. `~/.karajan/webperf/<projectSlug>/last.json` — fallback
+ *          discovery when the user ran `kj webperf` but didn't patch
+ *          their kj.config.yml.
+ *     evaluateCwv from src/webperf/cwv-gate.js produces a structured
+ *     verdict the prompt renders verbatim.
  *
  * The "live measurement" path is intentionally NOT wired here: the
  * audit's LLM sub-agent is forbidden from MCP tool use (SUBAGENT_PREAMBLE
  * in src/prompts/audit.js), and spawning Chrome / launching a preview
- * server during a read-only audit is out of scope. When a future
- * `kj webperf` command exists, it can write the result into
- * `config.webperf.lastResult` and this collector will surface it.
+ * server during a read-only audit is wrong layer. `kj webperf` does
+ * the measurement; `kj audit` consumes the persisted result.
  */
 
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
 import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
 
+// Resolve per call — `os.homedir()` reads $HOME each time, so test
+// suites that override $HOME for hermetic tmp dirs work without
+// special re-imports.
+function webperfHome() {
+  return path.join(os.homedir(), ".karajan", "webperf");
+}
+
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/**
+ * Try the three discovery paths in priority order. Returns the parsed
+ * scan object (shape produced by src/webperf/scanner.js) or null.
+ */
+function loadPersistedScan(webperfConfig, projectDir) {
+  // 1. Inline result on the config (back-compat)
+  if (webperfConfig.lastResult && typeof webperfConfig.lastResult === "object" && webperfConfig.lastResult.metrics) {
+    return webperfConfig.lastResult;
+  }
+  // 2. Explicit file path on the config
+  const candidates = [];
+  if (webperfConfig.lastResultPath) candidates.push(webperfConfig.lastResultPath);
+  // 3. Fallback: ~/.karajan/webperf/<slug>/last.json
+  if (projectDir) {
+    candidates.push(path.join(webperfHome(), projectSlug(projectDir), "last.json"));
+  }
+  for (const candidate of candidates) {
+    try {
+      const raw = fs.readFileSync(candidate, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && parsed.metrics) return parsed;
+    } catch { /* missing file or unparseable — try next */ }
+  }
+  return null;
+}
+
 /**
  * Decide what (if anything) to feed the audit prompt about web perf.
  *
@@ -32,17 +77,18 @@ import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
  */
 export function collectWebPerfInput(stack, config = {}) {
   const webperfConfig = config?.webperf || {};
-  const lastResult = webperfConfig.lastResult || null;
+  const projectDir = config?.projectDir;
+  const persisted = loadPersistedScan(webperfConfig, projectDir);
 
-  if (lastResult && typeof lastResult === "object" && lastResult.metrics) {
-    const verdict = evaluateCwv(lastResult.metrics, lastResult.thresholds || webperfConfig.thresholds);
+  if (persisted) {
+    const verdict = persisted.cwv || evaluateCwv(persisted.metrics, persisted.thresholds || webperfConfig.thresholds);
     return {
       available: true,
       mode: "cwv-result",
-      url: lastResult.url || webperfConfig.url || null,
-      capturedAt: lastResult.capturedAt || null,
+      url: persisted.url || webperfConfig.url || null,
+      capturedAt: persisted.capturedAt || null,
       cwv: verdict,
-      thresholds: lastResult.thresholds || webperfConfig.thresholds || CWV_THRESHOLDS,
+      thresholds: persisted.thresholds || webperfConfig.thresholds || CWV_THRESHOLDS,
     };
   }
 

package/src/cli/register-meta.js

@@ -5,6 +5,7 @@ import { architectCommand } from "../commands/architect.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
 import { boardCommand } from "../commands/board.js";
+import { webperfCommand } from "../commands/webperf.js";
 import { undoCommand } from "../commands/undo.js";
 import { syncCommand } from "../commands/sync.js";
 import { cleanCommand } from "../commands/clean.js";
@@ -125,6 +126,27 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  program
+    .command("webperf")
+    .description("Run a Lighthouse web-perf scan against a URL — Core Web Vitals + opportunities")
+    .argument("<url>", "Target URL (e.g. http://localhost:3000)")
+    .option("--mobile", "Use the Lighthouse mobile preset (default: desktop)")
+    .option("--json", "Output raw JSON")
+    .option("--no-persist", "Don't write the result into ~/.karajan/webperf/<slug>/last.json (kj audit reads it from there)")
+    .action(async (url, flags) => {
+      await withConfig(pkgVersion, "webperf", flags, async ({ config, logger }) => {
+        const result = await webperfCommand({
+          url,
+          config, logger,
+          mobile: Boolean(flags.mobile),
+          json: Boolean(flags.json),
+          persist: flags.persist !== false,
+        });
+        // Exit with non-zero when the verdict is FAIL so CI can gate.
+        if (result && result.ok === false) process.exitCode = 1;
+      });
+    });
+
   program
     .command("resume")
     .description("Resume a paused session")
@@ -167,10 +189,12 @@ export function registerMeta(program, { pkgVersion }) {
     .command("board [action]")
     .description("Manage HU Board (start|stop|status|open)")
     .option("--port <number>", "Port (default: 4000)", "4000")
+    .option("--bind <host>", "Bind host (default: 127.0.0.1; use 0.0.0.0 to expose on LAN — token auth auto-enforced)")
     .action(async (action = "start", opts) => {
       await withConfig(pkgVersion, "board", opts, async ({ config, logger }) => {
         const port = Number(opts.port) || config.hu_board?.port || 4000;
-        await boardCommand({ action, port, logger });
+        const bind = opts.bind || config.hu_board?.bind || "127.0.0.1";
+        await boardCommand({ action, port, bind, logger });
       });
     });
 

package/src/cli/register-pipeline.js

@@ -58,6 +58,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--enable-tester")
     .option("--enable-security")
     .option("--enable-impeccable")
+    .option("--enable-perf")
     .option("--enable-triage")
     .option("--enable-discover")
     .option("--enable-architect")

package/src/commands/board.js

@@ -89,7 +89,7 @@ function buildBoardUrl(port, projectSlug) {
 }
 
 export async function startBoard(desiredPort = 4000, opts = {}) {
-  const { projectSlug = null } = opts;
+  const { projectSlug = null, bind = "127.0.0.1" } = opts;
   const existingPid = readPid();
   if (existingPid && isProcessAlive(existingPid)) {
     // Trust the saved PID — port info comes from the PID file if present
@@ -129,7 +129,7 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   // Use process.execPath (absolute path to current node binary) instead of "node".
   // Fixes ENOENT on nvm setups where `node` is not in the spawned process's PATH.
   const child = spawn(process.execPath, [serverPath], {
-    env: { ...process.env, PORT: String(port) },
+    env: { ...process.env, PORT: String(port), BIND_HOST: bind },
     detached: true,
     stdio: "ignore",
     cwd: BOARD_DIR
@@ -265,14 +265,17 @@ export function renderBoardBanner({ url, status, projectName }) {
   return ["", rule, ...content, rule, ""].join("\n");
 }
 
-export async function boardCommand({ action = "start", port = 4000, logger }) {
+export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger }) {
   switch (action) {
     case "start": {
-      const result = await startBoard(port);
+      const result = await startBoard(port, { bind });
       if (result.alreadyRunning) {
         logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
       } else {
         logger.info(`HU Board started (PID ${result.pid}) at ${result.url}`);
+        if (bind !== "127.0.0.1" && bind !== "localhost") {
+          logger.warn(`HU Board bound to ${bind} — token auth enforced for non-loopback peers. Token: ~/.karajan/hu-board/token`);
+        }
       }
       return result;
     }

package/src/commands/webperf.js

@@ -0,0 +1,164 @@
+/**
+ * `kj webperf <url>` — KJC-TSK-0149.
+ *
+ * Headless Lighthouse wrapper. Produces structured CWV + opportunities
+ * JSON. Writes the result into `~/.karajan/webperf/<projectSlug>/last.json`
+ * so future `kj audit` runs can surface the verdict via the existing
+ * WebPerf section (KJC-TSK-0360 cwv-result mode).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import yaml from "js-yaml";
+import { runWebperfScan } from "../webperf/scanner.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
+
+// Resolve home each call so tests that override $HOME for hermetic
+// tmp dirs work without re-importing the module.
+function defaultReportDir() {
+  return path.join(os.homedir(), ".karajan", "webperf");
+}
+
+/**
+ * Slug a project directory the same way audit/basal-cost.js and
+ * plan/plan-store.js do, so the per-project webperf history aligns
+ * with audit history under ~/.karajan/.
+ */
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function formatHumanReport(result) {
+  if (!result.ok) {
+    return `WebPerf scan FAILED — ${result.reason}`;
+  }
+  const lines = ["## WebPerf Scan", ""];
+  lines.push(`- URL: ${result.url}`);
+  lines.push(`- Preset: ${result.preset}`);
+  lines.push(`- Captured: ${result.capturedAt}`);
+  if (result.lighthouseVersion) lines.push(`- Lighthouse: v${result.lighthouseVersion}`);
+  if (typeof result.performanceScore === "number") {
+    lines.push(`- Performance score: ${result.performanceScore}/100`);
+  }
+  lines.push("");
+  lines.push(`### Verdict: ${result.cwv.pass ? "PASS" : "FAIL"}`);
+  lines.push("");
+  lines.push("### Core Web Vitals");
+  for (const [metric, score] of Object.entries(result.cwv.scores || {})) {
+    const value = formatMetricValue(metric, score.value);
+    lines.push(`- ${metric.toUpperCase()}: ${value} (${score.rating})`);
+  }
+  if (result.cwv.blocking?.length) {
+    lines.push("");
+    lines.push("### Blocking metrics (above poor threshold)");
+    for (const b of result.cwv.blocking) {
+      lines.push(`- ${b.metric.toUpperCase()}: ${formatMetricValue(b.metric, b.value)} > ${formatMetricValue(b.metric, b.threshold)}`);
+    }
+  }
+  if (result.issues?.length) {
+    lines.push("");
+    lines.push(`### Top opportunities (${result.issues.length})`);
+    for (const issue of result.issues.slice(0, 10)) {
+      const savings = issue.savingsMs ? ` (saves ~${Math.round(issue.savingsMs)}ms)` : "";
+      lines.push(`- [${issue.severity.toUpperCase()}] ${issue.id}${savings}: ${issue.title}`);
+    }
+    if (result.issues.length > 10) {
+      lines.push(`- ... and ${result.issues.length - 10} more`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function formatMetricValue(metric, value) {
+  if (typeof value !== "number") return "n/a";
+  if (metric === "cls") return value.toFixed(3);
+  return `${Math.round(value)}ms`;
+}
+
+/**
+ * Persist the scan result into ~/.karajan/webperf/<slug>/last.json so
+ * `kj audit` can read it via collectWebPerfInput (KJC-TSK-0360).
+ */
+async function persistResult(result, projectDir) {
+  if (!result.ok) return null;
+  const dir = path.join(defaultReportDir(), projectSlug(projectDir));
+  await fs.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "last.json");
+  await fs.writeFile(filePath, JSON.stringify(result, null, 2), "utf8");
+  return filePath;
+}
+
+/**
+ * Optionally update kj.config.yml so `kj audit` finds the result by
+ * default (mirrors how sonar config is wired). Best-effort: never
+ * fails the command; absence of config file or write error is logged.
+ */
+async function patchConfigLastResult(configPath, lastResultPath, logger) {
+  if (!configPath || !lastResultPath) return false;
+  let raw;
+  try { raw = await fs.readFile(configPath, "utf8"); } catch { return false; }
+  let parsed;
+  try { parsed = yaml.load(raw) || {}; } catch (err) {
+    if (logger?.warn) logger.warn(`webperf: cannot parse ${configPath}: ${err.message}`);
+    return false;
+  }
+  parsed.webperf = parsed.webperf || {};
+  parsed.webperf.lastResultPath = lastResultPath;
+  try {
+    await fs.writeFile(configPath, yaml.dump(parsed), "utf8");
+    return true;
+  } catch (err) {
+    if (logger?.warn) logger.warn(`webperf: cannot write ${configPath}: ${err.message}`);
+    return false;
+  }
+}
+
+export async function webperfCommand({ url, config, logger, json = false, mobile = false, persist = true, thresholds = null }) {
+  if (!url) {
+    throw new Error("kj webperf: <url> is required (e.g. http://localhost:3000)");
+  }
+  return withCliRunLog("webperf", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    logger.info(`Running webperf scan against ${url} (preset: ${mobile ? "mobile" : "desktop"})`);
+    runLog.logText(`[webperf] scan url=${url} preset=${mobile ? "mobile" : "desktop"}`);
+
+    const scanThresholds = thresholds || config?.webperf?.thresholds || null;
+    const result = await runWebperfScan(url, {
+      preset: mobile ? "mobile" : "desktop",
+      thresholds: scanThresholds,
+      logger,
+    });
+
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatHumanReport(result));
+    }
+
+    if (!result.ok) {
+      runLog.logText(`[webperf] failed reason=${result.reason}`);
+      return { ok: false, reason: result.reason };
+    }
+
+    runLog.logText(`[webperf] verdict=${result.cwv.pass ? "PASS" : "FAIL"} score=${result.performanceScore}`);
+
+    let savedPath = null;
+    if (persist) {
+      try {
+        savedPath = await persistResult(result, config?.projectDir);
+        if (savedPath) {
+          logger.info(`WebPerf result saved: ${savedPath}`);
+          // Wire into kj.config.yml so `kj audit` picks it up automatically.
+          const configPath = config?.configFilePath
+            || path.join(config?.projectDir || process.cwd(), ".karajan", "kj.config.yml");
+          await patchConfigLastResult(configPath, savedPath, logger);
+        }
+      } catch (err) {
+        logger.warn(`webperf: persist failed (non-blocking): ${err.message}`);
+      }
+    }
+
+    // Exit code: 0 for PASS, 1 for FAIL. Lets CI gate on it.
+    return { ok: result.cwv.pass, result, savedPath };
+  });
+}

package/src/config/defaults.js

@@ -37,6 +37,7 @@ const DEFAULTS = {
     tester: { enabled: true },
     security: { enabled: true },
     impeccable: { enabled: false },
+    perf: { enabled: false },
     triage: { enabled: true },
     discover: { enabled: false },
     architect: { enabled: false },

package/src/config/overrides.js

@@ -37,6 +37,7 @@ const PIPELINE_ENABLE_FLAGS = [
   ["enablePlanner", "planner"], ["enableRefactorer", "refactorer"],
   ["enableSolomon", "solomon"], ["enableResearcher", "researcher"],
   ["enableTester", "tester"], ["enableSecurity", "security"], ["enableImpeccable", "impeccable"],
+  ["enablePerf", "perf"],
   ["enableTriage", "triage"], ["enableDiscover", "discover"],
   ["enableArchitect", "architect"],
   ["enableHuReviewer", "hu_reviewer"]

package/src/config/schema.js

@@ -89,6 +89,7 @@ const PipelineMap = v.optional(v.looseObject({
   tester: v.optional(PipelineEntry),
   security: v.optional(PipelineEntry),
   impeccable: v.optional(PipelineEntry),
+  perf: v.optional(PipelineEntry),
   triage: v.optional(PipelineEntry),
   discover: v.optional(PipelineEntry),
   architect: v.optional(PipelineEntry),

package/src/mcp/handlers/run-handler.js

@@ -263,7 +263,7 @@ export async function handleResume(a, server, extra) {
     }
     a.answer = validation.sanitized;
   }
-  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable"]);
+  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable", "enablePerf"]);
   return handleResumeDirect(a, server, extra);
 }
 
@@ -303,6 +303,6 @@ export async function handleRun(a, server, extra) {
     const logger = createLogger("info", "mcp");
     logger.info("Preflight auto-acknowledged with default agent config");
   }
-  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable"]);
+  applySessionOverrides(a, ["coder", "reviewer", "tester", "security", "solomon", "enableTester", "enableSecurity", "enableImpeccable", "enablePerf"]);
   return handleRunDirect(a, server, extra);
 }

package/src/mcp/run-kj.js

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

package/src/mcp/sovereignty-guard.js

@@ -14,7 +14,7 @@ const ALLOWED_PARAMS = new Set([
   "planner", "coder", "reviewer", "refactorer",
   "plannerModel", "coderModel", "reviewerModel", "refactorerModel",
   "enablePlanner", "enableReviewer", "enableRefactorer", "enableResearcher",
-  "enableTester", "enableSecurity", "enableImpeccable",
+  "enableTester", "enableSecurity", "enableImpeccable", "enablePerf",
   "enableDiscover", "enableArchitect",
   "architectModel", "huFile",
   "enableSerena", "enableCi",

package/src/mcp/tools.js

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

package/src/orchestrator/config-init.js

@@ -217,6 +217,7 @@ export function resolvePipelineFlags(config) {
     testerEnabled: Boolean(config.pipeline?.tester?.enabled),
     securityEnabled: Boolean(config.pipeline?.security?.enabled),
     impeccableEnabled: Boolean(config.pipeline?.impeccable?.enabled),
+    perfEnabled: Boolean(config.pipeline?.perf?.enabled),
     reviewerEnabled: config.pipeline?.reviewer?.enabled !== false,
     discoverEnabled: Boolean(config.pipeline?.discover?.enabled),
     architectEnabled: Boolean(config.pipeline?.architect?.enabled),
@@ -225,7 +226,7 @@ export function resolvePipelineFlags(config) {
 }
 
 export async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
-  const { plannerEnabled, refactorerEnabled, researcherEnabled, testerEnabled, securityEnabled, impeccableEnabled, reviewerEnabled, discoverEnabled, architectEnabled, huReviewerEnabled } = pipelineFlags;
+  const { plannerEnabled, refactorerEnabled, researcherEnabled, testerEnabled, securityEnabled, impeccableEnabled, perfEnabled, reviewerEnabled, discoverEnabled, architectEnabled, huReviewerEnabled } = pipelineFlags;
   const plannerRole = resolveRole(config, "planner");
   const coderRole = resolveRole(config, "coder");
   const reviewerRole = resolveRole(config, "reviewer");
@@ -259,6 +260,7 @@ export async function handleDryRun({ task, config, flags, emitter, pipelineFlags
       tester_enabled: testerEnabled,
       security_enabled: securityEnabled,
       impeccable_enabled: impeccableEnabled,
+      perf_enabled: perfEnabled,
       solomon_enabled: Boolean(config.pipeline?.solomon?.enabled),
       hu_reviewer_enabled: huReviewerEnabled
     },

package/src/orchestrator/drivers/iteration-phases/quality-gates.js

@@ -18,6 +18,7 @@ import {
   runTddCheckStage, runSonarStage, runSonarCloudStage,
 } from "../../iteration-stages.js";
 import { runImpeccableStage } from "../../post-loop-stages.js";
+import { runPerfStage } from "../../stages/perf-stage.js";
 import { tryCiComment } from "../../ci-integration.js";
 
 export async function runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults, coderRole, pipelineFlags, brainCtx }) {
@@ -72,5 +73,16 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
     }
   }
 
+  if (pipelineFlags?.perfEnabled) {
+    const perfResult = await runPerfStage({
+      config, logger, emitter, eventBase, session, trackBudget,
+      iteration: i, task, brainCtx
+    });
+    if (perfResult.stageResult) {
+      stageResults.perf = perfResult.stageResult;
+    }
+    if (perfResult.action === "continue") return { action: "continue" };
+  }
+
   return { action: "ok" };
 }

package/src/orchestrator/session-journal.js

@@ -239,6 +239,7 @@ export function buildPlanSummary({ pipelineFlags, config, stageResults, task })
   if (pipelineFlags.testerEnabled) activeStages.push("Tester");
   if (pipelineFlags.securityEnabled) activeStages.push("Security");
   if (pipelineFlags.impeccableEnabled) activeStages.push("Impeccable");
+  if (pipelineFlags.perfEnabled) activeStages.push("Perf");
   lines.push(`│ Stages: ${activeStages.join(" → ")}`);
 
   // Config

package/src/orchestrator/stages/perf-stage.js

@@ -0,0 +1,140 @@
+/**
+ * PerfStage — webperf quality gate inside the iteration loop.
+ *
+ * KJC-TSK-0151. Wraps PerfRole and slots into the existing
+ * runQualityGateStages flow alongside Sonar and Impeccable. Designed
+ * to be the simplest possible quality gate:
+ *
+ *   - PASS verdict (cwv.pass === true) → return ok, iteration continues.
+ *   - FAIL verdict → set reviewer feedback with the blocking metrics
+ *     so the coder receives concrete guidance next iteration. Returns
+ *     `continue` to retry the iteration loop. No repeat-detector +
+ *     retry-limit machinery: rerunning Lighthouse on the same URL
+ *     gives the same result unless the coder changes something, and
+ *     the iteration limit (max_iterations) is the natural ceiling.
+ *   - Scanner unavailable (lighthouse missing, URL unreachable, timeout)
+ *     → log a warn and return ok-skipped. Best-effort, never blocks
+ *     the pipeline by itself.
+ *
+ * The role surface (PerfRole) is responsible for persisting the result
+ * to ~/.karajan/webperf/<slug>/last.json so subsequent `kj audit` runs
+ * pick it up via the auto-discovery added in #602.
+ */
+
+import { PerfRole } from "../../roles/perf-role.js";
+import { setReviewerFeedback } from "../../session/mutators.js";
+import { saveSession } from "../../session/store.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+/**
+ * Build the human-readable feedback line that goes back to the coder
+ * on FAIL. Concrete enough that the LLM can act on it without re-reading
+ * the whole report.
+ */
+function buildFeedback(roleResult) {
+  const { result } = roleResult;
+  const score = typeof result.performanceScore === "number" ? result.performanceScore : null;
+  const blocking = (result.cwv?.blocking || []).map(b => `${b.metric.toUpperCase()}=${Math.round(b.value)} (poor>${b.threshold})`);
+  const top = (result.issues || []).slice(0, 3).map(i => `${i.id}${i.savingsMs ? ` (~${Math.round(i.savingsMs)}ms)` : ""}`);
+
+  const lines = [`Webperf gate FAILED${score !== null ? ` (score ${score}/100)` : ""}.`];
+  if (blocking.length > 0) lines.push(`Blocking metrics: ${blocking.join(", ")}.`);
+  if (top.length > 0) lines.push(`Top opportunities: ${top.join(", ")}.`);
+  lines.push("Address the blocking metric(s) before the next iteration; rerunning without code changes will produce the same verdict.");
+  return lines.join(" ");
+}
+
+/**
+ * Run the perf gate against config.webperf.url.
+ *
+ * @returns {Promise<{action: "ok"|"continue", stageResult?: object, summary?: string}>}
+ */
+export async function runPerfStage({ config, logger, emitter, eventBase, session, trackBudget, iteration, task: _task, brainCtx }) {
+  if (!session) {
+    throw new Error("runPerfStage: `session` is required.");
+  }
+  logger.setContext({ iteration, stage: "perf" });
+  emitProgress(
+    emitter,
+    makeEvent("perf:start", { ...eventBase, stage: "perf" }, {
+      message: "WebPerf gate scanning",
+      detail: { url: config?.webperf?.url || null, preset: config?.webperf?.preset || "desktop" },
+    })
+  );
+
+  const role = new PerfRole({ config, logger, emitter });
+  const roleResult = await role.execute();
+
+  // Track budget — the role doesn't spawn an LLM but it does consume wall
+  // time; surface that in the budget summary alongside the agent calls.
+  if (trackBudget) {
+    try { trackBudget("perf", { tokens_in: 0, tokens_out: 0, cost_usd: 0 }); } catch { /* best-effort */ }
+  }
+
+  // Scanner unavailable → skip with warn. PerfRole returns ok=false for
+  // both "verdict FAIL" and "scanner failed", so we differentiate on the
+  // result.error field (set only by the second case).
+  if (!roleResult.ok && roleResult.result?.error) {
+    logger.warn(`Perf gate skipped: ${roleResult.result.error}`);
+    emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
+      status: "warn",
+      message: `Perf gate skipped — ${roleResult.result.error}`,
+    }));
+    return { action: "ok", stageResult: { skipped: true, reason: roleResult.result.error } };
+  }
+
+  // PASS verdict
+  if (roleResult.ok === true) {
+    emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
+      status: "ok",
+      message: roleResult.summary,
+    }));
+    return {
+      action: "ok",
+      stageResult: {
+        verdict: "PASS",
+        url: roleResult.result?.url,
+        performanceScore: roleResult.result?.performanceScore,
+        cwv: roleResult.result?.cwv,
+        savedPath: roleResult.result?.savedPath,
+        summary: roleResult.summary,
+      },
+    };
+  }
+
+  // FAIL verdict → push concrete feedback to the coder for next iteration.
+  const feedback = buildFeedback(roleResult);
+  setReviewerFeedback(session, feedback);
+  await saveSession(session);
+
+  // Brain: when enabled, surface perf feedback on the queue too.
+  if (brainCtx?.enabled) {
+    try {
+      const { processRoleOutput } = await import("../brain-coordinator.js");
+      processRoleOutput(brainCtx, {
+        roleName: "perf",
+        output: { verdict: "fail", summary: feedback },
+        iteration,
+      });
+    } catch (err) {
+      logger.warn(`Perf gate: brain queue push failed (non-blocking): ${err.message}`);
+    }
+  }
+
+  emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
+    status: "fail",
+    message: roleResult.summary,
+  }));
+
+  return {
+    action: "continue",
+    stageResult: {
+      verdict: "FAIL",
+      url: roleResult.result?.url,
+      performanceScore: roleResult.result?.performanceScore,
+      cwv: roleResult.result?.cwv,
+      issues: roleResult.result?.issues,
+      summary: feedback,
+    },
+  };
+}

package/src/roles/perf-role.js

@@ -0,0 +1,122 @@
+/**
+ * PerfRole — webperf quality gate (KJC-TSK-0150).
+ *
+ * Same shape as SonarRole / AuditRole: extends BaseRole, exposes an
+ * `execute()` that returns `{ok, result, summary}`. Internally drives
+ * `runWebperfScan` from src/webperf/scanner.js (the Lighthouse wrapper
+ * added in KJC-TSK-0149) and persists the result so subsequent
+ * `kj audit` runs surface it via `cwv-result` mode (KJC-TSK-0360).
+ *
+ * Configuration (kj.config.yml):
+ *   webperf:
+ *     url: http://localhost:3000   # required for the role to run
+ *     preset: desktop              # or "mobile"
+ *     thresholds: { lcp: { good: 2500, poor: 4000 }, ... }
+ *     persist: true                # writes to ~/.karajan/webperf/<slug>/last.json
+ *
+ * Pipeline activation (KJC-TSK-0151) wires this role behind a triage-
+ * driven flag so it only runs for frontend / fullstack tasks.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { BaseRole } from "./base-role.js";
+import { runWebperfScan } from "../webperf/scanner.js";
+
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function defaultPersistDir() {
+  return path.join(os.homedir(), ".karajan", "webperf");
+}
+
+async function persistResult(result, projectDir) {
+  if (!result?.ok) return null;
+  const dir = path.join(defaultPersistDir(), projectSlug(projectDir));
+  await fs.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "last.json");
+  await fs.writeFile(filePath, JSON.stringify(result, null, 2), "utf8");
+  return filePath;
+}
+
+export class PerfRole extends BaseRole {
+  constructor({ config, logger, emitter = null, scanFn = null }) {
+    super({ name: "perf", config, logger, emitter });
+    // scanFn is injectable for tests so we don't need to mock execFile here.
+    this._scan = scanFn || runWebperfScan;
+  }
+
+  /**
+   * Run a webperf scan against the configured URL.
+   *
+   * @param {object} [_input] - unused; PerfRole reads its target from config
+   * @returns {Promise<{ok: boolean, result: object, summary: string}>}
+   */
+  async execute(_input) {
+    const webperfConfig = this.config?.webperf || {};
+    const url = webperfConfig.url;
+    const preset = webperfConfig.preset === "mobile" ? "mobile" : "desktop";
+    const thresholds = webperfConfig.thresholds || null;
+    const persist = webperfConfig.persist !== false;
+
+    if (!url) {
+      return {
+        ok: false,
+        result: { error: "config.webperf.url is required for PerfRole" },
+        summary: "PerfRole skipped: no config.webperf.url configured",
+      };
+    }
+
+    const scan = await this._scan(url, { preset, thresholds, logger: this.logger });
+
+    if (!scan.ok) {
+      return {
+        ok: false,
+        result: {
+          url,
+          error: scan.reason || "webperf scan failed",
+        },
+        summary: `Webperf scan failed: ${scan.reason || "unknown"}`,
+      };
+    }
+
+    let savedPath = null;
+    if (persist) {
+      try {
+        savedPath = await persistResult(scan, this.config?.projectDir);
+      } catch (err) {
+        if (this.logger?.warn) {
+          this.logger.warn(`PerfRole: failed to persist result (non-blocking): ${err.message}`);
+        }
+      }
+    }
+
+    const verdict = scan.cwv?.pass ? "PASS" : "FAIL";
+    const score = typeof scan.performanceScore === "number" ? scan.performanceScore : null;
+    const blockingMetrics = (scan.cwv?.blocking || []).map(b => `${b.metric.toUpperCase()}=${Math.round(b.value)}`).join(", ");
+    const summaryParts = [
+      `Webperf ${verdict}`,
+      score !== null ? `score ${score}/100` : null,
+      blockingMetrics ? `blocking: ${blockingMetrics}` : null,
+      `top opportunities: ${scan.issues?.length ?? 0}`,
+    ].filter(Boolean);
+
+    return {
+      ok: scan.cwv?.pass === true,
+      result: {
+        url: scan.url,
+        preset: scan.preset,
+        capturedAt: scan.capturedAt,
+        performanceScore: scan.performanceScore,
+        metrics: scan.metrics,
+        cwv: scan.cwv,
+        issues: scan.issues,
+        thresholds: scan.thresholds,
+        savedPath,
+      },
+      summary: summaryParts.join(" — "),
+    };
+  }
+}

package/src/skills/addyosmani-role-map.js

@@ -89,6 +89,12 @@ export const TASK_PATTERN_TO_SLUG = [
   { pattern: /\bsecurity\b|\bhardening\b|\bauth(entication|orization)?\b|\bxss\b|\bcsrf\b|\binjection\b/i, slug: "security-and-hardening" },
   { pattern: /\btdd\b|\btest[- ]driven\b/i, slug: "test-driven-development" },
   { pattern: /\bfrontend\b|\bui\b|\bux\b|\bcss\b|\bresponsive\b/i, slug: "frontend-ui-engineering" },
+  // Accessibility (a11y / WCAG / ARIA / screen reader / keyboard nav).
+  // No dedicated addyosmani skill exists yet for a11y; until one ships,
+  // route to frontend-ui-engineering — the closest authoritative source
+  // for WCAG-aware UI work. When upstream ships an a11y skill, change
+  // only the `slug` field here.
+  { pattern: /\baccessibility\b|\ba11y\b|\bwcag\b|\baria\b|\bscreen[\s-]?reader\b|\bkeyboard[\s-]?nav(igation)?\b/i, slug: "frontend-ui-engineering" },
   { pattern: /\bapi\b|\bendpoint\b|\binterface\s+design\b|\bopenapi\b|\brest\b|\bgraphql\b/i, slug: "api-and-interface-design" },
   { pattern: /\bci\b|\bcd\b|\bci\/cd\b|\bpipeline\b|\bgithub\s+actions\b|\bworkflow\b/i, slug: "ci-cd-and-automation" },
   { pattern: /\bgit\b|\bcommit\b|\bbranch\b|\bmerge\b|\bversioning\b|\bsemver\b/i, slug: "git-workflow-and-versioning" },

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";
+}