@kody-ade/kody-engine 0.4.86 → 0.4.88

package/dist/bin/kody.js

@@ -877,7 +877,7 @@ var init_loadPriorArt = __esm({
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.86",
+  version: "0.4.88",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -3307,6 +3307,10 @@ var CONVENTIONAL_PREFIXES = [
   "build:",
   "revert:"
 ];
+var PUSH_RETRY_DELAYS_MS = [2e3, 4e3, 8e3];
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function git(args, cwd) {
   try {
     return execFileSync5("git", args, {
@@ -3424,25 +3428,28 @@ function commitAndPush(branch, agentMessage, cwd) {
     throw err;
   }
   const sha = git(["rev-parse", "HEAD"], cwd).slice(0, 7);
-  try {
-    git(["push", "-u", "origin", branch], cwd);
-    return { committed: true, pushed: true, sha, message };
-  } catch (firstErr) {
+  let pushError = "push failed (no error detail)";
+  for (let attempt = 0; attempt <= PUSH_RETRY_DELAYS_MS.length; attempt++) {
     try {
-      git(["push", "--force-with-lease", "-u", "origin", branch], cwd);
+      git(["push", "-u", "origin", branch], cwd);
       return { committed: true, pushed: true, sha, message };
-    } catch (secondErr) {
-      const tail = (secondErr instanceof Error ? secondErr.message : String(secondErr)).slice(-400);
-      const initial = firstErr instanceof Error ? firstErr.message : String(firstErr);
-      return {
-        committed: true,
-        pushed: false,
-        sha,
-        message,
-        pushError: `push failed: ${initial.slice(-200)} | force-with-lease failed: ${tail}`
-      };
+    } catch (firstErr) {
+      try {
+        git(["push", "--force-with-lease", "-u", "origin", branch], cwd);
+        return { committed: true, pushed: true, sha, message };
+      } catch (secondErr) {
+        const tail = (secondErr instanceof Error ? secondErr.message : String(secondErr)).slice(-400);
+        const initial = firstErr instanceof Error ? firstErr.message : String(firstErr);
+        pushError = `push failed: ${initial.slice(-200)} | force-with-lease failed: ${tail}`;
+        const delay = PUSH_RETRY_DELAYS_MS[attempt];
+        if (delay === void 0) break;
+        process.stderr.write(`[kody:commit] push failed (attempt ${attempt + 1}); retrying in ${delay}ms
+`);
+        sleepSync(delay);
+      }
     }
   }
+  return { committed: true, pushed: false, sha, message, pushError };
 }
 function hasCommitsAhead(branch, defaultBranch2, cwd) {
   try {
@@ -5190,6 +5197,7 @@ init_issue();
 function goalLabel(goalId) {
   return `goal:${goalId}`;
 }
+var QA_GATE_LABEL = "kody:qa-gate";
 
 // src/goal/operations.ts
 function fail(err) {
@@ -5206,7 +5214,7 @@ function listGoalIssues(goalId, cwd) {
         "api",
         `repos/{owner}/{repo}/issues?labels=${goalLabel(goalId)}&state=all&per_page=100`,
         "--jq",
-        "[.[] | select(.pull_request == null) | {number, state: (.state | ascii_upcase)}]"
+        `[.[] | select(.pull_request == null) | {number, state: (.state | ascii_upcase), isQaGate: ([.labels[].name] | any(. == "${QA_GATE_LABEL}"))}]`
       ],
       { cwd }
     );
@@ -5242,7 +5250,7 @@ function pairIssuesWithPrs(issues, openPrs) {
     const pr = prByIssue.get(i.number);
     let prState = "absent";
     if (pr) prState = pr.isDraft ? "draft" : "ready";
-    return { number: i.number, state: i.state, prState };
+    return { number: i.number, state: i.state, prState, isQaGate: i.isQaGate };
   });
 }
 function claimPrForIssue(pr, prByIssue) {
@@ -5302,21 +5310,30 @@ function closePr(prNumber, comment, cwd) {
     return fail(err);
   }
 }
-function mergePrSquash(prNumber, cwd) {
+function editPrBase(prNumber, baseBranch, cwd) {
   try {
-    gh(["pr", "merge", String(prNumber), "--squash", "--delete-branch"], { cwd });
+    gh(
+      ["api", "--method", "PATCH", `repos/{owner}/{repo}/pulls/${prNumber}`, "-f", `base=${baseBranch}`],
+      { cwd }
+    );
     return { ok: true };
   } catch (err) {
     return fail(err);
   }
 }
-function editPrBase(prNumber, baseBranch, cwd) {
+function branchContains(leafHead, candidateHead, cwd) {
+  if (leafHead === candidateHead) return { ok: true, value: true };
   try {
-    gh(
-      ["api", "--method", "PATCH", `repos/{owner}/{repo}/pulls/${prNumber}`, "-f", `base=${baseBranch}`],
+    const out = gh(
+      [
+        "api",
+        `repos/{owner}/{repo}/compare/${encodeURIComponent(leafHead)}...${encodeURIComponent(candidateHead)}`,
+        "--jq",
+        ".ahead_by"
+      ],
       { cwd }
     );
-    return { ok: true };
+    return { ok: true, value: Number.parseInt(out.trim(), 10) === 0 };
   } catch (err) {
     return fail(err);
   }
@@ -5336,17 +5353,19 @@ function derivePhase(snap) {
   if (snap.lifecycleState === "abandoned") return "abandoned";
   if (snap.lifecycleState === "closed" || snap.lifecycleState === "done") return "terminal";
   if (snap.lifecycleState === "awaiting-merge") return "awaiting-merge";
-  const hasInFlight = snap.childTasks.some((t) => t.state === "OPEN" && t.prState === "draft");
+  const tasks = snap.childTasks.filter((t) => !t.isQaGate);
+  const qaGateOpen = snap.childTasks.some((t) => t.isQaGate && t.state === "OPEN");
+  const hasInFlight = tasks.some((t) => t.state === "OPEN" && t.prState === "draft");
   if (hasInFlight) return "in-flight";
-  if (snap.childTasks.length === 0) return "idle";
-  const allDone = snap.childTasks.every((t) => t.state === "CLOSED" || t.prState === "ready");
-  if (allDone) return "all-done";
-  const dispatchable = snap.childTasks.some((t) => t.state === "OPEN" && t.prState === "absent");
+  if (tasks.length === 0) return "idle";
+  const dispatchable = tasks.some((t) => t.state === "OPEN" && t.prState === "absent");
   if (dispatchable) return "ready-to-dispatch";
+  const allDone = tasks.every((t) => t.state === "CLOSED" || t.prState === "ready");
+  if (allDone) return qaGateOpen ? "idle" : "all-done";
   return "idle";
 }
 function pickNextDispatchable(snap) {
-  return snap.childTasks.filter((t) => t.state === "OPEN" && t.prState === "absent").sort((a, b) => a.number - b.number)[0];
+  return snap.childTasks.filter((t) => !t.isQaGate && t.state === "OPEN" && t.prState === "absent").sort((a, b) => a.number - b.number)[0];
 }
 
 // src/scripts/deriveGoalPhase.ts
@@ -6926,14 +6945,23 @@ function collectExpectedTests(raw) {
 }
 
 // src/scripts/finalizeGoal.ts
+function prIssueNumbers(pr) {
+  const nums = new Set(extractClosesIssues(pr.body));
+  const headMatch = pr.headRefName.match(/^(\d+)-/);
+  if (headMatch) {
+    const n = Number.parseInt(headMatch[1], 10);
+    if (Number.isFinite(n)) nums.add(n);
+  }
+  return [...nums];
+}
 var finalizeGoal = async (ctx) => {
   const goal = ctx.data.goal;
   if (!goal) return;
-  process.stdout.write(`[goal-tick] all task(s) done \u2014 finalising goal ${goal.id}
+  process.stdout.write(`[goal-tick] all task(s) done \u2014 preparing deliverable PR for goal ${goal.id}
 `);
   const leaf = goal.leafPr;
   if (!leaf) {
-    process.stdout.write(`[goal-tick] no leaf PR \u2014 marking goal done without merge
+    process.stdout.write(`[goal-tick] no leaf PR \u2014 marking goal done without a deliverable PR
 `);
     goal.state = "done";
     return;
@@ -6951,7 +6979,7 @@ var finalizeGoal = async (ctx) => {
     }
   }
   if (leaf.isDraft) {
-    process.stdout.write(`[goal-tick] promoting draft leaf PR #${leaf.number} \u2192 ready
+    process.stdout.write(`[goal-tick] promoting draft leaf PR #${leaf.number} \u2192 ready-for-review
 `);
     const ready = markPrReady(leaf.number, ctx.cwd);
     if (!ready.ok) {
@@ -6961,22 +6989,32 @@ var finalizeGoal = async (ctx) => {
     }
   }
   process.stdout.write(
-    `[goal-tick] squash-merging leaf PR #${leaf.number} \u2192 ${goal.defaultBranch} (cumulative goal diff)
+    `[goal-tick] leaf PR #${leaf.number} is the deliverable (cumulative goal diff vs ${goal.defaultBranch}) \u2014 left open for human merge
 `
   );
-  const merged = mergePrSquash(leaf.number, ctx.cwd);
-  if (!merged.ok) {
-    process.stderr.write(`[goal-tick] finalizeGoal: mergePrSquash #${leaf.number} failed: ${merged.error}
-`);
-    return;
-  }
+  const uncarriedIssues = /* @__PURE__ */ new Set();
   const others = (goal.openTaskPrs ?? []).filter((p) => p.number !== leaf.number);
   for (const pr of others) {
-    process.stdout.write(`[goal-tick] closing intermediate stacked PR #${pr.number} (subsumed by leaf merge)
+    const contained = branchContains(leaf.headRefName, pr.headRefName, ctx.cwd);
+    if (!contained.ok || contained.value !== true) {
+      const why = contained.ok ? `commits on \`${pr.headRefName}\` are NOT reachable from the deliverable leaf \`${leaf.headRefName}\`` : `could not verify containment (${contained.error})`;
+      process.stderr.write(
+        `[goal-tick] finalizeGoal: NOT closing PR #${pr.number} \u2014 ${why}; leaving it open (broken stack)
+`
+      );
+      for (const n of prIssueNumbers(pr)) uncarriedIssues.add(n);
+      commentOnIssue(
+        pr.number,
+        `\u26A0\uFE0F _Stacked-PR finalize: this PR's commits are **not** carried by the goal's deliverable PR #${leaf.number} (the stack chain was broken). Leaving this PR open so its work isn't lost \u2014 review and land it manually._`,
+        ctx.cwd
+      );
+      continue;
+    }
+    process.stdout.write(`[goal-tick] closing intermediate stacked PR #${pr.number} (carried by deliverable leaf)
 `);
     const closed = closePr(
       pr.number,
-      `_Stacked-PR finalize: this PR's content is included in the leaf squash to \`${goal.defaultBranch}\` (#${leaf.number})._`,
+      `_Stacked-PR finalize: this PR's content is carried by the goal's single deliverable PR #${leaf.number} (open against \`${goal.defaultBranch}\`, awaiting human merge)._`,
       ctx.cwd
     );
     if (!closed.ok) {
@@ -6986,12 +7024,19 @@ var finalizeGoal = async (ctx) => {
   }
   const openIssues = (goal.childTasks ?? []).filter((t) => t.state === "OPEN");
   for (const t of openIssues) {
-    process.stdout.write(`[goal-tick] closing task issue #${t.number} (goal finalized)
+    if (uncarriedIssues.has(t.number)) {
+      process.stderr.write(
+        `[goal-tick] finalizeGoal: NOT closing task issue #${t.number} \u2014 its PR's work is not carried by the deliverable (broken stack)
+`
+      );
+      continue;
+    }
+    process.stdout.write(`[goal-tick] closing task issue #${t.number} (goal finalized \u2014 carried by PR #${leaf.number})
 `);
     const closed = closeIssue(
       t.number,
       {
-        comment: `_Goal \`${goal.id}\` finalized \u2014 leaf PR #${leaf.number} squash-merged to \`${goal.defaultBranch}\` carries this task's changes._`,
+        comment: `_Goal \`${goal.id}\` finalized \u2014 its single deliverable PR #${leaf.number} (open against \`${goal.defaultBranch}\`) carries this task's changes. Merge that PR to ship._`,
         reason: "completed"
       },
       ctx.cwd
@@ -8357,23 +8402,6 @@ QA_REPORT_POSTED=${created.url} (verdict: ${verdict})
   ctx.output.exitCode = verdict === "FAIL" ? 1 : 0;
 };
 
-// src/scripts/parkGoalForMerge.ts
-var parkGoalForMerge = async (ctx) => {
-  const goal = ctx.data.goal;
-  if (!goal) return;
-  const approved = goal.raw?.mergeApproved === true;
-  if (approved) {
-    process.stdout.write(`[goal-tick] goal ${goal.id}: merge approved \u2014 running finalize (one-shot)
-`);
-    if (goal.raw) goal.raw.mergeApproved = false;
-    return;
-  }
-  process.stdout.write(`[goal-tick] all task(s) done \u2014 parking goal ${goal.id} for manual merge (no auto-merge)
-`);
-  goal.state = "awaiting-merge";
-  goal.phase = "awaiting-merge";
-};
-
 // src/scripts/parseAgentResult.ts
 init_prompt();
 var parseAgentResult2 = async (ctx, profile, agentResult) => {
@@ -10578,7 +10606,6 @@ var preflightScripts = {
   handleAbandonedGoal,
   deriveGoalPhase,
   dispatchNextTask,
-  parkGoalForMerge,
   finalizeGoal,
   saveGoalState
 };

package/dist/executables/goal-tick/profile.json

@@ -1,7 +1,7 @@
 {
   "name": "goal-tick",
   "role": "primitive",
-  "describe": "One deterministic tick for one goal in the stacked-PR model: read .kody/goals/<id>/state.json, dispatch @kody on the next ready task (stacked on the leaf PR), or — when all tasks are done — park the goal at awaiting-merge (the dashboard Merge button later flips it back to active+mergeApproved, which lets finalize squash-merge the leaf). No agent.",
+  "describe": "One deterministic tick for one goal in the stacked-PR model: read .kody/goals/<id>/state.json, dispatch @kody on the next ready task (stacked on the leaf PR), or — when all tasks are done — finalize by preparing the leaf as a single review-ready PR (retarget to default branch, mark ready, close intermediate PRs/issues) and leave it OPEN for a human to merge. The engine never auto-merges. No agent.",
   "kind": "oneshot",
   "inputs": [
     {
@@ -51,10 +51,6 @@
         "script": "deriveGoalPhase",
         "runWhen": { "data.goal.state": "active" }
       },
-      {
-        "script": "parkGoalForMerge",
-        "runWhen": { "data.goal.phase": "all-done" }
-      },
       {
         "script": "finalizeGoal",
         "runWhen": { "data.goal.phase": "all-done" }

package/package.json

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

package/templates/workers/goal-manager.md

@@ -0,0 +1,175 @@
+# Goal Manager
+
+Autonomous manager for **manager-driven goals**. One worker, every goal:
+each tick it picks up every goal flagged `managed`, breaks it into tasks,
+lets the deterministic `goal-tick` execute them, verifies the
+end-to-end user journey with `qa-engineer`, recovers stalled tasks, and
+stops a goal only when its single deliverable PR is open and the journey
+passes. It never edits code and never merges anything.
+
+> Drop this file at `.kody/workers/goal-manager.md` in a consumer repo.
+> The `worker-scheduler` cron invokes `worker-tick` on it automatically.
+
+## Worker
+
+You coordinate goals **only** through `gh`. You do not write code, open
+PRs, or merge. Everything below is per-goal; you handle all goals in one
+tick.
+
+### 1. Discover managed goals
+
+```
+ls .kody/goals/*/state.json 2>/dev/null
+```
+
+For each, read it (`cat`). A goal is **in scope** when BOTH:
+
+- `.state == "active"`, and
+- `.managed == true` (the dashboard's "Let Kody manage this goal" toggle
+  writes this; absent/false → ignore the goal entirely).
+
+For an in-scope goal, the goal **id** is the directory name
+(`.kody/goals/<id>/state.json`). Its definition (intent + the ordered
+end-to-end user journey that defines "done") is, in priority order:
+
+1. `.journey` / `.description` / `.intent` / `.title` fields in
+   `state.json` if present, else
+2. the goal's GitHub Discussion body — if `state.json` has a
+   `discussionNumber`, fetch it:
+   `gh api graphql -f query='{repository(owner:"OWNER",name:"REPO"){discussion(number:N){body title}}}'`
+   (resolve OWNER/REPO from `gh repo view --json owner,name`).
+
+The **journey** is the acceptance test. If you cannot find any journey
+text, do NOT guess — escalate the goal (see §5) with reason
+`no-journey-defined` and skip it.
+
+### 2. Per-goal cursor
+
+Keep all per-goal progress under `data.goals[<id>]`. Each entry:
+
+```
+{ "cursor": "...", "tasks": [<issue numbers you created>],
+  "gate": <qa-gate issue number|null>, "qaRound": <int>,
+  "stall": { "<issueNumber>": { "ticks": <int>, "attempts": <int> } },
+  "lastQaTick": "<ISO>" }
+```
+
+`cursor` ∈ `new | building | qa | finalizing | done | escalated`.
+Missing entry ⇒ treat as `new`.
+
+### 3. Decompose (`cursor: new`)
+
+One-time setup for the goal:
+
+1. Ensure labels exist (idempotent — ignore "already exists"):
+   `gh label create "goal:<id>" --color 5319e7 2>/dev/null || true`
+   `gh label create "kody:qa-gate" --color b60205 2>/dev/null || true`
+   `gh label create "kody:needs-human" --color d93f0b 2>/dev/null || true`
+2. Break the goal into the **smallest correct set of sequential tasks**.
+   For each, create an issue:
+   `gh issue create --title "<task>" --label "goal:<id>" --body "<precise spec, acceptance criteria>"`
+   Record the returned issue numbers in `tasks`. Order matters — the
+   stacked-PR model builds them lowest-number first.
+3. Create the **QA gate** issue (exactly one per goal):
+   `gh issue create --title "QA gate: <id> — end-to-end journey" --label "goal:<id>" --label "kody:qa-gate" --body "<the full ordered journey, step 1 → success state>"`
+   Record its number in `gate`.
+4. Set `cursor: building`. **Do not** dispatch anything yourself —
+   `goal-tick` (its own cron) sees the new `goal:<id>` issues and drives
+   them. The open `kody:qa-gate` issue keeps the goal short of
+   `all-done`, so nothing finalizes until you close it in §4.
+
+### 4. Drive + recover (`cursor: building`)
+
+Each tick, for the goal:
+
+- Enumerate tasks:
+  `gh issue list --label "goal:<id>" --state all --json number,state,title`
+  and the PRs:
+  `gh pr list --state open --json number,headRefName,body,isDraft`.
+  A task is **done** when its issue is CLOSED or it has a ready
+  (non-draft) open PR (`Closes #<n>` in body, or head ref `^<n>-`).
+- **Stall detection** (per non-gate, non-done task):
+  - Increment `stall[n].ticks`.
+  - If the task has **no open PR** and `stall[n].ticks >= 3`: it was
+    never picked up — re-nudge: `gh issue comment <n> --body "@kody"`,
+    `stall[n].attempts += 1`, reset `stall[n].ticks = 0`.
+  - If the task has a **draft PR with no new commits** for
+    `stall[n].ticks >= 4`: comment `@kody continue` on the PR, bump
+    attempts, reset ticks.
+  - When `stall[n].attempts >= 3` for any task → escalate (§5) and set
+    `cursor: escalated`.
+  - Clear `stall[n]` once the task is done.
+- When **every non-gate task is done** → `cursor: qa`.
+
+### 4b. Verify the journey (`cursor: qa`)
+
+- Throttle: skip if `lastQaTick` is < 20 min ago (avoid stacking QA
+  runs); otherwise:
+- Trigger QA against the journey by commenting on the **gate issue**:
+  `gh issue comment <gate> --body "@kody qa-engineer --goal <id> --scope \"<the full journey text>\""`
+  Set `lastQaTick` = now, `qaRound += 1`.
+- `qa-engineer` browses the running app and files **each failure as a
+  new `goal:<id>` task issue** automatically. So on the **next** tick:
+  - If new `goal:<id>` task issues appeared after this `qaRound` (issues
+    you didn't create / not in `tasks`) → add them to `tasks`, set
+    `cursor: building` (the loop fixes them, then QA re-runs).
+  - If no new task issues and the latest `qa-engineer` report comment on
+    the gate issue is a **PASS** (read it:
+    `gh issue view <gate> --json comments`) → the journey works:
+    close the gate `gh issue close <gate> --comment "QA passed — journey verified."`,
+    set `cursor: finalizing`.
+  - If the report is ambiguous/unreachable and `qaRound >= 4` →
+    escalate (§5).
+
+### 4c. Finish (`cursor: finalizing`)
+
+With the gate closed, `goal-tick` observes `all-done`, prepares the
+**single open deliverable PR** (cumulative diff vs the default branch,
+review-ready), closes the task issues, and sets `state: "done"` in
+`state.json`. You do **not** merge — a human merges that PR.
+
+- When `state.json.state == "done"` (or the deliverable PR is open and
+  task issues are closed): post one summary comment on the gate issue or
+  the discussion linking the deliverable PR, set `cursor: done`.
+
+### 5. Escalation
+
+Escalate by: commenting the reason on the goal's most relevant artifact
+(gate issue if it exists, else the highest-numbered task issue), adding
+the `kody:needs-human` label to that issue, and setting
+`cursor: escalated`. On later ticks, re-check an escalated goal: if a
+human removed `kody:needs-human` or the blocking condition cleared,
+resume at the appropriate cursor.
+
+### 6. `cursor: done | escalated`
+
+No action. Keep the entry so you don't reprocess it. (These are per-goal;
+the **worker** is evergreen — never emit worker-level `done: true`.)
+
+## Allowed Commands
+
+`gh` only: `gh issue ...`, `gh pr ...`, `gh label ...`, `gh api ...`,
+`gh repo view`. Read-only shell (`ls`, `cat`) on the checked-out tree to
+read `.kody/goals/*/state.json`.
+
+## Restrictions
+
+- Never edit, create, or delete files in the working tree (no code, no
+  `state.json` writes — the gate is GitHub-side via the qa-gate issue).
+- Never run `git`. Never merge or close a PR. Never mark a PR ready.
+- Never `@kody` a `kody:qa-gate` issue except the one `qa-engineer`
+  trigger in §4b.
+- One QA trigger per `qaRound`; honour the 20-min throttle.
+- Do not dispatch implementation tasks yourself — only create the issues;
+  `goal-tick` dispatches. Your only `@kody` comments are stall re-nudges
+  (§4) and the `qa-engineer` trigger (§4b).
+
+## State
+
+`cursor` (worker-level): always `"managing"` (evergreen). All real
+progress lives in `data.goals[<id>]` as described in §2. `done`: always
+`false`.
+
+**Cadence guard.** If `forceRun` is false and your last tick was < 4 min
+ago (compare a `data.lastTick` ISO you maintain), emit the prior state
+unchanged and exit. Always update `data.lastTick` when you do run.