@kody-ade/kody-engine 0.2.53 → 0.2.55

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.53",
+  version: "0.2.55",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -50,7 +50,7 @@ var package_default = {
 };
 
 // src/chat-cli.ts
-import { execFileSync as execFileSync20 } from "child_process";
+import { execFileSync as execFileSync21 } from "child_process";
 import * as fs22 from "fs";
 import * as path19 from "path";
 
@@ -182,9 +182,24 @@ function loadConfig(projectDir = process.cwd()) {
     issueContext: parseIssueContext(raw.issueContext),
     testRequirements: parseTestRequirements(raw.testRequirements),
     defaultExecutable: typeof raw.defaultExecutable === "string" && raw.defaultExecutable.length > 0 ? raw.defaultExecutable : void 0,
+    classify: parseClassifyConfig(raw.classify),
     release: parseReleaseConfig(raw.release)
   };
 }
+function parseClassifyConfig(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const r = raw;
+  const out = {};
+  if (r.labelMap && typeof r.labelMap === "object") {
+    const entries = Object.entries(r.labelMap).filter(
+      ([, v]) => typeof v === "string" && v.length > 0
+    );
+    if (entries.length > 0) {
+      out.labelMap = Object.fromEntries(entries.map(([k, v]) => [k.toLowerCase(), String(v)]));
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 function parseReleaseConfig(raw) {
   if (!raw || typeof raw !== "object") return void 0;
   const r = raw;
@@ -528,7 +543,7 @@ async function emit(sink, type, sessionId, suffix, payload) {
 }
 
 // src/kody2-cli.ts
-import { execFileSync as execFileSync19 } from "child_process";
+import { execFileSync as execFileSync20 } from "child_process";
 import * as fs21 from "fs";
 import * as path18 from "path";
 
@@ -738,6 +753,7 @@ import * as fs7 from "fs";
 import * as path6 from "path";
 var VALID_INPUT_TYPES = /* @__PURE__ */ new Set(["int", "string", "bool", "enum"]);
 var VALID_PERMISSION_MODES = /* @__PURE__ */ new Set(["default", "acceptEdits", "plan", "bypassPermissions"]);
+var VALID_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "watch", "utility"]);
 var ProfileError = class extends Error {
   constructor(profilePath, message) {
     super(`Invalid profile at ${profilePath}:
@@ -765,9 +781,17 @@ function loadProfile(profilePath) {
   if (kind === "scheduled" && typeof r.schedule !== "string") {
     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(" | ")}`
+    );
+  }
+  const role = r.role;
   const profile = {
     name: requireString(profilePath, r, "name"),
     describe: typeof r.describe === "string" ? r.describe : "",
+    role,
     kind,
     schedule: typeof r.schedule === "string" ? r.schedule : void 0,
     inputs: parseInputs(profilePath, r.inputs),
@@ -1490,6 +1514,41 @@ ${formatMissesForFeedback(misses)}`;
   ctx.data.coverageMisses = finalMisses;
 };
 
+// src/scripts/classifyByLabel.ts
+var VALID_CLASSES = /* @__PURE__ */ new Set(["feature", "bug", "spec", "chore"]);
+var classifyByLabel = async (ctx) => {
+  const issue = ctx.data.issue;
+  const labels = issue?.labels;
+  if (!labels || labels.length === 0) return;
+  const cfgMap = ctx.config.classify?.labelMap;
+  const map = cfgMap ?? defaultLabelMap();
+  for (const label of labels) {
+    const candidate = map[label.toLowerCase()];
+    if (candidate && VALID_CLASSES.has(candidate)) {
+      ctx.data.classification = candidate;
+      ctx.data.classificationSource = "label";
+      ctx.data.classificationReason = `label \`${label}\` \u2192 ${candidate}`;
+      ctx.skipAgent = true;
+      return;
+    }
+  }
+};
+function defaultLabelMap() {
+  return {
+    bug: "bug",
+    enhancement: "bug",
+    refactor: "feature",
+    feature: "feature",
+    performance: "feature",
+    rfc: "spec",
+    design: "spec",
+    spec: "spec",
+    docs: "chore",
+    chore: "chore",
+    dependencies: "chore"
+  };
+}
+
 // src/scripts/commitAndPush.ts
 import { execFileSync as execFileSync6 } from "child_process";
 
@@ -2357,7 +2416,7 @@ function gh2(args, options) {
   }).trim();
 }
 function getIssue(issueNumber, cwd) {
-  const output = gh2(["issue", "view", String(issueNumber), "--json", "number,title,body,comments"], { cwd });
+  const output = gh2(["issue", "view", String(issueNumber), "--json", "number,title,body,comments,labels"], { cwd });
   const parsed = JSON.parse(output);
   if (typeof parsed?.title !== "string") {
     throw new Error(`Issue #${issueNumber}: unexpected response shape`);
@@ -2370,12 +2429,16 @@ function getIssue(issueNumber, cwd) {
       body: c.body ?? "",
       author: c.author?.login ?? "unknown",
       createdAt: c.createdAt ?? ""
-    }))
+    })),
+    labels: Array.isArray(parsed.labels) ? parsed.labels.map((l) => l.name ?? "").filter((n) => n.length > 0) : []
   };
 }
+function stripKody2Mentions(body) {
+  return body.replace(/(@)(kody2)/gi, "$1\u200B$2");
+}
 function postIssueComment(issueNumber, body, cwd) {
   try {
-    gh2(["issue", "comment", String(issueNumber), "--body-file", "-"], { input: body, cwd });
+    gh2(["issue", "comment", String(issueNumber), "--body-file", "-"], { input: stripKody2Mentions(body), cwd });
   } catch (err) {
     process.stderr.write(
       `[kody2] failed to post comment on #${issueNumber}: ${err instanceof Error ? err.message : String(err)}
@@ -2460,7 +2523,7 @@ function getPrLatestReviewBody(prNumber, cwd) {
 }
 function postPrReviewComment(prNumber, body, cwd) {
   try {
-    gh2(["pr", "comment", String(prNumber), "--body-file", "-"], { input: body, cwd });
+    gh2(["pr", "comment", String(prNumber), "--body-file", "-"], { input: stripKody2Mentions(body), cwd });
   } catch (err) {
     process.stderr.write(
       `[kody2] failed to post review comment on PR #${prNumber}: ${err instanceof Error ? err.message : String(err)}
@@ -2698,7 +2761,11 @@ function parseGenericFlags(argv) {
 }
 
 // src/lifecycleLabels.ts
-var KODY_LABEL_PREFIX = "kody:";
+var KODY_NAMESPACE = "kody";
+function groupOf(label) {
+  const idx = label.indexOf(":");
+  return idx === -1 ? label : label.slice(0, idx + 1);
+}
 function collectProfileLabels() {
   const byLabel = /* @__PURE__ */ new Map();
   for (const exe of listExecutables()) {
@@ -2719,7 +2786,7 @@ function extractLabelSpec(entry) {
   const w = entry.with;
   if (!w) return null;
   const label = typeof w.label === "string" ? w.label : null;
-  if (!label || !label.startsWith(KODY_LABEL_PREFIX)) return null;
+  if (!label || !label.startsWith(KODY_NAMESPACE)) return null;
   return {
     label,
     color: typeof w.color === "string" ? w.color : void 0,
@@ -2766,16 +2833,17 @@ function createLabelInRepo(spec, cwd) {
 }
 function setKodyLabel(issueNumber, spec, cwd) {
   const target = spec.label;
-  if (!target.startsWith(KODY_LABEL_PREFIX)) {
+  if (!target.startsWith(KODY_NAMESPACE)) {
     process.stderr.write(
       `[kody2] setKodyLabel: refusing to set non-kody label "${target}"
 `
     );
     return;
   }
+  const targetGroup = groupOf(target);
   const present = getIssueLabels(issueNumber, cwd);
   for (const label of present) {
-    if (label !== target && label.startsWith(KODY_LABEL_PREFIX)) {
+    if (label !== target && label.startsWith(KODY_NAMESPACE) && groupOf(label) === targetGroup) {
       removeLabel(issueNumber, label, cwd);
     }
   }
@@ -2832,7 +2900,7 @@ var finishFlow = async (ctx, _profile, _agentResult, args) => {
   if (state) state.flow = void 0;
   if (!issueNumber) return;
   const label = typeof args?.label === "string" ? args.label : void 0;
-  if (label && label.startsWith(KODY_LABEL_PREFIX)) {
+  if (label && label.startsWith(KODY_NAMESPACE)) {
     setKodyLabel(
       issueNumber,
       {
@@ -3517,7 +3585,9 @@ var loadIssueContext = async (ctx) => {
   const kept = sorted.slice(0, limit);
   const commentsFormatted = kept.length === 0 ? "(no comments yet)" : kept.map((c) => `- **${c.author}** (${c.createdAt}):
   ${truncate2(c.body, maxBytes).replace(/\n/g, "\n  ")}`).join("\n\n");
-  ctx.data.issue = { ...issue, commentsFormatted };
+  const labels = issue.labels ?? [];
+  const labelsFormatted = labels.length === 0 ? "(no labels)" : labels.map((l) => `\`${l}\``).join(", ");
+  ctx.data.issue = { ...issue, commentsFormatted, labelsFormatted };
   ctx.data.commentTargetType = "issue";
   ctx.data.commentTargetNumber = issueNumber;
 };
@@ -3642,6 +3712,86 @@ var persistFlowState = async (ctx) => {
   }
 };
 
+// src/scripts/postClassification.ts
+import { execFileSync as execFileSync14 } from "child_process";
+var API_TIMEOUT_MS6 = 3e4;
+var VALID_CLASSES2 = /* @__PURE__ */ new Set(["feature", "bug", "spec", "chore"]);
+var postClassification = async (ctx) => {
+  const issueNumber = ctx.args.issue;
+  if (!issueNumber) return;
+  const presetClassification = ctx.data.classification;
+  let classification = null;
+  let reason = null;
+  if (presetClassification && VALID_CLASSES2.has(presetClassification)) {
+    classification = presetClassification;
+    reason = ctx.data.classificationReason ?? "label-based match";
+  } else {
+    const parsed = parseClassification(ctx.data.prSummary ?? "");
+    classification = parsed?.classification ?? null;
+    reason = parsed?.reason ?? null;
+  }
+  if (!classification) {
+    ctx.data.action = failedAction("classification missing or invalid");
+    tryAuditComment(issueNumber, "\u26A0\uFE0F kody2 classifier could not decide \u2014 please re-run with an explicit `@kody2 <type>`.", ctx.cwd);
+    ctx.output.exitCode = 1;
+    ctx.output.reason = "classify: no decision";
+    return;
+  }
+  tryAuditComment(
+    issueNumber,
+    `\u{1F50E} kody2 classified as \`${classification}\`${reason ? ` \u2014 ${reason}` : ""}`,
+    ctx.cwd
+  );
+  try {
+    execFileSync14("gh", ["issue", "comment", String(issueNumber), "--body", `@kody2 ${classification}`], {
+      cwd: ctx.cwd,
+      timeout: API_TIMEOUT_MS6,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 postClassification] failed to dispatch @kody2 ${classification}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    ctx.data.action = failedAction("dispatch post failed");
+    ctx.output.exitCode = 1;
+    ctx.output.reason = "classify: dispatch failed";
+    return;
+  }
+  ctx.data.action = makeAction2(`CLASSIFIED_AS_${classification.toUpperCase()}`, {
+    classification,
+    reason: reason ?? "",
+    source: ctx.data.classificationSource ?? "agent"
+  });
+  ctx.data.classification = classification;
+  ctx.data.classificationReason = reason ?? "";
+};
+function parseClassification(prSummary) {
+  if (!prSummary) return null;
+  const classMatch = prSummary.match(/classification:\s*(feature|bug|spec|chore)\b/i);
+  if (!classMatch) return null;
+  const classification = classMatch[1].toLowerCase();
+  const reasonMatch = prSummary.match(/reason:\s*(.+)$/im);
+  const reason = reasonMatch ? reasonMatch[1].trim() : "";
+  return { classification, reason };
+}
+function tryAuditComment(issueNumber, body, cwd) {
+  try {
+    execFileSync14("gh", ["issue", "comment", String(issueNumber), "--body", body], {
+      cwd,
+      timeout: API_TIMEOUT_MS6,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch {
+  }
+}
+function makeAction2(type, payload) {
+  return { type, payload, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function failedAction(reason) {
+  return { type: "CLASSIFY_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
+
 // src/scripts/postIssueComment.ts
 var postIssueComment2 = async (ctx) => {
   if (ctx.skipAgent && ctx.output.exitCode !== void 0) return;
@@ -3756,7 +3906,7 @@ function reviewAction(verdict, payload) {
   const type = verdict === "PASS" ? "REVIEW_PASS" : verdict === "CONCERNS" ? "REVIEW_CONCERNS" : verdict === "FAIL" ? "REVIEW_FAIL" : "REVIEW_COMPLETED";
   return { type, payload: { verdict, ...payload }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
-function failedAction(reason) {
+function failedAction2(reason) {
   return { type: "REVIEW_FAILED", payload: { reason }, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
 }
 var postReviewResult = async (ctx, _profile, agentResult) => {
@@ -3764,7 +3914,7 @@ var postReviewResult = async (ctx, _profile, agentResult) => {
   if (!prNumber) {
     ctx.output.exitCode = 99;
     ctx.output.reason = "review postflight: no PR number in context";
-    ctx.data.action = failedAction(ctx.output.reason);
+    ctx.data.action = failedAction2(ctx.output.reason);
     return;
   }
   if (!agentResult || agentResult.outcome !== "completed") {
@@ -3775,7 +3925,7 @@ var postReviewResult = async (ctx, _profile, agentResult) => {
     }
     ctx.output.exitCode = 1;
     ctx.output.reason = reason;
-    ctx.data.action = failedAction(reason);
+    ctx.data.action = failedAction2(reason);
     return;
   }
   const reviewBody = agentResult.finalText.trim();
@@ -3786,7 +3936,7 @@ var postReviewResult = async (ctx, _profile, agentResult) => {
     }
     ctx.output.exitCode = 1;
     ctx.output.reason = "empty review body";
-    ctx.data.action = failedAction("empty review body");
+    ctx.data.action = failedAction2("empty review body");
     return;
   }
   try {
@@ -3795,7 +3945,7 @@ var postReviewResult = async (ctx, _profile, agentResult) => {
     const msg = err instanceof Error ? err.message : String(err);
     ctx.output.exitCode = 4;
     ctx.output.reason = `failed to post review comment: ${msg}`;
-    ctx.data.action = failedAction(ctx.output.reason);
+    ctx.data.action = failedAction2(ctx.output.reason);
     return;
   }
   const verdict = detectVerdict(reviewBody);
@@ -3811,7 +3961,7 @@ REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.
 };
 
 // src/scripts/releaseFlow.ts
-import { execFileSync as execFileSync14, spawnSync } from "child_process";
+import { execFileSync as execFileSync15, spawnSync } from "child_process";
 import * as fs18 from "fs";
 import * as path16 from "path";
 function bumpVersion(current, bump) {
@@ -3841,7 +3991,7 @@ function generateChangelog(cwd, newVersion, lastTag) {
   const range = lastTag ? `${lastTag}..HEAD` : "HEAD";
   let log = "";
   try {
-    log = execFileSync14("git", ["log", range, "--pretty=format:%s||%h", "--no-merges"], {
+    log = execFileSync15("git", ["log", range, "--pretty=format:%s||%h", "--no-merges"], {
       cwd,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -3898,7 +4048,7 @@ ${entry}${prior.slice(idx + 1)}`);
   }
 }
 function git3(args, cwd, timeout = 6e4) {
-  return execFileSync14("git", args, {
+  return execFileSync15("git", args, {
     encoding: "utf-8",
     timeout,
     cwd,
@@ -4125,12 +4275,12 @@ function fail(ctx, profile, reason) {
   ctx.data.agentDone = false;
   ctx.data.agentFailureReason = reason;
   const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
-  const failedAction2 = {
+  const failedAction3 = {
     type: `${modeSeg}_FAILED`,
     payload: { reason },
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
-  ctx.data.action = failedAction2;
+  ctx.data.action = failedAction3;
 }
 function countActionItems(block) {
   if (!block.trim()) return 0;
@@ -4169,12 +4319,12 @@ function fail2(ctx, profile, reason) {
   ctx.data.agentDone = false;
   ctx.data.agentFailureReason = reason;
   const modeSeg = profile.name.replace(/-/g, "_").toUpperCase();
-  const failedAction2 = {
+  const failedAction3 = {
     type: `${modeSeg}_FAILED`,
     payload: { reason },
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
-  ctx.data.action = failedAction2;
+  ctx.data.action = failedAction3;
 }
 
 // src/scripts/resolveArtifacts.ts
@@ -4201,7 +4351,7 @@ var resolveArtifacts = async (ctx, profile) => {
 };
 
 // src/scripts/resolveFlow.ts
-import { execFileSync as execFileSync15 } from "child_process";
+import { execFileSync as execFileSync16 } from "child_process";
 var CONFLICT_DIFF_MAX_BYTES = 4e4;
 var resolveFlow = async (ctx) => {
   const prNumber = ctx.args.pr;
@@ -4253,7 +4403,7 @@ var resolveFlow = async (ctx) => {
 };
 function getConflictedFiles(cwd) {
   try {
-    const out = execFileSync15("git", ["diff", "--name-only", "--diff-filter=U"], {
+    const out = execFileSync16("git", ["diff", "--name-only", "--diff-filter=U"], {
       encoding: "utf-8",
       cwd,
       env: { ...process.env, HUSKY: "0" }
@@ -4268,7 +4418,7 @@ function getConflictMarkersPreview(files, cwd, maxBytes = CONFLICT_DIFF_MAX_BYTE
   let total = 0;
   for (const f of files) {
     try {
-      const content = execFileSync15("cat", [f], { encoding: "utf-8", cwd }).toString();
+      const content = execFileSync16("cat", [f], { encoding: "utf-8", cwd }).toString();
       const snippet = `### ${f}
 
 \`\`\`
@@ -4399,9 +4549,9 @@ function synthesizeAction(ctx) {
 // src/scripts/setLifecycleLabel.ts
 var setLifecycleLabel = async (ctx, _profile, args) => {
   const label = args?.label;
-  if (typeof label !== "string" || !label.startsWith(KODY_LABEL_PREFIX)) {
+  if (typeof label !== "string" || !label.startsWith(KODY_NAMESPACE)) {
     process.stderr.write(
-      `[kody2] setLifecycleLabel: missing or invalid "label" arg (must start with "${KODY_LABEL_PREFIX}"): ${String(label)}
+      `[kody2] setLifecycleLabel: missing or invalid "label" arg (must start with "${KODY_NAMESPACE}"): ${String(label)}
 `
     );
     return;
@@ -4432,8 +4582,8 @@ var skipAgent = async (ctx) => {
 };
 
 // src/scripts/startFlow.ts
-import { execFileSync as execFileSync16 } from "child_process";
-var API_TIMEOUT_MS6 = 3e4;
+import { execFileSync as execFileSync17 } from "child_process";
+var API_TIMEOUT_MS7 = 3e4;
 var startFlow = async (ctx, profile, _agentResult, args) => {
   const entry = args?.entry;
   if (!entry) {
@@ -4466,8 +4616,8 @@ function postKody2Comment(target, issueNumber, state, next, cwd) {
   const sub = target === "pr" && state?.core.prUrl ? "pr" : "issue";
   const body = `@kody2 ${next}`;
   try {
-    execFileSync16("gh", [sub, "comment", String(targetNumber), "--body", body], {
-      timeout: API_TIMEOUT_MS6,
+    execFileSync17("gh", [sub, "comment", String(targetNumber), "--body", body], {
+      timeout: API_TIMEOUT_MS7,
       cwd,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -4486,7 +4636,7 @@ function parsePr2(url) {
 }
 
 // src/scripts/syncFlow.ts
-import { execFileSync as execFileSync17 } from "child_process";
+import { execFileSync as execFileSync18 } from "child_process";
 var syncFlow = async (ctx) => {
   ctx.skipAgent = true;
   const prNumber = ctx.args.pr;
@@ -4545,7 +4695,7 @@ function bail2(ctx, prNumber, reason) {
 }
 function revParseHead(cwd) {
   try {
-    return execFileSync17("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
+    return execFileSync18("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
   } catch {
     return "";
   }
@@ -4553,9 +4703,9 @@ function revParseHead(cwd) {
 function pushBranch(branch, cwd) {
   const env = { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" };
   try {
-    execFileSync17("git", ["push", "-u", "origin", branch], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    execFileSync18("git", ["push", "-u", "origin", branch], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
   } catch {
-    execFileSync17("git", ["push", "--force-with-lease", "-u", "origin", branch], {
+    execFileSync18("git", ["push", "--force-with-lease", "-u", "origin", branch], {
       cwd,
       env,
       stdio: ["ignore", "pipe", "pipe"]
@@ -4773,7 +4923,8 @@ var preflightScripts = {
   resolvePreviewUrl,
   composePrompt,
   setLifecycleLabel,
-  skipAgent
+  skipAgent,
+  classifyByLabel
 };
 var postflightScripts = {
   parseAgentResult: parseAgentResult2,
@@ -4795,7 +4946,8 @@ var postflightScripts = {
   dispatch,
   finishFlow,
   advanceFlow,
-  persistFlowState
+  persistFlowState,
+  postClassification
 };
 var allScriptNames = /* @__PURE__ */ new Set([
   ...Object.keys(preflightScripts),
@@ -4803,7 +4955,7 @@ var allScriptNames = /* @__PURE__ */ new Set([
 ]);
 
 // src/tools.ts
-import { execFileSync as execFileSync18 } from "child_process";
+import { execFileSync as execFileSync19 } from "child_process";
 function verifyCliTools(tools, cwd) {
   const out = [];
   for (const t of tools) out.push(verifyOne(t, cwd));
@@ -4836,7 +4988,7 @@ function verifyOne(tool, cwd) {
 }
 function runShell2(cmd, cwd, timeoutMs = 3e4) {
   try {
-    execFileSync18("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
+    execFileSync19("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
     return true;
   } catch {
     return false;
@@ -5166,7 +5318,7 @@ function detectPackageManager2(cwd) {
 }
 function shellOut(cmd, args, cwd, stream = true) {
   try {
-    execFileSync19(cmd, args, {
+    execFileSync20(cmd, args, {
       cwd,
       stdio: stream ? "inherit" : "pipe",
       env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1", CI: process.env.CI ?? "1" }
@@ -5179,7 +5331,7 @@ function shellOut(cmd, args, cwd, stream = true) {
 }
 function isOnPath(bin) {
   try {
-    execFileSync19("which", [bin], { stdio: "pipe" });
+    execFileSync20("which", [bin], { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -5213,7 +5365,7 @@ function installLitellmIfNeeded(cwd) {
   } catch {
   }
   try {
-    execFileSync19("python3", ["-c", "import litellm"], { stdio: "pipe" });
+    execFileSync20("python3", ["-c", "import litellm"], { stdio: "pipe" });
     process.stdout.write("\u2192 kody2: litellm already installed\n");
     return 0;
   } catch {
@@ -5223,16 +5375,16 @@ function installLitellmIfNeeded(cwd) {
 }
 function configureGitIdentity(cwd) {
   try {
-    const name = execFileSync19("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
+    const name = execFileSync20("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
     if (name) return;
   } catch {
   }
   try {
-    execFileSync19("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
+    execFileSync20("git", ["config", "user.name", "github-actions[bot]"], { cwd, stdio: "pipe" });
   } catch {
   }
   try {
-    execFileSync19("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
+    execFileSync20("git", ["config", "user.email", "41898282+github-actions[bot]@users.noreply.github.com"], {
       cwd,
       stdio: "pipe"
     });
@@ -5409,9 +5561,9 @@ function commitChatFiles(cwd, sessionId, verbose) {
   if (paths.length === 0) return;
   const opts = { cwd, stdio: verbose ? "inherit" : "pipe" };
   try {
-    execFileSync20("git", ["add", ...paths], opts);
-    execFileSync20("git", ["commit", "--quiet", "-m", `chat: reply for ${sessionId}`], opts);
-    execFileSync20("git", ["push", "--quiet", "origin", "HEAD"], opts);
+    execFileSync21("git", ["add", ...paths], opts);
+    execFileSync21("git", ["commit", "--quiet", "-m", `chat: reply for ${sessionId}`], opts);
+    execFileSync21("git", ["push", "--quiet", "origin", "HEAD"], opts);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[kody2:chat] commit/push skipped: ${msg}

package/dist/executables/bug/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "bug",
+  "role": "orchestrator",
   "describe": "Sub-orchestrator for bug / enhancement issues — plan → run → review (→ fix on concerns/fail). No agent — the postflight entries ARE the transition table, evaluated top-to-bottom via runWhen.",
   "inputs": [
     {
@@ -27,6 +28,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody-flow:bug",
+          "color": "d73a4a",
+          "description": "kody2 flow: bug / enhancement"
+        }
+      },
       {
         "script": "setLifecycleLabel",
         "with": {

package/dist/executables/chore/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "chore",
+  "role": "orchestrator",
   "describe": "Sub-orchestrator for chore / docs / dep-bump issues — run → review (→ fix on concerns/fail). Skips planning entirely. No agent.",
   "inputs": [
     {
@@ -27,6 +28,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody-flow:chore",
+          "color": "c5def5",
+          "description": "kody2 flow: chore / docs / dep-bump"
+        }
+      },
       {
         "script": "setLifecycleLabel",
         "with": {

package/dist/executables/classify/profile.json

@@ -0,0 +1,64 @@
+{
+  "name": "classify",
+  "role": "primitive",
+  "describe": "Classify an issue into one of {feature, bug, spec, chore} and dispatch the matching sub-orchestrator. Label-first fast path; LLM fallback when labels don't decide.",
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number to classify."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [
+      "Read",
+      "Bash"
+    ],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:classifying",
+          "color": "0e8a16",
+          "description": "kody2: classifying the issue"
+        }
+      },
+      { "script": "loadIssueContext" },
+      { "script": "loadTaskState" },
+      { "script": "classifyByLabel" },
+      { "script": "loadConventions" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "parseAgentResult" },
+      { "script": "postClassification" },
+      { "script": "writeRunSummary" },
+      { "script": "saveTaskState" }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "CLASSIFIED_AS_FEATURE",
+      "CLASSIFIED_AS_BUG",
+      "CLASSIFIED_AS_SPEC",
+      "CLASSIFIED_AS_CHORE",
+      "CLASSIFY_FAILED"
+    ]
+  }
+}

package/dist/executables/classify/prompt.md

@@ -0,0 +1,49 @@
+You are Kody's issue-triage classifier. Your only job: read the issue below and pick ONE of the four flow types.
+
+# Repo
+{{repoOwner}}/{{repoName}}, default branch `{{defaultBranch}}`
+
+# Issue #{{issue.number}}: {{issue.title}}
+
+Labels: {{issue.labelsFormatted}}
+
+{{issue.body}}
+
+Recent comments (most recent first, truncated):
+{{issue.commentsFormatted}}
+
+{{conventionsBlock}}
+
+---
+
+# Classification rubric
+
+Pick **exactly one** of:
+
+- **feature** — new user-facing capability, refactor, performance work, or anything where scope is not fully known up front. Multi-file change likely. Use when the issue opens a design space (even if small).
+- **bug** — fix broken behavior, enhancement to existing feature, or any targeted change where the scope is localized and well understood. Skip research; go straight to plan.
+- **spec** — produce a design doc, RFC, architecture proposal, or exploration artifact. No code changes. Terminates at the plan artifact.
+- **chore** — trivial maintenance: docs tweak, dep bump, lint fix, README update. No planning needed.
+
+**If the issue ASKS for an RFC / design doc / spec / analysis with no implementation → `spec`.** Beats everything else.
+**If the issue is plainly "fix X" or "add tiny Y to existing Z" with clear boundaries → `bug`.**
+**If the issue is "tweak config / bump dep / fix typo" with no real design choice → `chore`.**
+**Otherwise → `feature`.**
+
+# Required output
+
+Your FINAL message must be exactly this shape (no extra text before or after):
+
+```
+DONE
+COMMIT_MSG: classify: <classification>
+PR_SUMMARY:
+classification: <feature|bug|spec|chore>
+reason: <one sentence explaining the pick, grounded in the issue text>
+```
+
+# Rules
+
+- Read-only. Do NOT modify any file. Do NOT run git or gh.
+- Output `FAILED: <reason>` if the issue is incoherent or ambiguous beyond the rubric.
+- Do not over-think. This is triage, not analysis.

package/dist/executables/feature/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "feature",
+  "role": "orchestrator",
   "describe": "Sub-orchestrator for feature / refactor issues — research → plan → run → review (→ fix on concerns/fail). No agent — the postflight entries ARE the transition table, evaluated top-to-bottom via runWhen.",
   "inputs": [
     {
@@ -27,6 +28,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody-flow:feature",
+          "color": "a2eeef",
+          "description": "kody2 flow: feature / refactor"
+        }
+      },
       {
         "script": "setLifecycleLabel",
         "with": {

package/dist/executables/fix/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "fix",
+  "role": "primitive",
   "describe": "Apply review feedback to an existing PR branch.",
   "inputs": [
     {

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

@@ -1,5 +1,6 @@
 {
   "name": "fix-ci",
+  "role": "primitive",
   "describe": "Fix a failing CI workflow on an existing PR.",
   "inputs": [
     {

package/dist/executables/init/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "init",
+  "role": "utility",
   "describe": "Scaffold a consumer repo with kody.config.json and the @kody2 workflow. No agent.",
   "inputs": [
     {

package/dist/executables/plan/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "plan",
+  "role": "primitive",
   "describe": "Research an issue and produce a concrete implementation plan as a comment. Read-only \u2014 no branches, no commits.",
   "inputs": [
     {

package/dist/executables/plan-verify/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "plan-verify",
+  "role": "utility",
   "describe": "Live-test executable. Loads kody-live-marker skill, /kody-live-probe command, kody-live-trace hook, and the bundled test-plugin. Asks the agent to emit confirmation tokens for each feature so Kody2 can validate plugin wiring end-to-end.",
   "inputs": [
     { "name": "issue", "flag": "--issue", "type": "int", "required": true, "describe": "GitHub issue number to verify against." }

package/dist/executables/release/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "release",
+  "role": "utility",
   "describe": "Version bump + changelog + release PR (prepare), or tag + publish + GH release (finalize). No agent.",
   "inputs": [
     {

package/dist/executables/research/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "research",
+  "role": "primitive",
   "describe": "Research an issue: understand the ask, map relevant repo context, and surface clarifying questions + gaps. Read-only — no branches, no commits, no prescribed next steps.",
   "inputs": [
     {
@@ -67,6 +68,9 @@
       },
       {
         "script": "saveTaskState"
+      },
+      {
+        "script": "advanceFlow"
       }
     ]
   },

package/dist/executables/resolve/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "resolve",
+  "role": "primitive",
   "describe": "Resolve merge conflicts between a PR branch and the default branch.",
   "inputs": [
     {

package/dist/executables/review/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "review",
+  "role": "primitive",
   "describe": "Read-only structured review of an open PR. Posts one comment, never commits.",
   "inputs": [
     {

package/dist/executables/run/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "run",
+  "role": "primitive",
   "describe": "Implement a GitHub issue end-to-end: branch, code, commit, open PR.",
   "inputs": [
     {

package/dist/executables/spec/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "spec",
+  "role": "orchestrator",
   "describe": "Sub-orchestrator for spec / RFC / design-doc issues — research → plan (stop). Terminates at the plan artifact; no run, no PR. No agent.",
   "inputs": [
     {
@@ -27,6 +28,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody-flow:spec",
+          "color": "7057ff",
+          "description": "kody2 flow: spec / RFC / design-doc"
+        }
+      },
       {
         "script": "setLifecycleLabel",
         "with": {

package/dist/executables/sync/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "sync",
+  "role": "primitive",
   "describe": "Merge the default (base) branch into a PR branch and push. No agent.",
   "inputs": [
     {

package/dist/executables/types.ts

@@ -18,7 +18,19 @@ export interface Profile {
   name: string
   describe: string
   /**
-   * Execution model. `oneshot` (default): single invocation on demand.
+   * Semantic role — what this executable IS, not when it runs.
+   *   - primitive:    single-step agent executor (flow → agent → verify → commit → PR).
+   *   - orchestrator: no-agent, drives primitives via a postflight transition table.
+   *   - watch:        scheduled observer that inspects repo state and may trigger other executables.
+   *   - utility:      no-agent, one-off administrative work (scaffolding, release, etc.).
+   *
+   * Roles enforce shape at profile-load time and let help/dispatch treat
+   * executables differently by category.
+   */
+  role: "primitive" | "orchestrator" | "watch" | "utility"
+  /**
+   * Execution model — orthogonal to `role`.
+   * `oneshot` (default): single invocation on demand.
    * `scheduled`: fires periodically via an external cron (typically GHA
    * `schedule:`). Scheduled profiles must declare a `schedule` cron string.
    */

package/dist/executables/ui-review/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "ui-review",
+  "role": "primitive",
   "describe": "UI/UX review of an open PR: browses the running preview with Playwright, compares behavior to diff intent, posts one structured review comment. Read-only on the repo (no commits); writes a throwaway Playwright spec under .kody2/.",
   "kind": "oneshot",
   "inputs": [

package/dist/executables/watch-stale-prs/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "watch-stale-prs",
+  "role": "watch",
   "describe": "Scheduled: list open PRs untouched for N days and report. No agent invocation.",
   "kind": "scheduled",
   "schedule": "0 8 * * MON",

package/package.json

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