@neriros/ralphy 3.1.0 → 3.3.0

package/README.md

@@ -187,6 +187,8 @@ Example `ralphy.config.json`:
     "mentionHandle": "@ralphy",
     "codeReviewTrigger": true,
     "codeReviewStaleHours": 24,
+    "syncTasksToComment": true,
+    "syncTasksToDescription": false,
     "indicators": {
       "getTodo": { "filter": [{ "type": "status", "value": "Todo" }] },
       "getInProgress": {
@@ -219,7 +221,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 +232,30 @@ 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 a Linear comment
+
+`linear.syncTasksToComment` (default `true`) mirrors the active change's
+`tasks.md` into a dedicated Linear **comment** instead of the issue
+description. The same comment is updated in place across iterations so
+the timeline stays clean. When `ralph_append_steering` is invoked the
+existing tasks comment is deleted and re-posted so it always lands at
+the bottom of the timeline, after the new steering comment.
+
+The first time planning completes (every `- [ ]` under `## Planning` in
+`tasks.md` becomes `- [x]`), Ralph posts a one-shot "📋 Plan" comment
+summarizing `proposal.md` (`## Why` + `## What Changes`) and the first
+paragraph of `design.md`.
+
+##### Legacy: sync into the issue description
+
+Set `linear.syncTasksToDescription: true` to mirror `tasks.md` into the
+linked Linear issue description body instead (the pre-RLF-62 behavior).
+Ralph writes a checklist between sentinel HTML comments
+(`<!-- ralphy:tasks:start -->` / `<!-- ralphy:tasks:end -->`); content
+outside the markers is preserved verbatim. When both
+`syncTasksToComment` and `syncTasksToDescription` are true,
+comment-sync wins and a one-time warning is logged.
+
 #### 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:

package/dist/mcp/index.js

@@ -24057,7 +24057,12 @@ var StateSchema = exports_external.object({
   createPr: exports_external.boolean().default(false),
   usage: UsageSchema.default({}),
   history: exports_external.array(HistoryEntrySchema).default([]),
-  metadata: exports_external.object({ branch: exports_external.string().optional() }).default({})
+  metadata: exports_external.object({ branch: exports_external.string().optional() }).default({}),
+  linearComments: exports_external.object({
+    planCommentId: exports_external.string().nullable().default(null),
+    tasksCommentId: exports_external.string().nullable().default(null),
+    planPostedAt: exports_external.string().nullable().default(null)
+  }).default({ planCommentId: null, tasksCommentId: null, planPostedAt: null })
 });
 var PhaseFrontmatterSchema = exports_external.object({
   name: exports_external.string(),
@@ -24132,7 +24137,7 @@ function buildInitialState(options) {
 function safeTool(server, name, config2, callback) {
   server.registerTool(name, config2, callback);
 }
-function registerTools(server, changesDir, changeStore, taskFilesDir = changesDir) {
+function registerTools(server, changesDir, changeStore, taskFilesDir = changesDir, hooks = {}) {
   safeTool(server, "ralph_list_changes", {
     description: "List all active OpenSpec changes with their status",
     inputSchema: {
@@ -24320,6 +24325,14 @@ function registerTools(server, changesDir, changeStore, taskFilesDir = changesDi
           };
         }
         await changeStore.appendSteering(name, message);
+        if (hooks.onSteeringAppended) {
+          try {
+            await hooks.onSteeringAppended(name, message);
+          } catch (err) {
+            process.stderr.write(`! onSteeringAppended hook failed for ${name}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+        }
         return {
           content: [{ type: "text", text: `Steering appended to change '${name}'` }]
         };
@@ -24982,6 +24995,50 @@ function runOpenspec(args, options = {}) {
     stderr: proc.stderr ? decoder.decode(proc.stderr) : ""
   };
 }
+function appendSteeringTaskToTasksMd(existing, taskLine) {
+  const SECTION = "## Steering";
+  const trimmed = existing.replace(/\s+$/, "");
+  if (trimmed.length === 0) {
+    return `${SECTION}
+
+${taskLine}
+`;
+  }
+  const lines = trimmed.split(/\r?\n/);
+  let sectionStart = -1;
+  for (let i = 0;i < lines.length; i += 1) {
+    if (/^##\s+Steering\s*$/i.test(lines[i])) {
+      sectionStart = i;
+      break;
+    }
+  }
+  if (sectionStart === -1) {
+    return `${trimmed}
+
+${SECTION}
+
+${taskLine}
+`;
+  }
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1;i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+  let insertAt = sectionEnd;
+  while (insertAt - 1 > sectionStart && (lines[insertAt - 1] ?? "").trim() === "") {
+    insertAt -= 1;
+  }
+  const before = lines.slice(0, insertAt);
+  const after = lines.slice(insertAt);
+  const out = [...before, taskLine, ...after.length ? [""] : [], ...after].join(`
+`);
+  return out.endsWith(`
+`) ? out : `${out}
+`;
+}
 
 class OpenSpecChangeStore {
   async createChange(name, description) {
@@ -25038,6 +25095,16 @@ ${existing.trimStart()}` : `${message}
 `;
     await mkdir(dirname3(path), { recursive: true });
     await Bun.write(path, updated);
+    const firstLine = message.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) ?? message.trim();
+    if (firstLine.length === 0)
+      return;
+    const tasksPath = join4("openspec", "changes", name, "tasks.md");
+    const tasksFile = Bun.file(tasksPath);
+    const existingTasks = await tasksFile.exists() ? await tasksFile.text() : "";
+    const taskLine = `- [ ] Address steering: ${firstLine}`;
+    const next = appendSteeringTaskToTasksMd(existingTasks, taskLine);
+    await mkdir(dirname3(tasksPath), { recursive: true });
+    await Bun.write(tasksPath, next);
   }
   async readSection(name, artifact, heading) {
     const file = Bun.file(join4("openspec", "changes", name, artifact));