feat: add --github-order flag to control issue execution order

[idorozin]

Summary

• Adds --github-order <issues> CLI flag that accepts comma-separated issue numbers (e.g. --github-order 2,3,4,5,6)
• When set, only the specified issues are executed, in the exact order given
• Without it, behavior is unchanged (issues returned in API default order)

Motivation: When using --github to pull tasks from GitHub Issues, the API returns issues newest-first. For sequential workflows where tasks have dependencies (e.g. "project setup" before "database layer" before "API routes"), you need control over execution order.

Changes

• cli/src/cli/args.ts — new --github-order option, parsed into number[] with NaN filtering and empty-array coercion
• cli/src/config/types.ts — githubOrder?: number[] added to RuntimeOptions
• cli/src/tasks/github.ts — filter and sort fetched issues by the specified order, warn on missing issues, consistent countCompleted() filtering
• cli/src/tasks/index.ts — pass order through to GitHubTaskSource
• cli/src/cli/commands/run.ts — wire githubOrder into createTaskSource
• README.md — documented in GitHub Issues section and Options table

Example

# Execute issues #2, #3, #4, #5, #6 in that exact order
ralphy --github owner/repo --github-label "task" --github-order 2,3,4,5,6 --claude

Test plan

• Tested manually against a real repo with 5 GitHub issues — confirmed correct execution order
• Verify --github-order without --github is a no-op (flag is only read by GitHubTaskSource)
• Verify omitting --github-order preserves existing behavior (guard checks this.order && this.order.length > 0)
• Non-numeric tokens in --github-order are filtered out (NaN filter)
• Fully invalid input (e.g. --github-order ,,,) coerces to undefined, falls back to default behavior
• countCompleted() only counts closed issues in the order list when --github-order is set
• Warning logged when ordered issue numbers are not found among open issues

🤖 Generated with Claude Code

Note

Add --github-order flag to control GitHub issue execution order

• Adds a --github-order <issues> CLI flag that accepts a comma-separated list of issue numbers, parsed into options.githubOrder in args.ts.
• When provided, GitHubTaskSource in github.ts filters open issues to only those specified and sorts them to match the given order; closed issue counts are also scoped to that list.
• Issues specified in --github-order that are not found among open issues trigger a console.warn.
• Default behavior (newest-first from the GitHub API) is unchanged when the flag is omitted.

^{Macroscope summarized b1e5a2b.}

[vercel]

@idorozin is attempting to deploy a commit to the Goshen Labs Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Summary

This PR adds a --github-order <issues> CLI flag that lets users specify an exact execution sequence for GitHub issues (e.g. --github-order 2,3,4,5,6), addressing the need for dependency-ordered sequential workflows when using --github.

The implementation is well-structured — argument parsing correctly handles invalid tokens and empty inputs, the type system is cleanly extended, and the filtering/sorting logic in GitHubTaskSource is sound. However, two logic issues need attention before merging:

• False-positive warning on every task completion (github.ts lines 96–102): The "issues not found among open issues" warning is triggered on every cache refresh after an issue is closed. Since issues are closed as they complete, this fires repeatedly throughout a normal run, telling the user that the issue they just successfully processed "was not found."
• Silent incompatibility with --parallel (run.ts lines 116–143): Using --github-order together with --parallel silently ignores the ordering guarantee. The tasks are sorted correctly but dispatched concurrently, which is contrary to the flag's documented purpose of enforcing dependency order. No warning or error is emitted.

Confidence Score: 2/5

• Not safe to merge — the missing-issue warning fires as a false positive on every completed task, and --github-order is silently broken when combined with --parallel.
• The core sorting and filtering logic is correct and NaN/empty-input edge cases are handled. However, two logic bugs will manifest in common usage: the warning spam after each issue is processed creates a poor and confusing UX, and the --parallel incompatibility can cause dependency-ordered workflows to silently execute out of order with potential race conditions.
• cli/src/tasks/github.ts (false-positive warning) and cli/src/cli/commands/run.ts (missing parallel-mode guard).

Important Files Changed

Filename	Overview
cli/src/tasks/github.ts	Core implementation of --github-order filtering and sorting; contains a logic bug where the missing-issue warning fires as a false positive on every cache refresh after issues are closed during normal operation.
cli/src/cli/commands/run.ts	Wires githubOrder into createTaskSource correctly, but provides no guard against using --github-order with --parallel, which silently breaks the ordering guarantee.
cli/src/cli/args.ts	Parses --github-order into number[]; correctly handles NaN filtering and coerces an empty result to undefined.
cli/src/config/types.ts	Adds optional githubOrder?: number[] to RuntimeOptions — straightforward and correct.
cli/src/tasks/index.ts	Adds order to TaskSourceOptions and passes it through to GitHubTaskSource — clean plumbing change.
README.md	Documents --github-order in the GitHub Issues section and options table — accurate and clear.

Sequence Diagram

sequenceDiagram
    participant CLI as CLI (args.ts)
    participant Run as runLoop (run.ts)
    participant Factory as createTaskSource (index.ts)
    participant GH as GitHubTaskSource (github.ts)
    participant API as GitHub API

    CLI->>CLI: parse --github-order "2,3,4,5"<br/>→ [2,3,4,5]
    CLI->>Run: RuntimeOptions { githubOrder: [2,3,4,5] }
    Run->>Factory: createTaskSource({ type:"github", order:[2,3,4,5] })
    Factory->>GH: new GitHubTaskSource(repo, label, [2,3,4,5])
    Run->>GH: fetchOpenIssues()
    GH->>API: listForRepo(state:"open", labels:...)
    API-->>GH: all open issues (unordered)
    GH->>GH: build orderMap {2→0, 3→1, 4→2, 5→3}
    GH->>GH: filter tasks to only issue #s in orderMap
    GH->>GH: warn if any order numbers not in open issues
    GH->>GH: sort filtered tasks by orderMap index
    GH-->>Run: [task#2, task#3, task#4, task#5]
    Run->>GH: markComplete("2:title")
    GH->>API: update(issue_number:2, state:"closed")
    GH->>GH: invalidateCache()
    Run->>GH: fetchOpenIssues() [cache miss]
    GH->>API: listForRepo(state:"open") — issue#2 now absent
    GH->>GH: missing = [2] → ⚠️ false-positive warning fires

Loading

Comments Outside Diff (1)

1. cli/src/cli/commands/run.ts, line 116-143 (link)

   --github-order silently incompatible with --parallel

   When both --github-order and --parallel are supplied, runParallel is invoked. The fetchOpenIssues method returns tasks in the correct sorted order, but runParallel will dispatch multiple tasks concurrently — completely defeating the ordering guarantee that --github-order is meant to provide.

   The PR description explicitly states this flag is for "sequential workflows where tasks have dependencies." Running those dependent tasks in parallel could cause race conditions or hard-to-debug failures, and the user receives no hint that the ordering contract is not being honored.

   Consider adding an early-exit check to warn (or error) when both flags are active:

   if (options.githubOrder && options.parallel) {
       logError("--github-order is incompatible with --parallel: ordered execution requires sequential mode.");
       process.exit(1);
   }

   If a warning-only approach is preferred, swap logError + process.exit for logInfo or console.warn.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: cli/src/cli/commands/run.ts
   Line: 116-143
   
   Comment:
   **`--github-order` silently incompatible with `--parallel`**
   
   When both `--github-order` and `--parallel` are supplied, `runParallel` is invoked. The `fetchOpenIssues` method returns tasks in the correct sorted order, but `runParallel` will dispatch multiple tasks concurrently — completely defeating the ordering guarantee that `--github-order` is meant to provide.
   
   The PR description explicitly states this flag is for "sequential workflows where tasks have dependencies." Running those dependent tasks in parallel could cause race conditions or hard-to-debug failures, and the user receives no hint that the ordering contract is not being honored.
   
   Consider adding an early-exit check to warn (or error) when both flags are active:
   
   ```ts
   if (options.githubOrder && options.parallel) {
       logError("--github-order is incompatible with --parallel: ordered execution requires sequential mode.");
       process.exit(1);
   }
   ```
   
   If a warning-only approach is preferred, swap `logError` + `process.exit` for `logInfo` or `console.warn`.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: cli/src/tasks/github.ts
Line: 96-102

Comment:
**Warning fires as false positive after issues are closed**

The missing-issue warning is emitted on every cache refresh, not just the first time. During normal operation, once issue `#2` is processed and closed via `markComplete()`, the cache is invalidated. The next call to `fetchOpenIssues()` fetches only `state: "open"` issues, so issue `#2` is no longer in the results. The check on line 97 then flags it as missing and emits the warning — even though it was just successfully completed.

This means a user running `--github-order 2,3,4,5` will see "Warning: issues not found among open issues: 2" after processing the very first issue, then "...2, 3" after the second, and so on. This is confusing and may cause users to think something went wrong when the workflow is proceeding correctly.

Consider filtering `this.order` to exclude issues that have already been closed before computing `missing`. You can cross-reference with the closed-count query, or simply only warn on the first fetch (e.g. when `this.cache` is null):

```ts
// Only warn on the initial fetch, not on subsequent refreshes after issues are closed
const isFirstFetch = !this.cache;
const foundNums = new Set(filtered.map(({ issueNum }) => issueNum));
const missing = this.order.filter((n) => !foundNums.has(n));
if (isFirstFetch && missing.length > 0) {
    console.warn(
        `[ralphy] Warning: --github-order specified issues not found among open issues: ${missing.join(", ")}`,
    );
}
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: cli/src/cli/commands/run.ts
Line: 116-143

Comment:
**`--github-order` silently incompatible with `--parallel`**

When both `--github-order` and `--parallel` are supplied, `runParallel` is invoked. The `fetchOpenIssues` method returns tasks in the correct sorted order, but `runParallel` will dispatch multiple tasks concurrently — completely defeating the ordering guarantee that `--github-order` is meant to provide.

The PR description explicitly states this flag is for "sequential workflows where tasks have dependencies." Running those dependent tasks in parallel could cause race conditions or hard-to-debug failures, and the user receives no hint that the ordering contract is not being honored.

Consider adding an early-exit check to warn (or error) when both flags are active:

```ts
if (options.githubOrder && options.parallel) {
    logError("--github-order is incompatible with --parallel: ordered execution requires sequential mode.");
    process.exit(1);
}
```

If a warning-only approach is preferred, swap `logError` + `process.exit` for `logInfo` or `console.warn`.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "fix: parse issue num..."}

[greptile-apps]

Warning fires as false positive after issues are closed

The missing-issue warning is emitted on every cache refresh, not just the first time. During normal operation, once issue #2 is processed and closed via markComplete(), the cache is invalidated. The next call to fetchOpenIssues() fetches only state: "open" issues, so issue #2 is no longer in the results. The check on line 97 then flags it as missing and emits the warning — even though it was just successfully completed.

This means a user running --github-order 2,3,4,5 will see "Warning: issues not found among open issues: 2" after processing the very first issue, then "...2, 3" after the second, and so on. This is confusing and may cause users to think something went wrong when the workflow is proceeding correctly.

Consider filtering this.order to exclude issues that have already been closed before computing missing. You can cross-reference with the closed-count query, or simply only warn on the first fetch (e.g. when this.cache is null):

// Only warn on the initial fetch, not on subsequent refreshes after issues are closed
const isFirstFetch = !this.cache;
const foundNums = new Set(filtered.map(({ issueNum }) => issueNum));
const missing = this.order.filter((n) => !foundNums.has(n));
if (isFirstFetch && missing.length > 0) {
    console.warn(
        `[ralphy] Warning: --github-order specified issues not found among open issues: ${missing.join(", ")}`,
    );
}

Prompt To Fix With AI

This is a comment left during a code review.
Path: cli/src/tasks/github.ts
Line: 96-102

Comment:
**Warning fires as false positive after issues are closed**

The missing-issue warning is emitted on every cache refresh, not just the first time. During normal operation, once issue `#2` is processed and closed via `markComplete()`, the cache is invalidated. The next call to `fetchOpenIssues()` fetches only `state: "open"` issues, so issue `#2` is no longer in the results. The check on line 97 then flags it as missing and emits the warning — even though it was just successfully completed.

This means a user running `--github-order 2,3,4,5` will see "Warning: issues not found among open issues: 2" after processing the very first issue, then "...2, 3" after the second, and so on. This is confusing and may cause users to think something went wrong when the workflow is proceeding correctly.

Consider filtering `this.order` to exclude issues that have already been closed before computing `missing`. You can cross-reference with the closed-count query, or simply only warn on the first fetch (e.g. when `this.cache` is null):

```ts
// Only warn on the initial fetch, not on subsequent refreshes after issues are closed
const isFirstFetch = !this.cache;
const foundNums = new Set(filtered.map(({ issueNum }) => issueNum));
const missing = this.order.filter((n) => !foundNums.has(n));
if (isFirstFetch && missing.length > 0) {
    console.warn(
        `[ralphy] Warning: --github-order specified issues not found among open issues: ${missing.join(", ")}`,
    );
}
```

How can I resolve this? If you propose a fix, please make it concise.