@kody-ade/kody-engine 0.3.34 → 0.3.38

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.3.34",
+  version: "0.3.38",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -51,8 +51,8 @@ var package_default = {
 
 // src/chat-cli.ts
 import { execFileSync as execFileSync23 } from "child_process";
-import * as fs22 from "fs";
-import * as path19 from "path";
+import * as fs24 from "fs";
+import * as path21 from "path";
 
 // src/chat/events.ts
 import * as fs from "fs";
@@ -501,11 +501,39 @@ function seedInitialMessage(file, message) {
 
 // src/chat/loop.ts
 var CHAT_SYSTEM_PROMPT = [
-  "You are Kody, an AI assistant for the Kody Operations Dashboard. Reply to the user's",
-  "latest message using the full conversation below as context. Keep replies focused,",
-  "technical when appropriate, and formatted in Markdown. Use the available tools to",
-  "read repository code or execute small checks when it helps you answer \u2014 otherwise",
-  "reply directly. Do not invent file paths, commit SHAs, or command output."
+  "You are Kody, an AI assistant for the Kody Operations Dashboard. Reply to the",
+  "user's latest message using the full conversation below as context. Keep replies",
+  "focused, technical when appropriate, and formatted in Markdown.",
+  "",
+  "# Your environment and capabilities",
+  "You run inside a GitHub Actions job with a full clone of the user's repository",
+  "checked out at the current working directory. You have real tools \u2014 use them",
+  "before claiming you cannot do something. Never tell the user you lack repo,",
+  "filesystem, or GitHub access; you have all three.",
+  "",
+  "Tools you can call:",
+  "- Read, Edit, Write \u2014 full read/write access to every file in the repo (permission",
+  "  mode is acceptEdits, so writes do not require confirmation).",
+  "- Glob, Grep \u2014 search the repo by filename pattern or content.",
+  "- Bash \u2014 run any shell command in the repo. The runner has:",
+  "    - `git` (the repo is a real git checkout \u2014 `git log`, `git diff`,",
+  "      `git show`, `git blame`, `git branch`, etc. all work).",
+  "    - `gh` authenticated against this repository's GitHub via the Actions",
+  "      `GITHUB_TOKEN` (read issues, PRs, workflows, runs, comments; query the API",
+  "      with `gh api`).",
+  "    - the repo's package manager and test/build/lint tooling (npm/pnpm/yarn,",
+  "      pytest, go test, cargo, etc., whatever the project uses).",
+  "    - standard Unix utilities (curl, jq, sed, awk, find, etc.).",
+  "",
+  "# How to answer",
+  "If the user asks about repo content, code, history, issues, PRs, CI status, or",
+  "anything else knowable from the checkout or GitHub API, INVESTIGATE FIRST with",
+  "the tools above and answer from what you find. Do not say 'I don't have access'",
+  "\u2014 if you have not yet tried, try. Only fall back to a limitation statement after",
+  "a tool actually fails, and in that case quote the failing command and its error.",
+  "",
+  "Do not invent file paths, commit SHAs, line numbers, or command output. If you",
+  "cite something concrete, you must have just read or run it in this session."
 ].join("\n");
 async function runChatTurn(opts) {
   const turns = readSession(opts.sessionFile);
@@ -578,8 +606,8 @@ async function emit(sink, type, sessionId, suffix, payload) {
 
 // src/kody-cli.ts
 import { execFileSync as execFileSync22 } from "child_process";
-import * as fs21 from "fs";
-import * as path18 from "path";
+import * as fs23 from "fs";
+import * as path20 from "path";
 
 // src/dispatch.ts
 import * as fs6 from "fs";
@@ -602,30 +630,51 @@ function getExecutablesRoot() {
   }
   return candidates[0];
 }
-function listExecutables(root = getExecutablesRoot()) {
-  if (!fs5.existsSync(root)) return [];
-  const entries = fs5.readdirSync(root, { withFileTypes: true });
+function getProjectExecutablesRoot() {
+  return path5.join(process.cwd(), ".kody", "executables");
+}
+function getExecutableRoots() {
+  return [getProjectExecutablesRoot(), getExecutablesRoot()];
+}
+function listExecutables(roots = getExecutableRoots()) {
+  const rootList = typeof roots === "string" ? [roots] : roots;
+  const seen = /* @__PURE__ */ new Set();
   const out = [];
-  for (const ent of entries) {
-    if (!ent.isDirectory()) continue;
-    const profilePath = path5.join(root, ent.name, "profile.json");
-    if (fs5.existsSync(profilePath) && fs5.statSync(profilePath).isFile()) {
-      out.push({ name: ent.name, profilePath });
+  for (const root of rootList) {
+    if (!fs5.existsSync(root)) continue;
+    const entries = fs5.readdirSync(root, { withFileTypes: true });
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      if (seen.has(ent.name)) continue;
+      const profilePath = path5.join(root, ent.name, "profile.json");
+      if (fs5.existsSync(profilePath) && fs5.statSync(profilePath).isFile()) {
+        out.push({ name: ent.name, profilePath });
+        seen.add(ent.name);
+      }
     }
   }
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
-function hasExecutable(name, root = getExecutablesRoot()) {
-  if (!isSafeName(name)) return false;
-  const profilePath = path5.join(root, name, "profile.json");
-  return fs5.existsSync(profilePath) && fs5.statSync(profilePath).isFile();
+function resolveExecutable(name, roots = getExecutableRoots()) {
+  if (!isSafeName(name)) return null;
+  const rootList = typeof roots === "string" ? [roots] : roots;
+  for (const root of rootList) {
+    const profilePath = path5.join(root, name, "profile.json");
+    if (fs5.existsSync(profilePath) && fs5.statSync(profilePath).isFile()) {
+      return profilePath;
+    }
+  }
+  return null;
+}
+function hasExecutable(name, roots = getExecutableRoots()) {
+  return resolveExecutable(name, roots) !== null;
 }
 function isSafeName(name) {
   return /^[a-z][a-z0-9-]*$/.test(name) && !name.includes("..");
 }
-function getProfileInputs(name, root = getExecutablesRoot()) {
-  if (!hasExecutable(name, root)) return null;
-  const profilePath = path5.join(root, name, "profile.json");
+function getProfileInputs(name, roots = getExecutableRoots()) {
+  const profilePath = resolveExecutable(name, roots);
+  if (!profilePath) return null;
   try {
     const raw = JSON.parse(fs5.readFileSync(profilePath, "utf-8"));
     if (!raw || typeof raw !== "object" || !Array.isArray(raw.inputs)) return [];
@@ -806,8 +855,8 @@ function coerceBare(spec, value) {
 
 // src/executor.ts
 import { spawnSync } from "child_process";
-import * as fs20 from "fs";
-import * as path17 from "path";
+import * as fs22 from "fs";
+import * as path19 from "path";
 
 // src/litellm.ts
 import { execFileSync, spawn } from "child_process";
@@ -954,10 +1003,7 @@ function loadProfile(profilePath) {
     throw new ProfileError(profilePath, `kind: "scheduled" requires a "schedule" cron string`);
   }
   if (typeof r.role !== "string" || !VALID_ROLES.has(r.role)) {
-    throw new ProfileError(
-      profilePath,
-      `"role" is required and must be one of: ${[...VALID_ROLES].join(" | ")}`
-    );
+    throw new ProfileError(profilePath, `"role" is required and must be one of: ${[...VALID_ROLES].join(" | ")}`);
   }
   const role = r.role;
   let phase;
@@ -1148,7 +1194,10 @@ function parseScriptList(p, key, raw) {
   const out = [];
   for (const [i, item] of raw.entries()) {
     if (!item || typeof item !== "object") {
-      throw new ProfileError(p, `scripts.${key}[${i}] must be an object like { script, runWhen? } or { shell, runWhen? }`);
+      throw new ProfileError(
+        p,
+        `scripts.${key}[${i}] must be an object like { script, runWhen? } or { shell, runWhen? }`
+      );
     }
     const r = item;
     const hasScript = typeof r.script === "string" && r.script.length > 0;
@@ -1157,7 +1206,10 @@ function parseScriptList(p, key, raw) {
       throw new ProfileError(p, `scripts.${key}[${i}] cannot set both "script" and "shell" \u2014 pick one`);
     }
     if (!hasScript && !hasShell) {
-      throw new ProfileError(p, `scripts.${key}[${i}] must set "script" (registered TS function) or "shell" (filename in executable dir)`);
+      throw new ProfileError(
+        p,
+        `scripts.${key}[${i}] must set "script" (registered TS function) or "shell" (filename in executable dir)`
+      );
     }
     const entry = {};
     if (hasScript) entry.script = r.script;
@@ -2065,11 +2117,11 @@ var diagMcp = async (_ctx) => {
   process.stderr.write(`[kody diag] chromium present: ${hasChromium ? "yes" : "no"}
 `);
   try {
-    const v = execFileSync6(
-      "npx",
-      ["-y", "--package=@playwright/mcp@latest", "--", "playwright-mcp", "--version"],
-      { stdio: "pipe", timeout: 6e4, encoding: "utf8" }
-    ).trim();
+    const v = execFileSync6("npx", ["-y", "--package=@playwright/mcp@latest", "--", "playwright-mcp", "--version"], {
+      stdio: "pipe",
+      timeout: 6e4,
+      encoding: "utf8"
+    }).trim();
     process.stderr.write(`[kody diag] @playwright/mcp version: ${v}
 `);
   } catch (e) {
@@ -2245,7 +2297,9 @@ function walkApiRoutes(dir, prefix, cwd, out) {
   if (routeFile) {
     try {
       const content = fs14.readFileSync(path13.join(dir, routeFile.name), "utf-8").slice(0, 5e3);
-      const methods = HTTP_METHODS.filter((m) => new RegExp(`export\\s+(?:async\\s+)?function\\s+${m}\\b`).test(content));
+      const methods = HTTP_METHODS.filter(
+        (m) => new RegExp(`export\\s+(?:async\\s+)?function\\s+${m}\\b`).test(content)
+      );
       if (methods.length > 0) {
         out.push({
           path: prefix,
@@ -2620,6 +2674,64 @@ function parsePr(url) {
   return Number.isFinite(n) ? n : null;
 }
 
+// src/scripts/dispatchMissionFileTicks.ts
+import * as fs16 from "fs";
+import * as path15 from "path";
+var dispatchMissionFileTicks = async (ctx, _profile, args) => {
+  ctx.skipAgent = true;
+  const targetExecutable = String(args?.targetExecutable ?? "");
+  if (!targetExecutable) {
+    throw new Error("dispatchMissionFileTicks: `with.targetExecutable` is required");
+  }
+  const missionsDir = String(args?.missionsDir ?? ".kody/missions");
+  const slugArg = String(args?.slugArg ?? "mission");
+  const slugs = listMissionSlugs(path15.join(ctx.cwd, missionsDir));
+  ctx.data.missionSlugCount = slugs.length;
+  if (slugs.length === 0) {
+    process.stdout.write(`[missions] no mission files in ${missionsDir}
+`);
+    return;
+  }
+  process.stdout.write(`[missions] ticking ${slugs.length} mission(s) via ${targetExecutable}
+`);
+  const results = [];
+  for (const slug of slugs) {
+    process.stdout.write(`[missions] \u2192 tick ${slug}
+`);
+    try {
+      const out = await runExecutable(targetExecutable, {
+        cliArgs: { [slugArg]: slug },
+        cwd: ctx.cwd,
+        config: ctx.config,
+        verbose: ctx.verbose,
+        quiet: ctx.quiet
+      });
+      results.push({ slug, exitCode: out.exitCode, reason: out.reason });
+      if (out.exitCode !== 0) {
+        process.stderr.write(`[missions] tick ${slug} failed (exit ${out.exitCode}): ${out.reason ?? ""}
+`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[missions] tick ${slug} crashed: ${msg}
+`);
+      results.push({ slug, exitCode: 99, reason: msg });
+    }
+  }
+  ctx.data.missionTickResults = results;
+  ctx.output.exitCode = 0;
+};
+function listMissionSlugs(absDir) {
+  if (!fs16.existsSync(absDir)) return [];
+  let entries;
+  try {
+    entries = fs16.readdirSync(absDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name.replace(/\.md$/, "")).filter((slug) => slug.length > 0 && !slug.startsWith("_") && !slug.startsWith(".")).sort();
+}
+
 // src/issue.ts
 import { execFileSync as execFileSync8 } from "child_process";
 var API_TIMEOUT_MS4 = 3e4;
@@ -2808,10 +2920,9 @@ var dispatchMissionTicks = async (ctx, _profile, args) => {
 function listIssuesByLabel(label, cwd) {
   let raw = "";
   try {
-    raw = gh2(
-      ["issue", "list", "--state", "open", "--label", label, "--limit", "100", "--json", "number,title"],
-      { cwd }
-    );
+    raw = gh2(["issue", "list", "--state", "open", "--label", label, "--limit", "100", "--json", "number,title"], {
+      cwd
+    });
   } catch {
     return [];
   }
@@ -3056,10 +3167,7 @@ function ensureLabels(cwd) {
 }
 function getIssueLabels(issueNumber, cwd) {
   try {
-    const output = gh2(
-      ["issue", "view", String(issueNumber), "--json", "labels", "--jq", ".labels[].name"],
-      { cwd }
-    );
+    const output = gh2(["issue", "view", String(issueNumber), "--json", "labels", "--jq", ".labels[].name"], { cwd });
     return output.split("\n").filter(Boolean);
   } catch {
     return [];
@@ -3083,10 +3191,8 @@ function createLabelInRepo(spec, cwd) {
 function setKodyLabel(issueNumber, spec, cwd) {
   const target = spec.label;
   if (!target.startsWith(KODY_NAMESPACE)) {
-    process.stderr.write(
-      `[kody] setKodyLabel: refusing to set non-kody label "${target}"
-`
-    );
+    process.stderr.write(`[kody] setKodyLabel: refusing to set non-kody label "${target}"
+`);
     return;
   }
   const targetGroup = groupOf(target);
@@ -3112,10 +3218,8 @@ function setKodyLabel(issueNumber, spec, cwd) {
         return;
       }
     }
-    process.stderr.write(
-      `[kody] setKodyLabel: failed to add ${target} on #${issueNumber}: ${errMsg(err)}
-`
-    );
+    process.stderr.write(`[kody] setKodyLabel: failed to add ${target} on #${issueNumber}: ${errMsg(err)}
+`);
   }
 }
 function looksLikeMissingLabel(err) {
@@ -3284,7 +3388,7 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd) {
 
 // src/gha.ts
 import { execFileSync as execFileSync11 } from "child_process";
-import * as fs16 from "fs";
+import * as fs17 from "fs";
 function getRunUrl() {
   const server = process.env.GITHUB_SERVER_URL;
   const repo = process.env.GITHUB_REPOSITORY;
@@ -3295,10 +3399,10 @@ function getRunUrl() {
 function reactToTriggerComment(cwd) {
   if (process.env.GITHUB_EVENT_NAME !== "issue_comment") return;
   const eventPath = process.env.GITHUB_EVENT_PATH;
-  if (!eventPath || !fs16.existsSync(eventPath)) return;
+  if (!eventPath || !fs17.existsSync(eventPath)) return;
   let event = null;
   try {
-    event = JSON.parse(fs16.readFileSync(eventPath, "utf-8"));
+    event = JSON.parse(fs17.readFileSync(eventPath, "utf-8"));
   } catch {
     return;
   }
@@ -3538,22 +3642,22 @@ function tryPostPr2(prNumber, body, cwd) {
 
 // src/scripts/initFlow.ts
 import { execFileSync as execFileSync13 } from "child_process";
-import * as fs18 from "fs";
-import * as path16 from "path";
+import * as fs19 from "fs";
+import * as path17 from "path";
 
 // src/scripts/loadQaGuide.ts
-import * as fs17 from "fs";
-import * as path15 from "path";
+import * as fs18 from "fs";
+import * as path16 from "path";
 var QA_GUIDE_REL_PATH = ".kody/qa-guide.md";
 var loadQaGuide = async (ctx) => {
-  const full = path15.join(ctx.cwd, QA_GUIDE_REL_PATH);
-  if (!fs17.existsSync(full)) {
+  const full = path16.join(ctx.cwd, QA_GUIDE_REL_PATH);
+  if (!fs18.existsSync(full)) {
     ctx.data.qaGuide = "";
     ctx.data.qaGuidePath = "";
     return;
   }
   try {
-    ctx.data.qaGuide = fs17.readFileSync(full, "utf-8");
+    ctx.data.qaGuide = fs18.readFileSync(full, "utf-8");
     ctx.data.qaGuidePath = QA_GUIDE_REL_PATH;
   } catch {
     ctx.data.qaGuide = "";
@@ -3563,9 +3667,9 @@ var loadQaGuide = async (ctx) => {
 
 // src/scripts/initFlow.ts
 function detectPackageManager(cwd) {
-  if (fs18.existsSync(path16.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs18.existsSync(path16.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs18.existsSync(path16.join(cwd, "bun.lockb"))) return "bun";
+  if (fs19.existsSync(path17.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs19.existsSync(path17.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs19.existsSync(path17.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function qualityCommandsFor(pm) {
@@ -3687,33 +3791,33 @@ function performInit(cwd, force) {
   const pm = detectPackageManager(cwd);
   const ownerRepo = detectOwnerRepo(cwd);
   const defaultBranch = defaultBranchFromGit(cwd);
-  const configPath = path16.join(cwd, "kody.config.json");
-  if (fs18.existsSync(configPath) && !force) {
+  const configPath = path17.join(cwd, "kody.config.json");
+  if (fs19.existsSync(configPath) && !force) {
     skipped.push("kody.config.json");
   } else {
     const cfg = makeConfig(pm, ownerRepo, defaultBranch);
-    fs18.writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}
+    fs19.writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}
 `);
     wrote.push("kody.config.json");
   }
-  const workflowDir = path16.join(cwd, ".github", "workflows");
-  const workflowPath = path16.join(workflowDir, "kody.yml");
-  if (fs18.existsSync(workflowPath) && !force) {
+  const workflowDir = path17.join(cwd, ".github", "workflows");
+  const workflowPath = path17.join(workflowDir, "kody.yml");
+  if (fs19.existsSync(workflowPath) && !force) {
     skipped.push(".github/workflows/kody.yml");
   } else {
-    fs18.mkdirSync(workflowDir, { recursive: true });
-    fs18.writeFileSync(workflowPath, WORKFLOW_TEMPLATE);
+    fs19.mkdirSync(workflowDir, { recursive: true });
+    fs19.writeFileSync(workflowPath, WORKFLOW_TEMPLATE);
     wrote.push(".github/workflows/kody.yml");
   }
-  const hasUi = fs18.existsSync(path16.join(cwd, "src/app")) || fs18.existsSync(path16.join(cwd, "app")) || fs18.existsSync(path16.join(cwd, "pages"));
+  const hasUi = fs19.existsSync(path17.join(cwd, "src/app")) || fs19.existsSync(path17.join(cwd, "app")) || fs19.existsSync(path17.join(cwd, "pages"));
   if (hasUi) {
-    const qaGuidePath = path16.join(cwd, QA_GUIDE_REL_PATH);
-    if (fs18.existsSync(qaGuidePath) && !force) {
+    const qaGuidePath = path17.join(cwd, QA_GUIDE_REL_PATH);
+    if (fs19.existsSync(qaGuidePath) && !force) {
       skipped.push(QA_GUIDE_REL_PATH);
     } else {
-      fs18.mkdirSync(path16.dirname(qaGuidePath), { recursive: true });
+      fs19.mkdirSync(path17.dirname(qaGuidePath), { recursive: true });
       const discovery = runQaDiscovery(cwd);
-      fs18.writeFileSync(qaGuidePath, generateQaGuideTemplate(discovery));
+      fs19.writeFileSync(qaGuidePath, generateQaGuideTemplate(discovery));
       wrote.push(QA_GUIDE_REL_PATH);
     }
   }
@@ -3725,12 +3829,12 @@ function performInit(cwd, force) {
       continue;
     }
     if (profile.kind !== "scheduled" || !profile.schedule) continue;
-    const target = path16.join(workflowDir, `kody-${exe.name}.yml`);
-    if (fs18.existsSync(target) && !force) {
+    const target = path17.join(workflowDir, `kody-${exe.name}.yml`);
+    if (fs19.existsSync(target) && !force) {
       skipped.push(`.github/workflows/kody-${exe.name}.yml`);
       continue;
     }
-    fs18.writeFileSync(target, renderScheduledWorkflow(exe.name, profile.schedule));
+    fs19.writeFileSync(target, renderScheduledWorkflow(exe.name, profile.schedule));
     wrote.push(`.github/workflows/kody-${exe.name}.yml`);
   }
   let labels;
@@ -3788,10 +3892,8 @@ var initFlow = async (ctx) => {
 `);
     }
     if (labels.failed.length > 0) {
-      process.stdout.write(
-        `  labels   ${labels.failed.length} failed (gh auth missing? will self-heal on first run)
-`
-      );
+      process.stdout.write(`  labels   ${labels.failed.length} failed (gh auth missing? will self-heal on first run)
+`);
     }
   }
   process.stdout.write(
@@ -3849,6 +3951,9 @@ function isStateEnvelope(x) {
   const o = x;
   return o.version === 1 && typeof o.rev === "number" && Number.isInteger(o.rev) && o.rev >= 0 && typeof o.cursor === "string" && typeof o.done === "boolean" && o.data !== null && typeof o.data === "object" && !Array.isArray(o.data);
 }
+function initialStateEnvelope(cursor = "seed") {
+  return { version: 1, rev: 0, cursor, data: {}, done: false };
+}
 function formatStateCommentBody(marker, state) {
   return `<!-- ${marker} -->
 
@@ -3896,10 +4001,10 @@ function findStateComment2(owner, repo, issueNumber, marker, cwd) {
 }
 function createStateComment(owner, repo, issueNumber, marker, state, cwd) {
   const body = formatStateCommentBody(marker, state);
-  const raw = gh2(
-    ["api", "--method", "POST", `repos/${owner}/${repo}/issues/${issueNumber}/comments`, "--input", "-"],
-    { cwd, input: JSON.stringify({ body }) }
-  );
+  const raw = gh2(["api", "--method", "POST", `repos/${owner}/${repo}/issues/${issueNumber}/comments`, "--input", "-"], {
+    cwd,
+    input: JSON.stringify({ body })
+  });
   const parsed = JSON.parse(raw);
   try {
     minimizeComment(parsed.node_id, cwd);
@@ -3909,10 +4014,10 @@ function createStateComment(owner, repo, issueNumber, marker, state, cwd) {
 }
 function updateStateComment(owner, repo, commentId, commentNodeId, marker, state, cwd) {
   const body = formatStateCommentBody(marker, state);
-  gh2(
-    ["api", "--method", "PATCH", `repos/${owner}/${repo}/issues/comments/${commentId}`, "--input", "-"],
-    { cwd, input: JSON.stringify({ body }) }
-  );
+  gh2(["api", "--method", "PATCH", `repos/${owner}/${repo}/issues/comments/${commentId}`, "--input", "-"], {
+    cwd,
+    input: JSON.stringify({ body })
+  });
   try {
     minimizeComment(commentNodeId, cwd);
   } catch {
@@ -3949,6 +4054,168 @@ var loadIssueStateComment = async (ctx, _profile, args) => {
   ctx.data.issueStateJson = loaded ? JSON.stringify(loaded.state, null, 2) : "null";
 };
 
+// src/scripts/loadMissionFromFile.ts
+import * as fs20 from "fs";
+import * as path18 from "path";
+
+// src/scripts/missionGist.ts
+function gistDescription(owner, repo, slug) {
+  return `kody-mission:${owner}/${repo}:${slug}`;
+}
+function listGists(cwd) {
+  let raw = "";
+  try {
+    raw = gh2(["api", "--paginate", "/gists?per_page=100"], { cwd });
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((g) => typeof g.id === "string").map((g) => ({
+    id: g.id,
+    description: typeof g.description === "string" ? g.description : null,
+    files: g.files ?? {}
+  }));
+}
+function getGist(gistId, cwd) {
+  let raw = "";
+  try {
+    raw = gh2(["api", `/gists/${gistId}`], { cwd });
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const o = parsed;
+  if (typeof o.id !== "string") return null;
+  return {
+    id: o.id,
+    description: typeof o.description === "string" ? o.description : null,
+    files: o.files ?? {}
+  };
+}
+function findGistByDescription(description, cwd) {
+  const all = listGists(cwd);
+  return all.find((g) => g.description === description) ?? null;
+}
+function readEnvelope(gist) {
+  const file = gist.files["state.json"];
+  if (!file?.content) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(file.content);
+  } catch {
+    const fallback = parseStateCommentBody("kody-mission-state", file.content);
+    return fallback ?? null;
+  }
+  return isStateEnvelope(parsed) ? parsed : null;
+}
+function findMissionGist(owner, repo, slug, cwd) {
+  const desc = gistDescription(owner, repo, slug);
+  const gist = findGistByDescription(desc, cwd);
+  if (!gist) return null;
+  const full = getGist(gist.id, cwd) ?? gist;
+  const envelope = readEnvelope(full);
+  if (!envelope) return null;
+  return { gistId: full.id, state: envelope };
+}
+function createMissionGist(owner, repo, slug, cursor = "seed", cwd) {
+  const description = gistDescription(owner, repo, slug);
+  const initial = initialStateEnvelope(cursor);
+  const payload = {
+    description,
+    public: false,
+    files: {
+      "state.json": { content: JSON.stringify(initial, null, 2) + "\n" }
+    }
+  };
+  const raw = gh2(["api", "--method", "POST", "/gists", "--input", "-"], {
+    cwd,
+    input: JSON.stringify(payload)
+  });
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`createMissionGist: gh did not return JSON: ${raw.slice(0, 200)}`);
+  }
+  if (!parsed || typeof parsed !== "object" || typeof parsed.id !== "string") {
+    throw new Error("createMissionGist: gist creation response missing id");
+  }
+  return { gistId: parsed.id, state: initial };
+}
+function writeMissionGist(gistId, next, cwd) {
+  const payload = {
+    files: {
+      "state.json": { content: JSON.stringify(next, null, 2) + "\n" }
+    }
+  };
+  gh2(["api", "--method", "PATCH", `/gists/${gistId}`, "--input", "-"], {
+    cwd,
+    input: JSON.stringify(payload)
+  });
+}
+
+// src/scripts/loadMissionFromFile.ts
+var loadMissionFromFile = async (ctx, _profile, args) => {
+  const missionsDir = String(args?.missionsDir ?? ".kody/missions");
+  const slugArg = String(args?.slugArg ?? "mission");
+  const slug = String(ctx.args[slugArg] ?? "").trim();
+  if (!slug) {
+    throw new Error(`loadMissionFromFile: ctx.args.${slugArg} must be a non-empty slug`);
+  }
+  const owner = ctx.config.github.owner;
+  const repo = ctx.config.github.repo;
+  if (!owner || !repo) {
+    throw new Error("loadMissionFromFile: ctx.config.github.owner/repo must be set");
+  }
+  const absPath = path18.join(ctx.cwd, missionsDir, `${slug}.md`);
+  if (!fs20.existsSync(absPath)) {
+    throw new Error(`loadMissionFromFile: mission file not found: ${absPath}`);
+  }
+  const raw = fs20.readFileSync(absPath, "utf-8");
+  const { title, body } = parseMissionFile(raw, slug);
+  let loaded = findMissionGist(owner, repo, slug, ctx.cwd);
+  if (!loaded) {
+    loaded = createMissionGist(owner, repo, slug, "seed", ctx.cwd);
+  }
+  ctx.data.missionSlug = slug;
+  ctx.data.missionTitle = title;
+  ctx.data.missionIntent = body;
+  ctx.data.missionGist = loaded;
+  ctx.data.missionStateJson = JSON.stringify(loaded.state, null, 2);
+};
+function parseMissionFile(raw, slug) {
+  let stripped = raw;
+  if (stripped.startsWith("---\n")) {
+    const end = stripped.indexOf("\n---\n", 4);
+    if (end !== -1) {
+      stripped = stripped.slice(end + 5);
+    }
+  }
+  const trimmed = stripped.trim();
+  const firstLine2 = trimmed.split("\n", 1)[0] ?? "";
+  const h1 = /^#\s+(.+?)\s*$/.exec(firstLine2);
+  if (h1) {
+    const rest = trimmed.slice(firstLine2.length).replace(/^\n+/, "");
+    return { title: h1[1].trim(), body: rest };
+  }
+  return { title: humanizeSlug(slug), body: trimmed };
+}
+function humanizeSlug(slug) {
+  return slug.split(/[-_]+/).filter((s) => s.length > 0).map((s) => s[0].toUpperCase() + s.slice(1)).join(" ");
+}
+
 // src/scripts/loadPriorArt.ts
 var PER_PR_DIFF_MAX_BYTES = 8e3;
 var TOTAL_MAX_BYTES = 3e4;
@@ -4241,6 +4508,53 @@ function escapeRegex(s) {
   return s.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
 }
 
+// src/scripts/parseMissionStateFromAgentResult.ts
+function isPartialEnvelope2(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return typeof o.cursor === "string" && o.cursor.length > 0 && typeof o.done === "boolean" && o.data !== null && typeof o.data === "object" && !Array.isArray(o.data);
+}
+var parseMissionStateFromAgentResult = async (ctx, _profile, agentResult, args) => {
+  const fenceLabel = String(args?.fenceLabel ?? "");
+  if (!fenceLabel) {
+    throw new Error("parseMissionStateFromAgentResult: `with.fenceLabel` is required");
+  }
+  if (!agentResult) {
+    ctx.data.nextStateParseError = "agent did not run";
+    return;
+  }
+  const fenceRegex = new RegExp("```" + escapeRegex2(fenceLabel) + "\\s*\\n([\\s\\S]*?)\\n```", "m");
+  const match = fenceRegex.exec(agentResult.finalText);
+  if (!match) {
+    ctx.data.nextStateParseError = `agent did not emit a \`${fenceLabel}\` fenced block`;
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(match[1].trim());
+  } catch (err) {
+    ctx.data.nextStateParseError = `state JSON parse error: ${err instanceof Error ? err.message : String(err)}`;
+    return;
+  }
+  if (!isPartialEnvelope2(parsed)) {
+    ctx.data.nextStateParseError = "state must be an object with string `cursor`, object `data`, and boolean `done`";
+    return;
+  }
+  const loaded = ctx.data.missionGist;
+  const prevRev = loaded?.state.rev ?? 0;
+  const next = {
+    version: 1,
+    rev: prevRev + 1,
+    cursor: parsed.cursor,
+    data: parsed.data,
+    done: parsed.done
+  };
+  ctx.data.nextMissionState = next;
+};
+function escapeRegex2(s) {
+  return s.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+}
+
 // src/scripts/persistArtifacts.ts
 var persistArtifacts = async (ctx, profile) => {
   if (profile.outputArtifacts.length === 0) return;
@@ -4306,16 +4620,16 @@ var postClassification = async (ctx) => {
   }
   if (!classification) {
     ctx.data.action = failedAction("classification missing or invalid");
-    tryAuditComment(issueNumber, "\u26A0\uFE0F kody classifier could not decide \u2014 please re-run with an explicit `@kody <type>`.", ctx.cwd);
+    tryAuditComment(
+      issueNumber,
+      "\u26A0\uFE0F kody classifier could not decide \u2014 please re-run with an explicit `@kody <type>`.",
+      ctx.cwd
+    );
     ctx.output.exitCode = 1;
     ctx.output.reason = "classify: no decision";
     return;
   }
-  tryAuditComment(
-    issueNumber,
-    `\u{1F50E} kody classified as \`${classification}\`${reason ? ` \u2014 ${reason}` : ""}`,
-    ctx.cwd
-  );
+  tryAuditComment(issueNumber, `\u{1F50E} kody classified as \`${classification}\`${reason ? ` \u2014 ${reason}` : ""}`, ctx.cwd);
   try {
     execFileSync15("gh", ["issue", "comment", String(issueNumber), "--body", `@kody ${classification}`], {
       cwd: ctx.cwd,
@@ -4605,7 +4919,9 @@ var requirePlanDeviations = async (ctx, profile) => {
   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);
+  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";
 }
@@ -5237,16 +5553,12 @@ var waitForCi = async (ctx, _profile, _agentResult, args) => {
 };
 function fetchChecks(prNumber, cwd) {
   try {
-    const raw = execFileSync20(
-      "gh",
-      ["pr", "checks", String(prNumber), "--json", "bucket,state,name,workflow,link"],
-      {
-        encoding: "utf-8",
-        timeout: API_TIMEOUT_MS9,
-        cwd,
-        stdio: ["ignore", "pipe", "pipe"]
-      }
-    );
+    const raw = execFileSync20("gh", ["pr", "checks", String(prNumber), "--json", "bucket,state,name,workflow,link"], {
+      encoding: "utf-8",
+      timeout: API_TIMEOUT_MS9,
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
     const parsed = JSON.parse(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch (err) {
@@ -5325,10 +5637,7 @@ function formatStaleReport(stale, staleDays) {
   if (stale.length === 0) {
     return `\u{1F7E2} **kody watch-stale-prs** \u2014 no open PRs untouched for more than ${staleDays} days. \u2728`;
   }
-  const lines = [
-    `\u{1F7E1} **kody watch-stale-prs** \u2014 ${stale.length} PR(s) untouched for > ${staleDays} days:`,
-    ""
-  ];
+  const lines = [`\u{1F7E1} **kody watch-stale-prs** \u2014 ${stale.length} PR(s) untouched for > ${staleDays} days:`, ""];
   for (const pr of stale.slice(0, 50)) {
     lines.push(`- [#${pr.number}](${pr.url}) \u2014 *${truncate2(pr.title, 80)}* (${pr.daysStale} days stale)`);
   }
@@ -5392,8 +5701,29 @@ var writeIssueStateComment = async (ctx, _profile, _agentResult, args) => {
   }
 };
 
+// src/scripts/writeMissionGistState.ts
+var writeMissionGistState = async (ctx, _profile, _agentResult) => {
+  const parseError = ctx.data.nextStateParseError;
+  if (parseError) {
+    process.stderr.write(`[kody] mission state write skipped: ${parseError}
+`);
+    if (ctx.output.exitCode === 0) ctx.output.exitCode = 1;
+    if (!ctx.output.reason) ctx.output.reason = `next-state parse failed: ${parseError}`;
+    return;
+  }
+  const next = ctx.data.nextMissionState;
+  if (!next) {
+    return;
+  }
+  const loaded = ctx.data.missionGist;
+  if (!loaded) {
+    throw new Error("writeMissionGistState: ctx.data.missionGist missing \u2014 preflight must run first");
+  }
+  writeMissionGist(loaded.gistId, next, ctx.cwd);
+};
+
 // src/scripts/writeRunSummary.ts
-import * as fs19 from "fs";
+import * as fs21 from "fs";
 var writeRunSummary = async (ctx, profile) => {
   const summaryPath = process.env.GITHUB_STEP_SUMMARY;
   if (!summaryPath) return;
@@ -5415,7 +5745,7 @@ var writeRunSummary = async (ctx, profile) => {
   if (reason) lines.push(`- **Reason:** ${reason}`);
   lines.push("");
   try {
-    fs19.appendFileSync(summaryPath, `${lines.join("\n")}
+    fs21.appendFileSync(summaryPath, `${lines.join("\n")}
 `);
   } catch {
   }
@@ -5434,6 +5764,7 @@ var preflightScripts = {
   loadTaskState,
   loadIssueContext,
   loadIssueStateComment,
+  loadMissionFromFile,
   loadConventions,
   loadCoverageRules,
   loadPriorArt,
@@ -5448,12 +5779,15 @@ var preflightScripts = {
   skipAgent,
   classifyByLabel,
   diagMcp,
-  dispatchMissionTicks
+  dispatchMissionTicks,
+  dispatchMissionFileTicks
 };
 var postflightScripts = {
   parseAgentResult: parseAgentResult2,
   parseIssueStateFromAgentResult,
+  parseMissionStateFromAgentResult,
   writeIssueStateComment,
+  writeMissionGistState,
   requireFeedbackActions,
   requirePlanDeviations,
   verify,
@@ -5588,9 +5922,9 @@ async function runExecutable(profileName, input) {
     data: {},
     output: { exitCode: 0 }
   };
-  const ndjsonDir = path17.join(input.cwd, ".kody");
+  const ndjsonDir = path19.join(input.cwd, ".kody");
   const invokeAgent = async (prompt) => {
-    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path17.isAbsolute(p) ? p : path17.resolve(profile.dir, p)).filter((p) => p.length > 0);
+    const externalPlugins = (profile.claudeCode.plugins ?? []).map((p) => path19.isAbsolute(p) ? p : path19.resolve(profile.dir, p)).filter((p) => p.length > 0);
     const syntheticPath = ctx.data.syntheticPluginPath;
     const pluginPaths = [...externalPlugins, ...syntheticPath ? [syntheticPath] : []];
     return runAgent({
@@ -5666,17 +6000,17 @@ async function runExecutable(profileName, input) {
   }
 }
 function resolveProfilePath(profileName) {
-  const here = path17.dirname(new URL(import.meta.url).pathname);
+  const here = path19.dirname(new URL(import.meta.url).pathname);
   const candidates = [
-    path17.join(here, "executables", profileName, "profile.json"),
+    path19.join(here, "executables", profileName, "profile.json"),
     // same-dir sibling (dev)
-    path17.join(here, "..", "executables", profileName, "profile.json"),
+    path19.join(here, "..", "executables", profileName, "profile.json"),
     // up one (prod: dist/bin → dist/executables)
-    path17.join(here, "..", "src", "executables", profileName, "profile.json")
+    path19.join(here, "..", "src", "executables", profileName, "profile.json")
     // fallback
   ];
   for (const c of candidates) {
-    if (fs20.existsSync(c)) return c;
+    if (fs22.existsSync(c)) return c;
   }
   return candidates[0];
 }
@@ -5769,8 +6103,8 @@ function finish(out) {
 var SHELL_TIMEOUT_MS = 3e5;
 function runShellEntry(entry, ctx, profile) {
   const shellName = entry.shell;
-  const shellPath = path17.join(profile.dir, shellName);
-  if (!fs20.existsSync(shellPath)) {
+  const shellPath = path19.join(profile.dir, shellName);
+  if (!fs22.existsSync(shellPath)) {
     ctx.skipAgent = true;
     ctx.output.exitCode = 99;
     ctx.output.reason = `shell script not found: ${shellName} (looked in ${profile.dir})`;
@@ -5920,9 +6254,9 @@ function resolveAuthToken(env = process.env) {
   return token;
 }
 function detectPackageManager2(cwd) {
-  if (fs21.existsSync(path18.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs21.existsSync(path18.join(cwd, "yarn.lock"))) return "yarn";
-  if (fs21.existsSync(path18.join(cwd, "bun.lockb"))) return "bun";
+  if (fs23.existsSync(path20.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs23.existsSync(path20.join(cwd, "yarn.lock"))) return "yarn";
+  if (fs23.existsSync(path20.join(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function shellOut(cmd, args, cwd, stream = true) {
@@ -6002,11 +6336,11 @@ function configureGitIdentity(cwd) {
 }
 function postFailureTail(issueNumber, cwd, reason) {
   if (!issueNumber) return;
-  const logPath = path18.join(cwd, ".kody", "last-run.jsonl");
+  const logPath = path20.join(cwd, ".kody", "last-run.jsonl");
   let tail = "";
   try {
-    if (fs21.existsSync(logPath)) {
-      const content = fs21.readFileSync(logPath, "utf-8");
+    if (fs23.existsSync(logPath)) {
+      const content = fs23.readFileSync(logPath, "utf-8");
       tail = content.slice(-3e3);
     }
   } catch {
@@ -6031,7 +6365,7 @@ async function runCi(argv) {
     return 0;
   }
   const args = parseCiArgs(argv);
-  const cwd = args.cwd ? path18.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path20.resolve(args.cwd) : process.cwd();
   let earlyConfig;
   try {
     earlyConfig = loadConfig(cwd);
@@ -6169,9 +6503,9 @@ function parseChatArgs(argv, env = process.env) {
   return result;
 }
 function commitChatFiles(cwd, sessionId, verbose) {
-  const sessionFile = path19.relative(cwd, sessionFilePath(cwd, sessionId));
-  const eventsFile = path19.relative(cwd, eventsFilePath(cwd, sessionId));
-  const paths = [sessionFile, eventsFile].filter((p) => fs22.existsSync(path19.join(cwd, p)));
+  const sessionFile = path21.relative(cwd, sessionFilePath(cwd, sessionId));
+  const eventsFile = path21.relative(cwd, eventsFilePath(cwd, sessionId));
+  const paths = [sessionFile, eventsFile].filter((p) => fs24.existsSync(path21.join(cwd, p)));
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
@@ -6209,7 +6543,7 @@ async function runChat(argv) {
 ${CHAT_HELP}`);
     return 64;
   }
-  const cwd = args.cwd ? path19.resolve(args.cwd) : process.cwd();
+  const cwd = args.cwd ? path21.resolve(args.cwd) : process.cwd();
   const sessionId = args.sessionId;
   const unpackedSecrets = unpackAllSecrets();
   if (unpackedSecrets > 0) {

package/dist/executables/mission-scheduler/profile.json

@@ -1,7 +1,7 @@
 {
   "name": "mission-scheduler",
   "role": "watch",
-  "describe": "Scheduled: for every open issue labeled kody:mission, invoke mission-tick once. No agent on the scheduler itself.",
+  "describe": "Scheduled: for every mission file under .kody/missions/, invoke mission-tick once. No agent on the scheduler itself.",
   "kind": "scheduled",
   "schedule": "*/5 * * * *",
   "inputs": [],
@@ -28,7 +28,7 @@
       },
       "verify": "gh auth status",
       "usage": "",
-      "allowedUses": ["issue"]
+      "allowedUses": ["api", "issue", "pr"]
     }
   ],
   "inputArtifacts": [],
@@ -36,13 +36,11 @@
   "scripts": {
     "preflight": [
       {
-        "script": "dispatchMissionTicks",
+        "script": "dispatchMissionFileTicks",
         "with": {
-          "label": "kody:mission",
-          "color": "1d76db",
-          "description": "kody: issue is a mission — scheduler ticks it every cron wake",
+          "missionsDir": ".kody/missions",
           "targetExecutable": "mission-tick",
-          "issueArg": "issue"
+          "slugArg": "mission"
         }
       }
     ],

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

@@ -1,15 +1,15 @@
 {
   "name": "mission-tick",
   "role": "primitive",
-  "describe": "One classifier tick for one mission issue: read intent + state, decide and execute via gh, emit next state.",
+  "describe": "One classifier tick for one mission file: read intent + state, decide and execute via gh, emit next state.",
   "kind": "oneshot",
   "inputs": [
     {
-      "name": "issue",
-      "flag": "--issue",
-      "type": "int",
+      "name": "mission",
+      "flag": "--mission",
+      "type": "string",
       "required": true,
-      "describe": "GitHub issue number that owns this mission."
+      "describe": "Mission slug — basename (without .md) of the file under .kody/missions/."
     }
   ],
   "claudeCode": {
@@ -34,8 +34,8 @@
         "checkCommand": "command -v gh"
       },
       "verify": "gh auth status",
-      "usage": "Use `gh` for all GitHub actions: `gh workflow run <workflow> -f <key>=<val>` to spawn a child run, `gh run view <id> --json status,conclusion` to check status, `gh issue comment <n> --body \"...\"` to post narration. NEVER edit files in the working tree.",
-      "allowedUses": ["workflow", "run", "issue", "pr", "api"]
+      "usage": "Use `gh` for all GitHub actions: `gh pr list ...` to enumerate candidate PRs, `gh pr comment <n> --body \"...\"` to issue a Kody command, `gh pr view <n> --json mergeable,statusCheckRollup,headRefOid` to inspect state, `gh api ...` for anything else. NEVER edit files in the working tree.",
+      "allowedUses": ["pr", "api", "issue"]
     }
   ],
   "inputArtifacts": [],
@@ -43,10 +43,10 @@
   "scripts": {
     "preflight": [
       {
-        "script": "loadIssueStateComment",
+        "script": "loadMissionFromFile",
         "with": {
-          "marker": "kody-mission-state",
-          "issueArg": "issue"
+          "missionsDir": ".kody/missions",
+          "slugArg": "mission"
         }
       },
       {
@@ -55,17 +55,13 @@
     ],
     "postflight": [
       {
-        "script": "parseIssueStateFromAgentResult",
+        "script": "parseMissionStateFromAgentResult",
         "with": {
           "fenceLabel": "kody-mission-next-state"
         }
       },
       {
-        "script": "writeIssueStateComment",
-        "with": {
-          "marker": "kody-mission-state",
-          "issueArg": "issue"
-        }
+        "script": "writeMissionGistState"
       }
     ]
   }

package/dist/executables/mission-tick/prompt.md

@@ -1,33 +1,29 @@
-You are **kody mission-tick**, the coordinator for one GitHub-issue-scoped mission. You do **not** touch code, do **not** commit, and do **not** edit files. You coordinate other kody executables by dispatching their workflows, observing their runs, and writing back state.
+You are **kody mission-tick**, the coordinator for one file-based mission. You do **not** touch code, do **not** commit, and do **not** edit files. You coordinate by inspecting GitHub state and issuing Kody commands as PR comments.
 
 ## The mission
 
-Issue **#{{issueNumber}}** — *{{issueTitle}}* — owns this mission. The issue description below is authoritative: it states what success looks like, constraints, deadlines, budget, or anything else a human operator has written. Re-read it every tick — the human may have edited it to steer you.
+Slug **`{{missionSlug}}`** — *{{missionTitle}}*. The mission body below is authoritative: it states what success looks like, allowed commands, and restrictions. The mission file is human-edited — re-read it every tick.
 
-### Mission (issue description)
+### Mission body
 
-{{issueIntent}}
+{{missionIntent}}
 
 ## Current state
 
 This is the state you wrote at the end of the previous tick (or `null` if this is the first tick):
 
 ```json
-{{issueStateJson}}
+{{missionStateJson}}
 ```
 
-`cursor` is *your* enum — pick whatever labels map cleanly to your mission's phases (e.g. `seed`, `spawn-release`, `waiting-release`, `merge-to-dev`, `finalize`, `done`). `data` is where you stash anything you need on the next tick (run IDs, SHAs, child issue numbers, budget counters). `done: true` is how you signal to future-you that the mission is over — check for it first on every tick and exit early without acting if it's set. Closing the issue also stops ticks (the scheduler only lists open issues).
+`cursor` is *your* enum — pick whatever labels map cleanly to your mission's phases. `data` is where you stash anything you need on the next tick (per-PR attempt counters, last-seen SHAs, etc). `done: true` is how you signal that the mission is permanently over — for evergreen missions this should always remain `false`.
 
 ## What to do on this tick
 
-1. **Check `done`.** If the prior state has `done: true`, emit the same state back unchanged and exit without any other action. The mission is over; don't resurrect it.
-2. **Re-read the mission.** If the human has edited the description in a way that changes what "on track" means, adapt.
-3. **Decide the single next step** based on (cursor, data, mission).
-   - If `cursor` is `null`/first-run, initialize: plan the pipeline, pick an initial cursor, record any baseline info in `data`.
-   - If you're waiting on a child run, check its status via `gh run view <id> --json status,conclusion`. If still running, just update cursor/data minimally and exit — the next cron wake will check again. If succeeded, advance. If failed, record the failure and either spawn a remediation child or mark `done: true` with an error.
-   - If it's time to spawn a child executable, use `gh workflow run kody.yml -f issue_number=<N>` (or the appropriate workflow + inputs for the consumer repo). Capture the dispatched run's ID via `gh run list --workflow=kody.yml --limit 1 --json databaseId --jq '.[0].databaseId'` and stash it in `data`.
-   - If the mission is complete, set `done: true` and a terminal cursor like `done`.
-4. **Optionally post a human-readable narration comment** on the issue summarizing what you just did (spawned run #12345, waiting on CI, etc.). Keep it short. Use `gh issue comment {{issueNumber}} --body "..."`.
+1. **Check `done`.** If the prior state has `done: true`, emit the same state back unchanged and exit without any action.
+2. **Re-read the mission body.** It may have changed since the last tick.
+3. **Execute exactly the work the body's `## Mission` section describes**, subject to its `## Allowed Commands` and `## Restrictions`. Use the `## State` section to interpret and update `data`.
+4. **Optionally post a short narration** wherever the mission tells you to (typically a PR comment alongside the action). Keep it terse.
 5. **Emit the new state** at the very end of your response using the fenced block below. Do not include `version` or `rev` — the postflight script manages those.
 
 ## Output contract (MANDATORY, exactly once, at the end)
@@ -44,12 +40,13 @@ End your response with a single fenced block using the `kody-mission-next-state`
 ```
 ````
 
-If you fail to emit this block, or the JSON is invalid, the tick fails and the state comment is NOT updated. On the next wake you'll see the same prior state and can retry.
+If you fail to emit this block, or the JSON is invalid, the tick fails and the gist state is NOT updated. On the next wake you'll see the same prior state and can retry.
 
 ## Rules
 
 - Never edit, create, or delete files in the working tree.
 - Never commit or push.
-- Only shell calls allowed: `gh` (for workflows, runs, issues, PRs, API). Everything must go through it.
-- Keep each tick focused: do one thing per wake. The cron will call you again.
-- If the state says you're waiting on something, just check and re-emit — don't spawn a duplicate.
+- Only shell calls allowed: `gh`. Everything must go through it.
+- Keep each tick focused: do one action per candidate per wake. The cron will call you again.
+- If state says you're waiting on something, just check and re-emit — don't spawn a duplicate.
+- Honour the mission body's `## Restrictions` over any inferred shortcut.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.3.34",
+  "version": "0.3.38",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",
@@ -12,18 +12,6 @@
     "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": {
     "@anthropic-ai/claude-agent-sdk": "0.2.119"
   },
@@ -43,5 +31,16 @@
     "url": "git+https://github.com/aharonyaircohen/kody-engine.git"
   },
   "homepage": "https://github.com/aharonyaircohen/kody-engine",
-  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues"
-}
+  "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"
+  }
+}