@neriros/ralphy 2.13.1 → 2.13.3

package/README.md

@@ -89,10 +89,10 @@ What it does on each tick:
 1. Polls Linear for open issues matching the filter (team / assignee / status / labels)
 2. Dedupes against `.ralph/agent-state.json` (already processed) plus any in-flight workers
 3. For each new issue: fetches existing comments, scaffolds `openspec/changes/<id-slug>/{proposal.md,tasks.md,design.md}` (with the comments embedded so the worker sees prior discussion), then spawns `ralph task --name <id-slug>` up to the concurrency cap
-4. Posts a "🤖 started" comment on the Linear issue and (optionally) moves it to `inProgressStatus`
-5. On worker exit, posts a success/failure comment and (on success) moves the issue to `doneStatus` and/or applies `doneLabel`
+4. Posts a "🤖 started" comment on the Linear issue and applies the `setInProgress` indicator (if configured)
+5. On worker exit, posts a success/failure comment and applies the `setDone` indicator on success or `setError` on failure (if configured)
 
-Defaults are written to `ralphy.config.json` on first run; CLI flags override config values per invocation.
+A default `ralphy.config.json` is written on first run with every defaulted setting filled in; CLI flags override config values per invocation.
 
 ```jsonc
 {
@@ -105,13 +105,23 @@ Defaults are written to `ralphy.config.json` on first run; CLI flags override co
   "linear": {
     "team": "ENG",
     "assignee": "me",
-    "statuses": ["Todo", "In Progress"],
-    "labels": ["ralph", "automation"],
-    "inProgressStatus": "In Progress",
-    "doneStatus": "In Review",
-    "doneLabel": "ralphy-done",
     "postComments": true,
     "updateEveryIterations": 10,
+    "indicators": {
+      "getTodo": { "filter": [{ "type": "status", "value": "Todo" }] },
+      "getInProgress": { "filter": [{ "type": "status", "value": "In Progress" }] },
+      "getConflicted": { "filter": [{ "type": "label", "value": "ralph:conflicted" }] },
+      "setInProgress": { "type": "status", "value": "In Progress" },
+      "setDone": {
+        "apply": [
+          { "type": "status", "value": "In Review" },
+          { "type": "label", "value": "ralphy-done" },
+        ],
+      },
+      "setError": { "type": "label", "value": "ralph:error" },
+      "setConflicted": { "type": "label", "value": "ralph:conflicted" },
+      "clearConflicted": { "type": "label", "value": "ralph:conflicted" },
+    },
   },
   "useWorktree": true,
   "cleanupWorktreeOnSuccess": false,
@@ -131,7 +141,13 @@ Defaults are written to `ralphy.config.json` on first run; CLI flags override co
 }
 ```
 
-`doneStatus` and `doneLabel` are independent — set either, both, or neither. Use `doneLabel` if your team marks completion via a label rather than a workflow state.
+Linear is the source of truth for which issues Ralph has touched. Each `linear.indicators` key names a lifecycle event:
+
+- `getTodo` / `getInProgress` / `getConflicted` — `{ filter: [...] }` selectors used to find issues to pick up, resume, or repair.
+- `setInProgress` / `setDone` / `setError` / `setConflicted` — single marker `{ type, value }` or `{ apply: [...] }` for multi-marker.
+- `clearConflicted` — labels to remove once a conflicted PR is fixed (status removal is not supported).
+
+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
 
@@ -147,7 +163,7 @@ Use `setupScript` (run inside the worktree right after scaffolding) to install d
 
 **`fixCiOnFailure`** (or `--fix-ci`) watches the PR's checks via `gh pr checks` and, on failure, fetches the failed-run logs (`gh run view --log-failed`), appends them to `proposal.md` under `## Steering`, re-spawns the task loop in the worktree, and pushes the new commits — repeating until checks go green or `maxCiFixAttempts` is hit (default 5, polling interval `ciPollIntervalSeconds` defaults to 30s). Requires `--create-pr`.
 
-When `fixCiOnFailure` is enabled, the issue is **not** moved to `doneStatus` (and `doneLabel` is not applied, and the issue is not marked processed in `.ralph/agent-state.json`) until CI actually goes green. If the fix loop exhausts its attempts the worker is treated as failed for completion-marking purposes and the issue will be re-picked-up on the next poll (the resume-in-progress filter ensures that).
+When `fixCiOnFailure` is enabled, the `setDone` indicator is **not** applied (and the issue is not marked processed in `.ralph/agent-state.json`) until CI actually goes green. If the fix loop exhausts its attempts the worker is treated as failed for completion-marking purposes and the issue will be re-picked-up on the next poll (the `getInProgress` filter ensures that).
 
 Every CLI flag is also configurable in `ralphy.config.json`; CLI values override config when both are set. The agent forwards `maxRuntimeMinutesPerTask` / `maxConsecutiveFailuresPerTask` / `iterationDelaySeconds` / `logRawStream` / `taskVerbose` to each spawned `ralph task` worker.
 
@@ -174,20 +190,16 @@ 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                                        |
-| `--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                                 |
-| `--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)                                        |
+| `--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`)  |
 
 ## OpenSpec Flow
 

package/dist/cli/index.js

@@ -56407,7 +56407,7 @@ function log(msg) {
 // package.json
 var package_default = {
   name: "@neriros/ralphy",
-  version: "2.13.1",
+  version: "2.13.3",
   description: "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   keywords: [
     "agent",
@@ -56653,8 +56653,6 @@ async function parseArgs(argv) {
   let expectMaxRuntime = false;
   let expectMaxFailures = false;
   let expectMaxIterations = false;
-  let expectTimeout = false;
-  let expectPushInterval = false;
   let expectLinearTeam = false;
   let expectLinearAssignee = false;
   let expectPollInterval = false;
@@ -56717,14 +56715,6 @@ async function parseArgs(argv) {
       expectMaxIterations = false;
       continue;
     }
-    if (expectTimeout) {
-      expectTimeout = false;
-      continue;
-    }
-    if (expectPushInterval) {
-      expectPushInterval = false;
-      continue;
-    }
     if (expectLinearTeam) {
       result2.linearTeam = arg;
       expectLinearTeam = false;
@@ -56794,12 +56784,6 @@ async function parseArgs(argv) {
       case "--max-iterations":
         expectMaxIterations = true;
         break;
-      case "--timeout":
-        expectTimeout = true;
-        break;
-      case "--push-interval":
-        expectPushInterval = true;
-        break;
       case "--unlimited":
         result2.maxIterations = 0;
         break;
@@ -70196,23 +70180,7 @@ var RalphyConfigSchema = exports_external.object({
     postComments: exports_external.boolean().default(true),
     updateEveryIterations: exports_external.number().int().nonnegative().default(10),
     indicators: IndicatorsSchema.default({})
-  }).passthrough().superRefine((value, ctx) => {
-    const LEGACY_KEYS = [
-      "statuses",
-      "labels",
-      "inProgressStatus",
-      "doneStatus",
-      "doneLabel"
-    ];
-    const found = LEGACY_KEYS.filter((k) => (k in value));
-    if (found.length === 0)
-      return;
-    ctx.addIssue({
-      code: exports_external.ZodIssueCode.custom,
-      path: ["linear"],
-      message: `legacy linear keys [${found.join(", ")}] cannot be used together with the new ` + `\`linear.indicators\` map \u2014 they describe the same lifecycle and combining them is ` + `not possible. Migrate by moving each legacy key into linear.indicators (e.g. ` + `doneStatus: "Done" \u2192 indicators.setDone: {type: "status", value: "Done"}; ` + `statuses/labels \u2192 indicators.getTodo.filter; inProgressStatus \u2192 indicators.setInProgress; ` + `doneLabel \u2192 indicators.setDone {type: "label", ...}).`
-    });
-  }).default({ postComments: true, updateEveryIterations: 10, indicators: {} })
+  }).strict().default({ postComments: true, updateEveryIterations: 10, indicators: {} })
 }).default({
   concurrency: 1,
   pollIntervalSeconds: 60,
@@ -70222,23 +70190,145 @@ var RalphyConfigSchema = exports_external.object({
   model: "opus",
   linear: { postComments: true, updateEveryIterations: 10, indicators: {} }
 });
+function stripJsonComments(text) {
+  return text.replace(/\/\/[^\n]*/g, "");
+}
 async function loadRalphyConfig(projectRoot) {
   const path = join10(projectRoot, "ralphy.config.json");
   const file = Bun.file(path);
   if (!await file.exists()) {
     return RalphyConfigSchema.parse({});
   }
-  const raw = await file.json();
+  const text = await file.text();
+  const raw = JSON.parse(stripJsonComments(text));
   return RalphyConfigSchema.parse(raw);
 }
+var DEFAULT_CONFIG_TEMPLATE = `{
+  // How many tasks to run in parallel.
+  "concurrency": 1,
+
+  // Seconds between polls for new Linear issues (agent mode).
+  "pollIntervalSeconds": 60,
+
+  // Maximum iterations per task. 0 = unlimited.
+  "maxIterationsPerTask": 0,
+
+  // Maximum cost in USD per task. 0 = unlimited.
+  "maxCostUsdPerTask": 0,
+
+  // Maximum wall-clock minutes per task. 0 = unlimited.
+  "maxRuntimeMinutesPerTask": 0,
+
+  // Stop a task after this many consecutive identical failures.
+  "maxConsecutiveFailuresPerTask": 5,
+
+  // Seconds to wait between loop iterations (throttle).
+  "iterationDelaySeconds": 0,
+
+  // Log the raw engine stream to stdout.
+  "logRawStream": false,
+
+  // Pass --verbose to the ralph task sub-process.
+  "taskVerbose": false,
+
+  // Run each task in an isolated git worktree.
+  "useWorktree": false,
+
+  // Delete the worktree after a successful task.
+  "cleanupWorktreeOnSuccess": false,
+
+  // Shell script to run inside the worktree before the task starts.
+  // "setupScript": "bun install",
+
+  // Shell script to run inside the worktree after the task finishes.
+  // "teardownScript": "bun run lint",
+
+  // Extra text appended to every task prompt.
+  // "appendPrompt": "Always run tests before finishing.",
+
+  // Open a pull request after a task succeeds.
+  "createPrOnSuccess": false,
+
+  // Base branch for pull requests.
+  "prBaseBranch": "main",
+
+  // Let the agent attempt to fix CI failures after a PR is created.
+  "fixCiOnFailure": false,
+
+  // Maximum number of CI-fix attempts per task.
+  "maxCiFixAttempts": 5,
+
+  // Seconds between CI status polls.
+  "ciPollIntervalSeconds": 30,
+
+  // Underlying engine: "claude" or "codex".
+  "engine": "claude",
+
+  // Model tier: "haiku", "sonnet", or "opus".
+  "model": "opus",
+
+  "linear": {
+    // Linear team key to filter issues (e.g. "ENG"). Omit to match all teams.
+    // "team": "ENG",
+
+    // Linear user to filter issues. Can be an email address or user ID.
+    // Omit to match issues regardless of assignee.
+    // "assignee": "dev@example.com",
+
+    // Post progress comments on the Linear issue while a task is running.
+    "postComments": true,
+
+    // Post a progress update every N iterations. 0 disables. Requires postComments.
+    "updateEveryIterations": 10,
+
+    // ---------------------------------------------------------------------------
+    // Linear indicators \u2014 COMMENTED OUT BY DEFAULT
+    //
+    // Indicators map Ralph lifecycle events to Linear labels/statuses.
+    // WARNING: Activating indicators will query AND mutate your Linear workspace.
+    // Labels or statuses that do not already exist may be created automatically.
+    // Review every value against your actual Linear workspace before enabling,
+    // then replace the empty object below with the full indicators block.
+    //
+    // To activate, replace "indicators": {} with:
+    //
+    // "indicators": {
+    //   // Issues to pick up (any-of filter \u2014 Ralph will start working on these).
+    //   "getTodo": { "filter": [{ "type": "status", "value": "Todo" }] },
+    //
+    //   // Issues already in flight (resume after restart).
+    //   "getInProgress": { "filter": [{ "type": "label", "value": "ralph:in-progress" }] },
+    //
+    //   // Issues whose PR has a merge conflict (Ralph will attempt a re-fix run).
+    //   "getConflicted": { "filter": [{ "type": "label", "value": "ralph:conflict" }] },
+    //
+    //   // Applied when Ralph picks up an issue.
+    //   "setInProgress": { "type": "label", "value": "ralph:in-progress" },
+    //
+    //   // Applied on clean success.
+    //   "setDone": { "type": "status", "value": "In Review" },
+    //
+    //   // Applied when the task exits with an error (quarantine signal).
+    //   "setError": { "type": "label", "value": "ralph:error" },
+    //
+    //   // Applied when a PR merge conflict is detected.
+    //   "setConflicted": { "type": "label", "value": "ralph:conflict" },
+    //
+    //   // Label-only marker(s) removed once the conflict is fixed.
+    //   // Note: only label-typed markers are valid here \u2014 status removal is not supported.
+    //   "clearConflicted": { "type": "label", "value": "ralph:conflict" }
+    // }
+    // ---------------------------------------------------------------------------
+    "indicators": {}
+  }
+}
+`;
 async function ensureRalphyConfig(projectRoot) {
   const path = join10(projectRoot, "ralphy.config.json");
   const file = Bun.file(path);
   if (await file.exists())
     return path;
-  const defaults2 = RalphyConfigSchema.parse({});
-  await Bun.write(path, JSON.stringify(defaults2, null, 2) + `
-`);
+  await Bun.write(path, DEFAULT_CONFIG_TEMPLATE);
   return path;
 }
 
@@ -71908,17 +71998,6 @@ PR: ${prUrl}` : ""
     postComments: cfg.linear.postComments,
     commentEveryIterations: cfg.linear.updateEveryIterations
   });
-  (async () => {
-    const legacy = Bun.file(projectLayout(projectRoot).agentStateFile);
-    if (await legacy.exists()) {
-      onLog("  legacy .ralph/agent-state.json detected \u2014 Linear is now the source of truth; deleting", "gray");
-      try {
-        await legacy.delete();
-      } catch (err) {
-        onLog(`! failed to delete legacy agent-state.json: ${err.message}`, "yellow");
-      }
-    }
-  })();
   const filterDesc = describeIndicators(indicators, team, assignee);
   return {
     coord,

package/package.json

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