@kody-ade/kody-engine 0.4.10 → 0.4.12

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.10",
+  version: "0.4.12",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -4347,15 +4347,54 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd, baseBranch)
     git2(["fetch", "origin"], cwd);
   } catch {
   }
+  let originBranchExists = false;
   try {
     git2(["rev-parse", "--verify", `origin/${branchName}`], cwd);
+    originBranchExists = true;
+  } catch {
+  }
+  if (originBranchExists && baseBranch && baseBranch !== defaultBranch) {
+    let baseExists = false;
+    try {
+      git2(["rev-parse", "--verify", `origin/${baseBranch}`], cwd);
+      baseExists = true;
+    } catch {
+    }
+    if (baseExists) {
+      let descendsFromBase = false;
+      try {
+        git2(["merge-base", "--is-ancestor", `origin/${baseBranch}`, `origin/${branchName}`], cwd);
+        descendsFromBase = true;
+      } catch {
+      }
+      if (!descendsFromBase) {
+        process.stderr.write(
+          `[kody branch] origin/${branchName} does not descend from origin/${baseBranch} \u2014 recreating from base
+`
+        );
+        try {
+          git2(["push", "origin", "--delete", branchName], cwd);
+        } catch {
+        }
+        try {
+          git2(["update-ref", "-d", `refs/remotes/origin/${branchName}`], cwd);
+        } catch {
+        }
+        try {
+          git2(["branch", "-D", branchName], cwd);
+        } catch {
+        }
+        originBranchExists = false;
+      }
+    }
+  }
+  if (originBranchExists) {
     git2(["checkout", branchName], cwd);
     try {
       git2(["pull", "origin", branchName], cwd);
     } catch {
     }
     return { branch: branchName, created: false };
-  } catch {
   }
   try {
     git2(["rev-parse", "--verify", branchName], cwd);
@@ -5571,6 +5610,171 @@ function composeBody({ label, exit, prUrl, reason, dryRun }) {
   return `\u2705 kody ${label} complete`;
 }
 
+// src/scripts/postReviewResult.ts
+function detectVerdict(body) {
+  const m = body.match(/##\s*Verdict\s*:\s*(PASS|CONCERNS|FAIL)\b/i);
+  if (!m) return "UNKNOWN";
+  return m[1].toUpperCase();
+}
+function reviewAction(verdict, payload) {
+  const type = verdict === "PASS" ? "REVIEW_PASS" : verdict === "CONCERNS" ? "REVIEW_CONCERNS" : verdict === "FAIL" ? "REVIEW_FAIL" : "REVIEW_COMPLETED";
+  return { type, payload: { verdict, ...payload }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function failedAction2(reason) {
+  return { type: "REVIEW_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+var postReviewResult = async (ctx, _profile, agentResult) => {
+  const prNumber = ctx.data.commentTargetNumber;
+  if (!prNumber) {
+    ctx.output.exitCode = 99;
+    ctx.output.reason = "review postflight: no PR number in context";
+    ctx.data.action = failedAction2(ctx.output.reason);
+    return;
+  }
+  if (!agentResult || agentResult.outcome !== "completed") {
+    const reason = agentResult?.error ?? "agent did not complete";
+    try {
+      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: ${truncate2(reason, 1e3)}`, ctx.cwd);
+    } catch {
+    }
+    ctx.output.exitCode = 1;
+    ctx.output.reason = reason;
+    ctx.data.action = failedAction2(reason);
+    return;
+  }
+  const reviewBody = agentResult.finalText.trim();
+  if (!reviewBody) {
+    try {
+      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: agent produced no review body`, ctx.cwd);
+    } catch {
+    }
+    ctx.output.exitCode = 1;
+    ctx.output.reason = "empty review body";
+    ctx.data.action = failedAction2("empty review body");
+    return;
+  }
+  try {
+    postPrReviewComment(prNumber, reviewBody, ctx.cwd);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.output.exitCode = 4;
+    ctx.output.reason = `failed to post review comment: ${msg}`;
+    ctx.data.action = failedAction2(ctx.output.reason);
+    return;
+  }
+  const verdict = detectVerdict(reviewBody);
+  ctx.data.reviewVerdict = verdict;
+  ctx.data.reviewBody = reviewBody;
+  ctx.data.action = reviewAction(verdict, { bodyPreview: truncate2(reviewBody, 500) });
+  ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
+  process.stdout.write(
+    `
+REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.repo}/pull/${prNumber} (verdict: ${verdict})
+`
+  );
+};
+
+// src/scripts/openQaIssue.ts
+var QA_LABEL = "kody:qa-report";
+function qaAction(verdict, payload) {
+  const type = verdict === "PASS" ? "QA_PASS" : verdict === "CONCERNS" ? "QA_CONCERNS" : verdict === "FAIL" ? "QA_FAIL" : "QA_COMPLETED";
+  return { type, payload: { verdict, ...payload }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function failedAction3(reason) {
+  return { type: "QA_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function slugifyScope(scope) {
+  return scope.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+}
+function buildIssueTitle(scope, verdict) {
+  const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const focus = scope?.trim() ? scope.trim() : "smoke";
+  const verdictTag = verdict === "UNKNOWN" ? "REPORT" : verdict;
+  return `QA [${verdictTag}]: ${focus} \u2014 ${date}`.slice(0, 240);
+}
+function ensureLabel(cwd) {
+  try {
+    gh2(["label", "create", QA_LABEL, "--color", "8b5cf6", "--description", "kody: QA report", "--force"], { cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function createQaIssue(title, body, hasLabel, cwd) {
+  const args = ["issue", "create", "--title", title, "--body-file", "-"];
+  if (hasLabel) args.push("--label", QA_LABEL);
+  const out = gh2(args, { input: body, cwd });
+  const url = out.split("\n").map((l) => l.trim()).filter(Boolean).pop() ?? "";
+  const m = url.match(/\/issues\/(\d+)\b/);
+  if (!m) throw new Error(`gh issue create returned unexpected output: ${out}`);
+  return { number: Number(m[1]), url };
+}
+var openQaIssue = async (ctx, _profile, agentResult) => {
+  if (!agentResult || agentResult.outcome !== "completed") {
+    const reason = agentResult?.error ?? "agent did not complete";
+    process.stderr.write(`qa-engineer: ${reason}
+`);
+    ctx.output.exitCode = 1;
+    ctx.output.reason = reason;
+    ctx.data.action = failedAction3(reason);
+    return;
+  }
+  const reportBody = agentResult.finalText.trim();
+  if (!reportBody) {
+    process.stderr.write("qa-engineer: agent produced no report body\n");
+    ctx.output.exitCode = 1;
+    ctx.output.reason = "empty report body";
+    ctx.data.action = failedAction3("empty report body");
+    return;
+  }
+  const verdict = detectVerdict(reportBody);
+  ctx.data.qaVerdict = verdict;
+  ctx.data.qaReport = reportBody;
+  const existingIssue = ctx.args.issue;
+  if (typeof existingIssue === "number" && Number.isFinite(existingIssue) && existingIssue > 0) {
+    try {
+      postIssueComment(existingIssue, reportBody, ctx.cwd);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      ctx.output.exitCode = 4;
+      ctx.output.reason = `failed to comment on issue #${existingIssue}: ${msg}`;
+      ctx.data.action = failedAction3(ctx.output.reason);
+      return;
+    }
+    process.stdout.write(
+      `
+QA_REPORT_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.repo}/issues/${existingIssue} (verdict: ${verdict})
+`
+    );
+    ctx.data.action = qaAction(verdict, { issueNumber: existingIssue, mode: "comment" });
+    ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
+    return;
+  }
+  const scope = ctx.args.scope;
+  const title = buildIssueTitle(scope, verdict);
+  const hasLabel = ensureLabel(ctx.cwd);
+  let created;
+  try {
+    created = createQaIssue(title, reportBody, hasLabel, ctx.cwd);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.output.exitCode = 4;
+    ctx.output.reason = `failed to open QA issue: ${truncate2(msg, 1e3)}`;
+    ctx.data.action = failedAction3(ctx.output.reason);
+    return;
+  }
+  process.stdout.write(`
+QA_REPORT_POSTED=${created.url} (verdict: ${verdict})
+`);
+  ctx.data.action = qaAction(verdict, {
+    issueNumber: created.number,
+    issueUrl: created.url,
+    titleSlug: scope ? slugifyScope(scope) : "smoke",
+    mode: "create"
+  });
+  ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
+};
+
 // src/scripts/parseAgentResult.ts
 var parseAgentResult2 = async (ctx, profile, agentResult) => {
   if (!agentResult) {
@@ -5945,70 +6149,6 @@ function renderResearchComment(issueNumber, body) {
 ${body}`;
 }
 
-// src/scripts/postReviewResult.ts
-function detectVerdict(body) {
-  const m = body.match(/##\s*Verdict\s*:\s*(PASS|CONCERNS|FAIL)\b/i);
-  if (!m) return "UNKNOWN";
-  return m[1].toUpperCase();
-}
-function reviewAction(verdict, payload) {
-  const type = verdict === "PASS" ? "REVIEW_PASS" : verdict === "CONCERNS" ? "REVIEW_CONCERNS" : verdict === "FAIL" ? "REVIEW_FAIL" : "REVIEW_COMPLETED";
-  return { type, payload: { verdict, ...payload }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
-}
-function failedAction2(reason) {
-  return { type: "REVIEW_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
-}
-var postReviewResult = async (ctx, _profile, agentResult) => {
-  const prNumber = ctx.data.commentTargetNumber;
-  if (!prNumber) {
-    ctx.output.exitCode = 99;
-    ctx.output.reason = "review postflight: no PR number in context";
-    ctx.data.action = failedAction2(ctx.output.reason);
-    return;
-  }
-  if (!agentResult || agentResult.outcome !== "completed") {
-    const reason = agentResult?.error ?? "agent did not complete";
-    try {
-      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: ${truncate2(reason, 1e3)}`, ctx.cwd);
-    } catch {
-    }
-    ctx.output.exitCode = 1;
-    ctx.output.reason = reason;
-    ctx.data.action = failedAction2(reason);
-    return;
-  }
-  const reviewBody = agentResult.finalText.trim();
-  if (!reviewBody) {
-    try {
-      postPrReviewComment(prNumber, `\u26A0\uFE0F kody review FAILED: agent produced no review body`, ctx.cwd);
-    } catch {
-    }
-    ctx.output.exitCode = 1;
-    ctx.output.reason = "empty review body";
-    ctx.data.action = failedAction2("empty review body");
-    return;
-  }
-  try {
-    postPrReviewComment(prNumber, reviewBody, ctx.cwd);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    ctx.output.exitCode = 4;
-    ctx.output.reason = `failed to post review comment: ${msg}`;
-    ctx.data.action = failedAction2(ctx.output.reason);
-    return;
-  }
-  const verdict = detectVerdict(reviewBody);
-  ctx.data.reviewVerdict = verdict;
-  ctx.data.reviewBody = reviewBody;
-  ctx.data.action = reviewAction(verdict, { bodyPreview: truncate2(reviewBody, 500) });
-  ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
-  process.stdout.write(
-    `
-REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.repo}/pull/${prNumber} (verdict: ${verdict})
-`
-  );
-};
-
 // src/scripts/recordClassification.ts
 import { execFileSync as execFileSync19 } from "child_process";
 var API_TIMEOUT_MS8 = 3e4;
@@ -6028,7 +6168,7 @@ var recordClassification = async (ctx) => {
     reason = parsed?.reason ?? null;
   }
   if (!classification) {
-    ctx.data.action = failedAction3("classification missing or invalid");
+    ctx.data.action = failedAction4("classification missing or invalid");
     tryAuditComment(
       issueNumber,
       "\u26A0\uFE0F kody classifier could not decide \u2014 please re-run with an explicit `@kody <type>`.",
@@ -6069,7 +6209,7 @@ function tryAuditComment(issueNumber, body, cwd) {
 function makeAction3(type, payload) {
   return { type, payload, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
-function failedAction3(reason) {
+function failedAction4(reason) {
   return { type: "CLASSIFY_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
 
@@ -6108,12 +6248,12 @@ function fail(ctx, profile, reason) {
   ctx.data.agentDone = false;
   ctx.data.agentFailureReason = reason;
   const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
-  const failedAction4 = {
+  const failedAction5 = {
     type: `${modeSeg}_FAILED`,
     payload: { reason },
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
-  ctx.data.action = failedAction4;
+  ctx.data.action = failedAction5;
 }
 function countActionItems(block) {
   if (!block.trim()) return 0;
@@ -6154,12 +6294,12 @@ function fail2(ctx, profile, reason) {
   ctx.data.agentDone = false;
   ctx.data.agentFailureReason = reason;
   const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
-  const failedAction4 = {
+  const failedAction5 = {
     type: `${modeSeg}_FAILED`,
     payload: { reason },
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
-  ctx.data.action = failedAction4;
+  ctx.data.action = failedAction5;
 }
 
 // src/scripts/resolveArtifacts.ts
@@ -7358,6 +7498,7 @@ var postflightScripts = {
   recordClassification,
   dispatchClassified,
   notifyTerminal,
+  openQaIssue,
   recordOutcome,
   mergeReleasePr,
   waitForCi,

package/dist/executables/qa-engineer/profile.json

@@ -0,0 +1,90 @@
+{
+  "name": "qa-engineer",
+  "role": "primitive",
+  "describe": "Free-form QA: browses a running site with Playwright MCP, explores routes, exercises UI states, posts a structured QA report. Opens a new issue per run by default; pass --issue <N> to comment on an existing one. Read-only on the repo.",
+  "kind": "oneshot",
+  "inputs": [
+    {
+      "name": "url",
+      "flag": "--url",
+      "type": "string",
+      "required": true,
+      "describe": "Base URL the agent should browse (e.g. http://localhost:3000)."
+    },
+    {
+      "name": "scope",
+      "flag": "--scope",
+      "type": "string",
+      "required": false,
+      "describe": "Optional feature focus (e.g. 'admin chat memory recall'). Without a scope the agent does a broad smoke pass over discovered routes."
+    },
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": false,
+      "describe": "Optional: comment the QA report on this existing issue instead of opening a new one."
+    },
+    {
+      "name": "authProfile",
+      "flag": "--auth-profile",
+      "type": "string",
+      "required": false,
+      "describe": "Path to a Playwright storageState.json for pre-authenticated sessions (skips manual login)."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash",
+      "Write",
+      "Edit",
+      "mcp__playwright"
+    ],
+    "hooks": ["block-git"],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "--package=@playwright/mcp@latest", "--", "playwright-mcp"]
+      }
+    ]
+  },
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "ls \"$HOME/.cache/ms-playwright\" 2>/dev/null | grep -q '^chromium' || ls \"$HOME/Library/Caches/ms-playwright\" 2>/dev/null | grep -q '^chromium'",
+        "installCommand": "npx --yes playwright install chromium"
+      },
+      "verify": "ls \"$HOME/.cache/ms-playwright\" 2>/dev/null | grep -q '^chromium' || ls \"$HOME/Library/Caches/ms-playwright\" 2>/dev/null | grep -q '^chromium'",
+      "usage": "The Playwright MCP server uses Chromium under the hood. Preflight ensures it is installed. Save screenshots under `.kody/qa-reports/<run>/` if you take any — that directory is gitignored.",
+      "allowedUses": ["--version"]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      { "script": "discoverQaContext" },
+      { "script": "loadQaGuide" },
+      { "script": "loadConventions" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "openQaIssue" }
+    ]
+  }
+}

package/dist/executables/qa-engineer/prompt.md

@@ -0,0 +1,103 @@
+You are Kody, a senior QA engineer. Your job is to **browse the running app like a real user**, exercise the UI broadly and intentionally, and produce one structured QA report. You do NOT fix bugs. You do NOT touch tracked source files. You do NOT run `git` or `gh`.
+
+You may write throwaway artifacts (screenshots, ad-hoc Playwright specs) under `.kody/qa-reports/` — that path is gitignored.
+
+# Target
+
+Base URL: `{{args.url}}`
+{{#args.scope}}Focus: **{{args.scope}}**{{/args.scope}}
+{{^args.scope}}Focus: broad smoke across discovered routes.{{/args.scope}}
+{{#args.authProfile}}Auth: a saved Playwright `storageState.json` is available at `{{args.authProfile}}`. Pass it to `mcp__playwright__browser_navigate` via the `storageState` parameter so the session starts pre-authenticated.{{/args.authProfile}}
+{{^args.authProfile}}Auth: log in fresh using credentials from the QA guide if needed.{{/args.authProfile}}
+
+Report destination: {{#args.issue}}existing issue #{{args.issue}} (postflight will comment on it){{/args.issue}}{{^args.issue}}a new issue (postflight will open one and label it `kody:qa-report`){{/args.issue}}.
+
+# How to browse
+
+You have the **Playwright MCP** tools (`mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`, `mcp__playwright__browser_click`, `mcp__playwright__browser_type`, `mcp__playwright__browser_take_screenshot`, etc.). These return structured accessibility snapshots — prefer them over raw screenshots when you need to reason about the DOM. Reach for screenshots when something *looks* wrong rather than *is* wrong.
+
+Before anything else, navigate to the base URL:
+
+```
+mcp__playwright__browser_navigate({ url: "{{args.url}}" })
+```
+
+If that errors (timeout, DNS, connection refused), the app is unreachable. STOP browsing, write a short report explaining the failure, and exit. Don't fabricate findings.
+
+# QA context (auto-discovered from the repo)
+
+```
+{{qaContext}}
+```
+
+# QA guide (committed in the repo — authoritative over the auto-discovery above)
+
+{{qaGuide}}
+
+{{conventionsBlock}}
+
+{{toolsUsage}}
+
+# What to do
+
+1. **Plan the session.** From the QA context, the QA guide, and the focus, build a short test matrix. For each candidate UI surface, list the user-visible behaviors worth verifying. Skip surfaces unrelated to the focus.
+
+2. **Authenticate if required.** If a route under test needs a role and you have credentials (in the QA guide or via `--auth-profile`), log in once. If credentials for a needed role are missing, note it as a gap and browse only what you can.
+
+3. **Exercise each surface.** For every UI surface in your matrix, run through the relevant states. Don't pad — apply the checklist where it actually matters:
+   - **Happy path.** The user-visible behavior the surface exists to support, end to end.
+   - **Empty state.** Zero items, no rows, no results. Is the screen meaningfully empty or just confusingly blank?
+   - **Loading.** What renders before data resolves? Skeletons? Layout shift?
+   - **Error.** Force a failure where you reasonably can — invalid input, broken nav, network throttle. Is the error visible and actionable?
+   - **Validation.** Submit forms with invalid / boundary / empty inputs. What's the feedback?
+   - **Mobile / narrow viewport.** Resize to ~375px wide. Anything cut off, overlapping, illegible?
+   - **Keyboard nav.** Tab through. Is focus visible at every step? Can a keyboard-only user reach every interactive element? Does Enter/Space activate the right control?
+   - **Destructive action.** If present (delete, archive, sign out), confirm it's gated behind a confirmation and the gate works.
+
+4. **Capture evidence.** Save screenshots that show the bug or the verified-good state under `.kody/qa-reports/<scope-slug>/<finding-slug>.png`. Reference them by relative path in the report. Don't screenshot every step — only what you need to back a finding.
+
+5. **Write the report.** Your FINAL MESSAGE must be **the entire QA report markdown, verbatim** — no preamble, no `DONE` marker, no `COMMIT_MSG` marker. The postflight reads your final message and posts it.
+
+# Required output format
+
+```
+## Verdict: PASS | CONCERNS | FAIL
+
+_QA by kody — browsed `{{args.url}}`{{#args.scope}} (focus: {{args.scope}}){{/args.scope}}_
+
+### Summary
+<2–3 sentences: what you covered and what the running app actually does>
+
+### What I browsed
+- `<route>` — <surface checked, states exercised, screenshot path if any>
+- ...
+
+### Findings
+- **[P0 | P1 | P2 | P3] <short title>** — `<route>`
+  - **Steps:** 1) … 2) … 3) …
+  - **Expected:** …
+  - **Actual:** …
+  - **Evidence:** `.kody/qa-reports/.../shot.png` (if applicable)
+- ...
+- (write "None." if you found no defects)
+
+### Gaps
+- <anything you could NOT verify and why — missing creds, unreachable surface, no test data — say "None." if you covered everything in your matrix>
+
+### Bottom line
+<one sentence>
+```
+
+# Severity rubric
+
+- **P0** — blocks core flow, data loss, security exposure, total breakage on a critical path. Verdict must be FAIL if any P0 lands.
+- **P1** — broken feature on a non-critical path, or a P0-class issue with a workaround. Verdict typically FAIL.
+- **P2** — degraded UX (visual bugs, minor a11y, confusing copy, edge-case handling). Verdict typically CONCERNS.
+- **P3** — polish (alignment, micro-copy, non-blocking inconsistency). Doesn't affect verdict on its own.
+
+# Rules
+
+- No commits. No `git` / `gh`. No edits outside `.kody/qa-reports/`.
+- Verdict **PASS** only when every UI surface you exercised behaved as the user would expect.
+- Be specific in every finding: route + concrete steps + screenshot path (or DOM snapshot reference). No "consider improving X" advice.
+- If the base URL was unreachable, the report should still be valid markdown — just say so under "Bottom line" and "Gaps", and use verdict **CONCERNS** (not FAIL — there's no defect, only an unreachable target).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",

package/templates/kody.yml

@@ -81,13 +81,16 @@ jobs:
           node-version: 22
 
       - name: Write pip cache key for LiteLLM
-        run: echo "litellm[proxy]" > "${{ runner.temp }}/kody-pip-requirements.txt"
+        run: echo "litellm[proxy]" > .kody-pip-requirements.txt
 
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
           cache: "pip"
-          cache-dependency-path: ${{ runner.temp }}/kody-pip-requirements.txt
+          cache-dependency-path: .kody-pip-requirements.txt
+
+      - name: Remove pip cache key file (avoid blocking branch switches)
+        run: rm -f .kody-pip-requirements.txt
 
       - env:
           ALL_SECRETS:   ${{ toJSON(secrets) }}