@kody-ade/kody-engine 0.4.6 → 0.4.8

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.6",
+  version: "0.4.8",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -3911,13 +3911,14 @@ function ensurePr(opts) {
     }
     return { url: existing.url, number: existing.number, draft: opts.draft, action: "updated" };
   }
+  const base = opts.baseBranch && opts.baseBranch.length > 0 ? opts.baseBranch : opts.defaultBranch;
   const args = [
     "pr",
     "create",
     "--head",
     opts.branch,
     "--base",
-    opts.defaultBranch,
+    base,
     "--title",
     title,
     "--body-file",
@@ -4045,6 +4046,7 @@ var ensurePr2 = async (ctx) => {
   const pr = ctx.data.pr;
   const targetNumber = Number(ctx.data.commentTargetNumber ?? 0);
   const title = issue?.title ?? pr?.title ?? `kody changes`;
+  const baseBranch = ctx.data.baseBranch;
   try {
     const result = ensurePr({
       branch,
@@ -4055,6 +4057,7 @@ var ensurePr2 = async (ctx) => {
       failureReason: isFailure ? failureReason : void 0,
       changedFiles,
       agentSummary: ctx.data.prSummary,
+      baseBranch,
       cwd: ctx.cwd
     });
     ctx.output.prUrl = result.url;
@@ -4332,7 +4335,7 @@ function mergeBase(baseBranch, cwd) {
     return "error";
   }
 }
-function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd) {
+function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd, baseBranch) {
   const branchName = deriveBranchName(issueNumber, title);
   const current = getCurrentBranch(cwd);
   if (current === branchName) {
@@ -4360,8 +4363,16 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd) {
     return { branch: branchName, created: false };
   } catch {
   }
+  let forkPoint = defaultBranch;
+  if (baseBranch && baseBranch !== defaultBranch) {
+    try {
+      git2(["rev-parse", "--verify", `origin/${baseBranch}`], cwd);
+      forkPoint = baseBranch;
+    } catch {
+    }
+  }
   try {
-    git2(["checkout", "-b", branchName, `origin/${defaultBranch}`], cwd);
+    git2(["checkout", "-b", branchName, `origin/${forkPoint}`], cwd);
   } catch {
     git2(["checkout", "-b", branchName], cwd);
   }
@@ -6507,8 +6518,17 @@ var runFlow = async (ctx) => {
   ctx.data.issue = issue;
   ctx.data.commentTargetType = "issue";
   ctx.data.commentTargetNumber = issueNumber;
+  const baseRaw = ctx.args.base;
+  const base = resolveBaseOverride(baseRaw);
+  if (baseRaw && !base) {
+    process.stderr.write(`[kody runFlow] ignoring --base "${baseRaw}" (must match /^goal-[a-z0-9-]+$/)
+`);
+  }
+  if (base) {
+    ctx.data.baseBranch = base;
+  }
   try {
-    const branchInfo = ensureFeatureBranch(issueNumber, issue.title, ctx.config.git.defaultBranch, ctx.cwd);
+    const branchInfo = ensureFeatureBranch(issueNumber, issue.title, ctx.config.git.defaultBranch, ctx.cwd, base ?? void 0);
     ctx.data.branch = branchInfo.branch;
   } catch (err) {
     if (err instanceof UncommittedChangesError) {
@@ -6530,6 +6550,10 @@ function tryPost(issueNumber, body, cwd) {
   } catch {
   }
 }
+function resolveBaseOverride(value) {
+  if (!value) return null;
+  return /^goal-[a-z0-9-]+$/.test(value) ? value : null;
+}
 
 // src/scripts/saveTaskState.ts
 var saveTaskState = async (ctx, profile) => {

package/dist/executables/fix/prompt.md

@@ -26,7 +26,7 @@ If a prior-art block is present above, scan it before editing — those are earl
 # Required steps
 1. **Extract** every actionable item from the feedback. A structured review uses headings like `### Concerns`, `### Suggestions`, and `### Bugs`; each bullet under those headings is a distinct item. `### Strengths`, `### Summary`, and `### Bottom line` are NOT items — skip them. If the feedback has no headings (plain inline feedback), treat the whole feedback as one item.
 2. **Number each item** internally (Item 1, Item 2, …). You will account for every one of them in your final message below.
-3. **Research** — read only what's needed to act on the items. Make the minimum edits required to implement each one. If the feedback or PR body links to external URLs (reproduction sites, bug recordings, spec pages), use the **Playwright MCP** tools (`mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`) to load them — do not rely on your interpretation of the URL alone.
+3. **Research** — read only what's needed to act on the items. Make the minimum edits required to implement each one. If the feedback or PR body links to external **non-GitHub** URLs (reproduction sites, bug recordings, spec pages), use the **Playwright MCP** tools (`mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`) to load them — do not rely on your interpretation of the URL alone. Do NOT open GitHub URLs (issues, PRs, repo files, gists) in Playwright — the browser session is anonymous and will 404 on private repos. Issue/PR context is already in this prompt; for anything else on GitHub, use the `gh` CLI via Bash.
 
    **Research floor (MUST be met before any Edit/Write):**
    - Read the **full** contents of every file you intend to change.

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

@@ -41,6 +41,35 @@ 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
+
   # Run the tick. Top-level kody invocation is `kody <executable>` —
   # there's no `dispatch` subcommand. A non-zero exit logs and continues
   # so one stuck goal doesn't starve the rest of the schedule.

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

@@ -5,17 +5,24 @@
 #
 # Inputs (env, set by the executor):
 #   KODY_ARG_GOAL   the goal id (directory name under .kody/goals/)
+#   KODY_CFG_GIT_DEFAULTBRANCH  the repo's default branch (usually main)
 #
 # What it does, per tick:
-#   1. Read .kody/goals/<id>/state.json. If missing or state != "active", exit.
-#   2. List issues with label `goal:<id>`.
-#   3. If every such issue is closed → set state=done, completedAt=now,
-#      commit + push state.json, exit.
-#   4. Otherwise pick the lowest-numbered open issue without label
-#      `goal-runner:dispatched`. Dispatch `@kody` on it (one new task per tick),
-#      add the label so we don't re-dispatch on the next tick.
-#   5. Bump updatedAt and commit state.json (cheap, but lets the engine
-#      track per-tick activity in the repo history).
+#   1. Read .kody/goals/<id>/state.json. If missing or state == "abandoned",
+#      run cleanup (close goal PR, close open tasks) and set state=closed.
+#   2. If state != "active", exit.
+#   3. List issues with label `goal:<id>`.
+#   4. If every such issue is closed → set state=done, open final goal-<id> →
+#      default-branch PR (if not already open), commit + push state.json.
+#   5. SERIALIZE: if any open issue still has the `goal-runner:dispatched`
+#      label, stay idle. We dispatch the next task only after the previous
+#      one has merged (issue closure follows PR merge via `Closes #N`).
+#   6. If any issue carries `goal-runner:failed`, stay idle (a human must
+#      unblock by removing the label or closing the issue).
+#   7. Otherwise pick the lowest-numbered open issue without
+#      `goal-runner:dispatched`. Comment `@kody --base goal-<id>` on it
+#      and add the label so we don't re-dispatch on the next tick.
+#   8. Bump updatedAt and commit state.json (cheap audit trail).
 #
 # Stdout signals:
 #   KODY_SKIP_AGENT=true   — always; this is a no-agent flow.
@@ -24,6 +31,8 @@
 set -euo pipefail
 
 goal_id="${KODY_ARG_GOAL:-}"
+default_branch="${KODY_CFG_GIT_DEFAULTBRANCH:-main}"
+
 if [ -z "$goal_id" ]; then
   echo "KODY_REASON=missing --goal"
   echo "KODY_SKIP_AGENT=true"
@@ -39,6 +48,10 @@ fi
 
 state_dir=".kody/goals/${goal_id}"
 state_file="${state_dir}/state.json"
+goal_branch="goal-${goal_id}"
+label="goal:${goal_id}"
+dispatched_label="goal-runner:dispatched"
+failed_label="goal-runner:failed"
 
 if [ ! -f "$state_file" ]; then
   echo "[goal-tick] no state file at $state_file — nothing to tick"
@@ -46,30 +59,106 @@ if [ ! -f "$state_file" ]; then
   exit 0
 fi
 
-# Read current state. python3 is already required by other shell executables
-# (e.g. release-prepare.sh), so we lean on it for JSON read/write.
+# Read current state.
 state=$(python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('state',''))" "$state_file")
 
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+set_state_field() {
+  # set_state_field <key> <value>  — value is treated as a JSON string.
+  python3 - "$state_file" "$1" "$2" <<'PY'
+import json, sys
+from datetime import datetime, timezone
+path, key, value = sys.argv[1], sys.argv[2], sys.argv[3]
+with open(path) as f:
+    s = json.load(f)
+s[key] = value
+s["updatedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+with open(path, "w") as f:
+    json.dump(s, f, indent=2)
+    f.write("\n")
+PY
+}
+
+bump_updated_at() {
+  python3 - "$state_file" <<'PY'
+import json, sys
+from datetime import datetime, timezone
+path = sys.argv[1]
+with open(path) as f:
+    s = json.load(f)
+s["updatedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+with open(path, "w") as f:
+    json.dump(s, f, indent=2)
+    f.write("\n")
+PY
+}
+
+commit_state() {
+  # commit_state <message>  — best-effort commit + push.
+  git add "$state_file"
+  if ! git diff --cached --quiet; then
+    git commit -m "$1" --quiet
+    git push --quiet || echo "[goal-tick] push failed (will retry next tick)"
+  fi
+}
+
+ensure_label() {
+  # ensure_label <name> <color> <description> — best-effort, never fails the tick.
+  gh label create "$1" --color "$2" --description "$3" --force >/dev/null 2>&1 || true
+}
+
+list_goal_issues() {
+  # Up to 100 goal-labelled issues. PRs filtered out.
+  gh api \
+    "repos/{owner}/{repo}/issues?labels=${label}&state=all&per_page=100" \
+    --jq '[.[] | select(.pull_request == null) | {number, state: (.state | ascii_upcase), labels: [.labels[].name]}]'
+}
+
+# ── Cleanup path: state == abandoned ──────────────────────────────────────────
+
+if [ "$state" = "abandoned" ]; then
+  echo "[goal-tick] $goal_id is abandoned — running cleanup"
+
+  # Close any open task issues with a brief note.
+  issues_json=$(list_goal_issues)
+  echo "$issues_json" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+for i in data:
+    if i['state'] == 'OPEN':
+        print(i['number'])
+" | while read -r num; do
+    [ -n "$num" ] || continue
+    gh issue comment "$num" --body "_Goal abandoned — closing this task without dispatch._" >/dev/null 2>&1 || true
+    gh issue close "$num" --reason "not planned" >/dev/null 2>&1 || true
+  done
+
+  # Close the goal PR if one is open.
+  goal_pr=$(gh pr list --head "$goal_branch" --state open --json number --jq '.[0].number // empty' 2>/dev/null || echo "")
+  if [ -n "$goal_pr" ]; then
+    gh pr close "$goal_pr" --comment "_Goal abandoned by operator — closing without merge._" >/dev/null 2>&1 || true
+  fi
+
+  set_state_field "state" "closed"
+  commit_state "chore(goals): abandon ${goal_id} (cleanup complete)"
+  echo "KODY_SKIP_AGENT=true"
+  exit 0
+fi
+
 if [ "$state" != "active" ]; then
   echo "[goal-tick] $goal_id is '$state' — skipping"
   echo "KODY_SKIP_AGENT=true"
   exit 0
 fi
 
-label="goal:${goal_id}"
-dispatched_label="goal-runner:dispatched"
+# ── Active path ───────────────────────────────────────────────────────────────
 
-# Fetch up to 100 goal-labelled issues. 100 is a soft ceiling — if a goal
-# grows past that, we'll need pagination.
-#
-# Use `gh api` (not `gh issue list --label`) because the latter chokes on
-# colons in label names, which is exactly the convention used here
-# (`goal:<id>` etc). `gh api` also lets us filter PRs out cleanly via the
-# `pull_request` field GitHub attaches to issue payloads.
-issues_json=$(gh api \
-  "repos/{owner}/{repo}/issues?labels=${label}&state=all&per_page=100" \
-  --jq '[.[] | select(.pull_request == null) | {number, state: (.state | ascii_upcase), labels: .labels}]')
+# Make sure the dedup labels exist before we read/write them.
+ensure_label "$dispatched_label" "ededed" "kody goal-runner: already dispatched this tick"
+ensure_label "$failed_label" "b60205" "kody goal-runner: task failed; needs human attention"
 
+issues_json=$(list_goal_issues)
 total=$(echo "$issues_json" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))")
 if [ "$total" = "0" ]; then
   echo "[goal-tick] no issues with label '$label' — leaving state untouched"
@@ -77,30 +166,81 @@ if [ "$total" = "0" ]; then
   exit 0
 fi
 
+# Counts.
 open_count=$(echo "$issues_json" | python3 -c "import json,sys; print(sum(1 for i in json.load(sys.stdin) if i['state']=='OPEN'))")
 
-# All done? mark goal done and commit.
+# All tasks closed → goal is done. Open the final goal-<id> → default-branch PR.
 if [ "$open_count" = "0" ]; then
-  echo "[goal-tick] all $total task(s) closed — marking goal done"
-  python3 - "$state_file" <<'PY'
+  echo "[goal-tick] all $total task(s) closed — finalising goal"
+
+  # Open the goal PR if it doesn't already exist. We only care about origin/<goal_branch>:
+  # the goal branch should exist (created by goal-scheduler). If not, log and skip
+  # PR creation but still mark state=done so the goal moves out of `active`.
+  goal_pr_url=""
+  if git ls-remote --exit-code --heads origin "$goal_branch" >/dev/null 2>&1; then
+    existing_pr=$(gh pr list --head "$goal_branch" --state open --json number,url --jq '.[0]' 2>/dev/null || echo "")
+    if [ -z "$existing_pr" ] || [ "$existing_pr" = "null" ]; then
+      title="goal: ${goal_id}"
+      body=$(printf "Final integration PR for goal **%s**.\n\nAll task issues are closed and merged into \`%s\`. Ready for review.\n" "$goal_id" "$goal_branch")
+      goal_pr_url=$(gh pr create \
+        --head "$goal_branch" \
+        --base "$default_branch" \
+        --title "$title" \
+        --body "$body" 2>/dev/null || echo "")
+    else
+      goal_pr_url=$(echo "$existing_pr" | python3 -c "import json,sys; print(json.load(sys.stdin).get('url',''))")
+    fi
+  else
+    echo "[goal-tick] goal branch ${goal_branch} not found on origin — skipping final PR"
+  fi
+
+  python3 - "$state_file" "$goal_pr_url" <<'PY'
 import json, sys
 from datetime import datetime, timezone
-path = sys.argv[1]
+path, pr_url = sys.argv[1], sys.argv[2]
 with open(path) as f:
     s = json.load(f)
 now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
 s["state"] = "done"
 s["completedAt"] = now
 s["updatedAt"] = now
+if pr_url:
+    s["goalPrUrl"] = pr_url
 with open(path, "w") as f:
     json.dump(s, f, indent=2)
     f.write("\n")
 PY
-  git add "$state_file"
-  if ! git diff --cached --quiet; then
-    git commit -m "chore(goals): mark $goal_id done" --quiet
-    git push --quiet || echo "[goal-tick] push failed (will retry next tick)"
-  fi
+  commit_state "chore(goals): mark $goal_id done"
+  echo "KODY_SKIP_AGENT=true"
+  exit 0
+fi
+
+# Failure gate: any task carrying the failed label means a human must intervene.
+failed_count=$(echo "$issues_json" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+print(sum(1 for i in data if 'goal-runner:failed' in i['labels']))
+")
+if [ "$failed_count" != "0" ]; then
+  echo "[goal-tick] $failed_count failed task(s) — staying idle until cleared"
+  bump_updated_at
+  commit_state "chore(goals): tick $goal_id (blocked by failed task)"
+  echo "KODY_SKIP_AGENT=true"
+  exit 0
+fi
+
+# Serialize: if any dispatched task is still open, wait. The previous task is
+# still merging. We dispatch the next one only after closure (which happens on
+# PR merge into the goal branch via `Closes #N`).
+in_flight=$(echo "$issues_json" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+print(sum(1 for i in data if i['state'] == 'OPEN' and 'goal-runner:dispatched' in i['labels']))
+")
+if [ "$in_flight" != "0" ]; then
+  echo "[goal-tick] $in_flight task(s) in flight — waiting for current task to merge into ${goal_branch}"
+  bump_updated_at
+  commit_state "chore(goals): tick $goal_id (waiting for in-flight task)"
   echo "KODY_SKIP_AGENT=true"
   exit 0
 fi
@@ -112,44 +252,25 @@ data = json.load(sys.stdin)
 opens = [
     i for i in data
     if i['state'] == 'OPEN'
-    and 'goal-runner:dispatched' not in [l['name'] for l in i.get('labels', [])]
+    and 'goal-runner:dispatched' not in i['labels']
 ]
 opens.sort(key=lambda x: x['number'])
 print(opens[0]['number'] if opens else '')
 ")
 
 if [ -z "$next_issue" ]; then
-  echo "[goal-tick] all open tasks already dispatched — waiting for them to complete"
-  # Bump updatedAt so the dashboard can show "last ticked at" without parsing logs.
-  python3 - "$state_file" <<'PY'
-import json, sys
-from datetime import datetime, timezone
-path = sys.argv[1]
-with open(path) as f:
-    s = json.load(f)
-s["updatedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-with open(path, "w") as f:
-    json.dump(s, f, indent=2)
-    f.write("\n")
-PY
-  git add "$state_file"
-  if ! git diff --cached --quiet; then
-    git commit -m "chore(goals): tick $goal_id (idle)" --quiet
-    git push --quiet || echo "[goal-tick] push failed (will retry next tick)"
-  fi
+  echo "[goal-tick] no undispatched open task — idle"
+  bump_updated_at
+  commit_state "chore(goals): tick $goal_id (idle)"
   echo "KODY_SKIP_AGENT=true"
   exit 0
 fi
 
-echo "[goal-tick] dispatching @kody on task #$next_issue"
-gh issue comment "$next_issue" --body "@kody"
-# Ensure the dedup label exists in the repo. It lives outside the `kody:`
-# namespace so `ensureLabels` doesn't create it at init time, and a missing
-# label silently swallowed here would re-dispatch the same issue every tick.
-gh label create "$dispatched_label" --color ededed --description "kody goal-runner: already dispatched this tick" --force >/dev/null 2>&1 || true
+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"
 
-# Bump updatedAt so the file changes (cheap audit trail in git log).
+# Bump updatedAt + record last dispatched issue.
 python3 - "$state_file" "$next_issue" <<'PY'
 import json, sys
 from datetime import datetime, timezone
@@ -163,11 +284,7 @@ with open(path, "w") as f:
     json.dump(s, f, indent=2)
     f.write("\n")
 PY
-git add "$state_file"
-if ! git diff --cached --quiet; then
-  git commit -m "chore(goals): dispatched #${next_issue} for ${goal_id}" --quiet
-  git push --quiet || echo "[goal-tick] push failed (will retry next tick)"
-fi
+commit_state "chore(goals): dispatched #${next_issue} for ${goal_id}"
 
 echo "KODY_SKIP_AGENT=true"
 exit 0

package/dist/executables/run/profile.json

@@ -9,6 +9,13 @@
       "type": "int",
       "required": true,
       "describe": "GitHub issue number to implement."
+    },
+    {
+      "name": "base",
+      "flag": "--base",
+      "type": "string",
+      "required": false,
+      "describe": "Optional base branch override. Must match /^goal-[a-z0-9-]+$/; used by goal-tick so the feature branch forks from the shared goal branch and the PR targets it."
     }
   ],
   "claudeCode": {

package/package.json

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