@kody-ade/kody-engine 0.2.46 → 0.2.48

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.46",
+  version: "0.2.48",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -51,8 +51,8 @@ var package_default = {
 
 // src/chat-cli.ts
 import { execFileSync as execFileSync20 } from "child_process";
-import * as fs19 from "fs";
-import * as path16 from "path";
+import * as fs22 from "fs";
+import * as path19 from "path";
 
 // src/chat/events.ts
 import * as fs from "fs";
@@ -529,8 +529,8 @@ async function emit(sink, type, sessionId, suffix, payload) {
 
 // src/kody2-cli.ts
 import { execFileSync as execFileSync19 } from "child_process";
-import * as fs18 from "fs";
-import * as path15 from "path";
+import * as fs21 from "fs";
+import * as path18 from "path";
 
 // src/dispatch.ts
 import * as fs5 from "fs";
@@ -572,6 +572,9 @@ function autoDispatch(opts) {
     if (/\bresolve\b/.test(afterTag)) {
       return { executable: "resolve", cliArgs: { pr: targetNum }, target: targetNum };
     }
+    if (/\bui-review\b/.test(afterTag)) {
+      return { executable: "ui-review", cliArgs: { pr: targetNum }, target: targetNum };
+    }
     if (/\breview\b/.test(afterTag)) {
       return { executable: "review", cliArgs: { pr: targetNum }, target: targetNum };
     }
@@ -591,7 +594,19 @@ function autoDispatch(opts) {
     return asDispatch(defaultExec, targetNum);
   }
   if (sub === "orchestrate" || sub === "orchestrator") {
-    return { executable: "orchestrator", cliArgs: { issue: targetNum }, target: targetNum };
+    const flow = extractFlowName(afterTag);
+    if (flow) {
+      return {
+        executable: `orchestrator-${flow}`,
+        cliArgs: { issue: targetNum, flow },
+        target: targetNum
+      };
+    }
+    return {
+      executable: "orchestrator-plan-build-review",
+      cliArgs: { issue: targetNum, flow: "plan-build-review" },
+      target: targetNum
+    };
   }
   if (sub === "build") {
     return { executable: "run", cliArgs: { issue: targetNum }, target: targetNum };
@@ -611,14 +626,18 @@ function extractSubcommand(afterTag) {
   if (!match) return null;
   return match[1];
 }
+function extractFlowName(afterTag) {
+  const match = afterTag.match(/--flow[=\s]+([a-z][a-z0-9-]{0,60})/);
+  return match ? match[1] : null;
+}
 function extractFeedback(afterTag) {
   const cleaned = afterTag.replace(/^(fix|please|kindly)(?:[\s:,.-]+|$)/i, "").trim();
   return cleaned.length > 0 ? cleaned : void 0;
 }
 
 // src/executor.ts
-import * as fs17 from "fs";
-import * as path14 from "path";
+import * as fs20 from "fs";
+import * as path17 from "path";
 
 // src/litellm.ts
 import { execFileSync, spawn } from "child_process";
@@ -948,6 +967,9 @@ function parseScriptList(p, key, raw) {
     if (r.runWhen && typeof r.runWhen === "object") {
       entry.runWhen = r.runWhen;
     }
+    if (r.with && typeof r.with === "object") {
+      entry.with = r.with;
+    }
     out.push(entry);
   }
   return out;
@@ -1078,29 +1100,11 @@ function noteFromAction(action) {
 }
 function renderStateComment(state) {
   const lines = [];
-  lines.push(STATE_BEGIN);
-  lines.push("");
-  lines.push("```json");
-  lines.push(
-    JSON.stringify(
-      {
-        schemaVersion: state.schemaVersion,
-        core: state.core,
-        artifacts: state.artifacts ?? {},
-        executables: state.executables,
-        history: state.history,
-        ...state.flow ? { flow: state.flow } : {}
-      },
-      null,
-      2
-    )
-  );
-  lines.push("```");
-  lines.push("");
-  lines.push(STATE_END);
-  lines.push("");
-  lines.push("## kody2 task state");
+  lines.push("## \u{1F4CB} kody2 task state");
   lines.push("");
+  if (state.flow) {
+    lines.push(`- **Flow:** \`${state.flow.name}\` (step: \`${state.flow.step}\`)`);
+  }
   lines.push(`- **Phase:** \`${state.core.phase}\`  **Status:** \`${state.core.status}\``);
   if (state.core.currentExecutable) {
     lines.push(`- **Last executable:** \`${state.core.currentExecutable}\``);
@@ -1127,6 +1131,31 @@ function renderStateComment(state) {
     }
     lines.push("");
   }
+  lines.push("<details>");
+  lines.push("<summary>Raw state (JSON)</summary>");
+  lines.push("");
+  lines.push(STATE_BEGIN);
+  lines.push("");
+  lines.push("```json");
+  lines.push(
+    JSON.stringify(
+      {
+        schemaVersion: state.schemaVersion,
+        core: state.core,
+        artifacts: state.artifacts ?? {},
+        executables: state.executables,
+        history: state.history,
+        ...state.flow ? { flow: state.flow } : {}
+      },
+      null,
+      2
+    )
+  );
+  lines.push("```");
+  lines.push("");
+  lines.push(STATE_END);
+  lines.push("");
+  lines.push("</details>");
   return lines.join("\n");
 }
 function readTaskState(target, number, cwd) {
@@ -1797,6 +1826,491 @@ function formatToolsUsage(profile) {
   return lines.join("\n");
 }
 
+// src/scripts/discoverQaContext.ts
+import * as fs13 from "fs";
+import * as path12 from "path";
+
+// src/scripts/frameworkDetectors.ts
+import * as fs12 from "fs";
+import * as path11 from "path";
+function detectFrameworks(cwd) {
+  const out = [];
+  let deps = {};
+  try {
+    const pkg = JSON.parse(fs12.readFileSync(path11.join(cwd, "package.json"), "utf-8"));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch {
+    return out;
+  }
+  if (deps.payload || deps["@payloadcms/next"]) {
+    out.push({
+      name: "payload-cms",
+      version: deps.payload ?? deps["@payloadcms/next"] ?? null,
+      configFile: findFile(cwd, ["payload.config.ts", "payload-config.ts", "src/payload.config.ts"])
+    });
+  }
+  if (deps["next-auth"]) {
+    out.push({
+      name: "nextauth",
+      version: deps["next-auth"] ?? null,
+      configFile: findFile(cwd, ["auth.ts", "auth.config.ts", "src/auth.ts", "src/auth.config.ts"])
+    });
+  }
+  if (deps.prisma || deps["@prisma/client"]) {
+    out.push({
+      name: "prisma",
+      version: deps.prisma ?? deps["@prisma/client"] ?? null,
+      configFile: findFile(cwd, ["prisma/schema.prisma"])
+    });
+  }
+  if (deps.next) {
+    out.push({
+      name: "nextjs",
+      version: deps.next ?? null,
+      configFile: findFile(cwd, ["next.config.ts", "next.config.mjs", "next.config.js"])
+    });
+  }
+  return out;
+}
+function findFile(cwd, candidates) {
+  for (const c of candidates) {
+    if (fs12.existsSync(path11.join(cwd, c))) return c;
+  }
+  return null;
+}
+var COLLECTION_DIRS = [
+  "src/server/payload/collections",
+  "src/payload/collections",
+  "src/collections",
+  "payload/collections"
+];
+function discoverPayloadCollections(cwd) {
+  const out = [];
+  for (const dir of COLLECTION_DIRS) {
+    const full = path11.join(cwd, dir);
+    if (!fs12.existsSync(full)) continue;
+    let files;
+    try {
+      files = fs12.readdirSync(full).filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      try {
+        const filePath = path11.join(full, file);
+        const content = fs12.readFileSync(filePath, "utf-8").slice(0, 1e4);
+        const slugMatch = content.match(/slug:\s*['"]([a-z0-9-]+)['"]/);
+        if (!slugMatch) continue;
+        const slug = slugMatch[1];
+        const name = file.replace(/\.(ts|tsx)$/, "");
+        const fields = [];
+        const fieldMatches = content.matchAll(/name:\s*['"]([a-zA-Z_][a-zA-Z0-9_]*)['"]/g);
+        for (const m of fieldMatches) {
+          if (!fields.includes(m[1])) fields.push(m[1]);
+        }
+        const hasAdmin = /components:\s*\{/.test(content) || /Field:\s*['"]/.test(content) || /Cell:\s*['"]/.test(content) || /views:\s*\{/.test(content);
+        out.push({
+          name,
+          slug,
+          filePath: path11.relative(cwd, filePath),
+          fields: fields.slice(0, 20),
+          hasAdmin
+        });
+      } catch {
+      }
+    }
+  }
+  return out;
+}
+var ADMIN_COMPONENT_DIRS = ["src/ui/admin", "src/admin/components", "src/components/admin"];
+function discoverAdminComponents(cwd, collections) {
+  const out = [];
+  for (const dir of ADMIN_COMPONENT_DIRS) {
+    const full = path11.join(cwd, dir);
+    if (!fs12.existsSync(full)) continue;
+    let entries;
+    try {
+      entries = fs12.readdirSync(full, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryPath = path11.join(full, entry.name);
+      let name;
+      let filePath;
+      if (entry.isDirectory()) {
+        const indexFile = ["index.tsx", "index.ts", "index.jsx", "index.js"].find(
+          (f) => fs12.existsSync(path11.join(entryPath, f))
+        );
+        if (!indexFile) continue;
+        name = entry.name;
+        filePath = path11.relative(cwd, path11.join(entryPath, indexFile));
+      } else if (/\.(tsx?|jsx?)$/.test(entry.name)) {
+        name = entry.name.replace(/\.(tsx?|jsx?)$/, "");
+        filePath = path11.relative(cwd, entryPath);
+      } else {
+        continue;
+      }
+      let usedInCollection = null;
+      if (collections) {
+        for (const col of collections) {
+          try {
+            const colContent = fs12.readFileSync(path11.join(cwd, col.filePath), "utf-8");
+            if (colContent.includes(name)) {
+              usedInCollection = col.slug;
+              break;
+            }
+          } catch {
+          }
+        }
+      }
+      out.push({ name, filePath, usedInCollection });
+    }
+  }
+  return out;
+}
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+function scanApiRoutes(cwd) {
+  const out = [];
+  const appDirs = ["src/app", "app"];
+  for (const appDir of appDirs) {
+    const apiDir = path11.join(cwd, appDir, "api");
+    if (!fs12.existsSync(apiDir)) continue;
+    walkApiRoutes(apiDir, "/api", cwd, out);
+    break;
+  }
+  return out;
+}
+function walkApiRoutes(dir, prefix, cwd, out) {
+  let entries;
+  try {
+    entries = fs12.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const routeFile = entries.find((e) => e.isFile() && /^route\.(ts|js|tsx|jsx)$/.test(e.name));
+  if (routeFile) {
+    try {
+      const content = fs12.readFileSync(path11.join(dir, routeFile.name), "utf-8").slice(0, 5e3);
+      const methods = HTTP_METHODS.filter((m) => new RegExp(`export\\s+(?:async\\s+)?function\\s+${m}\\b`).test(content));
+      if (methods.length > 0) {
+        out.push({
+          path: prefix,
+          methods,
+          filePath: path11.relative(cwd, path11.join(dir, routeFile.name))
+        });
+      }
+    } catch {
+    }
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === "node_modules" || entry.name === ".next") continue;
+    let segment = entry.name;
+    if (segment.startsWith("(") && segment.endsWith(")")) {
+      walkApiRoutes(path11.join(dir, entry.name), prefix, cwd, out);
+      continue;
+    }
+    if (segment.startsWith("[[") && segment.endsWith("]]")) {
+      segment = `:${segment.slice(2, -2)}?`;
+    } else if (segment.startsWith("[") && segment.endsWith("]")) {
+      segment = `:${segment.slice(1, -1)}`;
+    }
+    walkApiRoutes(path11.join(dir, entry.name), `${prefix}/${segment}`, cwd, out);
+  }
+}
+var BUILTIN_ENV_VARS = /* @__PURE__ */ new Set([
+  "NODE_ENV",
+  "HOME",
+  "PATH",
+  "USER",
+  "SHELL",
+  "TERM",
+  "LANG",
+  "PWD",
+  "HOSTNAME",
+  "PORT",
+  "CI",
+  "GITHUB_ACTIONS"
+]);
+function scanEnvVars(cwd) {
+  const candidates = [".env.example", ".env.local.example", ".env.template"];
+  for (const envFile of candidates) {
+    const envPath = path11.join(cwd, envFile);
+    if (!fs12.existsSync(envPath)) continue;
+    try {
+      const content = fs12.readFileSync(envPath, "utf-8");
+      const vars = [];
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const match = trimmed.match(/^([A-Z][A-Z0-9_]*)=/);
+        if (match && !BUILTIN_ENV_VARS.has(match[1])) vars.push(match[1]);
+      }
+      return vars;
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+// src/scripts/discoverQaContext.ts
+var MAX_SERIALIZED_LENGTH = 8e3;
+function runQaDiscovery(cwd) {
+  const out = {
+    routes: [],
+    authFiles: [],
+    loginPage: null,
+    adminPath: null,
+    roles: [],
+    devCommand: "",
+    devPort: 3e3,
+    frameworks: [],
+    collections: [],
+    adminComponents: [],
+    apiRoutes: [],
+    envVars: []
+  };
+  detectDevServer(cwd, out);
+  scanFrontendRoutes(cwd, out);
+  detectAuthFiles(cwd, out);
+  detectRoles(cwd, out);
+  out.frameworks = detectFrameworks(cwd);
+  const hasPayload = out.frameworks.some((f) => f.name === "payload-cms");
+  if (hasPayload) out.collections = discoverPayloadCollections(cwd);
+  out.adminComponents = discoverAdminComponents(cwd, out.collections.length > 0 ? out.collections : void 0);
+  out.apiRoutes = scanApiRoutes(cwd);
+  out.envVars = scanEnvVars(cwd);
+  if (hasPayload && !out.adminPath) out.adminPath = "/admin";
+  return out;
+}
+function detectDevServer(cwd, out) {
+  try {
+    const pkg = JSON.parse(fs13.readFileSync(path12.join(cwd, "package.json"), "utf-8"));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const pm = fs13.existsSync(path12.join(cwd, "pnpm-lock.yaml")) ? "pnpm" : fs13.existsSync(path12.join(cwd, "yarn.lock")) ? "yarn" : fs13.existsSync(path12.join(cwd, "bun.lockb")) ? "bun" : "npm";
+    if (pkg.scripts?.dev) out.devCommand = `${pm} dev`;
+    if (allDeps.next || allDeps.nuxt) out.devPort = 3e3;
+    else if (allDeps.vite) out.devPort = 5173;
+  } catch {
+  }
+}
+function scanFrontendRoutes(cwd, out) {
+  const appDirs = ["src/app", "app"];
+  for (const appDir of appDirs) {
+    const full = path12.join(cwd, appDir);
+    if (!fs13.existsSync(full)) continue;
+    walkFrontendRoutes(full, "", out);
+    break;
+  }
+}
+function walkFrontendRoutes(dir, prefix, out) {
+  let entries;
+  try {
+    entries = fs13.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const hasPage = entries.some((e) => e.isFile() && /^page\.(tsx?|jsx?)$/.test(e.name));
+  if (hasPage) {
+    const routePath = prefix || "/";
+    const group = prefix.startsWith("/admin") ? "admin" : prefix.includes("/login") || prefix.includes("/signup") ? "auth" : prefix.includes("/api") ? "api" : "frontend";
+    out.routes.push({ path: routePath, group });
+    if (prefix.includes("/login") && !out.loginPage) out.loginPage = routePath;
+    if (prefix.startsWith("/admin") && !out.adminPath) out.adminPath = prefix;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === "node_modules" || entry.name === ".next") continue;
+    let segment = entry.name;
+    if (segment.startsWith("(") && segment.endsWith(")")) {
+      walkFrontendRoutes(path12.join(dir, entry.name), prefix, out);
+      continue;
+    }
+    if (segment.startsWith("[[") && segment.endsWith("]]")) {
+      segment = `:${segment.slice(2, -2)}?`;
+    } else if (segment.startsWith("[") && segment.endsWith("]")) {
+      segment = `:${segment.slice(1, -1)}`;
+    }
+    walkFrontendRoutes(path12.join(dir, entry.name), `${prefix}/${segment}`, out);
+  }
+}
+function detectAuthFiles(cwd, out) {
+  const candidates = [
+    "middleware.ts",
+    "middleware.js",
+    "src/middleware.ts",
+    "src/middleware.js",
+    "src/app/api/auth",
+    "src/auth",
+    "src/lib/auth",
+    "auth.config.ts",
+    "auth.ts",
+    "src/app/api/oauth"
+  ];
+  for (const c of candidates) {
+    if (fs13.existsSync(path12.join(cwd, c))) out.authFiles.push(c);
+  }
+}
+function detectRoles(cwd, out) {
+  const rolePaths = ["src/types", "src/lib", "src/utils", "src/constants", "src/access", "src/collections"];
+  for (const rp of rolePaths) {
+    const dir = path12.join(cwd, rp);
+    if (!fs13.existsSync(dir)) continue;
+    let files;
+    try {
+      files = fs13.readdirSync(dir).filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      try {
+        const content = fs13.readFileSync(path12.join(dir, f), "utf-8").slice(0, 5e3);
+        const roleMatches = content.match(/(?:role|Role|ROLE)\s*[=:]\s*['"](\w+)['"]/g);
+        if (roleMatches) {
+          for (const m of roleMatches) {
+            const val = m.match(/['"](\w+)['"]/);
+            if (val && !out.roles.includes(val[1])) out.roles.push(val[1]);
+          }
+        }
+        const enumMatch = content.match(/(?:enum|type)\s+\w*[Rr]ole\w*\s*[={]([^}]+)/s);
+        if (enumMatch) {
+          const vals = enumMatch[1].match(/['"](\w+)['"]/g);
+          if (vals) {
+            for (const v of vals) {
+              const clean = v.replace(/['"]/g, "");
+              if (!out.roles.includes(clean)) out.roles.push(clean);
+            }
+          }
+        }
+      } catch {
+      }
+    }
+  }
+}
+function serializeDiscoveryForLLM(d) {
+  const sections = [];
+  sections.push(`Dev server: ${d.devCommand || "pnpm dev"} at http://localhost:${d.devPort}`);
+  if (d.loginPage) sections.push(`Login page: ${d.loginPage}`);
+  if (d.adminPath) sections.push(`Admin panel: ${d.adminPath}`);
+  if (d.roles.length > 0) sections.push(`Roles: ${d.roles.join(", ")}`);
+  if (d.frameworks.length > 0) {
+    sections.push(
+      `
+Frameworks: ${d.frameworks.map((f) => `${f.name}${f.version ? ` (${f.version})` : ""}`).join(", ")}`
+    );
+  }
+  if (d.collections.length > 0) {
+    sections.push("\nCollections (Payload CMS):");
+    for (const col of d.collections.slice(0, 15)) {
+      const fields = col.fields.slice(0, 10).join(", ");
+      let line = `- ${col.slug}: fields=[${fields}]`;
+      if (col.hasAdmin) line += " (has custom admin components)";
+      line += ` \u2014 ${col.filePath}`;
+      sections.push(line);
+    }
+    if (d.collections.length > 15) sections.push(`- ... and ${d.collections.length - 15} more collections`);
+  }
+  if (d.adminComponents.length > 0) {
+    sections.push("\nCustom Admin Components:");
+    for (const comp of d.adminComponents.slice(0, 10)) {
+      let line = `- ${comp.name} (${comp.filePath})`;
+      if (comp.usedInCollection) line += ` \u2192 used in "${comp.usedInCollection}" collection`;
+      sections.push(line);
+    }
+  }
+  if (d.apiRoutes.length > 0) {
+    sections.push("\nAPI Routes:");
+    for (const route of d.apiRoutes.slice(0, 20)) {
+      sections.push(`- ${route.methods.join("/")} ${route.path} \u2014 ${route.filePath}`);
+    }
+    if (d.apiRoutes.length > 20) sections.push(`- ... and ${d.apiRoutes.length - 20} more routes`);
+  }
+  if (d.routes.length > 0) {
+    sections.push("\nFrontend Routes:");
+    for (const route of d.routes.slice(0, 30)) {
+      sections.push(`- [${route.group}] ${route.path}`);
+    }
+    if (d.routes.length > 30) sections.push(`- ... and ${d.routes.length - 30} more routes`);
+  }
+  if (d.envVars.length > 0) sections.push(`
+Required env vars: ${d.envVars.join(", ")}`);
+  let result = sections.join("\n");
+  if (result.length > MAX_SERIALIZED_LENGTH) {
+    const cutoff = result.lastIndexOf("\n", MAX_SERIALIZED_LENGTH - 20);
+    result = result.slice(0, cutoff > 0 ? cutoff : MAX_SERIALIZED_LENGTH - 20) + "\n... (truncated)";
+  }
+  return result;
+}
+function generateQaGuideTemplate(d) {
+  const lines = [];
+  lines.push("# QA guide");
+  lines.push("");
+  lines.push("This file is read by `kody2 ui-review`. Fill in the credential placeholders");
+  lines.push("below and commit \u2014 the agent uses them to log in to your preview deployment.");
+  lines.push("");
+  lines.push("## Test accounts");
+  lines.push("");
+  lines.push("<!-- Replace CHANGE_ME with real credentials for your preview environment.");
+  lines.push("     Remove any role row you don't have an account for. -->");
+  lines.push("");
+  lines.push("| Role | Email | Password |");
+  lines.push("|------|-------|----------|");
+  if (d.roles.length > 0) {
+    for (const role of d.roles) {
+      lines.push(`| ${role} | CHANGE_ME | CHANGE_ME |`);
+    }
+  } else {
+    lines.push("| admin | admin@example.com | CHANGE_ME |");
+    lines.push("| user | user@example.com | CHANGE_ME |");
+  }
+  lines.push("");
+  lines.push("## Login");
+  lines.push("");
+  lines.push(`- Login page: \`${d.loginPage ?? "/login"}\``);
+  if (d.adminPath) lines.push(`- Admin panel: \`${d.adminPath}\``);
+  lines.push("");
+  lines.push("### Steps");
+  lines.push(`1. Navigate to \`${d.loginPage ?? "/login"}\``);
+  lines.push("2. Enter credentials from the table above");
+  lines.push("3. Submit the login form");
+  lines.push("4. Verify the redirect lands on the expected page");
+  lines.push("");
+  if (d.roles.length > 0) {
+    lines.push("## Roles");
+    lines.push("");
+    for (const role of d.roles) lines.push(`- \`${role}\``);
+    lines.push("");
+  }
+  if (d.routes.length > 0) {
+    lines.push("## Key pages");
+    lines.push("");
+    const groups = {};
+    for (const r of d.routes) {
+      if (!groups[r.group]) groups[r.group] = [];
+      groups[r.group].push(r.path);
+    }
+    for (const [group, routes] of Object.entries(groups)) {
+      lines.push(`### ${group[0].toUpperCase()}${group.slice(1)}`);
+      for (const r of routes.slice(0, 15).sort()) lines.push(`- \`${r}\``);
+      if (routes.length > 15) lines.push(`- \u2026 and ${routes.length - 15} more`);
+      lines.push("");
+    }
+  }
+  lines.push("## Notes for the reviewer");
+  lines.push("");
+  lines.push("<!-- Add any repo-specific quirks the UI-review agent should know:");
+  lines.push("     seed data assumptions, feature flags, preview-only behaviors, etc. -->");
+  lines.push("");
+  return lines.join("\n");
+}
+var discoverQaContext = async (ctx) => {
+  const discovery = runQaDiscovery(ctx.cwd);
+  ctx.data.qaDiscovery = discovery;
+  ctx.data.qaContext = serializeDiscoveryForLLM(discovery);
+};
+
 // src/scripts/dispatch.ts
 import { execFileSync as execFileSync7 } from "child_process";
 var API_TIMEOUT_MS3 = 3e4;
@@ -2274,7 +2788,7 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd) {
 
 // src/gha.ts
 import { execFileSync as execFileSync11 } from "child_process";
-import * as fs12 from "fs";
+import * as fs14 from "fs";
 function getRunUrl() {
   const server = process.env.GITHUB_SERVER_URL;
   const repo = process.env.GITHUB_REPOSITORY;
@@ -2285,10 +2799,10 @@ function getRunUrl() {
 function reactToTriggerComment(cwd) {
   if (process.env.GITHUB_EVENT_NAME !== "issue_comment") return;
   const eventPath = process.env.GITHUB_EVENT_PATH;
-  if (!eventPath || !fs12.existsSync(eventPath)) return;
+  if (!eventPath || !fs14.existsSync(eventPath)) return;
   let event = null;
   try {
-    event = JSON.parse(fs12.readFileSync(eventPath, "utf-8"));
+    event = JSON.parse(fs14.readFileSync(eventPath, "utf-8"));
   } catch {
     return;
   }
@@ -2514,35 +3028,35 @@ function tryPostPr2(prNumber, body, cwd) {
 
 // src/scripts/initFlow.ts
 import { execFileSync as execFileSync13 } from "child_process";
-import * as fs14 from "fs";
-import * as path12 from "path";
+import * as fs17 from "fs";
+import * as path15 from "path";
 
 // src/registry.ts
-import * as fs13 from "fs";
-import * as path11 from "path";
+import * as fs15 from "fs";
+import * as path13 from "path";
 function getExecutablesRoot() {
-  const here = path11.dirname(new URL(import.meta.url).pathname);
+  const here = path13.dirname(new URL(import.meta.url).pathname);
   const candidates = [
-    path11.join(here, "executables"),
+    path13.join(here, "executables"),
     // dev: src/
-    path11.join(here, "..", "executables"),
+    path13.join(here, "..", "executables"),
     // built: dist/bin → dist/executables
-    path11.join(here, "..", "src", "executables")
+    path13.join(here, "..", "src", "executables")
     // fallback
   ];
   for (const c of candidates) {
-    if (fs13.existsSync(c) && fs13.statSync(c).isDirectory()) return c;
+    if (fs15.existsSync(c) && fs15.statSync(c).isDirectory()) return c;
   }
   return candidates[0];
 }
 function listExecutables(root = getExecutablesRoot()) {
-  if (!fs13.existsSync(root)) return [];
-  const entries = fs13.readdirSync(root, { withFileTypes: true });
+  if (!fs15.existsSync(root)) return [];
+  const entries = fs15.readdirSync(root, { withFileTypes: true });
   const out = [];
   for (const ent of entries) {
     if (!ent.isDirectory()) continue;
-    const profilePath = path11.join(root, ent.name, "profile.json");
-    if (fs13.existsSync(profilePath) && fs13.statSync(profilePath).isFile()) {
+    const profilePath = path13.join(root, ent.name, "profile.json");
+    if (fs15.existsSync(profilePath) && fs15.statSync(profilePath).isFile()) {
       out.push({ name: ent.name, profilePath });
     }
   }
@@ -2550,8 +3064,8 @@ function listExecutables(root = getExecutablesRoot()) {
 }
 function hasExecutable(name, root = getExecutablesRoot()) {
   if (!isSafeName(name)) return false;
-  const profilePath = path11.join(root, name, "profile.json");
-  return fs13.existsSync(profilePath) && fs13.statSync(profilePath).isFile();
+  const profilePath = path13.join(root, name, "profile.json");
+  return fs15.existsSync(profilePath) && fs15.statSync(profilePath).isFile();
 }
 function isSafeName(name) {
   return /^[a-z][a-z0-9-]*$/.test(name) && !name.includes("..");
@@ -2578,11 +3092,31 @@ function parseGenericFlags(argv) {
   return args;
 }
 
+// src/scripts/loadQaGuide.ts
+import * as fs16 from "fs";
+import * as path14 from "path";
+var QA_GUIDE_REL_PATH = ".kody2/qa-guide.md";
+var loadQaGuide = async (ctx) => {
+  const full = path14.join(ctx.cwd, QA_GUIDE_REL_PATH);
+  if (!fs16.existsSync(full)) {
+    ctx.data.qaGuide = "";
+    ctx.data.qaGuidePath = "";
+    return;
+  }
+  try {
+    ctx.data.qaGuide = fs16.readFileSync(full, "utf-8");
+    ctx.data.qaGuidePath = QA_GUIDE_REL_PATH;
+  } catch {
+    ctx.data.qaGuide = "";
+    ctx.data.qaGuidePath = "";
+  }
+};
+
 // src/scripts/initFlow.ts
 function detectPackageManager(cwd) {
-  if (fs14.existsSync(path12.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs14.existsSync(path12.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs14.existsSync(path12.join(cwd, "bun.lockb"))) return "bun";
+  if (fs17.existsSync(path15.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs17.existsSync(path15.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs17.existsSync(path15.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function qualityCommandsFor(pm) {
@@ -2703,24 +3237,36 @@ function performInit(cwd, force) {
   const pm = detectPackageManager(cwd);
   const ownerRepo = detectOwnerRepo(cwd);
   const defaultBranch = defaultBranchFromGit(cwd);
-  const configPath = path12.join(cwd, "kody.config.json");
-  if (fs14.existsSync(configPath) && !force) {
+  const configPath = path15.join(cwd, "kody.config.json");
+  if (fs17.existsSync(configPath) && !force) {
     skipped.push("kody.config.json");
   } else {
     const cfg = makeConfig(pm, ownerRepo, defaultBranch);
-    fs14.writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}
+    fs17.writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}
 `);
     wrote.push("kody.config.json");
   }
-  const workflowDir = path12.join(cwd, ".github", "workflows");
-  const workflowPath = path12.join(workflowDir, "kody2.yml");
-  if (fs14.existsSync(workflowPath) && !force) {
+  const workflowDir = path15.join(cwd, ".github", "workflows");
+  const workflowPath = path15.join(workflowDir, "kody2.yml");
+  if (fs17.existsSync(workflowPath) && !force) {
     skipped.push(".github/workflows/kody2.yml");
   } else {
-    fs14.mkdirSync(workflowDir, { recursive: true });
-    fs14.writeFileSync(workflowPath, WORKFLOW_TEMPLATE);
+    fs17.mkdirSync(workflowDir, { recursive: true });
+    fs17.writeFileSync(workflowPath, WORKFLOW_TEMPLATE);
     wrote.push(".github/workflows/kody2.yml");
   }
+  const hasUi = fs17.existsSync(path15.join(cwd, "src/app")) || fs17.existsSync(path15.join(cwd, "app")) || fs17.existsSync(path15.join(cwd, "pages"));
+  if (hasUi) {
+    const qaGuidePath = path15.join(cwd, QA_GUIDE_REL_PATH);
+    if (fs17.existsSync(qaGuidePath) && !force) {
+      skipped.push(QA_GUIDE_REL_PATH);
+    } else {
+      fs17.mkdirSync(path15.dirname(qaGuidePath), { recursive: true });
+      const discovery = runQaDiscovery(cwd);
+      fs17.writeFileSync(qaGuidePath, generateQaGuideTemplate(discovery));
+      wrote.push(QA_GUIDE_REL_PATH);
+    }
+  }
   for (const exe of listExecutables()) {
     let profile;
     try {
@@ -2729,12 +3275,12 @@ function performInit(cwd, force) {
       continue;
     }
     if (profile.kind !== "scheduled" || !profile.schedule) continue;
-    const target = path12.join(workflowDir, `kody2-${exe.name}.yml`);
-    if (fs14.existsSync(target) && !force) {
+    const target = path15.join(workflowDir, `kody2-${exe.name}.yml`);
+    if (fs17.existsSync(target) && !force) {
       skipped.push(`.github/workflows/kody2-${exe.name}.yml`);
       continue;
     }
-    fs14.writeFileSync(target, renderScheduledWorkflow(exe.name, profile.schedule));
+    fs17.writeFileSync(target, renderScheduledWorkflow(exe.name, profile.schedule));
     wrote.push(`.github/workflows/kody2-${exe.name}.yml`);
   }
   return { wrote, skipped };
@@ -2931,6 +3477,22 @@ function readDottedString(source, dotted) {
   return String(cur);
 }
 
+// src/scripts/persistFlowState.ts
+var persistFlowState = async (ctx) => {
+  const state = ctx.data.taskState;
+  if (!state) return;
+  const issueNumber = ctx.args.issue ?? state.flow?.issueNumber;
+  if (!issueNumber) return;
+  try {
+    writeTaskState("issue", issueNumber, state, ctx.cwd);
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 persistFlowState] failed to write state on issue #${issueNumber}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+};
+
 // src/scripts/postIssueComment.ts
 var postIssueComment2 = async (ctx) => {
   if (ctx.skipAgent && ctx.output.exitCode !== void 0) return;
@@ -3093,8 +3655,8 @@ REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.
 
 // src/scripts/releaseFlow.ts
 import { execFileSync as execFileSync14, spawnSync } from "child_process";
-import * as fs15 from "fs";
-import * as path13 from "path";
+import * as fs18 from "fs";
+import * as path16 from "path";
 function bumpVersion(current, bump) {
   const m = current.match(/^(\d+)\.(\d+)\.(\d+)(.*)$/);
   if (!m) throw new Error(`cannot parse version '${current}' (expected x.y.z[-suffix])`);
@@ -3110,12 +3672,12 @@ function bumpVersion(current, bump) {
   return `${major}.${minor}.${patch}`;
 }
 function updateVersionInFile(file, newVersion, cwd) {
-  const abs = path13.join(cwd, file);
-  if (!fs15.existsSync(abs)) return false;
-  const content = fs15.readFileSync(abs, "utf-8");
+  const abs = path16.join(cwd, file);
+  if (!fs18.existsSync(abs)) return false;
+  const content = fs18.readFileSync(abs, "utf-8");
   const updated = content.replace(/"version"\s*:\s*"[^"]+"/, `"version": "${newVersion}"`);
   if (updated === content) return false;
-  fs15.writeFileSync(abs, updated);
+  fs18.writeFileSync(abs, updated);
   return true;
 }
 function generateChangelog(cwd, newVersion, lastTag) {
@@ -3163,19 +3725,19 @@ function generateChangelog(cwd, newVersion, lastTag) {
   return parts.join("\n");
 }
 function prependChangelog(cwd, entry) {
-  const p = path13.join(cwd, "CHANGELOG.md");
+  const p = path16.join(cwd, "CHANGELOG.md");
   const header = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n";
-  if (fs15.existsSync(p)) {
-    const prior = fs15.readFileSync(p, "utf-8");
+  if (fs18.existsSync(p)) {
+    const prior = fs18.readFileSync(p, "utf-8");
     if (/^#\s*Changelog\b/m.test(prior)) {
       const idx = prior.indexOf("\n", prior.indexOf("# Changelog"));
-      fs15.writeFileSync(p, `${prior.slice(0, idx + 1)}
+      fs18.writeFileSync(p, `${prior.slice(0, idx + 1)}
 ${entry}${prior.slice(idx + 1)}`);
     } else {
-      fs15.writeFileSync(p, `${header}${entry}${prior}`);
+      fs18.writeFileSync(p, `${header}${entry}${prior}`);
     }
   } else {
-    fs15.writeFileSync(p, `${header}${entry}`);
+    fs18.writeFileSync(p, `${header}${entry}`);
   }
 }
 function git3(args, cwd, timeout = 6e4) {
@@ -3226,13 +3788,13 @@ var releaseFlow = async (ctx) => {
 };
 async function runPrepare(args) {
   const { cwd, bump, dryRun, versionFiles, ctx } = args;
-  const pkgPath = path13.join(cwd, "package.json");
-  if (!fs15.existsSync(pkgPath)) {
+  const pkgPath = path16.join(cwd, "package.json");
+  if (!fs18.existsSync(pkgPath)) {
     ctx.output.exitCode = 99;
     ctx.output.reason = "release prepare: package.json not found";
     return;
   }
-  const pkg = JSON.parse(fs15.readFileSync(pkgPath, "utf-8"));
+  const pkg = JSON.parse(fs18.readFileSync(pkgPath, "utf-8"));
   if (typeof pkg.version !== "string") {
     ctx.output.exitCode = 99;
     ctx.output.reason = "release prepare: package.json has no version";
@@ -3303,8 +3865,8 @@ Merge this and then run \`kody2 release --mode finalize\`.`;
 }
 async function runFinalize(args) {
   const { cwd, dryRun, timeoutMs, releaseCfg, ctx } = args;
-  const pkgPath = path13.join(cwd, "package.json");
-  const pkg = JSON.parse(fs15.readFileSync(pkgPath, "utf-8"));
+  const pkgPath = path16.join(cwd, "package.json");
+  const pkg = JSON.parse(fs18.readFileSync(pkgPath, "utf-8"));
   if (typeof pkg.version !== "string") {
     ctx.output.exitCode = 99;
     ctx.output.reason = "release finalize: package.json has no version";
@@ -3571,6 +4133,25 @@ function tryPostPr3(prNumber, body, cwd) {
   }
 }
 
+// src/scripts/resolvePreviewUrl.ts
+var DEFAULT_PREVIEW_URL = "http://localhost:3000";
+var resolvePreviewUrl = async (ctx) => {
+  const fromFlag = typeof ctx.args.previewUrl === "string" ? ctx.args.previewUrl.trim() : "";
+  if (fromFlag.length > 0) {
+    ctx.data.previewUrl = fromFlag;
+    ctx.data.previewUrlSource = "flag";
+    return;
+  }
+  const fromEnv = (process.env.PREVIEW_URL ?? "").trim();
+  if (fromEnv.length > 0) {
+    ctx.data.previewUrl = fromEnv;
+    ctx.data.previewUrlSource = "env";
+    return;
+  }
+  ctx.data.previewUrl = DEFAULT_PREVIEW_URL;
+  ctx.data.previewUrlSource = "default";
+};
+
 // src/scripts/reviewFlow.ts
 var reviewFlow = async (ctx) => {
   const prNumber = ctx.args.pr;
@@ -3955,7 +4536,7 @@ var watchStalePrsFlow = async (ctx) => {
 };
 
 // src/scripts/writeRunSummary.ts
-import * as fs16 from "fs";
+import * as fs19 from "fs";
 var writeRunSummary = async (ctx, profile) => {
   const summaryPath = process.env.GITHUB_STEP_SUMMARY;
   if (!summaryPath) return;
@@ -3977,7 +4558,7 @@ var writeRunSummary = async (ctx, profile) => {
   if (reason) lines.push(`- **Reason:** ${reason}`);
   lines.push("");
   try {
-    fs16.appendFileSync(summaryPath, `${lines.join("\n")}
+    fs19.appendFileSync(summaryPath, `${lines.join("\n")}
 `);
   } catch {
   }
@@ -3998,8 +4579,11 @@ var preflightScripts = {
   loadIssueContext,
   loadConventions,
   loadCoverageRules,
+  loadQaGuide,
   buildSyntheticPlugin,
   resolveArtifacts,
+  discoverQaContext,
+  resolvePreviewUrl,
   composePrompt,
   skipAgent
 };
@@ -4022,7 +4606,8 @@ var postflightScripts = {
   startFlow,
   dispatch,
   finishFlow,
-  advanceFlow
+  advanceFlow,
+  persistFlowState
 };
 var allScriptNames = /* @__PURE__ */ new Set([
   ...Object.keys(preflightScripts),
@@ -4131,9 +4716,9 @@ async function runExecutable(profileName, input) {
     data: {},
     output: { exitCode: 0 }
   };
-  const ndjsonDir = path14.join(input.cwd, ".kody2");
+  const ndjsonDir = path17.join(input.cwd, ".kody2");
   const invokeAgent = async (prompt) => {
-    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path14.isAbsolute(p) ? p : path14.resolve(profile.dir, p)).filter((p) => p.length > 0);
+    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path17.isAbsolute(p) ? p : path17.resolve(profile.dir, p)).filter((p) => p.length > 0);
     const syntheticPath = ctx.data.syntheticPluginPath;
     const pluginPaths = [...externalPlugins, ...syntheticPath ? [syntheticPath] : []];
     return runAgent({
@@ -4200,17 +4785,17 @@ async function runExecutable(profileName, input) {
   }
 }
 function resolveProfilePath(profileName) {
-  const here = path14.dirname(new URL(import.meta.url).pathname);
+  const here = path17.dirname(new URL(import.meta.url).pathname);
   const candidates = [
-    path14.join(here, "executables", profileName, "profile.json"),
+    path17.join(here, "executables", profileName, "profile.json"),
     // same-dir sibling (dev)
-    path14.join(here, "..", "executables", profileName, "profile.json"),
+    path17.join(here, "..", "executables", profileName, "profile.json"),
     // up one (prod: dist/bin → dist/executables)
-    path14.join(here, "..", "src", "executables", profileName, "profile.json")
+    path17.join(here, "..", "src", "executables", profileName, "profile.json")
     // fallback
   ];
   for (const c of candidates) {
-    if (fs17.existsSync(c)) return c;
+    if (fs20.existsSync(c)) return c;
   }
   return candidates[0];
 }
@@ -4386,9 +4971,9 @@ function resolveAuthToken(env = process.env) {
   return token;
 }
 function detectPackageManager2(cwd) {
-  if (fs18.existsSync(path15.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs18.existsSync(path15.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs18.existsSync(path15.join(cwd, "bun.lockb"))) return "bun";
+  if (fs21.existsSync(path18.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs21.existsSync(path18.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs21.existsSync(path18.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function shellOut(cmd, args, cwd, stream = true) {
@@ -4468,11 +5053,11 @@ function configureGitIdentity(cwd) {
 }
 function postFailureTail(issueNumber, cwd, reason) {
   if (!issueNumber) return;
-  const logPath = path15.join(cwd, ".kody2", "last-run.jsonl");
+  const logPath = path18.join(cwd, ".kody2", "last-run.jsonl");
   let tail = "";
   try {
-    if (fs18.existsSync(logPath)) {
-      const content = fs18.readFileSync(logPath, "utf-8");
+    if (fs21.existsSync(logPath)) {
+      const content = fs21.readFileSync(logPath, "utf-8");
       tail = content.slice(-3e3);
     }
   } catch {
@@ -4497,7 +5082,7 @@ async function runCi(argv) {
     return 0;
   }
   const args = parseCiArgs(argv);
-  const cwd = args.cwd ? path15.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path18.resolve(args.cwd) : process.cwd();
   let earlyConfig;
   try {
     earlyConfig = loadConfig(cwd);
@@ -4630,9 +5215,9 @@ function parseChatArgs(argv, env = process.env) {
   return result;
 }
 function commitChatFiles(cwd, sessionId, verbose) {
-  const sessionFile = path16.relative(cwd, sessionFilePath(cwd, sessionId));
-  const eventsFile = path16.relative(cwd, eventsFilePath(cwd, sessionId));
-  const paths = [sessionFile, eventsFile].filter((p) => fs19.existsSync(path16.join(cwd, p)));
+  const sessionFile = path19.relative(cwd, sessionFilePath(cwd, sessionId));
+  const eventsFile = path19.relative(cwd, eventsFilePath(cwd, sessionId));
+  const paths = [sessionFile, eventsFile].filter((p) => fs22.existsSync(path19.join(cwd, p)));
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
@@ -4670,7 +5255,7 @@ async function runChat(argv) {
 ${CHAT_HELP}`);
     return 64;
   }
-  const cwd = args.cwd ? path16.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path19.resolve(args.cwd) : process.cwd();
   const sessionId = args.sessionId;
   const unpackedSecrets = unpackAllSecrets();
   if (unpackedSecrets > 0) {