@xn-intenton-z2a/agentic-lib 7.1.48 → 7.1.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.1.48",
+  "version": "7.1.49",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/actions/agentic-step/copilot.js

@@ -6,6 +6,7 @@
 
 import { CopilotClient, approveAll } from "@github/copilot-sdk";
 import { readFileSync, readdirSync, existsSync } from "fs";
+import { join } from "path";
 import { createAgentTools } from "./tools.js";
 import * as core from "@actions/core";
 
@@ -157,10 +158,10 @@ export function scanDirectory(dirPath, extensions, options = {}) {
     .slice(0, fileLimit)
     .map((f) => {
       try {
-        const content = readFileSync(`${dirPath}${f}`, "utf8");
+        const content = readFileSync(join(dirPath, f), "utf8");
         return { name: f, content: contentLimit ? content.substring(0, contentLimit) : content };
       } catch (err) {
-        core.debug(`[scanDirectory] ${dirPath}${f}: ${err.message}`);
+        core.debug(`[scanDirectory] ${join(dirPath, f)}: ${err.message}`);
         return { name: f, content: "" };
       }
     });

package/src/actions/agentic-step/tasks/enhance-issue.js

@@ -4,26 +4,18 @@
 //
 // Takes an issue and enhances it with clear, testable acceptance criteria
 // so that the resolve-issue task can implement it effectively.
+// Supports batch mode: when no issueNumber is provided, enhances up to 3 issues.
 
 import * as core from "@actions/core";
 import { isIssueResolved } from "../safety.js";
 import { runCopilotTask, readOptionalFile, scanDirectory } from "../copilot.js";
 
 /**
- * Enhance a GitHub issue with testable acceptance criteria.
- *
- * @param {Object} context - Task context from index.js
- * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ * Enhance a single GitHub issue with testable acceptance criteria.
  */
-export async function enhanceIssue(context) {
-  const { octokit, repo, config, issueNumber, instructions, model } = context;
-
-  if (!issueNumber) {
-    throw new Error("enhance-issue task requires issue-number input");
-  }
-
+async function enhanceSingleIssue({ octokit, repo, config, issueNumber, instructions, model }) {
   if (await isIssueResolved(octokit, repo, issueNumber)) {
-    return { outcome: "nop", details: "Issue already resolved" };
+    return { outcome: "nop", details: `Issue #${issueNumber} already resolved` };
   }
 
   const { data: issue } = await octokit.rest.issues.get({
@@ -32,11 +24,11 @@ export async function enhanceIssue(context) {
   });
 
   if (issue.labels.some((l) => l.name === "ready")) {
-    return { outcome: "nop", details: "Issue already has ready label" };
+    return { outcome: "nop", details: `Issue #${issueNumber} already has ready label` };
   }
 
   const contributing = readOptionalFile(config.paths.contributing.path);
-  const features = scanDirectory(config.paths.features.path, ".md", { contentLimit: 500 });
+  const features = scanDirectory(config.paths.features.path, ".md", { contentLimit: 2000 });
 
   const agentInstructions = instructions || "Enhance this issue with clear, testable acceptance criteria.";
 
@@ -61,7 +53,13 @@ export async function enhanceIssue(context) {
     "Output ONLY the new issue body text, no markdown code fences.",
   ].join("\n");
 
-  const { content: enhancedBody, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+  const {
+    content: enhancedBody,
+    tokensUsed,
+    inputTokens,
+    outputTokens,
+    cost,
+  } = await runCopilotTask({
     model,
     systemMessage: "You are a requirements analyst. Enhance GitHub issues with clear, testable acceptance criteria.",
     prompt,
@@ -105,3 +103,72 @@ export async function enhanceIssue(context) {
     details: `Enhanced issue #${issueNumber} with acceptance criteria`,
   };
 }
+
+/**
+ * Enhance a GitHub issue with testable acceptance criteria.
+ * When no issueNumber is provided, enhances up to 3 unready automated issues.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function enhanceIssue(context) {
+  const { octokit, repo, config, issueNumber, instructions, model } = context;
+
+  // Single issue mode
+  if (issueNumber) {
+    return enhanceSingleIssue({ octokit, repo, config, issueNumber, instructions, model });
+  }
+
+  // Batch mode: find up to 3 unready automated issues
+  const { data: openIssues } = await octokit.rest.issues.listForRepo({
+    ...repo,
+    state: "open",
+    labels: "automated",
+    per_page: 20,
+    sort: "created",
+    direction: "asc",
+  });
+  const unready = openIssues.filter((i) => !i.labels.some((l) => l.name === "ready")).slice(0, 3);
+
+  if (unready.length === 0) {
+    return { outcome: "nop", details: "No unready automated issues to enhance" };
+  }
+
+  const results = [];
+  let totalTokens = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let totalCost = 0;
+
+  for (const issue of unready) {
+    core.info(`Batch enhancing issue #${issue.number} (${results.length + 1}/${unready.length})`);
+    const result = await enhanceSingleIssue({
+      octokit,
+      repo,
+      config,
+      issueNumber: issue.number,
+      instructions,
+      model,
+    });
+    results.push(result);
+    totalTokens += result.tokensUsed || 0;
+    totalInputTokens += result.inputTokens || 0;
+    totalOutputTokens += result.outputTokens || 0;
+    totalCost += result.cost || 0;
+  }
+
+  const enhanced = results.filter((r) => r.outcome === "issue-enhanced").length;
+
+  return {
+    outcome: enhanced > 0 ? "issues-enhanced" : "nop",
+    tokensUsed: totalTokens,
+    inputTokens: totalInputTokens,
+    outputTokens: totalOutputTokens,
+    cost: totalCost,
+    model,
+    details: `Batch enhanced ${enhanced}/${results.length} issues. ${results
+      .map((r) => r.details)
+      .join("; ")
+      .substring(0, 500)}`,
+  };
+}

package/src/actions/agentic-step/tasks/fix-code.js

@@ -6,8 +6,36 @@
 // generates fixes using the Copilot SDK, and pushes a commit.
 
 import * as core from "@actions/core";
+import { execSync } from "child_process";
 import { runCopilotTask, formatPathsSection } from "../copilot.js";
 
+/**
+ * Extract run_id from a check run's details_url.
+ * e.g. "https://github.com/owner/repo/actions/runs/12345" → "12345"
+ */
+function extractRunId(detailsUrl) {
+  if (!detailsUrl) return null;
+  const match = detailsUrl.match(/\/runs\/(\d+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Fetch actual test output from a GitHub Actions run log.
+ */
+function fetchRunLog(runId) {
+  try {
+    const output = execSync(`gh run view ${runId} --log-failed`, {
+      encoding: "utf8",
+      timeout: 30000,
+      env: { ...process.env },
+    });
+    return output.substring(0, 8000);
+  } catch (err) {
+    core.debug(`[fix-code] Could not fetch log for run ${runId}: ${err.message}`);
+    return null;
+  }
+}
+
 /**
  * Fix failing code on a pull request.
  *
@@ -31,7 +59,19 @@ export async function fixCode(context) {
     return { outcome: "nop", details: "No failing checks found" };
   }
 
-  const failureDetails = failedChecks.map((cr) => `**${cr.name}:** ${cr.output?.summary || "Failed"}`).join("\n");
+  // Build detailed failure information with actual test logs where possible
+  const failureDetails = failedChecks
+    .map((cr) => {
+      const runId = extractRunId(cr.details_url);
+      let logContent = null;
+      if (runId) {
+        logContent = fetchRunLog(runId);
+      }
+      const detail = logContent || cr.output?.summary || "Failed";
+      return `**${cr.name}:**\n${detail}`;
+    })
+    .join("\n\n");
+
   const agentInstructions = instructions || "Fix the failing tests by modifying the source code.";
   const readOnlyPaths = config.readOnlyPaths;
 

package/src/actions/agentic-step/tasks/review-issue.js

@@ -4,56 +4,24 @@
 //
 // Checks open issues against the current codebase to determine
 // if they have been resolved, and closes them if so.
+// Supports batch mode: when no issueNumber is provided, reviews up to 3 issues.
 
 import * as core from "@actions/core";
 import { runCopilotTask, scanDirectory } from "../copilot.js";
 
 /**
- * Review open issues and close those that have been resolved.
+ * Review a single issue against the current codebase.
  *
- * @param {Object} context - Task context from index.js
+ * @param {Object} params
+ * @param {Object} params.octokit - GitHub API client
+ * @param {Object} params.repo - { owner, repo }
+ * @param {Object} params.config - Loaded config
+ * @param {number} params.targetIssueNumber - Issue number to review
+ * @param {string} params.instructions - Agent instructions
+ * @param {string} params.model - Model name
  * @returns {Promise<Object>} Result with outcome, tokensUsed, model
  */
-export async function reviewIssue(context) {
-  const { octokit, repo, config, issueNumber, instructions, model } = context;
-
-  // If no specific issue, review the oldest open automated issue that hasn't been recently reviewed
-  let targetIssueNumber = issueNumber;
-  if (!targetIssueNumber) {
-    const { data: openIssues } = await octokit.rest.issues.listForRepo({
-      ...repo,
-      state: "open",
-      labels: "automated",
-      per_page: 5,
-      sort: "created",
-      direction: "asc",
-    });
-    if (openIssues.length === 0) {
-      return { outcome: "nop", details: "No open automated issues to review" };
-    }
-    // Try each issue, skipping ones that already have a recent automated review comment
-    for (const candidate of openIssues) {
-      const { data: comments } = await octokit.rest.issues.listComments({
-        ...repo,
-        issue_number: candidate.number,
-        per_page: 5,
-        sort: "created",
-        direction: "desc",
-      });
-      const hasRecentReview = comments.some(
-        (c) => c.body?.includes("**Automated Review Result:**") && Date.now() - new Date(c.created_at).getTime() < 86400000,
-      );
-      if (!hasRecentReview) {
-        targetIssueNumber = candidate.number;
-        break;
-      }
-    }
-    // Fall back to the oldest if all have been recently reviewed
-    if (!targetIssueNumber) {
-      targetIssueNumber = openIssues[0].number;
-    }
-  }
-
+async function reviewSingleIssue({ octokit, repo, config, targetIssueNumber, instructions, model }) {
   const { data: issue } = await octokit.rest.issues.get({
     ...repo,
     issue_number: Number(targetIssueNumber),
@@ -64,13 +32,19 @@ export async function reviewIssue(context) {
   }
 
   const sourceFiles = scanDirectory(config.paths.source.path, [".js", ".ts"], {
-    contentLimit: 2000,
+    contentLimit: 5000,
+    fileLimit: 20,
     recursive: true,
   });
   const testFiles = scanDirectory(config.paths.tests.path, [".test.js", ".test.ts"], {
-    contentLimit: 2000,
+    contentLimit: 5000,
+    fileLimit: 20,
     recursive: true,
   });
+  const docsFiles = scanDirectory(config.paths.documentation?.path || "docs/", [".md"], {
+    fileLimit: 10,
+    contentLimit: 2000,
+  });
 
   const agentInstructions = instructions || "Review whether this issue has been resolved by the current codebase.";
 
@@ -87,6 +61,9 @@ export async function reviewIssue(context) {
     `## Current Tests (${testFiles.length} files)`,
     ...testFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
     "",
+    ...(docsFiles.length > 0
+      ? [`## Documentation (${docsFiles.length} files)`, ...docsFiles.map((f) => `- ${f.name}`), ""]
+      : []),
     config.configToml ? `## Configuration (agentic-lib.toml)\n\`\`\`toml\n${config.configToml}\n\`\`\`` : "",
     config.packageJson ? `## Dependencies (package.json)\n\`\`\`json\n${config.packageJson}\n\`\`\`` : "",
     "",
@@ -97,7 +74,13 @@ export async function reviewIssue(context) {
     '- "OPEN: <reason>" if the issue is not yet resolved',
   ].join("\n");
 
-  const { content: verdict, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+  const {
+    content: verdict,
+    tokensUsed,
+    inputTokens,
+    outputTokens,
+    cost,
+  } = await runCopilotTask({
     model,
     systemMessage: "You are a code reviewer determining if GitHub issues have been resolved.",
     prompt,
@@ -150,3 +133,98 @@ export async function reviewIssue(context) {
     details: `Issue #${targetIssueNumber} remains open: ${verdict.substring(0, 200)}`,
   };
 }
+
+/**
+ * Find unreviewed automated issues (no recent automated review comment).
+ */
+async function findUnreviewedIssues(octokit, repo, limit) {
+  const { data: openIssues } = await octokit.rest.issues.listForRepo({
+    ...repo,
+    state: "open",
+    labels: "automated",
+    per_page: limit + 5,
+    sort: "created",
+    direction: "asc",
+  });
+  if (openIssues.length === 0) return [];
+
+  const unreviewed = [];
+  for (const candidate of openIssues) {
+    if (unreviewed.length >= limit) break;
+    const { data: comments } = await octokit.rest.issues.listComments({
+      ...repo,
+      issue_number: candidate.number,
+      per_page: 5,
+      sort: "created",
+      direction: "desc",
+    });
+    const hasRecentReview = comments.some(
+      (c) =>
+        c.body?.includes("**Automated Review Result:**") && Date.now() - new Date(c.created_at).getTime() < 86400000,
+    );
+    if (!hasRecentReview) {
+      unreviewed.push(candidate.number);
+    }
+  }
+
+  // Fall back to oldest if all have been recently reviewed
+  if (unreviewed.length === 0 && openIssues.length > 0) {
+    unreviewed.push(openIssues[0].number);
+  }
+
+  return unreviewed;
+}
+
+/**
+ * Review open issues and close those that have been resolved.
+ * When no issueNumber is provided, reviews up to 3 issues in batch mode.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function reviewIssue(context) {
+  const { octokit, repo, config, issueNumber, instructions, model } = context;
+
+  // Single issue mode
+  if (issueNumber) {
+    return reviewSingleIssue({ octokit, repo, config, targetIssueNumber: issueNumber, instructions, model });
+  }
+
+  // Batch mode: find up to 3 unreviewed issues
+  const issueNumbers = await findUnreviewedIssues(octokit, repo, 3);
+  if (issueNumbers.length === 0) {
+    return { outcome: "nop", details: "No open automated issues to review" };
+  }
+
+  const results = [];
+  let totalTokens = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let totalCost = 0;
+
+  for (const num of issueNumbers) {
+    core.info(`Batch reviewing issue #${num} (${results.length + 1}/${issueNumbers.length})`);
+    const result = await reviewSingleIssue({ octokit, repo, config, targetIssueNumber: num, instructions, model });
+    results.push(result);
+    totalTokens += result.tokensUsed || 0;
+    totalInputTokens += result.inputTokens || 0;
+    totalOutputTokens += result.outputTokens || 0;
+    totalCost += result.cost || 0;
+  }
+
+  const closed = results.filter((r) => r.outcome === "issue-closed").length;
+  const reviewed = results.length;
+
+  return {
+    outcome: closed > 0 ? "issues-closed" : "issues-reviewed",
+    tokensUsed: totalTokens,
+    inputTokens: totalInputTokens,
+    outputTokens: totalOutputTokens,
+    cost: totalCost,
+    model,
+    details: `Batch reviewed ${reviewed} issues, closed ${closed}. ${results
+      .map((r) => r.details)
+      .join("; ")
+      .substring(0, 500)}`,
+  };
+}

package/src/actions/agentic-step/tasks/supervise.js

@@ -29,16 +29,16 @@ async function gatherContext(octokit, repo, config) {
     ...repo,
     state: "open",
     per_page: 20,
-    sort: "updated",
-    direction: "desc",
+    sort: "created",
+    direction: "asc",
+  });
+  const issuesOnly = openIssues.filter((i) => !i.pull_request);
+  const oldestReadyIssue = issuesOnly.find((i) => i.labels.some((l) => l.name === "ready"));
+  const issuesSummary = issuesOnly.map((i) => {
+    const age = Math.floor((Date.now() - new Date(i.created_at).getTime()) / 86400000);
+    const labels = i.labels.map((l) => l.name).join(", ");
+    return `#${i.number}: ${i.title} [${labels || "no labels"}] (${age}d old)`;
   });
-  const issuesSummary = openIssues
-    .filter((i) => !i.pull_request)
-    .map((i) => {
-      const age = Math.floor((Date.now() - new Date(i.created_at).getTime()) / 86400000);
-      const labels = i.labels.map((l) => l.name).join(", ");
-      return `#${i.number}: ${i.title} [${labels || "no labels"}] (${age}d old)`;
-    });
 
   const { data: openPRs } = await octokit.rest.pulls.list({
     ...repo,
@@ -72,6 +72,7 @@ async function gatherContext(octokit, repo, config) {
     libraryNames,
     libraryLimit,
     issuesSummary,
+    oldestReadyIssue,
     prsSummary,
     workflowsSummary,
     supervisor: config.supervisor,
@@ -117,6 +118,9 @@ function buildPrompt(ctx, agentInstructions) {
     "```",
     "",
     ...(ctx.packageJson ? ["### Dependencies (package.json)", "```json", ctx.packageJson, "```", ""] : []),
+    ...(ctx.oldestReadyIssue
+      ? [`### Oldest Ready Issue`, `#${ctx.oldestReadyIssue.number}: ${ctx.oldestReadyIssue.title}`, ""]
+      : []),
     `### Issue Limits`,
     `Feature development WIP limit: ${ctx.featureIssuesWipLimit}`,
     `Maintenance WIP limit: ${ctx.maintenanceIssuesWipLimit}`,
@@ -126,7 +130,7 @@ function buildPrompt(ctx, agentInstructions) {
     "Pick one or more actions. Output them in the format below.",
     "",
     "### Workflow Dispatches",
-    "- `dispatch:agent-flow-transform` — Pick up next issue, generate code, open PR",
+    "- `dispatch:agent-flow-transform | issue-number: <N>` — Pick up issue #N, generate code, open PR. Always specify the issue-number of the oldest ready issue.",
     "- `dispatch:agent-flow-maintain` — Refresh feature definitions and library docs",
     "- `dispatch:agent-flow-review` — Close resolved issues, enhance issue criteria",
     "- `dispatch:agent-flow-fix-code | pr-number: <N>` — Fix a failing PR",
@@ -190,6 +194,26 @@ async function executeDispatch(octokit, repo, actionName, params) {
   const workflowFile = actionName.replace("dispatch:", "") + ".yml";
   const inputs = {};
   if (params["pr-number"]) inputs["pr-number"] = params["pr-number"];
+  if (params["issue-number"]) inputs["issue-number"] = params["issue-number"];
+
+  // Guard: skip transform dispatch if one is already running
+  if (workflowFile === "agent-flow-transform.yml") {
+    try {
+      const { data: runs } = await octokit.rest.actions.listWorkflowRuns({
+        ...repo,
+        workflow_id: "agent-flow-transform.yml",
+        status: "in_progress",
+        per_page: 1,
+      });
+      if (runs.total_count > 0) {
+        core.info("Transform workflow already running — skipping dispatch");
+        return "skipped:transform-already-running";
+      }
+    } catch (err) {
+      core.warning(`Could not check transform status: ${err.message}`);
+    }
+  }
+
   core.info(`Dispatching workflow: ${workflowFile}`);
   await octokit.rest.actions.createWorkflowDispatch({ ...repo, workflow_id: workflowFile, ref: "main", inputs });
   return `dispatched:${workflowFile}`;
@@ -229,11 +253,13 @@ async function executeRespondDiscussions(octokit, repo, params) {
   const url = params["discussion-url"] || "";
   if (message) {
     core.info(`Dispatching discussions bot with response: ${message.substring(0, 100)}`);
+    const inputs = { message };
+    if (url) inputs["discussion-url"] = url;
     await octokit.rest.actions.createWorkflowDispatch({
       ...repo,
       workflow_id: "agent-discussions-bot.yml",
       ref: "main",
-      inputs: {},
+      inputs,
     });
     return `respond-discussions:${url || "no-url"}`;
   }

package/src/actions/agentic-step/tasks/transform.js

@@ -15,7 +15,7 @@ import { runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection } f
  * @returns {Promise<Object>} Result with outcome, tokensUsed, model
  */
 export async function transform(context) {
-  const { config, instructions, writablePaths, testCommand, model, octokit, repo } = context;
+  const { config, instructions, writablePaths, testCommand, model, octokit, repo, issueNumber } = context;
 
   // Read mission (required)
   const mission = readOptionalFile(config.paths.mission.path);
@@ -26,7 +26,7 @@ export async function transform(context) {
 
   const features = scanDirectory(config.paths.features.path, ".md");
   const sourceFiles = scanDirectory(config.paths.source.path, [".js", ".ts"], {
-    contentLimit: 2000,
+    contentLimit: 5000,
     recursive: true,
   });
 
@@ -36,6 +36,20 @@ export async function transform(context) {
     per_page: 20,
   });
 
+  // Fetch target issue if specified
+  let targetIssue = null;
+  if (issueNumber) {
+    try {
+      const { data: issue } = await octokit.rest.issues.get({
+        ...repo,
+        issue_number: Number(issueNumber),
+      });
+      targetIssue = issue;
+    } catch (err) {
+      core.warning(`Could not fetch target issue #${issueNumber}: ${err.message}`);
+    }
+  }
+
   const agentInstructions =
     instructions || "Transform the repository toward its mission by identifying the next best action.";
   const readOnlyPaths = config.readOnlyPaths;
@@ -60,17 +74,27 @@ export async function transform(context) {
     "## Instructions",
     agentInstructions,
     "",
+    ...(targetIssue
+      ? [
+          `## Target Issue #${targetIssue.number}: ${targetIssue.title}`,
+          targetIssue.body || "(no description)",
+          `Labels: ${targetIssue.labels.map((l) => l.name).join(", ") || "none"}`,
+          "",
+          "**Focus your transformation on resolving this specific issue.**",
+          "",
+        ]
+      : []),
     "## Mission",
     mission,
     "",
     `## Current Features (${features.length})`,
-    ...features.map((f) => `### ${f.name}\n${f.content.substring(0, 500)}`),
+    ...features.map((f) => `### ${f.name}\n${f.content.substring(0, 2000)}`),
     "",
     `## Current Source Files (${sourceFiles.length})`,
     ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
     "",
     `## Open Issues (${openIssues.length})`,
-    ...openIssues.slice(0, 10).map((i) => `- #${i.number}: ${i.title}`),
+    ...openIssues.slice(0, 20).map((i) => `- #${i.number}: ${i.title}`),
     "",
     "## Output Artifacts",
     "If your changes produce output artifacts (plots, visualizations, data files, usage examples),",
@@ -90,7 +114,13 @@ export async function transform(context) {
 
   core.info(`Transform prompt length: ${prompt.length} chars`);
 
-  const { content: resultContent, tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+  const {
+    content: resultContent,
+    tokensUsed,
+    inputTokens,
+    outputTokens,
+    cost,
+  } = await runCopilotTask({
     model,
     systemMessage:
       "You are an autonomous code transformation agent. Your goal is to advance the repository toward its mission by making the most impactful change possible in a single step.",
@@ -145,13 +175,13 @@ async function transformTdd({
     mission,
     "",
     `## Current Features (${features.length})`,
-    ...features.map((f) => `### ${f.name}\n${f.content.substring(0, 500)}`),
+    ...features.map((f) => `### ${f.name}\n${f.content.substring(0, 2000)}`),
     "",
     `## Current Source Files (${sourceFiles.length})`,
     ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
     "",
     `## Open Issues (${openIssues.length})`,
-    ...openIssues.slice(0, 10).map((i) => `- #${i.number}: ${i.title}`),
+    ...openIssues.slice(0, 20).map((i) => `- #${i.number}: ${i.title}`),
     "",
     formatPathsSection(writablePaths, readOnlyPaths, _config),
     "",

package/src/agents/agent-supervisor.md

@@ -64,6 +64,10 @@ When the transform agent has implemented all major features but minor polish rem
 2. `set-schedule:weekly` — reduce to weekly maintenance check-ins
 3. Check that `docs/` contains evidence of the library working before declaring done
 
+## Prerequisites
+
+- The `set-schedule` action requires a `WORKFLOW_TOKEN` secret (classic PAT with `workflow` scope) to push workflow file changes to main.
+
 ## Guidelines
 
 - Pick multiple actions when appropriate — concurrent work is encouraged.

package/src/seeds/zero-package.json

@@ -14,7 +14,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.1.48"
+    "@xn-intenton-z2a/agentic-lib": "^7.1.49"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.0",

package/src/workflows/agent-flow-review.yml

@@ -92,29 +92,11 @@ jobs:
         with:
           node-version: "24"
 
-      - name: Find issue to enhance
-        id: find-issue
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const { data: issues } = await github.rest.issues.listForRepo({
-              ...context.repo,
-              state: 'open',
-              labels: 'automated',
-              per_page: 20,
-              sort: 'created',
-              direction: 'asc',
-            });
-            const unready = issues.filter(i => !i.labels.some(l => l.name === 'ready'));
-            core.setOutput('issueNumber', unready.length > 0 ? String(unready[0].number) : '');
-
       - name: Install agentic-step dependencies
-        if: steps.find-issue.outputs.issueNumber != ''
         working-directory: .github/agentic-lib/actions/agentic-step
         run: npm ci
 
-      - name: Enhance issue
-        if: steps.find-issue.outputs.issueNumber != ''
+      - name: Enhance issues (batch)
         uses: ./.github/agentic-lib/actions/agentic-step
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -123,5 +105,4 @@ jobs:
           task: "enhance-issue"
           config: ${{ env.configPath }}
           instructions: ".github/agentic-lib/agents/agent-ready-issue.md"
-          issue-number: ${{ steps.find-issue.outputs.issueNumber }}
           model: ${{ needs.params.outputs.model }}

package/src/workflows/agent-flow-transform.yml

@@ -14,6 +14,11 @@ concurrency:
 on:
   workflow_dispatch:
     inputs:
+      issue-number:
+        description: "Issue number to target (optional)"
+        type: string
+        required: false
+        default: ""
       model:
         description: "Copilot SDK model to use"
         type: choice
@@ -53,6 +58,20 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Determine branch name
+        id: branch
+        shell: bash
+        run: |
+          ISSUE_NUMBER="${{ inputs.issue-number }}"
+          if [ -n "$ISSUE_NUMBER" ]; then
+            BRANCH="agentic-lib-issue-${ISSUE_NUMBER}"
+          else
+            BRANCH="agentic-lib-transform-${{ github.run_id }}"
+          fi
+          git checkout -b "${BRANCH}" 2>/dev/null || git checkout "${BRANCH}"
+          echo "branchName=${BRANCH}" >> $GITHUB_OUTPUT
+          echo "issueNumber=${ISSUE_NUMBER}" >> $GITHUB_OUTPUT
+
       - uses: actions/setup-node@v4
         with:
           node-version: "24"
@@ -86,10 +105,97 @@ jobs:
           instructions: ".github/agentic-lib/agents/agent-issue-resolution.md"
           test-command: "npm test"
           model: ${{ needs.params.outputs.model }}
+          issue-number: ${{ inputs.issue-number }}
           writable-paths: ${{ steps.config.outputs.writablePaths }}
 
       - name: Commit and push changes
         uses: ./.github/agentic-lib/actions/commit-if-changed
         with:
           commit-message: "agentic-step: transform"
-          push-ref: ${{ github.ref_name }}
+          push-ref: ${{ steps.branch.outputs.branchName }}
+    outputs:
+      branchName: ${{ steps.branch.outputs.branchName }}
+      issueNumber: ${{ steps.branch.outputs.issueNumber }}
+
+  create-pr:
+    needs: [params, transform]
+    if: always() && needs.transform.result == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR if branch has changes
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const branchName = '${{ needs.transform.outputs.branchName }}';
+            const issueNumber = '${{ needs.transform.outputs.issueNumber }}';
+
+            if (!branchName) {
+              core.info('No branch name — skipping PR creation');
+              return;
+            }
+
+            // Check if branch has commits ahead of main
+            try {
+              const { data: comparison } = await github.rest.repos.compareCommitsWithBasehead({
+                owner, repo,
+                basehead: `main...${branchName}`,
+              });
+              if (comparison.ahead_by === 0) {
+                core.info('Branch has no new commits — skipping PR creation');
+                return;
+              }
+            } catch (err) {
+              core.info(`Branch comparison failed (branch may not exist): ${err.message}`);
+              return;
+            }
+
+            // Check if PR already exists for this branch
+            const { data: existingPRs } = await github.rest.pulls.list({
+              owner, repo,
+              state: 'open',
+              head: `${owner}:${branchName}`,
+              per_page: 1,
+            });
+            if (existingPRs.length > 0) {
+              core.info(`PR already exists: #${existingPRs[0].number}`);
+              return;
+            }
+
+            // Create PR
+            const title = issueNumber
+              ? `fix: resolve issue #${issueNumber}`
+              : `agentic-step: transform (run ${context.runId})`;
+            const body = issueNumber
+              ? `Closes #${issueNumber}\n\nAutomated transformation targeting issue #${issueNumber}.`
+              : `Automated transformation run.`;
+
+            const { data: pr } = await github.rest.pulls.create({
+              owner, repo,
+              title,
+              body,
+              head: branchName,
+              base: 'main',
+            });
+            core.info(`Created PR #${pr.number}: ${pr.html_url}`);
+
+            // Add automerge label
+            await github.rest.issues.addLabels({
+              owner, repo,
+              issue_number: pr.number,
+              labels: ['automerge'],
+            });
+
+            // Add in-progress label to issue if specified
+            if (issueNumber) {
+              try {
+                await github.rest.issues.addLabels({
+                  owner, repo,
+                  issue_number: parseInt(issueNumber),
+                  labels: ['in-progress'],
+                });
+              } catch (err) {
+                core.warning(`Could not label issue #${issueNumber}: ${err.message}`);
+              }
+            }

package/src/workflows/agent-supervisor-schedule.yml

@@ -94,6 +94,20 @@ jobs:
               );
             }
 
+            // Always stamp the file with current date so the commit is never empty
+            // (GitHub re-registers cron schedules on push)
+            const dateStamp = `# Schedule updated: ${new Date().toISOString()}`;
+            const stampRegex = /^# Schedule updated: .*/m;
+            if (stampRegex.test(content)) {
+              content = content.replace(stampRegex, dateStamp);
+            } else {
+              // Insert after the header comment block
+              content = content.replace(
+                /^(# .*\n)+/m,
+                (match) => match + dateStamp + '\n'
+              );
+            }
+
             fs.writeFileSync(workflowPath, content);
             core.info(`Updated supervisor schedule to: ${frequency} (cron: ${cron || 'none'})`);
 
@@ -146,3 +160,9 @@ jobs:
           git diff --cached --quiet && echo "No changes to commit" && exit 0
           git commit -m "supervisor: set schedule to ${FREQUENCY}, model to ${MODEL:-gpt-5-mini}"
           git push origin main
+
+      - name: Dispatch supervisor
+        if: inputs.frequency != 'off'
+        env:
+          GH_TOKEN: ${{ secrets.WORKFLOW_TOKEN }}
+        run: gh workflow run agent-supervisor.yml --repo $GITHUB_REPOSITORY

package/src/workflows/agent-supervisor.yml

@@ -16,6 +16,9 @@
 
 name: agent-supervisor
 run-name: "agent-supervisor [${{ github.ref_name }}]"
+concurrency:
+  group: agentic-lib-supervisor
+  cancel-in-progress: false
 
 on:
   workflow_run:
@@ -50,7 +53,7 @@ permissions:
   discussions: write
 
 env:
-  maxFixAttempts: "3"
+  maxFixAttempts: "3"  # Corresponds to limits.attempts-per-branch in agentic-lib.toml
   stalePrDays: "3"
   configPath: ".github/agentic-lib/agents/agentic-lib.yml"
 
@@ -190,7 +193,36 @@ jobs:
               core.warning(`Post-transform review dispatch failed: ${err.message}`);
             }
 
-            // ─── 4. Successful init → dispatch discussions bot to announce new mission ───
+            // ─── 4. Stuck automerge recovery ─────────────────────────────────
+            try {
+              const { data: openPRs2 } = await github.rest.pulls.list({
+                owner, repo, state: 'open',
+                per_page: 10,
+              });
+              for (const pr of openPRs2) {
+                const hasAutomerge = pr.labels.some(l => l.name === 'automerge');
+                if (!hasAutomerge) continue;
+
+                const { data: fullPr } = await github.rest.pulls.get({
+                  owner, repo, pull_number: pr.number,
+                });
+
+                if (fullPr.mergeable_state === 'clean' && fullPr.mergeable === true) {
+                  core.info(`PR #${pr.number} is clean and mergeable but stuck — dispatching ci-automerge.`);
+                  await github.rest.actions.createWorkflowDispatch({
+                    owner, repo,
+                    workflow_id: 'ci-automerge.yml',
+                    ref: 'main',
+                    inputs: {},
+                  });
+                  break; // One dispatch per evaluate cycle
+                }
+              }
+            } catch (err) {
+              core.warning(`Stuck automerge check failed: ${err.message}`);
+            }
+
+            // ─── 5. Successful init → dispatch discussions bot to announce new mission ───
             try {
               if (workflowRun && workflowName === 'init' && conclusion === 'success') {
                 core.info('Init completed successfully — dispatching discussions bot to announce.');