@kody-ade/kody-engine 0.2.27 → 0.2.29

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.27",
+  version: "0.2.29",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -1135,11 +1135,19 @@ function parseAgentResult(finalText) {
       commitMessage: "",
       prSummary: "",
       feedbackActions: "",
+      planDeviations: "",
       failureReason: "agent produced no final message"
     };
   const failedMatch = text.match(/(?:^|\n)\s*FAILED\s*:\s*(.+?)\s*$/s);
   if (failedMatch) {
-    return { done: false, commitMessage: "", prSummary: "", feedbackActions: "", failureReason: failedMatch[1].trim() };
+    return {
+      done: false,
+      commitMessage: "",
+      prSummary: "",
+      feedbackActions: "",
+      planDeviations: "",
+      failureReason: failedMatch[1].trim()
+    };
   }
   if (!/(^|\n)\s*DONE\b/i.test(text)) {
     return {
@@ -1147,6 +1155,7 @@ function parseAgentResult(finalText) {
       commitMessage: "",
       prSummary: "",
       feedbackActions: "",
+      planDeviations: "",
       failureReason: "no DONE or FAILED marker in agent output"
     };
   }
@@ -1155,15 +1164,24 @@ function parseAgentResult(finalText) {
   const feedbackActions = extractBlock(
     text,
     /(?:^|\n)[ \t]*FEEDBACK_ACTIONS\s*:[ \t]*\n/i,
-    /(?:^|\n)[ \t]*(?:COMMIT_MSG|PR_SUMMARY)\s*:/i
+    /(?:^|\n)[ \t]*(?:PLAN_DEVIATIONS|COMMIT_MSG|PR_SUMMARY)\s*:/i
+  );
+  let planDeviations = extractBlock(
+    text,
+    /(?:^|\n)[ \t]*PLAN_DEVIATIONS\s*:[ \t]*\n/i,
+    /(?:^|\n)[ \t]*(?:COMMIT_MSG|PR_SUMMARY|FEEDBACK_ACTIONS)\s*:/i
   );
+  if (!planDeviations) {
+    const inline = text.match(/(?:^|\n)[ \t]*PLAN_DEVIATIONS\s*:[ \t]*(.+?)[ \t]*(?:\n|$)/i);
+    if (inline) planDeviations = inline[1].trim();
+  }
   const summaryStart = text.search(/(^|\n)[ \t]*PR_SUMMARY\s*:[ \t]*\n/i);
   let prSummary = "";
   if (summaryStart !== -1) {
     const afterMarker = text.slice(summaryStart).replace(/^[\s\S]*?PR_SUMMARY\s*:[ \t]*\n/i, "");
     prSummary = afterMarker.replace(/\n\s*```\s*$/g, "").replace(/```\s*$/g, "").trim();
   }
-  return { done: true, commitMessage, prSummary, feedbackActions, failureReason: "" };
+  return { done: true, commitMessage, prSummary, feedbackActions, planDeviations, failureReason: "" };
 }
 function extractBlock(text, startMarker, endMarker) {
   const startIdx = text.search(startMarker);
@@ -2517,11 +2535,13 @@ function parseStateComment(body) {
   const beginIdx = body.indexOf(STATE_BEGIN);
   const endIdx = body.indexOf(STATE_END, beginIdx + 1);
   if (beginIdx < 0 || endIdx < 0) return emptyState();
-  const between = body.slice(beginIdx + STATE_BEGIN.length, endIdx);
-  const fenceMatch = between.match(/```json\s*([\s\S]*?)\s*```/);
-  if (!fenceMatch) return emptyState();
+  const between = body.slice(beginIdx + STATE_BEGIN.length, endIdx).trim();
+  const OPEN = "```json";
+  const CLOSE = "```";
+  if (!between.startsWith(OPEN) || !between.endsWith(CLOSE)) return emptyState();
+  const jsonStr = between.slice(OPEN.length, between.length - CLOSE.length).trim();
   try {
-    const parsed = JSON.parse(fenceMatch[1]);
+    const parsed = JSON.parse(jsonStr);
     if (parsed?.schemaVersion !== 1) return emptyState();
     return {
       schemaVersion: 1,
@@ -2682,6 +2702,7 @@ var parseAgentResult2 = async (ctx, profile, agentResult) => {
   ctx.data.commitMessage = parsed.commitMessage;
   ctx.data.prSummary = parsed.prSummary;
   ctx.data.feedbackActions = parsed.feedbackActions;
+  ctx.data.planDeviations = parsed.planDeviations;
   ctx.data.agentFailureReason = parsed.failureReason;
   ctx.data.agentOutcome = agentResult.outcome;
   ctx.data.agentError = agentResult.error;
@@ -2754,7 +2775,8 @@ var postIssueComment2 = async (ctx) => {
   }
   const failureReason = computeFailureReason2(ctx);
   const isFailure = failureReason.length > 0;
-  const successMsg = prAction === "updated" ? `\u2705 kody2 pushed to ${prUrl}` : `\u2705 kody2 PR opened: ${prUrl}`;
+  const justPushedToExistingPr = prAction === "updated" && commitResult?.committed === true;
+  const successMsg = justPushedToExistingPr ? `\u2705 kody2 pushed to ${prUrl}` : prAction === "updated" ? `\u2139\uFE0F kody2 made no changes \u2014 PR: ${prUrl}` : `\u2705 kody2 PR opened: ${prUrl}`;
   const failurePrSuffix = prUrl ? prAction === "updated" ? ` \u2014 PR: ${prUrl}` : ` \u2014 draft PR: ${prUrl}` : "";
   const msg = isFailure ? `\u26A0\uFE0F kody2 FAILED: ${truncate2(failureReason, 1500)}${failurePrSuffix}` : successMsg;
   postWith(targetType, targetNumber, msg, ctx.cwd);
@@ -2813,11 +2835,19 @@ function detectVerdict(body) {
   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 failedAction(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 = failedAction(ctx.output.reason);
     return;
   }
   if (!agentResult || agentResult.outcome !== "completed") {
@@ -2828,6 +2858,7 @@ var postReviewResult = async (ctx, _profile, agentResult) => {
     }
     ctx.output.exitCode = 1;
     ctx.output.reason = reason;
+    ctx.data.action = failedAction(reason);
     return;
   }
   const reviewBody = agentResult.finalText.trim();
@@ -2838,6 +2869,7 @@ var postReviewResult = async (ctx, _profile, agentResult) => {
     }
     ctx.output.exitCode = 1;
     ctx.output.reason = "empty review body";
+    ctx.data.action = failedAction("empty review body");
     return;
   }
   try {
@@ -2846,10 +2878,13 @@ var postReviewResult = async (ctx, _profile, agentResult) => {
     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 = failedAction(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(
     `
@@ -3156,33 +3191,108 @@ ${truncate2(r.stderr, 2e3)}
 
 // src/scripts/requireFeedbackActions.ts
 var MIN_ITEMS = 1;
+var ACTIONABLE_HEADINGS = /^#{1,6}\s+(Concerns|Suggestions|Bugs)\b/i;
+var NEXT_HEADING = /^#{1,6}\s+/;
 var requireFeedbackActions = async (ctx, profile) => {
   if (!ctx.data.agentDone) return;
   const actions = String(ctx.data.feedbackActions ?? "").trim();
   const items = countActionItems(actions);
-  if (items >= MIN_ITEMS) return;
-  const reason = actions.length === 0 ? "agent omitted required FEEDBACK_ACTIONS block \u2014 cannot verify that review feedback was addressed" : "agent FEEDBACK_ACTIONS block listed no items \u2014 cannot verify that review feedback was addressed";
+  if (items < MIN_ITEMS) {
+    fail(
+      ctx,
+      profile,
+      actions.length === 0 ? "agent omitted required FEEDBACK_ACTIONS block \u2014 cannot verify that review feedback was addressed" : "agent FEEDBACK_ACTIONS block listed no items \u2014 cannot verify that review feedback was addressed"
+    );
+    return;
+  }
+  const reviewBody = String(ctx.data.feedback ?? "");
+  const expectedItems = countActionableReviewBullets(reviewBody);
+  ctx.data.feedbackReviewItemCount = expectedItems;
+  ctx.data.feedbackAgentItemCount = items;
+  if (expectedItems > 0 && items < expectedItems) {
+    fail(
+      ctx,
+      profile,
+      `agent FEEDBACK_ACTIONS listed ${items} item(s) but the review has ${expectedItems} actionable bullet(s) under ### Concerns / ### Suggestions / ### Bugs \u2014 every review item must be accounted for`
+    );
+    return;
+  }
+};
+function fail(ctx, profile, reason) {
   ctx.data.agentDone = false;
   ctx.data.agentFailureReason = reason;
   const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
-  const failedAction = {
+  const failedAction2 = {
     type: `${modeSeg}_FAILED`,
     payload: { reason },
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
-  ctx.data.action = failedAction;
-};
+  ctx.data.action = failedAction2;
+}
 function countActionItems(block) {
   if (!block.trim()) return 0;
-  const lines = block.split("\n");
   let count = 0;
+  for (const raw of block.split("\n")) {
+    if (/^\s*[-*]\s+/.test(raw)) count++;
+  }
+  return count;
+}
+function countActionableReviewBullets(reviewBody) {
+  if (!reviewBody.trim()) return 0;
+  const lines = reviewBody.split("\n");
+  let count = 0;
+  let insideActionable = false;
   for (const raw of lines) {
-    const line = raw.trim();
-    if (/^[-*]\s+/.test(line)) count++;
+    if (ACTIONABLE_HEADINGS.test(raw)) {
+      insideActionable = true;
+      continue;
+    }
+    if (insideActionable && NEXT_HEADING.test(raw)) {
+      insideActionable = false;
+      continue;
+    }
+    if (!insideActionable) continue;
+    if (/^[-*]\s+\S/.test(raw)) count++;
   }
   return count;
 }
 
+// src/scripts/requirePlanDeviations.ts
+var requirePlanDeviations = async (ctx, profile) => {
+  if (!ctx.data.agentDone) return;
+  const artifacts = ctx.data.artifacts ?? {};
+  const planContent = (artifacts.plan ?? "").trim();
+  if (!planContent) return;
+  const raw = String(ctx.data.planDeviations ?? "").trim();
+  if (raw.length === 0) {
+    fail2(ctx, profile, "agent omitted required PLAN_DEVIATIONS block \u2014 cannot verify whether the plan was followed");
+    return;
+  }
+  if (isNoneSentinel(raw)) return;
+  const bullets = raw.split("\n").filter((l) => /^\s*[-*]\s+/.test(l));
+  if (bullets.length === 0) {
+    fail2(ctx, profile, "agent PLAN_DEVIATIONS block is not 'none' and lists no bullet items");
+    return;
+  }
+  ctx.data.planDeviationCount = bullets.length;
+};
+function isNoneSentinel(block) {
+  const stripped = block.split("\n").map((l) => l.replace(/^\s*[-*]\s*/, "").trim().toLowerCase()).filter((l) => l.length > 0);
+  if (stripped.length !== 1) return false;
+  return stripped[0] === "none";
+}
+function fail2(ctx, profile, reason) {
+  ctx.data.agentDone = false;
+  ctx.data.agentFailureReason = reason;
+  const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
+  const failedAction2 = {
+    type: `${modeSeg}_FAILED`,
+    payload: { reason },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  ctx.data.action = failedAction2;
+}
+
 // src/scripts/resolveArtifacts.ts
 var resolveArtifacts = async (ctx, profile) => {
   if (profile.inputArtifacts.length === 0) return;
@@ -3551,6 +3661,59 @@ var verify = async (ctx) => {
   }
 };
 
+// src/scripts/verifyFixAlignment.ts
+function summarizeFeedbackActions(block) {
+  const summary = { totalItems: 0, fixedItems: 0, declinedItems: 0, unparsedLines: 0 };
+  if (!block.trim()) return summary;
+  for (const raw of block.split("\n")) {
+    if (!/^\s*[-*]\s+/.test(raw)) continue;
+    const line = raw.replace(/^\s*[-*]\s*/, "").trim();
+    summary.totalItems++;
+    if (/\bfixed\s*:/i.test(line)) summary.fixedItems++;
+    else if (/\bdeclined\s*:/i.test(line)) summary.declinedItems++;
+    else summary.unparsedLines++;
+  }
+  return summary;
+}
+function makeAction2(type, payload) {
+  return { type, payload, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+var verifyFixAlignment = async (ctx, profile) => {
+  if (profile.name !== "fix") return;
+  if (ctx.skipAgent) return;
+  if (!ctx.data.agentDone) return;
+  const feedbackActions = ctx.data.feedbackActions ?? "";
+  const summary = summarizeFeedbackActions(feedbackActions);
+  ctx.data.feedbackActionsSummary = summary;
+  const committed = Boolean(ctx.data.commitResult?.committed);
+  if (summary.totalItems === 0) {
+    ctx.output.exitCode = 1;
+    ctx.output.reason = "fix produced no FEEDBACK_ACTIONS items";
+    ctx.data.agentDone = false;
+    ctx.data.action = makeAction2("FIX_FAILED", {
+      reason: ctx.output.reason,
+      feedbackActionsSummary: summary
+    });
+    return;
+  }
+  if (summary.fixedItems > 0 && !committed) {
+    ctx.output.exitCode = 1;
+    ctx.output.reason = `fix claimed ${summary.fixedItems} fixed item(s) but produced no commit`;
+    ctx.data.agentDone = false;
+    ctx.data.action = makeAction2("FIX_FAILED", {
+      reason: ctx.output.reason,
+      feedbackActionsSummary: summary
+    });
+    return;
+  }
+  if (summary.fixedItems === 0 && summary.declinedItems > 0 && !committed) {
+    ctx.data.action = makeAction2("FIX_DECLINED", {
+      feedbackActionsSummary: summary,
+      note: "agent declined all feedback items; no commit made"
+    });
+  }
+};
+
 // src/scripts/watchStalePrsFlow.ts
 function readWatchConfig(ctx) {
   const cfg = ctx.config.watch;
@@ -3671,6 +3834,7 @@ var preflightScripts = {
 var postflightScripts = {
   parseAgentResult: parseAgentResult2,
   requireFeedbackActions,
+  requirePlanDeviations,
   verify,
   checkCoverageWithRetry,
   commitAndPush: commitAndPush2,
@@ -3679,6 +3843,7 @@ var postflightScripts = {
   postPlanComment,
   postReviewResult,
   persistArtifacts,
+  verifyFixAlignment,
   writeRunSummary,
   saveTaskState
 };
@@ -4346,6 +4511,14 @@ ${CHAT_HELP}`);
 `);
     return 64;
   }
+  if (needsLitellmProxy(model)) {
+    const code = installLitellmIfNeeded(cwd);
+    if (code !== 0) {
+      process.stderr.write(`error: litellm install failed (exit ${code})
+`);
+      return 99;
+    }
+  }
   let litellm = null;
   try {
     litellm = await startLitellmIfNeeded(model, cwd);

package/dist/executables/fix/profile.json

@@ -72,6 +72,9 @@
       {
         "script": "commitAndPush"
       },
+      {
+        "script": "verifyFixAlignment"
+      },
       {
         "script": "ensurePr"
       },

package/dist/executables/review/profile.json

@@ -34,6 +34,9 @@
       {
         "script": "reviewFlow"
       },
+      {
+        "script": "loadTaskState"
+      },
       {
         "script": "loadConventions"
       },
@@ -44,6 +47,9 @@
     "postflight": [
       {
         "script": "postReviewResult"
+      },
+      {
+        "script": "saveTaskState"
       }
     ]
   }

package/dist/executables/run/profile.json

@@ -56,6 +56,9 @@
       {
         "script": "parseAgentResult"
       },
+      {
+        "script": "requirePlanDeviations"
+      },
       {
         "script": "verify"
       },

package/dist/executables/run/prompt.md

@@ -10,17 +10,20 @@ You are Kody, an autonomous engineer. Take a GitHub issue from spec to a tested
 # Existing plan (produced by `@kody2 plan`, if present)
 {{artifacts.plan}}
 
-If the plan above is non-empty, TREAT IT AS AUTHORITATIVE — follow its file list and approach rather than inventing your own. Deviate only if the plan is wrong; if you do, say so explicitly. If the plan is empty, proceed from first principles.
+If the plan above is non-empty, TREAT IT AS AUTHORITATIVE — follow its file list and approach rather than inventing your own. Deviate only if the plan is wrong; if you do, you MUST declare each deviation in the `PLAN_DEVIATIONS:` block of your final message (format below). Silent deviations are a hard failure, even if the code works. If the plan is empty, proceed from first principles and emit `PLAN_DEVIATIONS: none` in the final message.
 
 # Required steps (all in this one session — no handoff)
 1. **Research** — read the issue carefully. Use Grep/Glob/Read to investigate the codebase: locate relevant files, understand existing patterns, check related tests, identify constraints. Do not edit anything yet.
 2. **Plan** — before any Edit/Write, output a short plan (5–10 lines): what files you'll change, the approach, what could go wrong. No fluff.
 3. **Build** — Edit/Write to implement the change. Stay within the plan; if you discover the plan was wrong, briefly say so and adjust.
 4. **Verify** — run each quality command with Bash. On failure, fix the root cause and re-run. When reporting that a command passed, you MUST have just run it and seen exit code 0 in this session — do not paraphrase prior output.
-5. Your FINAL message must use this exact format (or a single `FAILED: <reason>` line on failure):
+5. Your FINAL message must use this exact format (or a single `FAILED: <reason>` line on failure). The `PLAN_DEVIATIONS:` block is REQUIRED whenever a plan was provided.
 
    ```
    DONE
+   PLAN_DEVIATIONS:
+   - <plan item> → <what you did instead> (reason: <why>)
+   - (repeat for each deviation; if you followed the plan exactly, write the single line `- none`)
    COMMIT_MSG: <conventional-commit message, e.g. "feat: add X" or "fix: handle Y">
    PR_SUMMARY:
    <2-6 short bullet points naming the files/functions/endpoints you added or modified. No marketing fluff. No restating the issue.>

package/package.json

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

package/templates/kody2.yml

@@ -76,13 +76,13 @@ jobs:
           node-version: 22
 
       - name: Write pip cache key for LiteLLM
-        run: echo "litellm[proxy]" > "$RUNNER_TEMP/kody2-pip-requirements.txt"
+        run: echo "litellm[proxy]" > .kody2-pip-requirements.txt
 
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
           cache: "pip"
-          cache-dependency-path: ${{ runner.temp }}/kody2-pip-requirements.txt
+          cache-dependency-path: .kody2-pip-requirements.txt
 
       - env:
           ALL_SECRETS:   ${{ toJSON(secrets) }}