@neriros/ralphy 3.0.1 → 3.2.0

package/README.md

@@ -187,6 +187,7 @@ Example `ralphy.config.json`:
     "mentionHandle": "@ralphy",
     "codeReviewTrigger": true,
     "codeReviewStaleHours": 24,
+    "syncTasksToDescription": false,
     "indicators": {
       "getTodo": { "filter": [{ "type": "status", "value": "Todo" }] },
       "getInProgress": {
@@ -219,7 +220,7 @@ When a Linear issue is in a done state and a reviewer adds the `getReview` marke
 
 #### `@ralphy` mention trigger
 
-Set `linear.mentionTrigger: true` to scan done-issue comments on Linear _and_ on the linked GitHub PR for a configurable handle (`linear.mentionHandle`, default `@ralphy`). Each unprocessed mention queues the issue as a review run, with the mention text used **verbatim** as the prepended task. Idempotency: a mention is processed when its `createdAt` is older than Ralph's latest `🔁 picked up` Linear comment, so the same comment never re-fires. Requires `gh` for the GitHub side.
+Set `linear.mentionTrigger: true` to scan Linear issue comments on every non-cancelled issue (Todo, In Progress, Backlog, Triage, Done) _and_ on the linked GitHub PR for a configurable handle (`linear.mentionHandle`, default `@ralphy`). Each unprocessed mention queues the issue as a review run, with the mention text used **verbatim** as the prepended task. Idempotency: a mention is processed when its `createdAt` is older than Ralph's latest `🔁 picked up` Linear comment, so the same comment never re-fires. Requires `gh` for the GitHub side.
 
 #### Code-review iteration
 
@@ -230,6 +231,10 @@ Set `linear.codeReviewTrigger: true` (or pass `--code-review`) to watch open, un
 
 The loop exits; the next poll re-checks the PR. The cycle continues until the PR is **approved** or **merged**. If the reviewer is silent for more than `linear.codeReviewStaleHours` (default `24`, `0` disables) while Ralph is the last actor, one `@`-mention ping comment is posted on the GitHub PR.
 
+#### Sync tasks into Linear description
+
+Set `linear.syncTasksToDescription: true` to mirror the active change's `tasks.md` into the linked Linear issue description. Ralph writes a checklist between sentinel HTML comments (`<!-- ralphy:tasks:start -->` / `<!-- ralphy:tasks:end -->`); any content outside the markers is preserved verbatim. The block is refreshed when the worker launches, on the same cadence as `updateEveryIterations`, and on done-transition. Sync failures are logged but never abort the loop.
+
 #### Conflict re-fix
 
 Done issues whose PR `gh pr view --json mergeable` reports as `CONFLICTING` get `setConflicted` applied and a conflict-fix task prepended. The scanner is resilient to:
@@ -250,6 +255,35 @@ Done issues whose PR `gh pr view --json mergeable` reports as `CONFLICTING` get
 | `ignoreCiChecks`                         | Array of check names to ignore when computing pass/fail.                                                                                                                                                                                                                                                                                                                                                            |
 | `codeReviewTrigger` / `--code-review`    | See [Code-review iteration](#code-review-iteration).                                                                                                                                                                                                                                                                                                                                                                |
 
+### Pre-existing error check
+
+Opt-in gate that protects the agent from chasing failures it cannot fix. When
+enabled (config `preExistingErrorCheck.enabled: true` or `--pre-existing-error-check`),
+on every poll tick Ralph runs the configured commands against the base branch
+HEAD. If any command fails:
+
+1. A Linear issue is created with the failing command, exit code, and truncated
+   output (fingerprint embedded in the body so re-runs with the same failure
+   don't open duplicates).
+2. The coordinator pauses — new fresh/resume/conflict-fix/review pickups are
+   blocked until the trunk is green again. **In-flight workers are not killed.**
+3. The dashboard shows a red `⛔ BASELINE BROKEN <LIN-ID> · <duration>` banner.
+
+When the baseline goes green (the human merged the fix), the next poll lifts
+the pause automatically.
+
+```jsonc
+{
+  "preExistingErrorCheck": {
+    "enabled": false,
+    "commands": ["bun run lint", "bun run test"], // falls back to commands.lint + commands.test when empty
+    "baseBranch": "main",
+    "label": "ralph:pre-existing-error",
+    "outputCharLimit": 4000,
+  },
+}
+```
+
 ### Worktrees, setup, teardown
 
 With `useWorktree: true` (or `--worktree`) each task runs in an isolated worktree at `~/.ralph/<project>/worktrees/<change-name>` checked out onto a fresh `ralph/<change-name>` branch. Concurrent workers can't stomp on each other, and the worker's cwd _is_ the worktree.