@neriros/ralphy 3.1.0 → 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:

package/dist/shell/index.js

@@ -18928,8 +18928,8 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("3.1.0")
-      return "3.1.0";
+    if ("3.2.0")
+      return "3.2.0";
   } catch {}
   const dirsToTry = [];
   try {
@@ -68864,7 +68864,7 @@ function StatusBar({
     return () => clearInterval(id);
   }, [isRunning, startedAt]);
   const { columns } = useTerminalSize();
-  const barWidth = Math.max(8, Math.min(52, columns));
+  const barWidth = Math.max(8, columns);
   const bar = "\u2500".repeat(barWidth);
   return /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(Box_default, {
     flexDirection: "column",
@@ -70223,6 +70223,37 @@ ${failureOutput.trim()}
 ${fence}`;
   await Bun.write(tasksPath, prependSection(existing, stamped, body));
 }
+function normalizeNewlyAppendedSectionWithReport(previous, current) {
+  const prevHeadings = new Set;
+  for (const line of previous.split(`
+`)) {
+    if (line.startsWith("## "))
+      prevHeadings.add(line);
+  }
+  const sections = current.split(/(?=^## )/m);
+  const headings = [];
+  let count = 0;
+  const out = sections.map((section) => {
+    const nlIdx = section.indexOf(`
+`);
+    const headingLine = nlIdx === -1 ? section.replace(/\n$/, "") : section.slice(0, nlIdx);
+    if (!headingLine.startsWith("## "))
+      return section;
+    if (prevHeadings.has(headingLine))
+      return section;
+    let localCount = 0;
+    const rewritten = section.replace(/^(\s*)- \[[xX]\] (.+)$/gm, (_m, indent, rest2) => {
+      localCount += 1;
+      return `${indent}- [ ] ${rest2}`;
+    });
+    if (localCount > 0) {
+      headings.push(headingLine.slice(3));
+      count += localCount;
+    }
+    return rewritten;
+  });
+  return { text: count > 0 ? out.join("") : current, headings, count };
+}
 var MISSION_TASKS_FILENAME = "tasks.md", AGENT_TASKS_FILENAME = "agent-tasks.md", FLOW_TASK_HEADING_PREFIXES;
 var init_tasks_md = __esm(() => {
   FLOW_TASK_HEADING_PREFIXES = [
@@ -92474,6 +92505,7 @@ var init_schema = __esm(() => {
       mentionHandle: exports_external2.string().default("@ralphy"),
       codeReviewTrigger: exports_external2.boolean().default(false),
       codeReviewStaleHours: exports_external2.number().nonnegative().default(24),
+      syncTasksToDescription: exports_external2.boolean().default(false),
       indicators: IndicatorsSchema.default({})
     }).strict().default({
       postComments: true,
@@ -92482,6 +92514,7 @@ var init_schema = __esm(() => {
       mentionHandle: "@ralphy",
       codeReviewTrigger: false,
       codeReviewStaleHours: 24,
+      syncTasksToDescription: false,
       indicators: {}
     }),
     github: exports_external2.object({
@@ -92630,6 +92663,11 @@ linear:
   codeReviewTrigger: false
   codeReviewStaleHours: 24
 
+  # Mirror the loop's tasks.md into the Linear issue description as a
+  # checklist between sentinel markers. Updates on worker launch, on the
+  # same cadence as updateEveryIterations, and on done-transition.
+  syncTasksToDescription: false
+
   # Indicators map Ralph lifecycle events to Linear labels/statuses.
   # Grouped by lifecycle: each get* is followed by the set*/clear* that
   # mutates the same state, so the lifecycle reads top-to-bottom.
@@ -93574,6 +93612,51 @@ function buildIssueFilter(spec) {
   }
   return where;
 }
+async function fetchMentionScanIssues(apiKey, spec) {
+  const where = {
+    state: { type: { in: ["unstarted", "started", "backlog", "triage", "completed"] } }
+  };
+  if (spec.team)
+    where.team = { key: { eq: spec.team } };
+  if (spec.assignee) {
+    if (spec.assignee === "me")
+      where.assignee = { isMe: { eq: true } };
+    else if (spec.assignee.includes("@"))
+      where.assignee = { email: { eq: spec.assignee } };
+    else
+      where.assignee = { id: { eq: spec.assignee } };
+  }
+  const query = `query MentionScanIssues($filter: IssueFilter) {
+    issues(filter: $filter, first: 50) {
+      nodes {
+        id identifier title description url priority createdAt
+        state { name type }
+        assignee { id email name }
+        labels { nodes { name } }
+        relations(first: 50) {
+          nodes { type relatedIssue { id state { type } } }
+        }
+      }
+    }
+  }`;
+  const data = await linearRequest(apiKey, query, {
+    filter: where
+  });
+  const DONE_STATE_TYPES = new Set(["completed", "cancelled"]);
+  return data.issues.nodes.map((n) => ({
+    id: n.id,
+    identifier: n.identifier,
+    title: n.title,
+    description: n.description,
+    url: n.url,
+    state: n.state,
+    assignee: n.assignee,
+    labels: n.labels.nodes.map((l) => l.name),
+    priority: n.priority,
+    createdAt: n.createdAt ?? "",
+    blockedByIds: (n.relations?.nodes ?? []).filter((r) => r.type === "blocked_by" && !DONE_STATE_TYPES.has(r.relatedIssue.state.type)).map((r) => r.relatedIssue.id)
+  }));
+}
 async function fetchOpenIssues(apiKey, spec) {
   const where = buildIssueFilter(spec);
   const query = `query Issues($filter: IssueFilter) {
@@ -94117,6 +94200,13 @@ class AgentCoordinator {
       } catch (err) {
         this.deps.onLog(`! Linear progress comment failed for ${w.issueIdentifier}: ${err.message}`, "red");
       }
+      if (this.deps.syncTasks) {
+        try {
+          await this.deps.syncTasks(w, count);
+        } catch (err) {
+          this.deps.onLog(`! sync-tasks (progress) failed for ${w.issueIdentifier}: ${err.message}`, "yellow");
+        }
+      }
     }
   }
   async scanDoneForConflicts() {
@@ -94289,6 +94379,13 @@ class AgentCoordinator {
       issue_identifier: issue2.identifier
     });
     this.deps.onWorkersChanged();
+    if (this.deps.syncTasks) {
+      try {
+        await this.deps.syncTasks(worker, 0);
+      } catch (err) {
+        this.deps.onLog(`! sync-tasks (launch) failed for ${issue2.identifier}: ${err.message}`, "yellow");
+      }
+    }
     handle.exited.then(async (code) => {
       const idx = this.workers.indexOf(worker);
       if (idx >= 0)
@@ -94333,6 +94430,31 @@ class AgentCoordinator {
   }
   async notifyExited(issue2, changeName, code, mode) {
     const ok = code === 0;
+    if (this.deps.syncTasks && ok) {
+      const synthetic = {
+        changeName,
+        issueId: issue2.id,
+        issueIdentifier: issue2.identifier,
+        issue: issue2,
+        mode,
+        kill: () => {},
+        lastReportedIteration: 0,
+        restarting: false
+      };
+      try {
+        let iteration = 0;
+        if (this.deps.getIterationCount) {
+          try {
+            iteration = await this.deps.getIterationCount(changeName);
+          } catch {
+            iteration = 0;
+          }
+        }
+        await this.deps.syncTasks(synthetic, iteration);
+      } catch (err) {
+        this.deps.onLog(`! sync-tasks (done) failed for ${issue2.identifier}: ${err.message}`, "yellow");
+      }
+    }
     if (this.opts.postComments !== false) {
       const body = ok ? mode === "conflict-fix" ? `\u2705 Ralph resolved merge conflicts on this issue. Change: \`${changeName}\`` : `\u2705 Ralph completed work on this issue. Change: \`${changeName}\`` : `\u2717 Ralph exited with code ${code} on this issue. Change: \`${changeName}\`
 
@@ -94483,7 +94605,7 @@ async function scaffoldChangeForIssue(tasksDir, statesDir, issue2, comments = []
     `- [ ] Fill in \`## Why\` and \`## What Changes\` in proposal.md so \`openspec validate\` passes (these sections are required by the validator)`,
     `- [ ] Add at least one spec delta under \`specs/<capability>/spec.md\` describing the behavior added/modified/removed by this change`,
     `- [ ] Fill in design.md with the technical design (files to touch, data flow, edge cases)`,
-    `- [ ] Append an \`## Implementation\` section below with concrete mission-specific tasks derived from the plan (one \`- [ ] task\` per discrete unit of work, including tests and \`bun run lint\` / \`bun run test\`)`,
+    `- [ ] Append an \`## Implementation\` section below with concrete mission-specific tasks derived from the plan, including tests and \`bun run lint\` / \`bun run test\`. Every item in the new section MUST start as \`- [ ]\` (unchecked) \u2014 do not pre-check items even if you already did the work during planning. The loop ticks them off in later iterations after each one is verified.`,
     ""
   ].join(`
 `);
@@ -95517,6 +95639,143 @@ var init_gate = __esm(() => {
   FINGERPRINT_MARKER_RE = /<!--\s*ralphy:baseline:([a-f0-9]+)\s*-->/i;
 });
 
+// apps/agent/src/agent/linear-sync/index.ts
+function parseTasksMd(md) {
+  const lines = md.split(/\r?\n/);
+  const sections = [];
+  let current = null;
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const headingMatch = /^##\s+(.+?)\s*$/.exec(line);
+    if (headingMatch) {
+      current = { heading: headingMatch[1], items: [] };
+      sections.push(current);
+      i += 1;
+      continue;
+    }
+    const bulletMatch = /^(\s*)-\s+\[( |x|X)\]\s+(.+?)\s*$/.exec(line);
+    if (bulletMatch && current) {
+      const indent = bulletMatch[1] ?? "";
+      const checked = bulletMatch[2]?.toLowerCase() === "x";
+      const text = bulletMatch[3] ?? "";
+      const bullet = `${indent}- [${checked ? "x" : " "}] ${text}`;
+      i += 1;
+      let j = i;
+      while (j < lines.length && lines[j].trim() === "")
+        j += 1;
+      let code;
+      if (j < lines.length && /^\s*```/.test(lines[j])) {
+        const fenceOpen = lines[j];
+        const fenceMatch = /^(\s*)```/.exec(fenceOpen);
+        const fenceIndent = fenceMatch?.[1] ?? "";
+        const buf = [];
+        j += 1;
+        while (j < lines.length) {
+          if (new RegExp(`^${fenceIndent}\`\`\`\\s*$`).test(lines[j])) {
+            j += 1;
+            break;
+          }
+          buf.push(lines[j]);
+          j += 1;
+        }
+        code = buf.join(`
+`);
+        i = j;
+      }
+      current.items.push(code !== undefined ? { bullet, code } : { bullet });
+      continue;
+    }
+    i += 1;
+  }
+  return sections;
+}
+function truncate4(s, max2) {
+  if (s.length <= max2)
+    return s;
+  return `${s.slice(0, max2)}
+\u2026(truncated)`;
+}
+function renderTasksBlock(tasksMd, meta3) {
+  const sections = parseTasksMd(tasksMd);
+  const out = [];
+  out.push(RALPHY_TASKS_START);
+  out.push("### Ralph progress");
+  out.push("");
+  for (const section of sections) {
+    if (section.items.length === 0)
+      continue;
+    out.push(`**${section.heading}**`);
+    out.push("");
+    for (const item of section.items) {
+      out.push(item.bullet);
+      if (item.code !== undefined) {
+        const inner = truncate4(item.code, MAX_CODE_BLOCK_BYTES);
+        out.push(`  <details><summary>output</summary><pre>${inner}</pre></details>`);
+      }
+    }
+    out.push("");
+  }
+  out.push(`<sub>\`${meta3.changeName}\` \xB7 iteration ${meta3.iteration}</sub>`);
+  out.push(RALPHY_TASKS_END);
+  return out.join(`
+`);
+}
+function applyTasksBlock(existingDescription, block) {
+  const existing = existingDescription ?? "";
+  const startIdx = existing.indexOf(RALPHY_TASKS_START);
+  const endIdx = startIdx >= 0 ? existing.indexOf(RALPHY_TASKS_END, startIdx + RALPHY_TASKS_START.length) : -1;
+  if (startIdx >= 0 && endIdx >= 0) {
+    const before2 = existing.slice(0, startIdx);
+    const after2 = existing.slice(endIdx + RALPHY_TASKS_END.length);
+    return `${before2}${block}${after2}`;
+  }
+  if (existing.length === 0)
+    return block;
+  const trimmed = existing.replace(/\s+$/, "");
+  return `${trimmed}
+
+${block}`;
+}
+async function syncTasksToLinearDescription(deps) {
+  const file2 = Bun.file(deps.tasksPath);
+  if (!await file2.exists()) {
+    deps.log(`  sync-tasks: tasks.md missing at ${deps.tasksPath}, skipping`, "gray");
+    return null;
+  }
+  let tasksMd;
+  try {
+    tasksMd = await file2.text();
+  } catch (err) {
+    deps.log(`! sync-tasks: read failed for ${deps.tasksPath}: ${err.message}`, "yellow");
+    return null;
+  }
+  const block = renderTasksBlock(tasksMd, {
+    changeName: deps.changeName,
+    iteration: deps.iteration
+  });
+  if (block.length > MAX_BLOCK_BYTES) {
+    deps.log(`! sync-tasks: rendered block exceeds ${MAX_BLOCK_BYTES} bytes (${block.length}), skipping update`, "yellow");
+    return null;
+  }
+  const next = applyTasksBlock(deps.currentDescription, block);
+  if (next === (deps.currentDescription ?? ""))
+    return null;
+  try {
+    await deps.updateIssueDescription(deps.apiKey, deps.issueId, next);
+    deps.log(`  sync-tasks: updated Linear description for ${deps.changeName}`, "gray");
+    return next;
+  } catch (err) {
+    deps.log(`! sync-tasks: updateIssueDescription failed: ${err.message}`, "yellow");
+    return null;
+  }
+}
+var RALPHY_TASKS_START = "<!-- ralphy:tasks:start -->", RALPHY_TASKS_END = "<!-- ralphy:tasks:end -->", MAX_BLOCK_BYTES, MAX_CODE_BLOCK_BYTES;
+var init_linear_sync = __esm(() => {
+  MAX_BLOCK_BYTES = 60 * 1024;
+  MAX_CODE_BLOCK_BYTES = 2 * 1024;
+});
+
 // apps/agent/src/agent/wire.ts
 import { join as join21 } from "path";
 import { mkdir as mkdir6 } from "fs/promises";
@@ -96069,6 +96328,11 @@ PR: ${prUrl}` : ""
   function spawnWorker(changeName) {
     const cwd2 = cwdByChange.get(changeName) ?? projectRoot;
     const injected = input.runners?.spawnWorker;
+    const missionTasksPath = join21(projectLayout(cwd2).changeDir(changeName), MISSION_TASKS_FILENAME);
+    const prevTasksPromise = (async () => {
+      const f2 = Bun.file(missionTasksPath);
+      return await f2.exists() ? await f2.text() : "";
+    })();
     let logFilePath;
     let handle;
     if (injected) {
@@ -96094,6 +96358,21 @@ PR: ${prUrl}` : ""
     const wantAutoMerge = issueForChange ? issueMatchesGetIndicator(issueForChange, indicators.getAutoMerge) : false;
     const wrapped = handle.exited.then(async (code) => {
       const workerLayout = projectLayout(cwd2);
+      try {
+        const prevTasks = await prevTasksPromise;
+        const nextFile = Bun.file(missionTasksPath);
+        if (await nextFile.exists()) {
+          const nextTasks = await nextFile.text();
+          const report = normalizeNewlyAppendedSectionWithReport(prevTasks, nextTasks);
+          if (report.text !== nextTasks) {
+            await Bun.write(missionTasksPath, report.text);
+            const sections = report.headings.map((h) => `## ${h}`).join(", ");
+            onLog(`! normalized ${report.count} pre-checked item(s) in newly added section(s) ${sections}`, "yellow");
+          }
+        }
+      } catch (err) {
+        onLog(`! tasks.md normalization failed: ${err.message}`, "yellow");
+      }
       const effectiveCode = await runPostTask({
         changeName,
         cwd: cwd2,
@@ -96327,9 +96606,9 @@ PR: ${prUrl}` : ""
     const handle = cfg.linear.mentionHandle;
     let candidates = [];
     try {
-      candidates = await fetchDoneCandidates();
+      candidates = await fetchMentionScanIssues(apiKey, { team, assignee });
     } catch (err) {
-      onLog(`! mention scan: fetchDoneCandidates failed: ${err.message}`, "yellow");
+      onLog(`! mention scan: fetchMentionScanIssues failed: ${err.message}`, "yellow");
       return [];
     }
     const out = [];
@@ -96620,7 +96899,29 @@ PR: ${prUrl}` : ""
         return 0;
       const json2 = await file2.json();
       return json2.iteration ?? 0;
-    }
+    },
+    ...cfg.linear.syncTasksToDescription && apiKey ? {
+      syncTasks: async (worker, iteration) => {
+        const root = cwdByChange.get(worker.changeName) ?? projectRoot;
+        const tasksPath = join21(projectLayout(root).changeDir(worker.changeName), "tasks.md");
+        const cachedIssue = issueByChange.get(worker.changeName) ?? worker.issue;
+        const next = await syncTasksToLinearDescription({
+          apiKey,
+          issueId: worker.issueId,
+          currentDescription: cachedIssue.description,
+          tasksPath,
+          changeName: worker.changeName,
+          iteration,
+          log: onLog,
+          updateIssueDescription
+        });
+        if (next !== null) {
+          const updated = { ...cachedIssue, description: next };
+          issueByChange.set(worker.changeName, updated);
+          worker.issue = updated;
+        }
+      }
+    } : {}
   }, {
     concurrency,
     ...indicators.setInProgress !== undefined ? { setInProgress: indicators.setInProgress } : {},
@@ -96687,6 +96988,7 @@ PR: ${prUrl}` : ""
     concurrency,
     pollInterval,
     getWorkerCwd: (changeName) => cwdByChange.get(changeName),
+    syncTasksEnabled: Boolean(cfg.linear.syncTasksToDescription && apiKey),
     runBaselineGate: runBaselineGateOnce
   };
 }
@@ -96722,6 +97024,7 @@ var init_wire = __esm(() => {
   init_post_task();
   init_gate();
   init_workflow();
+  init_linear_sync();
   GITHUB_PR_URL_RE = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/;
   bunGitRunner = {
     run: async (args, cwd2) => {
@@ -97313,6 +97616,7 @@ function AgentMode({
   const workerMetaRef = import_react61.useRef(new Map);
   const nextPollAtRef = import_react61.useRef(0);
   const cfgRef = import_react61.useRef(null);
+  const [effective, setEffective] = import_react61.useState(null);
   const [pollStatus, setPollStatus] = import_react61.useState({
     state: "idle",
     lastFound: null,
@@ -97411,6 +97715,7 @@ function AgentMode({
             m.prUrl = prUrl;
         }
       });
+      setEffective({ concurrency, pollInterval });
       coordRef.current = coord2;
       await coord2.init();
       const tick = async () => {
@@ -97670,14 +97975,14 @@ function AgentMode({
                         dimColor: true,
                         children: [
                           " \u2502 \xD7",
-                          cfg.concurrency
+                          effective?.concurrency ?? cfg.concurrency
                         ]
                       }, undefined, true, undefined, this),
                       /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Text, {
                         dimColor: true,
                         children: [
                           " \u2502 poll ",
-                          cfg.pollIntervalSeconds,
+                          effective?.pollInterval ?? cfg.pollIntervalSeconds,
                           "s"
                         ]
                       }, undefined, true, undefined, this),
@@ -97794,18 +98099,6 @@ function AgentMode({
                               dimColor: true,
                               children: "\xB7"
                             }, undefined, false, undefined, this),
-                            /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Text, {
-                              dimColor: true,
-                              children: "conflict"
-                            }, undefined, false, undefined, this),
-                            /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Text, {
-                              color: pollStatus.lastBuckets.conflicted > 0 ? "red" : "white",
-                              children: pollStatus.lastBuckets.conflicted
-                            }, undefined, false, undefined, this),
-                            /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Text, {
-                              dimColor: true,
-                              children: "\xB7"
-                            }, undefined, false, undefined, this),
                             /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Text, {
                               dimColor: true,
                               children: "review"
@@ -97836,6 +98129,7 @@ function AgentMode({
                     children: [
                       secsToNextPoll !== null ? /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Box_default, {
                         gap: 1,
+                        width: 7,
                         children: [
                           /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Text, {
                             dimColor: true,

package/package.json

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