@neriros/ralphy 2.19.0 → 2.20.0

package/README.md

@@ -171,6 +171,8 @@ A default `ralphy.config.json` is written on first run with every defaulted sett
     "updateEveryIterations": 10,
     "mentionTrigger": true,
     "mentionHandle": "@ralphy",
+    "codeReviewTrigger": true,
+    "codeReviewStaleHours": 24,
     "indicators": {
       "getTodo": { "filter": [{ "type": "status", "value": "Todo" }] },
       "getInProgress": { "filter": [{ "type": "status", "value": "In Progress" }] },
@@ -217,6 +219,8 @@ Linear is the source of truth for which issues Ralph has touched. Each `linear.i
 
 **`@ralphy` mention trigger.** Set `linear.mentionTrigger: true` (default `false`) to scan done-issue comments on both Linear and their linked GitHub PR for `@ralphy` mentions (configurable via `linear.mentionHandle`). New mentions enqueue the issue as a review run with the mention text used verbatim as the prepended task. Idempotency: a mention is considered processed when its `createdAt` is older than the most recent Ralph `🔁 picked up` comment on the Linear issue, so the same comment never re-fires across polls. Requires the `gh` CLI authenticated for the GitHub side.
 
+**Code-review iteration.** Set `linear.codeReviewTrigger: true` (or pass `--code-review`) to watch open, unmerged, unapproved tracked PRs for unresolved review-thread comments. When any unresolved thread has activity newer than Ralph's last `🔁 picked up` ack, the issue is queued as a review run whose prepended task is a digest of every unresolved thread plus instructions: fix-and-push for comments Ralph agrees with (resolve the thread after the commit lands), or reply on GitHub with reasoning for ones it disagrees with. The cycle repeats every poll until the PR is approved or merged. If the reviewer has been silent for more than `linear.codeReviewStaleHours` (default 24) while Ralph is the last actor, a one-shot `@`-mention ping comment is posted on the GitHub PR.
+
 Marker types are `"label"` or `"status"`. Combine markers under `apply` when one event needs to set multiple — e.g. `setDone` flipping a status _and_ adding a "shipped" label.
 
 #### Per-task git worktrees
@@ -260,17 +264,18 @@ Failed workers (non-zero exit) are not marked processed, so they'll be retried o
 
 ### Agent mode flags
 
-| Option                    | Description                                                                   |
-| ------------------------- | ----------------------------------------------------------------------------- |
-| `--linear-team <key>`     | Linear team key (e.g. `ENG`)                                                  |
-| `--linear-assignee <id>`  | Filter by assignee (user id, email, or `me`)                                  |
-| `--poll-interval <s>`     | Seconds between Linear polls (default: 60)                                    |
-| `--concurrency <n>`       | Max concurrent task loops (default: 1)                                        |
-| `--max-tickets <n>`       | Stop picking up new issues after N have been started this run (0 = unlimited) |
-| `--worktree`              | Run each task in its own git worktree                                         |
-| `--indicator <k>:<t>:<v>` | Override a `linear.indicators` entry; repeatable (e.g. `setDone:status:Done`) |
-| `--create-pr`             | Push worker branch + open a GitHub PR on success (needs `--worktree`)         |
-| `--fix-ci`                | After PR opens, re-run task on CI failures until green (needs `--create-pr`)  |
+| Option                    | Description                                                                          |
+| ------------------------- | ------------------------------------------------------------------------------------ |
+| `--linear-team <key>`     | Linear team key (e.g. `ENG`)                                                         |
+| `--linear-assignee <id>`  | Filter by assignee (user id, email, or `me`)                                         |
+| `--poll-interval <s>`     | Seconds between Linear polls (default: 60)                                           |
+| `--concurrency <n>`       | Max concurrent task loops (default: 1)                                               |
+| `--max-tickets <n>`       | Stop picking up new issues after N have been started this run (0 = unlimited)        |
+| `--worktree`              | Run each task in its own git worktree                                                |
+| `--indicator <k>:<t>:<v>` | Override a `linear.indicators` entry; repeatable (e.g. `setDone:status:Done`)        |
+| `--create-pr`             | Push worker branch + open a GitHub PR on success (needs `--worktree`)                |
+| `--fix-ci`                | After PR opens, re-run task on CI failures until green (needs `--create-pr`)         |
+| `--code-review`           | Watch open tracked PRs for unresolved review comments and prepend a code-review task |
 
 #### `--max-tickets`
 

package/dist/cli/index.js

@@ -35029,8 +35029,8 @@ import { readFileSync as readFileSync2 } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("2.19.0")
-      return "2.19.0";
+    if ("2.20.0")
+      return "2.20.0";
   } catch {}
   const dirsToTry = [];
   try {
@@ -35130,6 +35130,7 @@ async function parseArgs(argv) {
     indicators: {},
     createPr: false,
     fixCi: false,
+    codeReview: false,
     maxTickets: 0,
     projectRoot: undefined,
     jsonOutput: false
@@ -35323,6 +35324,9 @@ async function parseArgs(argv) {
       case "--fix-ci":
         result2.fixCi = true;
         break;
+      case "--code-review":
+        result2.codeReview = true;
+        break;
       case "--json-output":
         result2.jsonOutput = true;
         break;
@@ -35417,6 +35421,7 @@ var init_cli = __esm(() => {
     "                          Types: label, status",
     "  --create-pr             Push the worker branch and open a GitHub PR on success (needs --worktree)",
     "  --fix-ci                After opening the PR, re-run on CI failures until green (needs --create-pr)",
+    "  --code-review           Watch open tracked PRs for unresolved review comments and prepend a code-review task",
     "  --max-tickets <n>       Stop picking up new issues after N have been started (0 = unlimited)",
     "  --json-output           Emit JSONL to stdout instead of the Ink dashboard (for scripting/CI)",
     "",
@@ -59627,6 +59632,12 @@ var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, Ralp
     "mentionTrigger": false,
     // "mentionHandle": "@ralphy",
 
+    // Watch open tracked PRs for unresolved review-thread comments and
+    // prepend a code-review task. Pings the reviewer on the GitHub PR
+    // when stalled for more than codeReviewStaleHours.
+    "codeReviewTrigger": false,
+    "codeReviewStaleHours": 24,
+
     // Indicators map Ralph lifecycle events to Linear labels/statuses.
     // WARNING: activating indicators will query AND mutate your Linear workspace.
     // Uncomment each entry after confirming the label/status names match your workspace.
@@ -59738,12 +59749,16 @@ var init_config = __esm(() => {
       updateEveryIterations: exports_external.number().int().nonnegative().default(10),
       mentionTrigger: exports_external.boolean().default(false),
       mentionHandle: exports_external.string().default("@ralphy"),
+      codeReviewTrigger: exports_external.boolean().default(false),
+      codeReviewStaleHours: exports_external.number().nonnegative().default(24),
       indicators: IndicatorsSchema.default({})
     }).strict().default({
       postComments: true,
       updateEveryIterations: 10,
       mentionTrigger: false,
       mentionHandle: "@ralphy",
+      codeReviewTrigger: false,
+      codeReviewStaleHours: 24,
       indicators: {}
     })
   }).default({
@@ -59759,6 +59774,8 @@ var init_config = __esm(() => {
       updateEveryIterations: 10,
       mentionTrigger: false,
       mentionHandle: "@ralphy",
+      codeReviewTrigger: false,
+      codeReviewStaleHours: 24,
       indicators: {}
     }
   });
@@ -60348,7 +60365,7 @@ class AgentCoordinator {
       }
     }
     if (mode === "review" && this.opts.postComments !== false) {
-      const sourceTag = trigger ? trigger.source === "github" ? " (GitHub @mention)" : " (Linear @mention)" : "";
+      const sourceTag = trigger ? trigger.source === "github" ? " (GitHub @mention)" : trigger.source === "github-review" ? " (GitHub code review)" : " (Linear @mention)" : "";
       try {
         await this.deps.postComment(issue, `\uD83D\uDD01 Ralph picked up new review comments${sourceTag}. Tracking change: \`${prep.changeName}\``);
       } catch (err) {
@@ -61145,6 +61162,26 @@ function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function buildMentionTaskBody(trigger, issueUrl) {
+  if (trigger.source === "github-review") {
+    return [
+      `Open code-review on ${trigger.url ?? issueUrl} has unresolved comments:`,
+      "",
+      trigger.body.trim(),
+      "",
+      "For every comment above, decide:",
+      "- If you agree, fix the code, commit, and push. The push will surface",
+      "  the new commit on the PR; the worker should then resolve the thread",
+      "  via `gh api graphql` (`resolveReviewThread`) \u2014 see GitHub docs.",
+      "- If you disagree, post a polite reply on the thread explaining your",
+      "  reasoning via `gh api repos/{owner}/{repo}/pulls/{num}/comments/{id}/replies`,",
+      "  and leave the thread unresolved.",
+      "",
+      "When this round is done the loop exits; the agent will re-poll the",
+      "PR on the next cycle and pick up any new reviewer activity until the",
+      "PR is approved or merged."
+    ].join(`
+`);
+  }
   const sourceLabel = trigger.source === "github" ? "GitHub PR" : "Linear issue";
   const permalink = trigger.url ?? issueUrl;
   const header = `${trigger.author ?? "unknown"} \u2014 ${trigger.createdAt} (${sourceLabel})`;
@@ -61320,6 +61357,7 @@ function buildAgentCoordinator(input) {
   const issueByChange = new Map;
   const prByChange = new Map;
   const prUnavailable = new Set;
+  const stalePingedAt = new Map;
   const useWorktree = args.worktree || cfg.useWorktree;
   const scriptRunner = input.runners?.runScript ?? (async (cmd, cwd2) => {
     const proc = Bun.spawn({
@@ -61691,7 +61729,9 @@ PR: ${prUrl}` : ""
     return fetchOpenIssues(apiKey, { team, assignee, include, exclude });
   }
   async function fetchMentions() {
-    if (!cfg.linear.mentionTrigger)
+    const wantMention = cfg.linear.mentionTrigger;
+    const wantCodeReview = args.codeReview || cfg.linear.codeReviewTrigger;
+    if (!wantMention && !wantCodeReview)
       return [];
     const handle = cfg.linear.mentionHandle;
     let candidates = [];
@@ -61702,6 +61742,7 @@ PR: ${prUrl}` : ""
       return [];
     }
     const out = [];
+    const queued = new Set;
     for (const issue of candidates) {
       let comments = [];
       try {
@@ -61711,51 +61752,191 @@ PR: ${prUrl}` : ""
         continue;
       }
       const lastRalphPickup = findLastRalphPickupISO(comments);
-      for (const c of comments) {
-        if (isRalphComment(c.body))
-          continue;
-        if (!containsHandle(c.body, handle))
-          continue;
-        if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+      if (wantMention) {
+        for (const c of comments) {
+          if (isRalphComment(c.body))
+            continue;
+          if (!containsHandle(c.body, handle))
+            continue;
+          if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+            continue;
+          out.push({
+            issue,
+            trigger: {
+              source: "linear",
+              body: c.body,
+              createdAt: c.createdAt,
+              ...c.user?.name ? { author: c.user.name } : {},
+              url: issue.url
+            }
+          });
+          queued.add(issue.id);
+          break;
+        }
+        if (queued.has(issue.id))
           continue;
-        out.push({
-          issue,
-          trigger: {
-            source: "linear",
-            body: c.body,
-            createdAt: c.createdAt,
-            ...c.user?.name ? { author: c.user.name } : {},
-            url: issue.url
-          }
-        });
-        break;
       }
-      if (out.length > 0 && out[out.length - 1].issue.id === issue.id)
-        continue;
       const prUrl = await resolvePrUrlForIssue(issue);
       if (!prUrl)
         continue;
-      const ghComments = await fetchPrIssueComments(prUrl);
-      for (const c of ghComments) {
-        if (!containsHandle(c.body, handle))
-          continue;
-        if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+      if (wantMention) {
+        const ghComments = await fetchPrIssueComments(prUrl);
+        for (const c of ghComments) {
+          if (!containsHandle(c.body, handle))
+            continue;
+          if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+            continue;
+          out.push({
+            issue,
+            trigger: {
+              source: "github",
+              body: c.body,
+              createdAt: c.createdAt,
+              ...c.author ? { author: c.author } : {},
+              url: c.url
+            }
+          });
+          queued.add(issue.id);
+          break;
+        }
+        if (queued.has(issue.id))
           continue;
-        out.push({
-          issue,
-          trigger: {
-            source: "github",
-            body: c.body,
-            createdAt: c.createdAt,
-            ...c.author ? { author: c.author } : {},
-            url: c.url
-          }
-        });
-        break;
+      }
+      if (wantCodeReview) {
+        const trigger = await scanCodeReview(issue, prUrl, lastRalphPickup);
+        if (trigger) {
+          out.push({ issue, trigger });
+          queued.add(issue.id);
+        }
       }
     }
     return out;
   }
+  async function scanCodeReview(issue, prUrl, lastRalphPickup) {
+    const state = await fetchPrReviewState(prUrl);
+    if (!state || !state.isOpen || state.merged || state.approved)
+      return null;
+    const unresolved = state.threads.filter((t) => !t.isResolved && t.comments.length > 0);
+    if (unresolved.length === 0)
+      return null;
+    const newestReviewerActivity = unresolved.reduce((acc, t) => {
+      const last2 = t.comments[t.comments.length - 1].createdAt;
+      return last2 > acc ? last2 : acc;
+    }, "");
+    if (!lastRalphPickup || newestReviewerActivity > lastRalphPickup) {
+      const body = unresolved.map((t) => {
+        const head3 = t.path ? `_${t.path}${t.line ? `:${t.line}` : ""}_` : "_(general)_";
+        const lines = t.comments.map((c) => `> **${c.author ?? "reviewer"}** (${c.createdAt})
+>
+> ${c.body.trim().replace(/\n/g, `
+> `)}`);
+        return [head3, "", ...lines].join(`
+`);
+      }).join(`
+
+---
+
+`);
+      return {
+        source: "github-review",
+        body,
+        createdAt: newestReviewerActivity || new Date().toISOString(),
+        ...state.lastReviewer ? { author: state.lastReviewer } : {},
+        url: prUrl
+      };
+    }
+    await maybePingStaleReviewer(issue, prUrl, state, newestReviewerActivity);
+    return null;
+  }
+  async function maybePingStaleReviewer(issue, prUrl, state, newestReviewerActivity) {
+    const staleHours = cfg.linear.codeReviewStaleHours;
+    if (staleHours <= 0)
+      return;
+    const reviewer = state.requestedReviewer ?? state.lastReviewer;
+    if (!reviewer)
+      return;
+    const lastPinged = stalePingedAt.get(prUrl);
+    const now2 = Date.now();
+    if (lastPinged && now2 - lastPinged < staleHours * 3600000)
+      return;
+    const elapsedH = newestReviewerActivity ? (now2 - Date.parse(newestReviewerActivity)) / 3600000 : Infinity;
+    if (elapsedH < staleHours)
+      return;
+    const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+    if (!m)
+      return;
+    const [, owner, repo, num] = m;
+    const body = `\uD83D\uDD14 @${reviewer} \u2014 Ralph has been waiting ${elapsedH.toFixed(0)}h on a re-review for ${prUrl}. Could you take another look when you have a moment?`;
+    try {
+      await cmdRunner.run(["gh", "api", `repos/${owner}/${repo}/issues/${num}/comments`, "-f", `body=${body}`], projectRoot);
+      stalePingedAt.set(prUrl, now2);
+      onLog(`  ${issue.identifier}: pinged reviewer @${reviewer} on ${prUrl}`, "gray");
+    } catch (err) {
+      onLog(`! reviewer ping failed for ${prUrl}: ${err.message}`, "yellow");
+    }
+  }
+  async function fetchPrReviewState(prUrl) {
+    const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+    if (!m)
+      return null;
+    const [, owner, repo, num] = m;
+    const query = `query($owner:String!,$repo:String!,$num:Int!){
+      repository(owner:$owner,name:$repo){
+        pullRequest(number:$num){
+          state merged reviewDecision
+          reviewRequests(first:5){nodes{requestedReviewer{... on User{login}}}}
+          latestReviews(first:5){nodes{author{login} state submittedAt}}
+          reviewThreads(first:50){nodes{
+            isResolved path line
+            comments(first:20){nodes{body author{login} createdAt url}}
+          }}
+        }
+      }
+    }`;
+    try {
+      const res = await cmdRunner.run([
+        "gh",
+        "api",
+        "graphql",
+        "-f",
+        `query=${query}`,
+        "-F",
+        `owner=${owner}`,
+        "-F",
+        `repo=${repo}`,
+        "-F",
+        `num=${num}`
+      ], projectRoot);
+      const parsed = JSON.parse(res.stdout);
+      const pr = parsed.data?.repository?.pullRequest;
+      if (!pr)
+        return null;
+      const requested = pr.reviewRequests?.nodes.map((n) => n.requestedReviewer?.login).filter((x) => !!x)[0];
+      const latestReviews = pr.latestReviews?.nodes ?? [];
+      const lastReviewer = latestReviews.slice().sort((a, b) => b.submittedAt > a.submittedAt ? 1 : -1).map((n) => n.author?.login).filter((x) => !!x)[0];
+      return {
+        isOpen: pr.state === "OPEN",
+        merged: pr.merged,
+        approved: pr.reviewDecision === "APPROVED",
+        threads: (pr.reviewThreads?.nodes ?? []).map((t) => ({
+          isResolved: t.isResolved,
+          ...t.path ? { path: t.path } : {},
+          ...t.line != null ? { line: t.line } : {},
+          comments: t.comments.nodes.map((c) => ({
+            ...c.author?.login ? { author: c.author.login } : {},
+            body: c.body,
+            createdAt: c.createdAt,
+            ...c.url ? { url: c.url } : {}
+          }))
+        })),
+        ...requested ? { requestedReviewer: requested } : {},
+        ...lastReviewer ? { lastReviewer } : {}
+      };
+    } catch (err) {
+      onLog(`! gh graphql review-state failed for ${prUrl}: ${err.message}`, "yellow");
+      return null;
+    }
+  }
   function findLastRalphPickupISO(comments) {
     let latest = null;
     for (const c of comments) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",