From edf4ef97f8b87ca195a21e5b0806d8de65499a1b Mon Sep 17 00:00:00 2001
From: idorozin <rozin.ido@gmail.com>
Date: Fri, 20 Mar 2026 12:15:06 +0200
Subject: [PATCH 1/4] feat: add --github-order flag to control issue execution
 order

When using GitHub issues as a task source, issues are returned newest-first
by the API, which may not match the desired execution order. The new
--github-order flag accepts comma-separated issue numbers (e.g. 2,3,4,5,6)
to execute issues in a specific sequence. Only the listed issues are
executed, and in the exact order specified.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md                   |  4 ++++
 cli/src/cli/args.ts         |  4 ++++
 cli/src/cli/commands/run.ts |  1 +
 cli/src/config/types.ts     |  2 ++
 cli/src/tasks/github.ts     | 21 +++++++++++++++++++--
 cli/src/tasks/index.ts      |  4 +++-
 6 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 91c074a0..d81d5302 100644
--- a/README.md
+++ b/README.md
@@ -179,8 +179,11 @@ Titles must be unique.
 ```bash
 ralphy --github owner/repo
 ralphy --github owner/repo --github-label "ready"
+ralphy --github owner/repo --github-label "task" --github-order 2,3,4,5,6
 ```
 
+Use `--github-order` to execute issues in a specific order. Without it, issues are processed in the order returned by the GitHub API (newest first). The flag takes comma-separated issue numbers — only those issues will be executed, in the exact order specified.
+
 ## Parallel Execution
 
 ```bash
@@ -300,6 +303,7 @@ ralphy --parallel --sandbox
 | `--json FILE` | JSON task file |
 | `--github REPO` | use GitHub issues |
 | `--github-label TAG` | filter issues by label |
+| `--github-order 2,3,4` | execute issues in this order |
 | `--sync-issue N` | sync PRD progress to GitHub issue #N |
 | `--model NAME` | override model for any engine |
 | `--sonnet` | shortcut for `--claude --model sonnet` |
diff --git a/cli/src/cli/args.ts b/cli/src/cli/args.ts
index beadad1d..2e74bb40 100644
--- a/cli/src/cli/args.ts
+++ b/cli/src/cli/args.ts
@@ -49,6 +49,7 @@ export function createProgram(): Command {
 		.option("--json <file>", "JSON task file")
 		.option("--github <repo>", "GitHub repo for issues (owner/repo)")
 		.option("--github-label <label>", "Filter GitHub issues by label")
+		.option("--github-order <issues>", "Execute GitHub issues in this order (comma-separated issue numbers, e.g. 2,3,4,5,6)")
 		.option("--sync-issue <number>", "Sync PRD file to GitHub issue body on each iteration")
 		.option("--no-commit", "Don't auto-commit changes")
 		.option("--browser", "Enable browser automation (agent-browser)")
@@ -152,6 +153,9 @@ export function parseArgs(args: string[]): {
 		prdIsFolder,
 		githubRepo: opts.github || "",
 		githubLabel: opts.githubLabel || "",
+		githubOrder: opts.githubOrder
+			? opts.githubOrder.split(",").map((n: string) => Number.parseInt(n.trim(), 10))
+			: undefined,
 		syncIssue: opts.syncIssue ? Number.parseInt(opts.syncIssue, 10) || undefined : undefined,
 		autoCommit: opts.commit !== false,
 		browserEnabled: opts.browser === true ? "true" : opts.browser === false ? "false" : "auto",
diff --git a/cli/src/cli/commands/run.ts b/cli/src/cli/commands/run.ts
index e9fc95b7..7e93ac05 100644
--- a/cli/src/cli/commands/run.ts
+++ b/cli/src/cli/commands/run.ts
@@ -71,6 +71,7 @@ export async function runLoop(options: RuntimeOptions): Promise<void> {
 		filePath: options.prdFile,
 		repo: options.githubRepo,
 		label: options.githubLabel,
+		order: options.githubOrder,
 	});
 	const taskSource = new CachedTaskSource(innerTaskSource);
 
diff --git a/cli/src/config/types.ts b/cli/src/config/types.ts
index 6a292aa9..bf158b74 100644
--- a/cli/src/config/types.ts
+++ b/cli/src/config/types.ts
@@ -101,6 +101,8 @@ export interface RuntimeOptions {
 	githubRepo: string;
 	/** GitHub issue label filter */
 	githubLabel: string;
+	/** Ordered list of GitHub issue numbers to execute in sequence */
+	githubOrder?: number[];
 	/** GitHub issue number to sync PRD with on each iteration */
 	syncIssue?: number;
 	/** Auto-commit changes */
diff --git a/cli/src/tasks/github.ts b/cli/src/tasks/github.ts
index 651f01d3..9b4f50bc 100644
--- a/cli/src/tasks/github.ts
+++ b/cli/src/tasks/github.ts
@@ -25,9 +25,10 @@ export class GitHubTaskSource implements TaskSource {
 	private owner: string;
 	private repo: string;
 	private label?: string;
+	private order?: number[];
 	private cache: GitHubCache | null = null;
 
-	constructor(repoPath: string, label?: string) {
+	constructor(repoPath: string, label?: string, order?: number[]) {
 		// Parse owner/repo format
 		const [owner, repo] = repoPath.split("/");
 		if (!owner || !repo) {
@@ -37,6 +38,7 @@ export class GitHubTaskSource implements TaskSource {
 		this.owner = owner;
 		this.repo = repo;
 		this.label = label;
+		this.order = order;
 
 		// Use GITHUB_TOKEN from environment
 		this.octokit = new Octokit({
@@ -75,13 +77,28 @@ export class GitHubTaskSource implements TaskSource {
 			per_page: 100,
 		});
 
-		const tasks = issues.map((issue) => ({
+		let tasks = issues.map((issue) => ({
 			id: `${issue.number}:${issue.title}`,
 			title: issue.title,
 			body: issue.body || undefined,
 			completed: false,
 		}));
 
+		// Sort by specified order if provided
+		if (this.order && this.order.length > 0) {
+			const orderMap = new Map(this.order.map((num, idx) => [num, idx]));
+			tasks = tasks
+				.filter((t) => {
+					const issueNum = Number.parseInt(t.id.split(":")[0], 10);
+					return orderMap.has(issueNum);
+				})
+				.sort((a, b) => {
+					const aNum = Number.parseInt(a.id.split(":")[0], 10);
+					const bNum = Number.parseInt(b.id.split(":")[0], 10);
+					return (orderMap.get(aNum) ?? 0) - (orderMap.get(bNum) ?? 0);
+				});
+		}
+
 		// Update cache (preserve closed count if we have it)
 		this.cache = {
 			openIssues: tasks,
diff --git a/cli/src/tasks/index.ts b/cli/src/tasks/index.ts
index 445fb38b..738c3bb3 100644
--- a/cli/src/tasks/index.ts
+++ b/cli/src/tasks/index.ts
@@ -21,6 +21,8 @@ interface TaskSourceOptions {
 	repo?: string;
 	/** Label filter for GitHub source */
 	label?: string;
+	/** Ordered list of issue numbers to execute in sequence */
+	order?: number[];
 }
 
 /**
@@ -56,7 +58,7 @@ export function createTaskSource(options: TaskSourceOptions): TaskSource {
 			if (!options.repo) {
 				throw new Error("repo is required for github task source");
 			}
-			return new GitHubTaskSource(options.repo, options.label);
+			return new GitHubTaskSource(options.repo, options.label, options.order);
 
 		default:
 			throw new Error(`Unknown task source type: ${options.type}`);

From e7686d178ef9d9c692c17f33a062480755fe412f Mon Sep 17 00:00:00 2001
From: idorozin <rozin.ido@gmail.com>
Date: Fri, 20 Mar 2026 12:20:19 +0200
Subject: [PATCH 2/4] fix: validate NaN in --github-order and fix
 countCompleted filtering

- Filter out NaN values from parsed --github-order input so that
  non-numeric tokens (e.g. --github-order 2,abc,4) are silently
  ignored instead of producing unexpected behavior.
- When --github-order is set, countCompleted() now only counts closed
  issues whose numbers appear in the order list, consistent with
  fetchOpenIssues() which already filters by order.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 cli/src/cli/args.ts     | 5 ++++-
 cli/src/tasks/github.ts | 7 ++++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/cli/src/cli/args.ts b/cli/src/cli/args.ts
index 2e74bb40..24a7bf16 100644
--- a/cli/src/cli/args.ts
+++ b/cli/src/cli/args.ts
@@ -154,7 +154,10 @@ export function parseArgs(args: string[]): {
 		githubRepo: opts.github || "",
 		githubLabel: opts.githubLabel || "",
 		githubOrder: opts.githubOrder
-			? opts.githubOrder.split(",").map((n: string) => Number.parseInt(n.trim(), 10))
+			? opts.githubOrder
+					.split(",")
+					.map((n: string) => Number.parseInt(n.trim(), 10))
+					.filter((n: number) => !Number.isNaN(n))
 			: undefined,
 		syncIssue: opts.syncIssue ? Number.parseInt(opts.syncIssue, 10) || undefined : undefined,
 		autoCommit: opts.commit !== false,
diff --git a/cli/src/tasks/github.ts b/cli/src/tasks/github.ts
index 9b4f50bc..cf11e47a 100644
--- a/cli/src/tasks/github.ts
+++ b/cli/src/tasks/github.ts
@@ -156,7 +156,12 @@ export class GitHubTaskSource implements TaskSource {
 			per_page: 100,
 		});
 
-		const closedCount = issues.length;
+		// When order is specified, only count closed issues that are in the order list
+		let closedCount = issues.length;
+		if (this.order && this.order.length > 0) {
+			const orderSet = new Set(this.order);
+			closedCount = issues.filter((issue) => orderSet.has(issue.number)).length;
+		}
 
 		// Update cache with closed count
 		if (this.cache) {

From 76d062e7f96c6382b634e8924db34ddd454c74f3 Mon Sep 17 00:00:00 2001
From: idorozin <rozin.ido@gmail.com>
Date: Fri, 20 Mar 2026 12:26:19 +0200
Subject: [PATCH 3/4] fix: coerce empty --github-order to undefined

When all tokens in --github-order are invalid (e.g. ",,,"), the filtered
result is an empty array. Coerce it to undefined so the behavior falls
back to default API order instead of silently producing no tasks.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 cli/src/cli/args.ts | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/cli/src/cli/args.ts b/cli/src/cli/args.ts
index 24a7bf16..0895194c 100644
--- a/cli/src/cli/args.ts
+++ b/cli/src/cli/args.ts
@@ -154,10 +154,13 @@ export function parseArgs(args: string[]): {
 		githubRepo: opts.github || "",
 		githubLabel: opts.githubLabel || "",
 		githubOrder: opts.githubOrder
-			? opts.githubOrder
-					.split(",")
-					.map((n: string) => Number.parseInt(n.trim(), 10))
-					.filter((n: number) => !Number.isNaN(n))
+			? (() => {
+					const nums = opts.githubOrder
+						.split(",")
+						.map((n: string) => Number.parseInt(n.trim(), 10))
+						.filter((n: number) => !Number.isNaN(n));
+					return nums.length > 0 ? nums : undefined;
+				})()
 			: undefined,
 		syncIssue: opts.syncIssue ? Number.parseInt(opts.syncIssue, 10) || undefined : undefined,
 		autoCommit: opts.commit !== false,

From b1e5a2b258e3f611dda93582a55667bc55f53587 Mon Sep 17 00:00:00 2001
From: idorozin <rozin.ido@gmail.com>
Date: Fri, 20 Mar 2026 16:33:23 +0200
Subject: [PATCH 4/4] fix: parse issue numbers once, warn on missing ordered
 issues

- Parse issue number once per task instead of separately in filter and
  sort, removing the unreachable ?? 0 fallback.
- Warn when --github-order specifies issues not found among open issues,
  so typos and already-closed issues are surfaced to the user.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 cli/src/tasks/github.ts | 27 +++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/cli/src/tasks/github.ts b/cli/src/tasks/github.ts
index cf11e47a..86cb4bc5 100644
--- a/cli/src/tasks/github.ts
+++ b/cli/src/tasks/github.ts
@@ -87,16 +87,23 @@ export class GitHubTaskSource implements TaskSource {
 		// Sort by specified order if provided
 		if (this.order && this.order.length > 0) {
 			const orderMap = new Map(this.order.map((num, idx) => [num, idx]));
-			tasks = tasks
-				.filter((t) => {
-					const issueNum = Number.parseInt(t.id.split(":")[0], 10);
-					return orderMap.has(issueNum);
-				})
-				.sort((a, b) => {
-					const aNum = Number.parseInt(a.id.split(":")[0], 10);
-					const bNum = Number.parseInt(b.id.split(":")[0], 10);
-					return (orderMap.get(aNum) ?? 0) - (orderMap.get(bNum) ?? 0);
-				});
+			const tagged = tasks.map((t) => ({
+				task: t,
+				issueNum: Number.parseInt(t.id.split(":")[0], 10),
+			}));
+			const filtered = tagged.filter(({ issueNum }) => orderMap.has(issueNum));
+
+			const foundNums = new Set(filtered.map(({ issueNum }) => issueNum));
+			const missing = this.order.filter((n) => !foundNums.has(n));
+			if (missing.length > 0) {
+				console.warn(
+					`[ralphy] Warning: --github-order specified issues not found among open issues: ${missing.join(", ")}`,
+				);
+			}
+
+			tasks = filtered
+				.sort((a, b) => orderMap.get(a.issueNum)! - orderMap.get(b.issueNum)!)
+				.map(({ task }) => task);
 		}
 
 		// Update cache (preserve closed count if we have it)