@neriros/ralphy 2.7.4 → 2.7.6

package/README.md

@@ -104,11 +104,13 @@ Defaults are written to `ralphy.config.json` on first run; CLI flags override co
     "doneStatus": "In Review",
     "doneLabel": "ralphy-done",
     "postComments": true,
+    "updateEveryIterations": 10,
   },
   "useWorktree": true,
   "cleanupWorktreeOnSuccess": false,
   "setupScript": "bun install",
   "teardownScript": "git status",
+  "appendPrompt": "Always run lint before committing.",
 }
 ```
 
@@ -120,6 +122,10 @@ With `--worktree` (or `useWorktree: true` in config) each task runs in an isolat
 
 Use `setupScript` (run inside the worktree right after scaffolding) to install dependencies, copy `.env`, etc. Use `teardownScript` (run after the loop exits, before any worktree cleanup) to gather artifacts or roll back local mutations. Both run via `sh -c`; failures are logged but never block the loop. With `cleanupWorktreeOnSuccess: true` the worktree is removed when the worker exits 0 — failed workers always keep their worktree (and branch) for human inspection.
 
+**`appendPrompt`** (or `--prompt` in agent mode) is appended to every scaffolded `proposal.md` under an `## Additional instructions` section — use it for cross-cutting guidance every task should see.
+
+**`updateEveryIterations`** (default `10`, `0` disables) posts a "🔄 Ralph progress update: iteration N" comment on the Linear issue every N task iterations. Requires `postComments: true`.
+
 Failed workers (non-zero exit) are not marked processed, so they'll be retried on the next poll. SIGINT/SIGTERM cleanly stops polling and kills active workers. All Linear side effects are best-effort — failures log a warning but never block the task loop.
 
 ## CLI Options
@@ -143,15 +149,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`) |
-| `--linear-status <name>` | Filter by status name (repeatable)           |
-| `--linear-label <name>`  | Filter by label name (repeatable, any-of)    |
-| `--poll-interval <s>`    | Seconds between Linear polls (default: 60)   |
-| `--concurrency <n>`      | Max concurrent task loops (default: 1)       |
-| `--worktree`             | Run each task in its own git worktree        |
+| Option                        | Description                                   |
+| ----------------------------- | --------------------------------------------- |
+| `--linear-team <key>`         | Linear team key (e.g. `ENG`)                  |
+| `--linear-assignee <id>`      | Filter by assignee (user id, email, or `me`)  |
+| `--linear-status <name>`      | Filter by status name (repeatable)            |
+| `--linear-label <name>`       | Filter by label name (repeatable, any-of)     |
+| `--poll-interval <s>`         | Seconds between Linear polls (default: 60)    |
+| `--concurrency <n>`           | Max concurrent task loops (default: 1)        |
+| `--worktree`                  | Run each task in its own git worktree         |
+| `--in-progress-status <name>` | Linear status to set when work starts         |
+| `--done-status <name>`        | Linear status to set on successful completion |
+| `--done-label <name>`         | Linear label to add on successful completion  |
 
 ## OpenSpec Flow
 

package/dist/cli/index.js

@@ -56131,7 +56131,7 @@ var HELP_TEXT = [
   "",
   "Options:",
   "  --name <name>           Change name (required for most commands)",
-  "  --prompt <text>         Task description",
+  "  --prompt <text>         Task description (in agent mode: appended to every scaffolded proposal)",
   "  --prompt-file <path>    Read prompt from file",
   "  --model <model>         Set model (haiku|sonnet|opus)",
   "  --claude [model]        Use Claude engine (haiku|sonnet|opus, default: opus)",
@@ -56153,6 +56153,9 @@ var HELP_TEXT = [
   "  --poll-interval <s>     Seconds between Linear polls (default: 60)",
   "  --concurrency <n>       Max concurrent task loops (default: 1)",
   "  --worktree              Run each task in its own git worktree (.ralph/worktrees/<name>)",
+  "  --in-progress-status <name>  Linear status to set when work starts on an issue",
+  "  --done-status <name>    Linear status to set when work completes successfully",
+  "  --done-label <name>     Linear label to add when work completes successfully",
   "",
   "  --help, -h              Show this help message",
   "",
@@ -56189,7 +56192,10 @@ async function parseArgs(argv) {
     linearLabel: [],
     pollInterval: 60,
     concurrency: 1,
-    worktree: false
+    worktree: false,
+    inProgressStatus: "",
+    doneStatus: "",
+    doneLabel: ""
   };
   let expectModel = false;
   let expectModelFlag = false;
@@ -56209,6 +56215,9 @@ async function parseArgs(argv) {
   let expectLinearLabel = false;
   let expectPollInterval = false;
   let expectConcurrency = false;
+  let expectInProgressStatus = false;
+  let expectDoneStatus = false;
+  let expectDoneLabel = false;
   for (const arg of argv) {
     if (expectModel) {
       if (VALID_MODELS.has(arg)) {
@@ -56304,6 +56313,21 @@ async function parseArgs(argv) {
       expectConcurrency = false;
       continue;
     }
+    if (expectInProgressStatus) {
+      result2.inProgressStatus = arg;
+      expectInProgressStatus = false;
+      continue;
+    }
+    if (expectDoneStatus) {
+      result2.doneStatus = arg;
+      expectDoneStatus = false;
+      continue;
+    }
+    if (expectDoneLabel) {
+      result2.doneLabel = arg;
+      expectDoneLabel = false;
+      continue;
+    }
     switch (arg) {
       case "--claude":
         if (result2.engineSet && result2.engine !== "claude") {
@@ -56383,6 +56407,15 @@ async function parseArgs(argv) {
       case "--worktree":
         result2.worktree = true;
         break;
+      case "--in-progress-status":
+        expectInProgressStatus = true;
+        break;
+      case "--done-status":
+        expectDoneStatus = true;
+        break;
+      case "--done-label":
+        expectDoneLabel = true;
+        break;
       default:
         if (VALID_MODES.has(arg)) {
           result2.mode = arg;
@@ -69739,7 +69772,7 @@ function changeNameForIssue(issue) {
   const slug = issue.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
   return slug ? `${issue.identifier.toLowerCase()}-${slug}` : issue.identifier.toLowerCase();
 }
-async function scaffoldChangeForIssue(tasksDir, statesDir, issue, comments = []) {
+async function scaffoldChangeForIssue(tasksDir, statesDir, issue, comments = [], appendPrompt = "") {
   const name = changeNameForIssue(issue);
   const changeDir = join11(tasksDir, name);
   const stateDir = join11(statesDir, name);
@@ -69769,6 +69802,7 @@ async function scaffoldChangeForIssue(tasksDir, statesDir, issue, comments = [])
     "",
     issue.description?.trim() || "_No description provided in Linear._",
     ...commentsBlock,
+    ...appendPrompt.trim() ? ["", "## Additional instructions", "", appendPrompt.trim()] : [],
     "",
     "## Steering",
     "",
@@ -69810,6 +69844,7 @@ var RalphyConfigSchema = exports_external.object({
   cleanupWorktreeOnSuccess: exports_external.boolean().default(false),
   setupScript: exports_external.string().optional(),
   teardownScript: exports_external.string().optional(),
+  appendPrompt: exports_external.string().optional(),
   engine: exports_external.enum(["claude", "codex"]).default("claude"),
   model: exports_external.enum(["haiku", "sonnet", "opus"]).default("opus"),
   linear: exports_external.object({
@@ -69820,7 +69855,8 @@ var RalphyConfigSchema = exports_external.object({
     inProgressStatus: exports_external.string().optional(),
     doneStatus: exports_external.string().optional(),
     doneLabel: exports_external.string().optional(),
-    postComments: exports_external.boolean().default(true)
+    postComments: exports_external.boolean().default(true),
+    updateEveryIterations: exports_external.number().int().nonnegative().default(10)
   }).default({ statuses: [], labels: [], postComments: true })
 }).default({
   concurrency: 1,
@@ -69906,8 +69942,37 @@ class AgentCoordinator {
     state.lastPollAt = new Date().toISOString();
     await this.deps.saveState(state);
     this.spawnNext();
+    await this.reportProgress();
     return { found: issues.length, added };
   }
+  async reportProgress() {
+    const updater = this.deps.updater;
+    const everyN = this.opts.commentEveryIterations ?? 0;
+    if (everyN <= 0 || !updater || this.opts.postComments === false || !this.deps.getIterationCount) {
+      return;
+    }
+    for (const w of this.workers) {
+      let count;
+      try {
+        count = await this.deps.getIterationCount(w.changeName);
+      } catch (err) {
+        this.deps.onLog(`! iteration count read failed for ${w.issueIdentifier}: ${err.message}`, "yellow");
+        continue;
+      }
+      if (count < everyN)
+        continue;
+      const currMilestone = Math.floor(count / everyN);
+      const lastMilestone = Math.floor(w.lastReportedIteration / everyN);
+      if (currMilestone <= lastMilestone)
+        continue;
+      try {
+        await updater.postComment(w.issue, `\uD83D\uDD04 Ralph progress update: iteration ${count} on \`${w.changeName}\``);
+        w.lastReportedIteration = count;
+      } catch (err) {
+        this.deps.onLog(`! Linear progress comment failed for ${w.issueIdentifier}: ${err.message}`, "red");
+      }
+    }
+  }
   spawnNext() {
     if (this.stopped || !this.state)
       return;
@@ -69937,7 +70002,9 @@ class AgentCoordinator {
       changeName,
       issueId: issue.id,
       issueIdentifier: issue.identifier,
-      kill: handle.kill
+      issue,
+      kill: handle.kill,
+      lastReportedIteration: 0
     };
     this.workers.push(worker);
     this.pendingIds.delete(issue.id);
@@ -70124,6 +70191,7 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
       const teamKeyOf = (issue) => issue.identifier.split("-")[0];
       const useWorktree = args.worktree || cfg.useWorktree;
       const cwdByChange = new Map;
+      const statesDirByChange = new Map;
       async function runScript(label, cmd, cwd2) {
         appendLog(`  ${label}: ${cmd}`, "gray");
         const proc = Bun.spawn({
@@ -70164,8 +70232,10 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
               appendLog(`! worktree create failed for ${issue.identifier}: ${err.message} \u2014 falling back to project root`, "yellow");
             }
           }
-          const changeName = await scaffoldChangeForIssue(scaffoldTasksDir, scaffoldStatesDir, issue, comments);
+          const appendPrompt = args.prompt || cfg.appendPrompt || "";
+          const changeName = await scaffoldChangeForIssue(scaffoldTasksDir, scaffoldStatesDir, issue, comments, appendPrompt);
           cwdByChange.set(changeName, workerCwd);
+          statesDirByChange.set(changeName, scaffoldStatesDir);
           if (cfg.setupScript) {
             await runScript("setup", cfg.setupScript, workerCwd);
           }
@@ -70213,6 +70283,7 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
               }
             }
             cwdByChange.delete(changeName);
+            statesDirByChange.delete(changeName);
             return code;
           });
           return { exited: wrapped, kill: () => proc.kill() };
@@ -70221,6 +70292,14 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
         saveState: (s) => writeAgentState(projectRoot, s),
         onLog: appendLog,
         onWorkersChanged: () => setTick((t) => t + 1),
+        getIterationCount: async (changeName) => {
+          const dir = statesDirByChange.get(changeName) ?? statesDir;
+          const file = Bun.file(join14(dir, changeName, ".ralph-state.json"));
+          if (!await file.exists())
+            return 0;
+          const json = await file.json();
+          return json.iteration ?? 0;
+        },
         updater: {
           postComment: (issue, body) => addIssueComment(apiKey, issue.id, body),
           setState: (issue, stateId) => updateIssueState(apiKey, issue.id, stateId),
@@ -70249,10 +70328,11 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
       }, {
         concurrency,
         filter: filter2,
-        inProgressStatus: cfg.linear.inProgressStatus,
-        doneStatus: cfg.linear.doneStatus,
-        doneLabel: cfg.linear.doneLabel,
-        postComments: cfg.linear.postComments
+        inProgressStatus: args.inProgressStatus || cfg.linear.inProgressStatus,
+        doneStatus: args.doneStatus || cfg.linear.doneStatus,
+        doneLabel: args.doneLabel || cfg.linear.doneLabel,
+        postComments: cfg.linear.postComments,
+        commentEveryIterations: cfg.linear.updateEveryIterations
       });
       coordRef.current = coord2;
       await coord2.init();

package/package.json

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