@kody-ade/kody-engine 0.4.210 → 0.4.212-live.0

package/README.md

@@ -121,9 +121,9 @@ kody-engine release-publish   --issue <N> [--dry-run]
 kody-engine release-deploy    --issue <N> [--dry-run]
 
 # scheduled duties and goals
-kody-engine job-scheduler                                     # fan out due .kody/duties/*.md files
-kody-engine job-tick          --job <slug> [--force]          # one agent tick for one duty
-kody-engine job-tick-scripted --job <slug> [--force]          # one deterministic tickScript duty tick
+kody-engine duty-scheduler                                    # fan out due .kody/duties/*.md files
+kody-engine duty-tick          --duty <slug> [--force]        # one agent tick for one duty
+kody-engine duty-tick-scripted --duty <slug> [--force]        # one deterministic tickScript duty tick
 kody-engine goal-scheduler                                    # fan out active .kody/goals/* state files
 kody-engine goal-tick         --goal <id>                     # advance one stacked-PR goal
 
@@ -141,7 +141,7 @@ kody-engine stats                                             # inspect run/even
 
 ### Duties
 
-A **duty** is a markdown file at `.kody/duties/<slug>.md` with frontmatter such as `every:` and `staff:` plus human-owned prose. `job-scheduler` wakes on cron, finds due duties, and dispatches either `job-tick` for an agent tick or `job-tick-scripted` for a deterministic `tickScript:` duty. `kody init` copies built-in starter duties and scaffolds `.kody/staff/kody.md`.
+A **duty** is a markdown file at `.kody/duties/<slug>.md` with frontmatter such as `every:` and `staff:` plus human-owned prose. `duty-scheduler` wakes on cron, finds due duties, and dispatches either `duty-tick` for an agent tick or `duty-tick-scripted` for a deterministic `tickScript:` duty. `kody init` copies built-in starter duties and scaffolds `.kody/staff/kody.md`.
 
 Locked-toolbox duties can declare `tools: [...]` to run with only the named high-level MCP intents plus `submit_state`; duties without `tools:` keep the legacy Bash/gh toolbox.
 

package/dist/bin/kody.js

@@ -858,7 +858,7 @@ function dutyToolDefinitions(opts) {
   };
   const checkRunsTool = {
     name: "read_check_runs",
-    description: "Read CI for a branch or commit ref (e.g. 'dev'). Returns {sha, state, failing:[{name,conclusion,detailsUrl}], pending:[{name,status}]}. state is RED (\u22651 check has a terminal-failure conclusion: failure/timed_out/startup_failure/action_required), PENDING (none failed but some still running), or GREEN (all completed, none failed). Kody's own job check-runs (run/kody/job-tick/\u2026) are excluded by default. This reads the commit's authoritative check-runs \u2014 use it instead of guessing CI health from a run list.",
+    description: "Read CI for a branch or commit ref (e.g. 'dev'). Returns {sha, state, failing:[{name,conclusion,detailsUrl}], pending:[{name,status}]}. state is RED (\u22651 check has a terminal-failure conclusion: failure/timed_out/startup_failure/action_required), PENDING (none failed but some still running), or GREEN (all completed, none failed). Kody's own job check-runs (run/kody/duty-tick/\u2026) are excluded by default. This reads the commit's authoritative check-runs \u2014 use it instead of guessing CI health from a run list.",
     inputSchema: {
       ref: z2.string().min(1).describe("Branch name or commit SHA to read CI for (e.g. 'dev')."),
       ignoreNames: z2.array(z2.string()).optional().describe("Check names to exclude (default: Kody's own job names).")
@@ -980,7 +980,7 @@ var init_dutyMcp = __esm({
     TRUST_STATE_BRANCH = "kody-state";
     THREAD_BODY_MAX = 4e3;
     CHECK_FAIL_CONCLUSIONS = /* @__PURE__ */ new Set(["FAILURE", "TIMED_OUT", "STARTUP_FAILURE", "ACTION_REQUIRED"]);
-    DEFAULT_IGNORE_CHECKS = ["run", "kody", "job-tick", "goal-tick", "worker-ask", "chat"];
+    DEFAULT_IGNORE_CHECKS = ["run", "kody", "duty-tick", "goal-tick", "worker-ask", "chat"];
     trackMarker = (key) => `<!-- kody-track:${key} -->`;
     commentMarker = (key) => `<!-- kody-track-comment:${key} -->`;
     GATE_EXEMPT_EXECUTABLES = /* @__PURE__ */ new Set(["qa-engineer", "ui-review"]);
@@ -1542,7 +1542,7 @@ var init_loadCoverageRules = __esm({
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.210",
+  version: "0.4.212-live.0",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -4406,6 +4406,7 @@ import { execFileSync as execFileSync2 } from "child_process";
 var STATE_BEGIN = "<!-- kody:state:v1:begin -->";
 var STATE_END = "<!-- kody:state:v1:end -->";
 var HISTORY_MAX_ENTRIES = 20;
+var JOB_RUNS_MAX_ENTRIES = 20;
 var API_TIMEOUT_MS2 = 3e4;
 function emptyState() {
   return {
@@ -4419,6 +4420,7 @@ function emptyState() {
     },
     executables: {},
     artifacts: {},
+    jobs: {},
     history: []
   };
 }
@@ -4487,6 +4489,7 @@ function parseStateComment(body) {
     core: { ...emptyState().core, ...parsed.core },
     executables: parsed.executables ?? {},
     artifacts: parsed.artifacts && typeof parsed.artifacts === "object" ? parsed.artifacts : {},
+    jobs: normalizeJobs(parsed.jobs),
     history: Array.isArray(parsed.history) ? parsed.history : [],
     flow: parsed.flow
   };
@@ -4512,6 +4515,7 @@ function reduce(state, executable, action, phase, staff, job) {
     ...job?.runUrl ? { runUrl: job.runUrl } : {}
   };
   const newHistory = [...state.history, entry].slice(-HISTORY_MAX_ENTRIES);
+  const newJobs = reduceJobs(state.jobs ?? {}, executable, action, staff, job);
   return {
     schemaVersion: 1,
     core: {
@@ -4525,10 +4529,47 @@ function reduce(state, executable, action, phase, staff, job) {
     },
     executables: newExecutables,
     artifacts: { ...state.artifacts ?? {} },
+    jobs: newJobs,
     history: newHistory,
     flow: state.flow
   };
 }
+function reduceJobs(jobs, executable, action, staff, job) {
+  const status = statusFromAction(action);
+  const id = job?.jobKey || job?.jobId || `legacy:${executable}`;
+  const prior = jobs[id];
+  const note = noteFromAction(action);
+  const prUrl = job?.prUrl ?? prUrlFromAction(action);
+  const run = {
+    id: job?.jobId || `${id}:${action.timestamp}`,
+    timestamp: action.timestamp,
+    action: action.type,
+    status,
+    ...note ? { note } : {},
+    ...job?.runUrl ? { runUrl: job.runUrl } : {},
+    ...prUrl ? { prUrl } : {}
+  };
+  const runs = [...prior?.runs ?? [], run].slice(-JOB_RUNS_MAX_ENTRIES);
+  const ranAsStaff = typeof staff === "string" && staff.length > 0 ? staff : job?.persona;
+  const next = {
+    id,
+    executable: job?.executable ?? prior?.executable ?? executable,
+    ...job?.duty ?? prior?.duty ? { duty: job?.duty ?? prior?.duty } : {},
+    ...ranAsStaff ?? prior?.staff ? { staff: ranAsStaff ?? prior?.staff } : {},
+    ...job?.flavor ?? prior?.flavor ? { flavor: job?.flavor ?? prior?.flavor } : {},
+    ...job?.schedule ?? prior?.schedule ? { schedule: job?.schedule ?? prior?.schedule } : {},
+    ...typeof job?.target === "number" ? { target: job.target } : prior?.target !== void 0 ? { target: prior.target } : {},
+    ...job?.why ?? prior?.reason ? { reason: job?.why ?? prior?.reason } : {},
+    status,
+    createdAt: prior?.createdAt ?? action.timestamp,
+    updatedAt: action.timestamp,
+    ...status === "succeeded" ? { completedAt: action.timestamp } : {},
+    ...job?.runUrl ?? prior?.runUrl ? { runUrl: job?.runUrl ?? prior?.runUrl } : {},
+    ...prUrl ?? prior?.prUrl ? { prUrl: prUrl ?? prior?.prUrl } : {},
+    runs
+  };
+  return { ...jobs, [id]: next };
+}
 function statusFromAction(action) {
   if (/FAILED$|ERROR$|MISSING$|REJECTED$/i.test(action.type)) return "failed";
   if (/COMPLETED$|SHIPPED$|MERGED$|SUCCESS$/i.test(action.type)) return "succeeded";
@@ -4545,6 +4586,46 @@ function noteFromAction(action) {
   if (typeof p?.commitMessage === "string") return p.commitMessage.slice(0, 120);
   return void 0;
 }
+function prUrlFromAction(action) {
+  const p = action.payload;
+  return typeof p?.prUrl === "string" ? p.prUrl : void 0;
+}
+function normalizeJobs(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const raw = value;
+    if (typeof raw.id !== "string" || typeof raw.executable !== "string") continue;
+    if (!isStatus(raw.status)) continue;
+    out[key] = {
+      id: raw.id,
+      executable: raw.executable,
+      ...typeof raw.duty === "string" ? { duty: raw.duty } : {},
+      ...typeof raw.staff === "string" ? { staff: raw.staff } : {},
+      ...raw.flavor === "instant" || raw.flavor === "scheduled" ? { flavor: raw.flavor } : {},
+      ...typeof raw.schedule === "string" ? { schedule: raw.schedule } : {},
+      ...typeof raw.target === "number" ? { target: raw.target } : {},
+      ...typeof raw.reason === "string" ? { reason: raw.reason } : {},
+      status: raw.status,
+      createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "",
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : "",
+      ...typeof raw.completedAt === "string" ? { completedAt: raw.completedAt } : {},
+      ...typeof raw.runUrl === "string" ? { runUrl: raw.runUrl } : {},
+      ...typeof raw.prUrl === "string" ? { prUrl: raw.prUrl } : {},
+      runs: Array.isArray(raw.runs) ? raw.runs.filter(isTaskJobRun).slice(-JOB_RUNS_MAX_ENTRIES) : []
+    };
+  }
+  return out;
+}
+function isTaskJobRun(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return false;
+  const run = input;
+  return typeof run.id === "string" && typeof run.timestamp === "string" && typeof run.action === "string" && isStatus(run.status);
+}
+function isStatus(input) {
+  return input === "pending" || input === "running" || input === "succeeded" || input === "failed";
+}
 function renderStateComment(state) {
   const lines = [];
   lines.push("## \u{1F4CB} kody task state");
@@ -4566,6 +4647,11 @@ function renderStateComment(state) {
   if (attempts) lines.push(`- **Attempts:** ${attempts}`);
   if (state.core.prUrl) lines.push(`- **PR:** ${state.core.prUrl}`);
   if (state.core.runUrl) lines.push(`- **Run:** ${state.core.runUrl}`);
+  const jobEntries = Object.values(state.jobs ?? {});
+  if (jobEntries.length > 0) {
+    const completed = jobEntries.filter((j) => j.status === "succeeded").length;
+    lines.push(`- **Jobs:** ${completed}/${jobEntries.length} complete`);
+  }
   const artifactNames = Object.keys(state.artifacts ?? {});
   if (artifactNames.length > 0) {
     lines.push(`- **Artifacts:** ${artifactNames.map((n) => `\`${n}\``).join(", ")}`);
@@ -4581,6 +4667,14 @@ function renderStateComment(state) {
     }
     lines.push("");
   }
+  if (jobEntries.length > 0) {
+    lines.push("### Jobs");
+    lines.push("");
+    for (const job of jobEntries) {
+      lines.push(`- \`${job.id}\` **${job.executable}** \u2192 \`${job.status}\` (${job.runs.length} runs)`);
+    }
+    lines.push("");
+  }
   lines.push("<details>");
   lines.push("<summary>Raw state (JSON)</summary>");
   lines.push("");
@@ -4593,6 +4687,7 @@ function renderStateComment(state) {
         schemaVersion: state.schemaVersion,
         core: state.core,
         artifacts: state.artifacts ?? {},
+        jobs: state.jobs ?? {},
         executables: state.executables,
         history: state.history,
         ...state.flow ? { flow: state.flow } : {}
@@ -4906,19 +5001,7 @@ function readContainerState(ctx, child, reader) {
   if (cached2 && typeof cached2 === "object") {
     return cached2;
   }
-  return {
-    schemaVersion: 1,
-    core: {
-      phase: "idle",
-      status: "pending",
-      currentExecutable: null,
-      lastOutcome: null,
-      attempts: {}
-    },
-    executables: {},
-    artifacts: {},
-    history: []
-  };
+  return emptyState();
 }
 function parsePrNumber2(url) {
   const m = url.match(/\/pull\/(\d+)(?:[/?#]|$)/);
@@ -5560,10 +5643,16 @@ import { execFileSync as execFileSync7 } from "child_process";
 // src/scripts/saveTaskState.ts
 function jobMetaFromData(data) {
   return {
+    jobKey: typeof data.jobKey === "string" ? data.jobKey : void 0,
     jobId: typeof data.jobId === "string" ? data.jobId : void 0,
     flavor: typeof data.jobFlavor === "string" ? data.jobFlavor : void 0,
     schedule: typeof data.jobSchedule === "string" ? data.jobSchedule : void 0,
-    runUrl: typeof data.runUrl === "string" ? data.runUrl : void 0
+    runUrl: typeof data.runUrl === "string" ? data.runUrl : void 0,
+    duty: typeof data.jobDuty === "string" ? data.jobDuty : void 0,
+    executable: typeof data.jobExecutable === "string" ? data.jobExecutable : void 0,
+    target: typeof data.jobTarget === "number" ? data.jobTarget : void 0,
+    persona: typeof data.jobPersona === "string" ? data.jobPersona : void 0,
+    why: typeof data.jobWhy === "string" ? data.jobWhy : void 0
   };
 }
 var saveTaskState = async (ctx, profile) => {
@@ -5573,7 +5662,10 @@ var saveTaskState = async (ctx, profile) => {
   if (!target || !number || !state) return;
   const executable = profile.name;
   const action = ctx.data.action ?? synthesizeAction(ctx);
-  const next = reduce(state, executable, action, profile.phase, profile.staff, jobMetaFromData(ctx.data));
+  const next = reduce(state, executable, action, profile.phase, profile.staff, {
+    ...jobMetaFromData(ctx.data),
+    ...ctx.output.prUrl ? { prUrl: ctx.output.prUrl } : {}
+  });
   if (ctx.output.prUrl) next.core.prUrl = ctx.output.prUrl;
   if (typeof ctx.data.runUrl === "string") next.core.runUrl = ctx.data.runUrl;
   writeTaskState(target, number, next, ctx.cwd);
@@ -6289,7 +6381,19 @@ var composePrompt = async (ctx, profile) => {
     repoOwner: ctx.config.github.owner,
     repoName: ctx.config.github.repo,
     defaultBranch: ctx.config.git.defaultBranch,
-    branch: ctx.data.branch ?? ""
+    branch: ctx.data.branch ?? "",
+    // The `{{dutyReference}}` block is built from ctx.data.* (with legacy
+    // jobSlug/jobTitle/workerSlug/jobSchedule fallbacks) so a duty prompt can
+    // place a labeled summary at the top. The five underlying tokens are
+    // also exposed individually so a template can compose them differently
+    // (e.g. put the executable slug inline in a header).
+    dutyReference: formatDutyReference(ctx.data, profile.name),
+    dutySlug: pickToken(ctx.data, "dutySlug", "jobSlug"),
+    dutyTitle: pickToken(ctx.data, "dutyTitle", "jobTitle"),
+    executableSlug: pickToken(ctx.data, "executableSlug") || profile.name,
+    staffSlug: pickToken(ctx.data, "staffSlug", "workerSlug"),
+    staffTitle: pickToken(ctx.data, "staffTitle", "workerTitle"),
+    dutySchedule: pickToken(ctx.data, "dutySchedule", "jobSchedule")
   };
   ctx.data.prompt = template.replace(MUSTACHE, (_, key) => {
     const value = tokens[key] ?? "";
@@ -6354,6 +6458,39 @@ function formatToolsUsage(profile) {
   }
   return lines.join("\n");
 }
+function formatDutyReference(data, profileName) {
+  const dutySlug = pickToken(data, "dutySlug", "jobSlug");
+  const dutyTitle = pickToken(data, "dutyTitle", "jobTitle");
+  const executableSlug = pickToken(data, "executableSlug") || profileName;
+  const staffSlug = pickToken(data, "staffSlug", "workerSlug");
+  const staffTitle = pickToken(data, "staffTitle", "workerTitle");
+  const dutySchedule = pickToken(data, "dutySchedule", "jobSchedule");
+  const lines = ["# Duty reference", ""];
+  if (dutySlug) {
+    lines.push(`- Duty: \`${dutySlug}\`${dutyTitle ? ` \u2014 *${dutyTitle}*` : ""}`);
+  }
+  if (executableSlug) {
+    lines.push(`- Executable: \`${executableSlug}\``);
+  }
+  const staffLine = staffSlug ? `\`${staffSlug}\`${staffTitle && staffTitle !== staffSlug ? ` \u2014 *${staffTitle}*` : ""}` : "";
+  if (staffLine) {
+    lines.push(`- Staff: ${staffLine}`);
+  }
+  if (dutySchedule) {
+    lines.push(`- Cadence: \`${dutySchedule}\``);
+  }
+  if (lines.length === 2) {
+    return "";
+  }
+  return lines.join("\n");
+}
+function pickToken(data, ...keys) {
+  for (const k of keys) {
+    const v = data[k];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return "";
+}
 
 // src/scripts/createQaGoal.ts
 init_issue();
@@ -7654,16 +7791,32 @@ ${stateBody}`;
   ctx.output.nextDispatch = { executable: classification, cliArgs };
 };
 
-// src/scripts/dispatchJobFileTicks.ts
+// src/scripts/dispatchDutyFileTicks.ts
 import * as fs29 from "fs";
 import * as path26 from "path";
 
 // src/job.ts
 var DEFAULT_INSTANT_PERSONA = "kody";
+var localJobSeq = 0;
 function newJobId(flavor) {
   const runId = process.env.GITHUB_RUN_ID;
   if (runId) return `gh-${runId}-${process.env.GITHUB_RUN_ATTEMPT ?? "1"}`;
-  return `${flavor}-${Date.now()}`;
+  localJobSeq += 1;
+  return `${flavor}-${Date.now()}-${localJobSeq}`;
+}
+function stableJobKey(job) {
+  const executable = job.executable ?? job.duty ?? "unknown";
+  if (job.flavor === "scheduled" && job.duty) return `scheduled:${job.duty}:${executable}`;
+  const target = typeof job.target === "number" ? job.target : targetFromCliArgs(job.cliArgs);
+  return target === void 0 ? `${job.flavor}:${executable}` : `${job.flavor}:${executable}:${target}`;
+}
+function targetFromCliArgs(cliArgs) {
+  if (!cliArgs) return void 0;
+  for (const key of ["issue", "pr", "target", "issue_number"]) {
+    const value = cliArgs[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return void 0;
 }
 var InvalidJobError = class extends Error {
   constructor(message) {
@@ -7705,7 +7858,9 @@ async function runJob(job, base) {
   }
   const preloadedData = {};
   preloadedData.jobId = newJobId(valid.flavor);
+  preloadedData.jobKey = stableJobKey(valid);
   preloadedData.jobFlavor = valid.flavor;
+  if (valid.target !== void 0) preloadedData.jobTarget = valid.target;
   if (valid.duty !== void 0 && valid.duty.length > 0) preloadedData.jobDuty = valid.duty;
   if (valid.executable !== void 0 && valid.executable.length > 0) preloadedData.jobExecutable = valid.executable;
   if (valid.schedule !== void 0 && valid.schedule.length > 0) preloadedData.jobSchedule = valid.schedule;
@@ -8200,16 +8355,16 @@ function resolveBackend(opts) {
   }
 }
 
-// src/scripts/dispatchJobFileTicks.ts
-var dispatchJobFileTicks = async (ctx, _profile, args) => {
+// src/scripts/dispatchDutyFileTicks.ts
+var dispatchDutyFileTicks = async (ctx, _profile, args) => {
   ctx.skipAgent = true;
   const targetExecutable = String(args?.targetExecutable ?? "");
   if (!targetExecutable) {
-    throw new Error("dispatchJobFileTicks: `with.targetExecutable` is required");
+    throw new Error("dispatchDutyFileTicks: `with.targetExecutable` is required");
   }
   const jobsDir = String(args?.jobsDir ?? ".kody/duties");
-  const scriptedExecutable = String(args?.scriptedExecutable ?? "job-tick-scripted");
-  const slugArg = String(args?.slugArg ?? "job");
+  const scriptedExecutable = String(args?.scriptedExecutable ?? "duty-tick-scripted");
+  const slugArg = String(args?.slugArg ?? "duty");
   const backend = resolveBackend({ config: ctx.config, cwd: ctx.cwd, jobsDir });
   if (backend.hydrate) {
     await backend.hydrate();
@@ -8422,14 +8577,14 @@ async function stampFired(backend, slug, now) {
   }
 }
 
-// src/scripts/dispatchJobTicks.ts
+// src/scripts/dispatchDutyTicks.ts
 init_issue();
-var dispatchJobTicks = async (ctx, _profile, args) => {
+var dispatchDutyTicks = async (ctx, _profile, args) => {
   ctx.skipAgent = true;
   const label = String(args?.label ?? "");
   const targetExecutable = String(args?.targetExecutable ?? "");
-  if (!label) throw new Error("dispatchJobTicks: `with.label` is required");
-  if (!targetExecutable) throw new Error("dispatchJobTicks: `with.targetExecutable` is required");
+  if (!label) throw new Error("dispatchDutyTicks: `with.label` is required");
+  if (!targetExecutable) throw new Error("dispatchDutyTicks: `with.targetExecutable` is required");
   const issueArg = String(args?.issueArg ?? "issue");
   const issues = listIssuesByLabel(label, ctx.cwd);
   ctx.data.jobIssueCount = issues.length;
@@ -9761,6 +9916,12 @@ var loadDutyState = async (ctx, profile, args) => {
   ctx.data.jobSlug = slug;
   ctx.data.jobState = loaded;
   ctx.data.jobStateJson = JSON.stringify(loaded.state, null, 2);
+  ctx.data.dutySlug = slug;
+  ctx.data.dutyTitle = profile.describe;
+  ctx.data.executableSlug = profile.executable ?? profile.name;
+  ctx.data.staffSlug = profile.staff ?? "";
+  ctx.data.staffTitle = "";
+  ctx.data.dutySchedule = profile.every ?? profile.schedule ?? "";
   const mentions = (profile.mentions ?? []).map((l) => `@${l}`).join(" ");
   ctx.data.mentions = mentions;
   const declaredTools = profile.dutyTools ?? [];
@@ -9931,6 +10092,12 @@ var loadJobFromFile = async (ctx, profile, args) => {
   ctx.data.workerTitle = workerTitle;
   ctx.data.workerPersona = workerPersona;
   ctx.data.mentions = mentions;
+  ctx.data.dutySlug = slug;
+  ctx.data.dutyTitle = title;
+  ctx.data.staffSlug = workerSlug;
+  ctx.data.staffTitle = workerTitle;
+  ctx.data.executableSlug = profile.name;
+  ctx.data.dutySchedule = "";
   const declaredTools = frontmatter.tools ?? [];
   if (declaredTools.length > 0) {
     const unknown = declaredTools.filter((name) => !DUTY_TOOL_PALETTE2.has(name));
@@ -10697,6 +10864,10 @@ var parseIssueStateFromAgentResult = async (ctx, _profile, agentResult, args) =>
 };
 
 // src/scripts/parseJobStateFromAgentResult.ts
+var DUTY_NEXT_STATE_FENCE_ALIASES = {
+  "kody-job-next-state": "kody-duty-next-state",
+  "kody-duty-next-state": "kody-job-next-state"
+};
 var parseJobStateFromAgentResult = async (ctx, _profile, agentResult, args) => {
   const fenceLabel = String(args?.fenceLabel ?? "");
   if (!fenceLabel) {
@@ -10719,7 +10890,16 @@ var parseJobStateFromAgentResult = async (ctx, _profile, agentResult, args) => {
     };
     return;
   }
-  const result = extractNextStateFromText(agentResult.finalText, fenceLabel, prevRev);
+  let result = extractNextStateFromText(agentResult.finalText, fenceLabel, prevRev);
+  if (result.error?.startsWith("missing `")) {
+    const alias = DUTY_NEXT_STATE_FENCE_ALIASES[fenceLabel];
+    if (alias) {
+      const aliasResult = extractNextStateFromText(agentResult.finalText, alias, prevRev);
+      if (!aliasResult.error?.startsWith("missing `")) {
+        result = aliasResult;
+      }
+    }
+  }
   if (result.error) {
     const cleanFinishNoBlock = result.error.startsWith("missing `") && agentResult.outcome === "completed" && loaded != null;
     if (cleanFinishNoBlock) {
@@ -12266,7 +12446,7 @@ var runTickScript = async (ctx, _profile, args) => {
   const tickScript = frontmatter.tickScript;
   if (!tickScript) {
     ctx.output.exitCode = 99;
-    ctx.output.reason = `runTickScript: job ${slug} has no \`tickScript:\` frontmatter \u2014 route via job-tick instead`;
+    ctx.output.reason = `runTickScript: duty ${slug} has no \`tickScript:\` frontmatter \u2014 route via duty-tick instead`;
     return;
   }
   const scriptPath = path34.isAbsolute(tickScript) ? tickScript : path34.join(ctx.cwd, tickScript);
@@ -13249,8 +13429,8 @@ var preflightScripts = {
   classifyByLabel,
   diagMcp,
   warmupMcp,
-  dispatchJobTicks,
-  dispatchJobFileTicks,
+  dispatchDutyTicks,
+  dispatchDutyFileTicks,
   runTickScript,
   runPreviewBuild,
   loadGoalState,

package/dist/executables/{job-scheduler → duty-scheduler}/profile.json

@@ -1,7 +1,7 @@
 {
-  "name": "job-scheduler",
+  "name": "duty-scheduler",
   "role": "watch",
-  "describe": "Scheduled: for every duty file under .kody/duties/, invoke job-tick once. No agent on the scheduler itself.",
+  "describe": "Scheduled: for every duty file under .kody/duties/, invoke duty-tick once. No agent on the scheduler itself.",
   "kind": "scheduled",
   "schedule": "*/5 * * * *",
   "inputs": [],
@@ -36,11 +36,11 @@
   "scripts": {
     "preflight": [
       {
-        "script": "dispatchJobFileTicks",
+        "script": "dispatchDutyFileTicks",
         "with": {
           "jobsDir": ".kody/duties",
-          "targetExecutable": "job-tick",
-          "slugArg": "job"
+          "targetExecutable": "duty-tick",
+          "slugArg": "duty"
         }
       }
     ],

package/dist/executables/{job-tick → duty-tick}/profile.json

@@ -1,12 +1,12 @@
 {
-  "name": "job-tick",
+  "name": "duty-tick",
   "role": "primitive",
   "describe": "One classifier tick for one duty file: read intent + state, decide and execute via gh, emit next state.",
   "kind": "oneshot",
   "inputs": [
     {
-      "name": "job",
-      "flag": "--job",
+      "name": "duty",
+      "flag": "--duty",
       "type": "string",
       "required": true,
       "describe": "Duty slug — basename (without .md) of the file under .kody/duties/."
@@ -15,7 +15,7 @@
       "name": "force",
       "flag": "--force",
       "type": "bool",
-      "describe": "When true, the agent ignores the job body's cadence guard and executes the work this tick. All other body rules (allowed commands, restrictions, state schema) still apply. Used for manual triggers from the dashboard's 'Run now' button."
+      "describe": "When true, the agent ignores the duty body's cadence guard and executes the work this tick. All other body rules (allowed commands, restrictions, state schema) still apply. Used for manual triggers from the dashboard's 'Run now' button."
     }
   ],
   "claudeCode": {
@@ -53,7 +53,7 @@
         "script": "loadJobFromFile",
         "with": {
           "jobsDir": ".kody/duties",
-          "slugArg": "job"
+          "slugArg": "duty"
         }
       },
       {

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

@@ -0,0 +1,77 @@
+{{dutyReference}}
+
+You are **{{staffTitle}}** (staff `{{staffSlug}}`), running through **kody duty-tick** — the coordinator for one file-based duty. 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.
+
+## Who you are — staff persona (authoritative identity)
+
+The duty below assigns you, staff **`{{staffSlug}}`**, as its executor. This persona defines *who* runs the duty: your authority, doctrine, voice, and hard limits. Where the persona's restrictions are stricter than the duty body, **the persona wins** — a duty can never grant you authority your staff persona withholds.
+
+{{workerPersona}}
+
+## The duty
+
+Slug **`{{dutySlug}}`** — *{{dutyTitle}}*, assigned to staff **`{{staffSlug}}`**, running on executable **`{{executableSlug}}`**. The duty body below is authoritative for *what* to do, *when* (cadence), allowed commands, and state schema. It is human-edited — re-read it every tick. Execute it **as** the persona above.
+
+**Addressing the operator.** When the duty body tells you to @-mention the operator (e.g. the first line of an inbox recommendation), the exact handle(s) to use are: {{mentions}}. Copy that string **verbatim** — never invent, abbreviate, guess, or retype a GitHub username. A wrong handle silently fails to route to the operator's inbox, so the recommendation is lost. If the line above is blank, the duty declared no operator; post without a mention.
+
+### Duty body
+
+{{jobIntent}}
+
+## Current state
+
+This is the state you wrote at the end of the previous tick (or `null` if this is the first tick):
+
+```json
+{{jobStateJson}}
+```
+
+`cursor` is *your* enum — pick whatever labels map cleanly to your duty'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 duty is permanently over — for evergreen duties this should always remain `false`.
+
+## What to do on this tick
+
+`forceRun = {{args.force}}` — set to `true` when an operator clicked "Run now" on the dashboard. When `forceRun` is `true`, ignore the duty body's `**Cadence guard.**` paragraph (or any equivalent "skip if last run was within X" rule) and execute the work as if the guard had passed. All other body rules — allowed commands, restrictions, state schema — still apply. Force only overrides cadence.
+
+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 duty body.** It may have changed since the last tick.
+3. **Execute exactly the work the body's `## Duty` 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 duty tells you to (typically a PR comment alongside the action). Keep it terse.
+5. **Submit the new state** by calling the `submit_state` tool (see contract below). Do not include `version` or `rev` — the postflight script manages those.
+
+## Output contract (MANDATORY, exactly once, at the end)
+
+Call the **`submit_state`** tool exactly once, as the final step, with your next state:
+
+- `cursor` — your next cursor (string, e.g. `"idle"`).
+- `data` — your next `data` object. Carry forward prior `data` and mutate only what you acted on this tick.
+- `done` — `true` only if the duty is permanently finished; evergreen duties stay `false`.
+
+This is the ONLY way your decision is saved. If you don't call it, the tick fails and the state is NOT updated — on the next wake you'll see the same prior state and can retry.
+
+> Backstop (legacy): if the `submit_state` tool is unavailable, end your reply with the same JSON in a single fenced block tagged `kody-job-next-state` (or the new `kody-duty-next-state` alias) instead:
+>
+> ````
+> ```kody-job-next-state
+> { "cursor": "<next>", "data": { ... }, "done": <true|false> }
+> ```
+> ````
+
+## Rules
+
+- Never edit, create, or delete files in the working tree.
+- Never commit or push via `git`. The only permitted commit path is `gh api -X PUT` against the report file (see exception below).
+- 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 duty body's `## Restrictions` over any inferred shortcut.
+
+### Single permitted write: the duty's report file
+
+A duty MAY (optionally — only if its body asks for it) write a single
+markdown report file at the canonical path:
+
+```
+.kody/reports/{{dutySlug}}.md
+```
+
+Only that exact path. Only via `gh api -X PUT /repos/<owner>/<repo>/contents/.kody/reports/{{dutySlug}}.md` (with base64 content + `sha` of the existing file when updating). All other writes — code files, other report paths, other slugs — remain forbidden. The dashboard's `/reports` page surfaces these files automatically; this is the canonical channel for a duty's diagnostic output when an issue comment isn't expressive enough.

package/dist/executables/{job-tick → duty-tick}/prompts/locked.md

@@ -1,4 +1,6 @@
-You are **{{workerTitle}}** (staff `{{workerSlug}}`), running duty **`{{jobSlug}}`** — *{{jobTitle}}* — in **locked-toolbox mode**.
+{{dutyReference}}
+
+You are **{{staffTitle}}** (staff `{{staffSlug}}`), running duty **`{{dutySlug}}`** — *{{dutyTitle}}* — in **locked-toolbox mode**.
 
 You have NO shell. You cannot run `gh`, edit files, or post raw comments. The only actions you can take this tick are the typed tools listed below, plus `submit_state` at the end. The duty body tells you *when* to use each tool; the tools themselves do the work.
 
@@ -15,7 +17,7 @@ Anything not in that list does not exist for this tick. If the duty body asks fo
 
 ## The duty
 
-Slug **`{{jobSlug}}`** — assigned to staff **`{{workerSlug}}`**. The body is authoritative for *what* and *when*; re-read it every tick.
+Slug **`{{dutySlug}}`** — assigned to staff **`{{staffSlug}}`**, running on executable **`{{executableSlug}}`**. The body is authoritative for *what* and *when*; re-read it every tick.
 
 **Operator handle.** Where the duty refers to "the operator," the `recommend_to_operator` tool already prepends this string: `{{mentions}}`. Never type it yourself.
 

package/dist/executables/{job-tick-scripted → duty-tick-scripted}/profile.json

@@ -1,12 +1,12 @@
 {
-  "name": "job-tick-scripted",
+  "name": "duty-tick-scripted",
   "role": "utility",
-  "describe": "Deterministic job tick: runs the slug's `tickScript:` (declared in job frontmatter), parses next-state from its stdout, persists. No agent.",
+  "describe": "Deterministic duty tick: runs the slug's `tickScript:` (declared in duty frontmatter), parses next-state from its stdout, persists. No agent.",
   "kind": "oneshot",
   "inputs": [
     {
-      "name": "job",
-      "flag": "--job",
+      "name": "duty",
+      "flag": "--duty",
       "type": "string",
       "required": true,
       "describe": "Duty slug — basename (without .md) of the file under .kody/duties/."
@@ -15,7 +15,7 @@
       "name": "force",
       "flag": "--force",
       "type": "bool",
-      "describe": "Accepted for parity with `job-tick`. Scripted ticks have no agent cadence guard to bypass — the dispatcher already gated on frontmatter `every:`. Forwarded to the script via env if it cares."
+      "describe": "Accepted for parity with `duty-tick`. Scripted ticks have no agent cadence guard to bypass — the dispatcher already gated on frontmatter `every:`. Forwarded to the script via env if it cares."
     }
   ],
   "claudeCode": {
@@ -52,7 +52,7 @@
         "script": "runTickScript",
         "with": {
           "jobsDir": ".kody/duties",
-          "slugArg": "job",
+          "slugArg": "duty",
           "fenceLabel": "kody-job-next-state"
         }
       }

package/dist/executables/fix-ci/profile.json

@@ -0,0 +1,71 @@
+{
+  "name": "fix-ci",
+  "role": "primitive",
+  "describe": "Fix a failing CI workflow on an existing PR.",
+  "inputs": [
+    {
+      "name": "pr",
+      "flag": "--pr",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub PR number whose CI is failing."
+    },
+    {
+      "name": "runId",
+      "flag": "--run-id",
+      "type": "string",
+      "required": false,
+      "describe": "Specific failed workflow run ID. Defaults to latest failed run on the PR branch."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "maxTurnTimeoutSec": 1200,
+    "systemPromptAppend": null,
+    "cacheable": true,
+    "enableVerifyTool": true,
+    "verifyAttempts": 4,
+    "tools": [
+      "Read",
+      "Write",
+      "Edit",
+      "Bash",
+      "Grep",
+      "Glob",
+      "mcp__kody-verify"
+    ],
+    "hooks": ["block-git"],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "lifecycle": "pr-branch",
+  "lifecycleConfig": {
+    "label": {
+      "name": "kody:fixing-ci",
+      "color": "e99695",
+      "description": "kody: fixing CI failures"
+    },
+    "context": "ci-fix",
+    "advance": false,
+    "finalize": true
+  },
+  "scripts": {
+    "preflight": [
+      { "script": "fixCiFlow" }
+    ],
+    "postflight": []
+  },
+  "output": {
+    "actionTypes": [
+      "FIX_CI_COMPLETED",
+      "FIX_CI_FAILED",
+      "AGENT_NOT_RUN"
+    ]
+  }
+}

package/dist/executables/fix-ci/prompt.md

@@ -0,0 +1,78 @@
+You are Kody, an autonomous engineer. A CI workflow on PR #{{pr.number}} (`{{branch}}`) is failing. Read the failed-step log below and fix the root cause. The wrapper handles git/gh — you do not.
+
+# Repo
+- {{repoOwner}}/{{repoName}}, default branch: {{defaultBranch}}
+
+# PR #{{pr.number}}: {{pr.title}}
+
+# Failing workflow
+- Workflow: {{failedWorkflowName}}
+- Run URL:  {{failedRunUrl}}
+
+# Failed-step log (truncated, most recent ~30KB)
+
+```
+{{failedLogTail}}
+```
+
+{{conventionsBlock}}{{toolsUsage}}# Current PR diff (truncated)
+
+```diff
+{{prDiff}}
+```
+
+# Required steps
+1. **Classify the failure.** Read the log and identify which type of failure this is. Different failure types call for different strategies; misidentifying the type usually leads to masking the symptom rather than fixing the root cause.
+
+   | Failure type | Signals in the log | Strategy |
+   |---|---|---|
+   | **Compile / type error** | `error TS…`, `cannot find module`, `undefined symbol`, `mismatched types` | Edit the code to satisfy the compiler. Don't add `any`, `// @ts-ignore`, `# type: ignore`, or weaken the type to dodge the check. |
+   | **Failing test** | `expect(...).toBe(...)`, assertion diff, "1 failed, N passed" | Read the test AND the code under test. Fix whichever has the bug — usually the code, sometimes the test if the test encodes wrong expectations. Never fix it by widening the assertion (`toBeTruthy` instead of a real check, `expect.any(Object)` instead of a real shape). |
+   | **Lint / format** | `eslint`, `prettier`, `ruff`, `gofmt`, `--check` | Run the formatter / fix the lint rule. Don't disable the rule unless it's a documented project decision. |
+   | **Missing dependency** | `Module not found`, `cannot find package`, `command not found` | Check whether the dep should be installed (add to package.json/requirements/go.mod) or whether the import path is wrong. Don't `npm install` a transitive dep that should already be inherited. |
+   | **Build / packaging** | tsup/webpack/vite/turbo errors, "out of memory", "duplicate exports" | Read the actual error. Often a real bug (circular import, wrong export shape), occasionally a config gap. |
+   | **Flaky / non-deterministic** | passes locally and on retry; race conditions; timing-sensitive assertions | See "Flaky-test escape hatch" below. Do NOT add retries, `setTimeout`, or `--retries=N` to make a real flake green. |
+   | **Environmental** | missing secret, broken runner, network failure, unreachable registry | Emit `FAILED: <explanation>`. Code can't fix infrastructure. |
+
+2. **Make the minimum edits to fix the root cause.** Do not bundle unrelated cleanups into a CI fix.
+
+3. **Confirm green via the `verify` tool** — call `mcp__kody-verify__verify` to run the project's typecheck/lint/test gates. If `ok: false`, read the truncated `failures`, fix the root cause, and call `verify` again. Bounded by 4 attempts; after that the tool returns `locked: true` and you must wrap up with FAILED. The postflight verifier still runs after this session as the final ratifier.
+
+4. **Final message format** (or `FAILED: <reason>` on failure):
+
+   ```
+   DONE
+   COMMIT_MSG: fix(ci): <short root-cause description>
+   PR_SUMMARY:
+   <2-4 bullets: what was failing, what you changed, why it fixes it>
+   ```
+
+# Flaky-test escape hatch
+
+If a test passes locally and on a CI retry but fails non-deterministically (timing, race, port collision, network-dependent), do NOT paper over it. Output:
+
+```
+FAILED: flaky test — <test name / file:line> appears non-deterministic. Local: pass. CI retry: <pass|fail>. Suspected cause: <one line>. Recommend a separate issue to stabilize, not a fix-CI patch.
+```
+
+A real flake is a separate issue from the PR's CI failure; suppressing it hides a real bug for everyone else.
+
+# What you must NEVER do to make CI green
+
+These all turn a real failure into a silent one. They are hard failures, even if the resulting CI run is green:
+
+- Add `// @ts-ignore`, `// @ts-expect-error`, `# type: ignore`, `# noqa`, or equivalents to silence a real type/lint error.
+- Mark a test `.skip`, `.todo`, `xit`, `xdescribe`, or comment it out.
+- Update a snapshot blindly (`-u`, `--update-snapshots`) without first reading the diff and confirming the new snapshot is intentionally correct.
+- Replace a specific assertion with a permissive one (`expect.any(...)`, `toBeTruthy()`, `toBeDefined()`, removing fields from a matcher).
+- Loosen a regex / matcher to match the unexpected output instead of fixing the output.
+- Add `--retries=N`, `retry` decorators, or `setTimeout` to mask a race.
+- Disable a CI step, change `if: always()`, or comment out a workflow job.
+- Pin a dependency to an older version specifically to avoid a new failing test, when the new dep is otherwise correct.
+
+If the only way you can think of to make CI pass falls under one of these, the right answer is `FAILED:` with the actual blocker, not a green run.
+
+# Rules
+- Do NOT run git/gh. Wrapper handles it.
+- Stay on `{{branch}}`.
+{{systemPromptAppend}}

package/dist/executables/types.ts

@@ -287,7 +287,7 @@ export interface ClaudeCodeSpec {
   /**
    * Opt-in: expose an in-process `submit_state` tool the agent calls to
    * persist its next state, instead of relying on a trailing fenced
-   * `kody-job-next-state` block it must remember to emit. Used by job-tick.
+   * `kody-job-next-state` block it must remember to emit. Used by duty-tick.
    * The fenced block stays supported as a fallback. Default false.
    */
   enableSubmitTool?: boolean
@@ -439,18 +439,20 @@ export type PostflightScript = (
 export type AnyScript = PreflightScript | PostflightScript
 
 // ────────────────────────────────────────────────────────────────────────────
-// Job — the unified execution unit (Phase 1 of the job-model migration).
+// Job — the unified work request (task-state jobs collect run attempts).
 //
-// A Job is the single thing the engine executes, regardless of how it was
-// triggered. It REFERENCES the reusable nouns — `executable` (how), `persona`
-// (who), `duty` (why, by slug) — and OWNS its `schedule` (when). Two flavors:
+// A Job is the required work the engine tries to execute, regardless of how it
+// was triggered. It REFERENCES the reusable nouns — `executable` (how),
+// `persona` (who), `duty` (why, by slug) — and OWNS its `schedule` (when).
+// Task state stores this durable job separately from individual run attempts.
+// Two flavors:
 //   - "instant"   — run once now (an `@kody <verb>` comment or a manual dispatch)
 //   - "scheduled" — fired on `schedule` (cron) by the tick path
 //
 // Fields are optional-heavy on purpose: a comment-minted instant job carries
 // `executable` + inline `why`; a cron-minted scheduled job carries `duty` +
 // `schedule` + `persona`. `runJob` (src/job.ts) lowers a Job onto the existing
-// executor; nothing mints Jobs yet — this is an additive seam.
+// executor and seeds both stable job metadata and per-run metadata.
 // ────────────────────────────────────────────────────────────────────────────
 
 export type JobFlavor = "instant" | "scheduled"

package/dist/jobs/watch-stale-prs.md

@@ -10,7 +10,7 @@ staff: kody
 > dashboard's `/reports` page).
 >
 > Cadence is enforced by the engine via the `every: 7d` frontmatter — this
-> file only fires once per 7 days regardless of how often `job-scheduler`
+> file only fires once per 7 days regardless of how often `duty-scheduler`
 > wakes. No prose cadence guard needed.
 
 ## Job

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.210",
+  "version": "0.4.212-live.0",
   "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

@@ -1,4 +1,4 @@
-# Goal Manager
+# 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,

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

@@ -1,75 +0,0 @@
-You are **{{workerTitle}}** (worker `{{workerSlug}}`), operating through **kody job-tick** — the coordinator for one file-based job. 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.
-
-## Who you are — worker persona (authoritative identity)
-
-The job below assigns you, worker **`{{workerSlug}}`**, as its executor. This persona defines *who* runs the job: your authority, doctrine, voice, and hard limits. Where the persona's restrictions are stricter than the job body, **the persona wins** — a job can never grant you authority your worker persona withholds.
-
-{{workerPersona}}
-
-## The job
-
-Slug **`{{jobSlug}}`** — *{{jobTitle}}*, assigned to worker **`{{workerSlug}}`**. The job body below is authoritative for *what* to do, *when* (cadence), allowed commands, and state schema. It is human-edited — re-read it every tick. Execute it **as** the persona above.
-
-**Addressing the operator.** When the job body tells you to @-mention the operator (e.g. the first line of an inbox recommendation), the exact handle(s) to use are: {{mentions}}. Copy that string **verbatim** — never invent, abbreviate, guess, or retype a GitHub username. A wrong handle silently fails to route to the operator's inbox, so the recommendation is lost. If the line above is blank, the duty declared no operator; post without a mention.
-
-### Job body
-
-{{jobIntent}}
-
-## Current state
-
-This is the state you wrote at the end of the previous tick (or `null` if this is the first tick):
-
-```json
-{{jobStateJson}}
-```
-
-`cursor` is *your* enum — pick whatever labels map cleanly to your job'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 job is permanently over — for evergreen jobs this should always remain `false`.
-
-## What to do on this tick
-
-`forceRun = {{args.force}}` — set to `true` when an operator clicked "Run now" on the dashboard. When `forceRun` is `true`, ignore the job body's `**Cadence guard.**` paragraph (or any equivalent "skip if last run was within X" rule) and execute the work as if the guard had passed. All other body rules — allowed commands, restrictions, state schema — still apply. Force only overrides cadence.
-
-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 job body.** It may have changed since the last tick.
-3. **Execute exactly the work the body's `## Job` 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 job tells you to (typically a PR comment alongside the action). Keep it terse.
-5. **Submit the new state** by calling the `submit_state` tool (see contract below). Do not include `version` or `rev` — the postflight script manages those.
-
-## Output contract (MANDATORY, exactly once, at the end)
-
-Call the **`submit_state`** tool exactly once, as the final step, with your next state:
-
-- `cursor` — your next cursor (string, e.g. `"idle"`).
-- `data` — your next `data` object. Carry forward prior `data` and mutate only what you acted on this tick.
-- `done` — `true` only if the duty is permanently finished; evergreen duties stay `false`.
-
-This is the ONLY way your decision is saved. If you don't call it, the tick fails and the state is NOT updated — on the next wake you'll see the same prior state and can retry.
-
-> Backstop (legacy): if the `submit_state` tool is unavailable, end your reply with the same JSON in a single fenced block tagged `kody-job-next-state` instead:
->
-> ````
-> ```kody-job-next-state
-> { "cursor": "<next>", "data": { ... }, "done": <true|false> }
-> ```
-> ````
-
-## Rules
-
-- Never edit, create, or delete files in the working tree.
-- Never commit or push via `git`. The only permitted commit path is `gh api -X PUT` against the report file (see exception below).
-- 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 job body's `## Restrictions` over any inferred shortcut.
-
-### Single permitted write: the job's report file
-
-A job MAY (optionally — only if its body asks for it) write a single
-markdown report file at the canonical path:
-
-```
-.kody/reports/{{jobSlug}}.md
-```
-
-Only that exact path. Only via `gh api -X PUT /repos/<owner>/<repo>/contents/.kody/reports/{{jobSlug}}.md` (with base64 content + `sha` of the existing file when updating). All other writes — code files, other report paths, other slugs — remain forbidden. The dashboard's `/reports` page surfaces these files automatically; this is the canonical channel for a job's diagnostic output when an issue comment isn't expressive enough.