@kody-ade/kody-engine 0.4.13 → 0.4.14

package/dist/executables/goal-scheduler/scheduler.sh

@@ -41,34 +41,13 @@ for state_file in "${state_files[@]}"; do
   active=$((active + 1))
   echo "[goal-scheduler] → tick $goal_id"
 
-  # Ensure the shared goal branch exists on origin before we tick. This is
-  # the integration target for every task PR under this goal. Idempotent:
-  # if origin/goal-<id> already exists we skip. We deliberately create from
-  # the latest origin/<defaultBranch> so the goal branch starts from a
-  # known-clean base; subsequent task PRs build on top.
-  goal_branch="goal-${goal_id}"
-  default_branch="${KODY_CFG_GIT_DEFAULTBRANCH:-main}"
-
-  # Best-effort fetch so origin refs are fresh.
-  git fetch origin --quiet 2>/dev/null || true
-
-  if git rev-parse --verify --quiet "refs/remotes/origin/${goal_branch}" >/dev/null 2>&1; then
-    echo "[goal-scheduler] origin/${goal_branch} already exists — leaving as-is"
-  else
-    if ! git rev-parse --verify --quiet "refs/remotes/origin/${default_branch}" >/dev/null 2>&1; then
-      echo "[goal-scheduler] cannot create goal branch: origin/${default_branch} missing"
-    else
-      echo "[goal-scheduler] creating origin/${goal_branch} from origin/${default_branch}"
-      # Push a new ref directly without checking it out — avoids touching the
-      # working tree, which other ticks/scripts in this same scheduler run
-      # may rely on. Failures here are logged and we proceed; goal-tick will
-      # still dispatch task issues, and ensureFeatureBranch will fall back to
-      # forking from defaultBranch when origin/goal-<id> is absent.
-      if ! git push origin "refs/remotes/origin/${default_branch}:refs/heads/${goal_branch}" --quiet 2>&1; then
-        echo "[goal-scheduler] push of ${goal_branch} failed (will retry next tick)"
-      fi
-    fi
-  fi
+  # NOTE: the shared goal branch is created lazily by goal-tick at the moment
+  # it's about to dispatch the first task. Goals whose ticks never dispatch
+  # (e.g. all tasks closed as won't-fix, or every task carries goal-runner:failed)
+  # never spawn an orphan goal-<id> ref on origin. The trade-off vs. the prior
+  # eager creation: the goal branch's base is "origin/<defaultBranch> at first
+  # dispatch" rather than "origin/<defaultBranch> at goal activation", which
+  # is better for short-lived QA-style goals where main may have moved on.
 
   # Run the tick. Top-level kody invocation is `kody <executable>` —
   # there's no `dispatch` subcommand. A non-zero exit logs and continues

package/dist/executables/goal-tick/tick.sh

@@ -266,6 +266,26 @@ if [ -z "$next_issue" ]; then
   exit 0
 fi
 
+# Lazy goal-branch creation: only spin up origin/goal-<id> at the moment we're
+# about to dispatch the first task. Goals whose ticks never dispatch (every
+# task closed as won't-fix, or every open task already has goal-runner:failed)
+# never produce an orphan branch on origin. Idempotent: if origin/goal-<id>
+# already exists we skip. Failure here is non-fatal — ensureFeatureBranch in
+# the dispatched run falls back to forking from defaultBranch.
+git fetch origin --quiet 2>/dev/null || true
+if git rev-parse --verify --quiet "refs/remotes/origin/${goal_branch}" >/dev/null 2>&1; then
+  echo "[goal-tick] origin/${goal_branch} already exists — leaving as-is"
+else
+  if ! git rev-parse --verify --quiet "refs/remotes/origin/${default_branch}" >/dev/null 2>&1; then
+    echo "[goal-tick] cannot create goal branch: origin/${default_branch} missing"
+  else
+    echo "[goal-tick] creating origin/${goal_branch} from origin/${default_branch}"
+    if ! git push origin "refs/remotes/origin/${default_branch}:refs/heads/${goal_branch}" --quiet 2>&1; then
+      echo "[goal-tick] push of ${goal_branch} failed — task dispatch will fall back to defaultBranch"
+    fi
+  fi
+fi
+
 echo "[goal-tick] dispatching @kody on task #$next_issue (--base $goal_branch)"
 gh issue comment "$next_issue" --body "@kody --base ${goal_branch}"
 gh issue edit "$next_issue" --add-label "$dispatched_label"

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

@@ -8,8 +8,8 @@
       "name": "url",
       "flag": "--url",
       "type": "string",
-      "required": true,
-      "describe": "Base URL the agent should browse (e.g. http://localhost:3000)."
+      "required": false,
+      "describe": "Base URL the agent should browse. Optional — resolveQaUrl preflight falls back to the goal-branch Vercel deployment (when --goal is set), then $PREVIEW_URL, then qa.fallbackUrl from kody.config.json. Errors if none resolve."
     },
     {
       "name": "scope",
@@ -18,6 +18,13 @@
       "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": "goal",
+      "flag": "--goal",
+      "type": "string",
+      "required": false,
+      "describe": "Optional kody goal id to attach findings to. When set: (1) resolveQaUrl looks up the goal-branch's latest Vercel deployment and uses its URL, (2) createQaGoal skips manifest creation and labels finding issues `goal:<id>` directly."
+    },
     {
       "name": "issue",
       "flag": "--issue",
@@ -57,7 +64,7 @@
       {
         "name": "playwright",
         "command": "npx",
-        "args": ["-y", "--package=@playwright/mcp@latest", "--", "playwright-mcp"]
+        "args": ["-y", "--package=@playwright/mcp@latest", "--", "playwright-mcp", "--headless"]
       }
     ]
   },
@@ -78,6 +85,7 @@
   "outputArtifacts": [],
   "scripts": {
     "preflight": [
+      { "script": "resolveQaUrl" },
       { "script": "discoverQaContext" },
       { "script": "loadQaGuide" },
       { "script": "loadConventions" },
@@ -85,7 +93,7 @@
       { "script": "composePrompt" }
     ],
     "postflight": [
-      { "script": "openQaIssue" }
+      { "script": "createQaGoal" }
     ]
   }
 }

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

@@ -4,13 +4,13 @@ You may write throwaway artifacts (screenshots, ad-hoc Playwright specs) under `
 
 # Target
 
-Base URL: `{{args.url}}`
+Base URL: `{{previewUrl}}` (resolved from: {{previewUrlSource}})
 {{#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}}.
+Report destination: {{#args.goal}}existing kody goal `{{args.goal}}` (each finding becomes a `goal:{{args.goal}}` task issue){{/args.goal}}{{^args.goal}}{{#args.issue}}existing issue #{{args.issue}} (postflight will comment on it){{/args.issue}}{{^args.issue}}a new kody goal (postflight will append to the goals manifest and open one task issue per finding){{/args.issue}}{{/args.goal}}.
 
 # How to browse
 
@@ -19,7 +19,7 @@ You have the **Playwright MCP** tools (`mcp__playwright__browser_navigate`, `mcp
 Before anything else, navigate to the base URL:
 
 ```
-mcp__playwright__browser_navigate({ url: "{{args.url}}" })
+mcp__playwright__browser_navigate({ url: "{{previewUrl}}" })
 ```
 
 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.
@@ -63,7 +63,7 @@ If that errors (timeout, DNS, connection refused), the app is unreachable. STOP
 ```
 ## Verdict: PASS | CONCERNS | FAIL
 
-_QA by kody — browsed `{{args.url}}`{{#args.scope}} (focus: {{args.scope}}){{/args.scope}}_
+_QA by kody — browsed `{{previewUrl}}`{{#args.scope}} (focus: {{args.scope}}){{/args.scope}}_
 
 ### Summary
 <2–3 sentences: what you covered and what the running app actually does>
@@ -86,8 +86,40 @@ _QA by kody — browsed `{{args.url}}`{{#args.scope}} (focus: {{args.scope}}){{/
 
 ### Bottom line
 <one sentence>
+
+<!-- KODY_QA_REPORT_JSON
+```json
+{
+  "findings": [
+    {
+      "severity": "P1",
+      "title": "Short imperative title — what's broken",
+      "route": "/admin/...",
+      "steps": "1. Step one\n2. Step two\n3. Step three",
+      "expected": "What should happen",
+      "actual": "What actually happens. Cite console errors / API responses / screenshots.",
+      "evidence": ".kody/qa-reports/<scope>/<finding>.png"
+    }
+  ]
+}
+```
+-->
 ```
 
+# Required: structured findings block
+
+After the "Bottom line" section, you MUST emit one machine-readable block exactly as shown in the template above. The postflight uses it to open one severity-labelled GitHub issue per finding.
+
+Rules for the JSON block:
+- Every finding listed in the human-readable "Findings" section above MUST appear in the JSON `findings` array. No more, no fewer.
+- `severity` is one of `"P0"`, `"P1"`, `"P2"`, `"P3"` — must match the prefix in the markdown.
+- `title` is a concise imperative (5–12 words). It becomes the issue title — no `[Pn]` prefix here, the postflight adds it.
+- `steps`, `expected`, `actual` are required. `route` and `evidence` are optional but include them when applicable.
+- Use `\n` literal newlines inside string values (the JSON parser will handle them).
+- If you found zero defects (verdict PASS), emit `{"findings": []}`.
+
+If you don't include this block, the postflight falls back to opening a single record-style issue. That's acceptable when there are zero findings, but for any run with defects the block is mandatory — without it, individual findings won't get triageable tickets.
+
 # Severity rubric
 
 - **P0** — blocks core flow, data loss, security exposure, total breakage on a critical path. Verdict must be FAIL if any P0 lands.

package/kody.config.schema.json

@@ -396,6 +396,17 @@
       },
       "additionalProperties": false
     },
+    "qa": {
+      "type": "object",
+      "description": "qa-engineer defaults. Used by the resolveQaUrl preflight when no explicit --url is passed and no $PREVIEW_URL env var is set.",
+      "properties": {
+        "fallbackUrl": {
+          "type": "string",
+          "description": "Fallback URL the qa-engineer should target. Typically the project's stable dev environment (e.g. 'https://dev.example.com'). No localhost defaults — CI has no localhost to fall back to."
+        }
+      },
+      "additionalProperties": false
+    },
     "devServer": {
       "type": "object",
       "description": "Dev server configuration for browser tool verification. Works with any provider (MCP or CLI-based).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,18 @@
     "templates",
     "kody.config.schema.json"
   ],
+  "scripts": {
+    "kody": "tsx bin/kody.ts",
+    "build": "tsup && node scripts/copy-assets.cjs",
+    "test": "vitest run tests/unit tests/int --no-coverage",
+    "test:e2e": "vitest run tests/e2e --no-coverage",
+    "test:all": "vitest run tests --no-coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "prepublishOnly": "pnpm build"
+  },
   "dependencies": {
     "@actions/cache": "^6.0.0",
     "@anthropic-ai/claude-agent-sdk": "0.2.119"
@@ -32,16 +44,5 @@
     "url": "git+https://github.com/aharonyaircohen/kody-engine.git"
   },
   "homepage": "https://github.com/aharonyaircohen/kody-engine",
-  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues",
-  "scripts": {
-    "kody": "tsx bin/kody.ts",
-    "build": "tsup && node scripts/copy-assets.cjs",
-    "test": "vitest run tests/unit tests/int --no-coverage",
-    "test:e2e": "vitest run tests/e2e --no-coverage",
-    "test:all": "vitest run tests --no-coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check",
-    "lint:fix": "biome check --write",
-    "format": "biome format --write"
-  }
-}
+  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues"
+}