ralphctl 0.3.1 → 0.4.1

package/dist/{chunk-CSC4TBJB.mjs → chunk-3HJNVQ7N.mjs}

@@ -1681,6 +1681,37 @@ function collectRepoIds(tasks) {
 
 // src/business/usecases/execute.ts
 import { basename } from "path";
+
+// src/business/usecases/recover-dirty-tree.ts
+async function recoverDirtyTree(deps, params) {
+  const { external, logger, signalBus } = deps;
+  const { sprintId, taskId, taskName, repoPath } = params;
+  if (!external.hasUncommittedChanges(repoPath)) return;
+  logger.warn(
+    `Dirty tree after "${taskName}" \u2014 auto-committing on the harness's behalf. The agent should commit its own work; see prompt guidance.`,
+    { taskId, projectPath: repoPath }
+  );
+  signalBus.emit({
+    type: "signal",
+    signal: {
+      type: "note",
+      text: `harness auto-commit: dirty tree after task "${taskName}" settlement`,
+      timestamp: /* @__PURE__ */ new Date()
+    },
+    ctx: { sprintId, taskId, projectPath: repoPath }
+  });
+  const message = `chore(harness): auto-commit leftover changes from "${taskName}"`;
+  try {
+    await external.autoCommit(repoPath, message);
+  } catch (err) {
+    logger.error(`Auto-commit failed in ${repoPath}: ${err instanceof Error ? err.message : String(err)}`, {
+      taskId,
+      projectPath: repoPath
+    });
+  }
+}
+
+// src/business/usecases/execute.ts
 var ExecuteTasksUseCase = class {
   constructor(persistence, aiSession, promptBuilder, parser, ui, logger, external, fs, signalParser2, signalHandler, signalBus) {
     this.persistence = persistence;
@@ -1940,6 +1971,10 @@ ${instructions}`;
           );
           if (finishStatus === "done") finishStatus = "failed";
         }
+        await recoverDirtyTree(
+          { external: this.external, logger: this.logger, signalBus: this.signalBus },
+          { sprintId: sprint.id, taskId: syntheticTask.id, taskName: syntheticTask.name, repoPath }
+        );
         this.signalBus.emit({
           type: "task-finished",
           sprintId: sprint.id,
@@ -2760,6 +2795,19 @@ function evaluateTask(deps) {
   });
 }
 
+// src/business/pipelines/execute/steps/recover-dirty-tree.ts
+function recoverDirtyTree2(deps) {
+  return step("recover-dirty-tree", async (ctx) => {
+    const { task, sprint } = ctx;
+    const repoPath = await deps.persistence.resolveRepoPath(task.repoId);
+    await recoverDirtyTree(
+      { external: deps.external, logger: deps.logger, signalBus: deps.signalBus },
+      { sprintId: sprint.id, taskId: task.id, taskName: task.name, repoPath }
+    );
+    return Result.ok({});
+  });
+}
+
 // src/business/pipelines/execute/steps/mark-done.ts
 function markDone(deps) {
   return step("mark-done", async (ctx) => {
@@ -2801,28 +2849,71 @@ function markDone(deps) {
 
 // src/business/pipelines/execute/per-task-pipeline.ts
 function createPerTaskPipeline(deps, useCase, options = {}) {
+  const trace = withStepTrace(deps.signalBus);
   return pipeline("per-task", [
-    branchPreflight({ external: deps.external, persistence: deps.persistence }),
-    contractNegotiate({ persistence: deps.persistence, fs: deps.fs }),
-    markInProgress({ persistence: deps.persistence, signalBus: deps.signalBus }),
-    executeTask({ useCase, options, taskSessionIds: deps.taskSessionIds, logger: deps.logger }),
-    storeVerification({ persistence: deps.persistence, logger: deps.logger }),
-    postTaskCheck({ useCase }),
-    evaluateTask({
-      persistence: deps.persistence,
-      fs: deps.fs,
-      aiSession: deps.aiSession,
-      promptBuilder: deps.promptBuilder,
-      parser: deps.parser,
-      ui: deps.ui,
-      logger: deps.logger,
-      external: deps.external,
-      useCase,
-      options
-    }),
-    markDone({ persistence: deps.persistence, logger: deps.logger, signalBus: deps.signalBus })
+    trace(branchPreflight({ external: deps.external, persistence: deps.persistence })),
+    trace(contractNegotiate({ persistence: deps.persistence, fs: deps.fs })),
+    trace(markInProgress({ persistence: deps.persistence, signalBus: deps.signalBus })),
+    trace(executeTask({ useCase, options, taskSessionIds: deps.taskSessionIds, logger: deps.logger })),
+    trace(storeVerification({ persistence: deps.persistence, logger: deps.logger })),
+    trace(postTaskCheck({ useCase })),
+    trace(
+      evaluateTask({
+        persistence: deps.persistence,
+        fs: deps.fs,
+        aiSession: deps.aiSession,
+        promptBuilder: deps.promptBuilder,
+        parser: deps.parser,
+        ui: deps.ui,
+        logger: deps.logger,
+        external: deps.external,
+        useCase,
+        options
+      })
+    ),
+    trace(
+      recoverDirtyTree2({
+        persistence: deps.persistence,
+        external: deps.external,
+        logger: deps.logger,
+        signalBus: deps.signalBus
+      })
+    ),
+    trace(markDone({ persistence: deps.persistence, logger: deps.logger, signalBus: deps.signalBus }))
   ]);
 }
+function withStepTrace(signalBus) {
+  return (inner) => ({
+    name: inner.name,
+    execute: inner.execute,
+    hooks: {
+      pre: async (ctx) => {
+        signalBus.emit({
+          type: "task-step",
+          sprintId: ctx.sprint.id,
+          taskId: ctx.task.id,
+          stepName: inner.name,
+          phase: "start",
+          timestamp: /* @__PURE__ */ new Date()
+        });
+        const prior = await inner.hooks?.pre?.(ctx);
+        return prior ?? Result.ok(ctx);
+      },
+      post: async (ctx, result) => {
+        const prior = await inner.hooks?.post?.(ctx, result);
+        signalBus.emit({
+          type: "task-step",
+          sprintId: ctx.sprint.id,
+          taskId: ctx.task.id,
+          stepName: inner.name,
+          phase: "finish",
+          timestamp: /* @__PURE__ */ new Date()
+        });
+        return prior ?? Result.ok({});
+      }
+    }
+  });
+}
 
 // src/business/pipelines/execute.ts
 var EXIT_SUCCESS = 0;
@@ -3260,7 +3351,6 @@ function executeTasksStep(deps, options) {
         onSettle: (task, result) => {
           if (result === "success") {
             taskSessionIds.delete(task.id);
-            deps.logger.success(`Completed: ${task.name}`);
           }
         }
       },
@@ -5183,6 +5273,25 @@ function hasUncommittedChanges(cwd) {
   }
   return result.stdout.trim().length > 0;
 }
+function autoCommit(cwd, message) {
+  assertSafeCwd(cwd);
+  const add = spawnSync3("git", ["add", "-A"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (add.status !== 0) {
+    throw new Error(`Failed to stage changes in ${cwd}: ${add.stderr.trim()}`);
+  }
+  const commit = spawnSync3("git", ["commit", "-m", message], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (commit.status !== 0) {
+    throw new Error(`Failed to commit in ${cwd}: ${commit.stderr.trim() || commit.stdout.trim()}`);
+  }
+}
 function generateBranchName(sprintId) {
   return `ralphctl/${sprintId}`;
 }
@@ -5242,6 +5351,10 @@ var DefaultExternalAdapter = class {
   hasUncommittedChanges(projectPath) {
     return hasUncommittedChanges(projectPath);
   }
+  autoCommit(projectPath, message) {
+    autoCommit(projectPath, message);
+    return Promise.resolve();
+  }
   createAndCheckoutBranch(projectPath, branchName) {
     createAndCheckoutBranch(projectPath, branchName);
   }

package/dist/{chunk-EPDR6VO5.mjs → chunk-SM4GGZSU.mjs}

@@ -52,7 +52,7 @@ import {
   updateTask,
   updateTaskStatus,
   validateImportTasks
-} from "./chunk-CSC4TBJB.mjs";
+} from "./chunk-3HJNVQ7N.mjs";
 import {
   fetchIssueFromUrl,
   formatIssueContext,
@@ -177,7 +177,7 @@ import {
 // package.json
 var package_default = {
   name: "ralphctl",
-  version: "0.3.1",
+  version: "0.4.1",
   description: "Agent harness for long-running AI coding tasks \u2014 orchestrates Claude Code & GitHub Copilot across repositories",
   homepage: "https://github.com/lukas-grigis/ralphctl",
   type: "module",
@@ -422,8 +422,8 @@ function useCurrentPrompt() {
 }
 
 // src/integration/ui/prompts/confirm-prompt.tsx
-import "react";
-import { Box, Text } from "ink";
+import { useEffect as useEffect2, useMemo, useState as useState2 } from "react";
+import { Box, Text, useInput, useStdout } from "ink";
 import { ConfirmInput } from "@inkjs/ui";
 
 // src/integration/ui/theme/tokens.ts
@@ -493,11 +493,43 @@ var FIELD_LABEL_WIDTH = 12;
 
 // src/integration/ui/prompts/confirm-prompt.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var RESERVED_ROWS = 10;
+var MIN_VIEWPORT = 6;
+var MAX_VIEWPORT = 40;
+function useTerminalRows() {
+  const { stdout } = useStdout();
+  const [rows, setRows] = useState2(stdout.rows);
+  useEffect2(() => {
+    const onResize = () => {
+      setRows(stdout.rows);
+    };
+    stdout.on("resize", onResize);
+    return () => {
+      stdout.off("resize", onResize);
+    };
+  }, [stdout]);
+  return rows;
+}
 function ConfirmPrompt({ options, onSubmit }) {
   const hint = options.default === false ? "(y/N)" : "(Y/n)";
   const details = options.details?.trim();
+  const lines = useMemo(() => details ? details.split("\n") : [], [details]);
+  const terminalRows = useTerminalRows();
+  const viewport = Math.max(MIN_VIEWPORT, Math.min(MAX_VIEWPORT, terminalRows - RESERVED_ROWS));
+  const total = lines.length;
+  const maxOffset = Math.max(0, total - viewport);
+  const scrollable = total > viewport;
+  const [offset, setOffset] = useState2(0);
+  useInput((_input, key) => {
+    if (!scrollable) return;
+    if (key.upArrow) setOffset((o) => Math.max(0, o - 1));
+    else if (key.downArrow) setOffset((o) => Math.min(maxOffset, o + 1));
+    else if (key.pageUp) setOffset((o) => Math.max(0, o - viewport));
+    else if (key.pageDown) setOffset((o) => Math.min(maxOffset, o + viewport));
+  });
+  const visibleLines = scrollable ? lines.slice(offset, offset + viewport) : lines;
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
-    details ? /* @__PURE__ */ jsx(
+    details ? /* @__PURE__ */ jsxs(
       Box,
       {
         flexDirection: "column",
@@ -505,13 +537,30 @@ function ConfirmPrompt({ options, onSubmit }) {
         borderColor: inkColors.muted,
         paddingX: spacing.gutter,
         marginBottom: spacing.section,
-        children: details.split("\n").map((line, idx) => /* @__PURE__ */ jsx(Text, { children: line.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
-          /* @__PURE__ */ jsxs(Text, { color: inkColors.muted, children: [
-            glyphs.quoteRail,
-            " "
-          ] }),
-          line
-        ] }) : " " }, idx))
+        children: [
+          visibleLines.map((line, idx) => /* @__PURE__ */ jsx(Text, { children: line.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsxs(Text, { color: inkColors.muted, children: [
+              glyphs.quoteRail,
+              " "
+            ] }),
+            line
+          ] }) : " " }, idx)),
+          scrollable ? /* @__PURE__ */ jsxs(Text, { color: inkColors.muted, children: [
+            glyphs.inlineDot,
+            " lines ",
+            String(offset + 1),
+            "\u2013",
+            String(Math.min(offset + viewport, total)),
+            " of",
+            " ",
+            String(total),
+            " ",
+            glyphs.inlineDot,
+            " \u2191/\u2193 scroll ",
+            glyphs.inlineDot,
+            " PgUp/PgDn page"
+          ] }) : null
+        ]
       }
     ) : null,
     /* @__PURE__ */ jsxs(Box, { children: [
@@ -542,13 +591,13 @@ function ConfirmPrompt({ options, onSubmit }) {
 }
 
 // src/integration/ui/prompts/input-prompt.tsx
-import { useState as useState2 } from "react";
-import { Box as Box2, Text as Text2, useInput } from "ink";
+import { useState as useState3 } from "react";
+import { Box as Box2, Text as Text2, useInput as useInput2 } from "ink";
 import { TextInput } from "@inkjs/ui";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 function InputPrompt({ options, onSubmit, onCancel }) {
-  const [error2, setError] = useState2(null);
-  useInput((_input, key) => {
+  const [error2, setError] = useState3(null);
+  useInput2((_input, key) => {
     if (key.escape) onCancel();
   });
   return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", children: [
@@ -586,13 +635,13 @@ function InputPrompt({ options, onSubmit, onCancel }) {
 }
 
 // src/integration/ui/prompts/select-prompt.tsx
-import { useState as useState3 } from "react";
-import { Box as Box3, Text as Text3, useInput as useInput2 } from "ink";
+import { useState as useState4 } from "react";
+import { Box as Box3, Text as Text3, useInput as useInput3 } from "ink";
 import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 function SelectPrompt({ options, onSubmit, onCancel }) {
   const initialIdx = findInitialIdx(options);
-  const [focusedIdx, setFocusedIdx] = useState3(initialIdx);
-  useInput2((_input, key) => {
+  const [focusedIdx, setFocusedIdx] = useState4(initialIdx);
+  useInput3((_input, key) => {
     if (key.escape) {
       onCancel();
       return;
@@ -655,14 +704,14 @@ function stepFocus(choices, from, delta) {
 }
 
 // src/integration/ui/prompts/checkbox-prompt.tsx
-import { useState as useState4 } from "react";
-import { Box as Box4, Text as Text4, useInput as useInput3 } from "ink";
+import { useState as useState5 } from "react";
+import { Box as Box4, Text as Text4, useInput as useInput4 } from "ink";
 import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 function CheckboxPrompt({ options, onSubmit, onCancel }) {
   const initialFocus = options.choices.findIndex((c) => !isDisabled2(c));
-  const [focusedIdx, setFocusedIdx] = useState4(initialFocus >= 0 ? initialFocus : 0);
-  const [checked, setChecked] = useState4(() => seedCheckedSet(options));
-  useInput3((input, key) => {
+  const [focusedIdx, setFocusedIdx] = useState5(initialFocus >= 0 ? initialFocus : 0);
+  const [checked, setChecked] = useState5(() => seedCheckedSet(options));
+  useInput4((input, key) => {
     if (key.escape) {
       onCancel();
       return;
@@ -738,8 +787,8 @@ function stepFocus2(choices, from, delta) {
 }
 
 // src/integration/ui/prompts/editor-prompt.tsx
-import { useState as useState5, useMemo } from "react";
-import { Box as Box5, Text as Text5, useInput as useInput4 } from "ink";
+import { useState as useState6, useMemo as useMemo2 } from "react";
+import { Box as Box5, Text as Text5, useInput as useInput5 } from "ink";
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 var MIN_EDIT_ROWS = 8;
 function splitLines(text) {
@@ -755,13 +804,13 @@ function clampCursor(lines, cursor) {
   return { row, col };
 }
 function EditorPrompt({ options, onSubmit, onCancel }) {
-  const [lines, setLines] = useState5(() => splitLines(options.default ?? ""));
-  const [cursor, setCursor] = useState5(() => {
+  const [lines, setLines] = useState6(() => splitLines(options.default ?? ""));
+  const [cursor, setCursor] = useState6(() => {
     const init = splitLines(options.default ?? "");
     const lastRow = init.length - 1;
     return { row: lastRow, col: (init[lastRow] ?? "").length };
   });
-  useInput4((input, key) => {
+  useInput5((input, key) => {
     if (key.escape || key.ctrl && input === "c") {
       onCancel();
       return;
@@ -857,7 +906,7 @@ function EditorPrompt({ options, onSubmit, onCancel }) {
       });
     }
   });
-  const renderedLines = useMemo(() => {
+  const renderedLines = useMemo2(() => {
     const padCount = Math.max(0, MIN_EDIT_ROWS - lines.length);
     const padded = lines.map((line, i) => {
       if (i !== cursor.row) return line.length > 0 ? line : " ";
@@ -904,11 +953,11 @@ function EditorPrompt({ options, onSubmit, onCancel }) {
 }
 
 // src/integration/ui/prompts/file-browser-prompt.tsx
-import { useEffect as useEffect2, useMemo as useMemo2, useState as useState6 } from "react";
+import { useEffect as useEffect3, useMemo as useMemo3, useState as useState7 } from "react";
 import { readdirSync, statSync } from "fs";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
-import { Box as Box6, Text as Text6, useInput as useInput5 } from "ink";
+import { Box as Box6, Text as Text6, useInput as useInput6 } from "ink";
 import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
 function listDirectories(dirPath) {
   try {
@@ -926,20 +975,20 @@ function isGitRepo(dirPath) {
 }
 var PAGE_SIZE = 12;
 function FileBrowserPrompt({ options, onSubmit, onCancel }) {
-  const [currentPath, setCurrentPath] = useState6(
+  const [currentPath, setCurrentPath] = useState7(
     () => options.startPath ? resolve(options.startPath) : homedir()
   );
-  const [dirs, setDirs] = useState6([]);
-  const [cursor, setCursor] = useState6(0);
-  const [offset, setOffset] = useState6(0);
-  useEffect2(() => {
+  const [dirs, setDirs] = useState7([]);
+  const [cursor, setCursor] = useState7(0);
+  const [offset, setOffset] = useState7(0);
+  useEffect3(() => {
     setDirs(listDirectories(currentPath));
     setCursor(0);
     setOffset(0);
   }, [currentPath]);
   const message = options.message ?? "Browse to directory:";
   const parent = dirname(currentPath);
-  useInput5((input, key) => {
+  useInput6((input, key) => {
     if (key.escape) {
       onCancel();
       return;
@@ -973,11 +1022,11 @@ function FileBrowserPrompt({ options, onSubmit, onCancel }) {
       return;
     }
   });
-  useEffect2(() => {
+  useEffect3(() => {
     if (cursor < offset) setOffset(cursor);
     else if (cursor >= offset + PAGE_SIZE) setOffset(cursor - PAGE_SIZE + 1);
   }, [cursor, offset]);
-  const visible = useMemo2(() => dirs.slice(offset, offset + PAGE_SIZE), [dirs, offset]);
+  const visible = useMemo3(() => dirs.slice(offset, offset + PAGE_SIZE), [dirs, offset]);
   return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1, children: [
     /* @__PURE__ */ jsx6(Box6, { children: /* @__PURE__ */ jsxs6(Text6, { children: [
       emoji.donut,
@@ -2709,6 +2758,8 @@ function parseArgs2(args) {
     if (arg === "--project") {
       options.project = nextArg;
       i++;
+    } else if (arg === "--auto") {
+      options.auto = true;
     } else if (!arg?.startsWith("-")) {
       sprintId = arg;
     }
@@ -2731,7 +2782,7 @@ async function sprintRefineCommand(args) {
   console.log(field("ID", sprint.id));
   log.newline();
   const shared = getSharedDeps();
-  const pipeline = createRefinePipeline(shared, { project: options.project });
+  const pipeline = createRefinePipeline(shared, { project: options.project, auto: options.auto });
   const result = await executePipeline(pipeline, { sprintId: id });
   if (!result.ok) {
     showError(result.error.message);
@@ -3914,6 +3965,100 @@ async function taskImportCommand(args) {
   }
 }
 
+// src/integration/cli/commands/task/why.ts
+function collectBlockers(root, byId) {
+  const out = [];
+  const visited = /* @__PURE__ */ new Set([root.id]);
+  function walk(task, depth) {
+    for (const blockerId of task.blockedBy) {
+      const blocker = byId.get(blockerId);
+      if (!blocker) {
+        out.push({
+          task: { id: blockerId, name: `(missing ${blockerId})`, status: "todo" },
+          depth,
+          missing: true
+        });
+        continue;
+      }
+      if (visited.has(blocker.id)) continue;
+      visited.add(blocker.id);
+      out.push({ task: blocker, depth, missing: false });
+      if (blocker.status !== "done") walk(blocker, depth + 1);
+    }
+  }
+  walk(root, 0);
+  return out;
+}
+function renderBlockerLine(node) {
+  const indent = "    " + "  ".repeat(node.depth);
+  const connector = colors.muted(node.depth === 0 ? "\u251C\u2500" : "\u21B3");
+  const idPart = colors.muted(node.task.id);
+  if (node.missing) {
+    return `${indent}${connector} ${colors.error(icons.error)} ${idPart}  ${colors.error("(referenced but missing)")}`;
+  }
+  const status = formatTaskStatus(node.task.status);
+  const marker = node.task.status === "done" ? colors.success(icons.success) : colors.warning(icons.warning);
+  return `${indent}${connector} ${marker} ${idPart}  ${node.task.name}  ${status}`;
+}
+async function taskWhyCommand(taskId) {
+  let id = taskId;
+  if (!id) {
+    const selected = await selectTask("Which task is blocked?");
+    if (!selected) return;
+    id = selected;
+  }
+  const r = await wrapAsync(() => getTasks(), ensureError);
+  if (!r.ok) {
+    showError(r.error.message);
+    return;
+  }
+  const tasks = r.value;
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const root = byId.get(id);
+  if (!root) {
+    showError(new TaskNotFoundError(id).message);
+    return;
+  }
+  printHeader("Why blocked?");
+  log.newline();
+  console.log(`  ${icons.task} ${colors.highlight(root.name)}  ${formatTaskStatus(root.status)}`);
+  console.log(`  ${colors.muted("id:")} ${colors.muted(root.id)}`);
+  log.newline();
+  if (root.status === "done") {
+    console.log(`  ${colors.success(icons.success)} ${colors.success("Task is done \u2014 nothing blocking it.")}`);
+    log.newline();
+    return;
+  }
+  if (root.blockedBy.length === 0) {
+    console.log(`  ${colors.success(icons.success)} ${colors.success("No blockers \u2014 ready to execute.")}`);
+    log.newline();
+    showNextStep(`ralphctl task status ${root.id} in_progress`, "Start working on this task");
+    log.newline();
+    return;
+  }
+  const nodes = collectBlockers(root, byId);
+  const unmet = nodes.filter((n) => !n.missing && n.task.status !== "done");
+  const leafUnmet = unmet.filter((n) => n.task.blockedBy.every((bid) => byId.get(bid)?.status === "done"));
+  console.log(`  ${colors.muted("Dependency chain:")}`);
+  for (const node of nodes) console.log(renderBlockerLine(node));
+  log.newline();
+  if (unmet.length === 0) {
+    console.log(`  ${colors.success(icons.success)} ${colors.success("All blockers are done \u2014 ready to execute.")}`);
+    log.newline();
+    showNextStep(`ralphctl task status ${root.id} in_progress`, "Start working on this task");
+    log.newline();
+    return;
+  }
+  const actionable = leafUnmet.length > 0 ? leafUnmet : unmet;
+  console.log(
+    `  ${colors.warning(icons.warning)} ${colors.warning(`Unblock by completing ${String(actionable.length)} task${actionable.length !== 1 ? "s" : ""} first:`)}`
+  );
+  for (const node of actionable) {
+    console.log(`    ${colors.muted("\u2192")} ${colors.highlight(node.task.id)}  ${node.task.name}`);
+  }
+  log.newline();
+}
+
 // src/integration/cli/commands/ticket/edit.ts
 function validateUrl(url) {
   try {
@@ -5069,6 +5214,7 @@ export {
   taskNextCommand,
   taskReorderCommand,
   taskImportCommand,
+  taskWhyCommand,
   ticketEditCommand,
   ticketListCommand,
   ticketShowCommand,

package/dist/cli.mjs

@@ -5,6 +5,8 @@ import {
   configShowCommand,
   createSharedDeps,
   doctorCommand,
+  getNextAction,
+  loadDashboardData,
   progressLogCommand,
   progressShowCommand,
   projectListCommand,
@@ -33,12 +35,13 @@ import {
   taskReorderCommand,
   taskShowCommand,
   taskStatusCommand,
+  taskWhyCommand,
   ticketEditCommand,
   ticketListCommand,
   ticketRefineCommand,
   ticketRemoveCommand,
   ticketShowCommand
-} from "./chunk-EPDR6VO5.mjs";
+} from "./chunk-SM4GGZSU.mjs";
 import {
   projectAddCommand
 } from "./chunk-D2YGPLIV.mjs";
@@ -52,7 +55,7 @@ import "./chunk-NUYQK5MN.mjs";
 import {
   getTasks,
   sprintStartCommand
-} from "./chunk-CSC4TBJB.mjs";
+} from "./chunk-3HJNVQ7N.mjs";
 import {
   truncate
 } from "./chunk-JOQO4HMM.mjs";
@@ -70,6 +73,7 @@ import {
 import {
   colors,
   error,
+  formatSprintStatus,
   icons,
   log,
   printBanner,
@@ -283,10 +287,11 @@ Examples:
   sprint.command("switch").description("Quick sprint switcher (opens selector)").action(async () => {
     await sprintSwitchCommand();
   });
-  sprint.command("refine [id]").description("Refine ticket specifications").option("--project <name>", "Only refine tickets for specific project").action(async (id, opts) => {
+  sprint.command("refine [id]").description("Refine ticket specifications").option("--project <name>", "Only refine tickets for specific project").option("--auto", "Run without approval prompts (AI drafts requirements autonomously)").action(async (id, opts) => {
     const args = [];
     if (id) args.push(id);
     if (opts?.project) args.push("--project", opts.project);
+    if (opts?.auto) args.push("--auto");
     await sprintRefineCommand(args);
   });
   sprint.command("ideate [id]").description("Quick idea to tasks (refine + plan in one session)").option("--auto", "Run without user interaction (AI decides autonomously)").option("--all-paths", "Explore all project repositories instead of prompting for selection").option("--project <name>", "Pre-select project (skip interactive selection)").action(async (id, opts) => {
@@ -426,6 +431,9 @@ Examples:
     });
   });
   task.command("next").description("Get next task").action(taskNextCommand);
+  task.command("why [id]").description("Explain why a task is blocked (walks the dependency chain)").action(async (id) => {
+    await taskWhyCommand(id);
+  });
   task.command("reorder [id] [position]").description("Change task priority").action(async (id, position) => {
     const args = [];
     if (id) args.push(id);
@@ -578,6 +586,85 @@ Checks performed:
   });
 }
 
+// src/integration/cli/commands/next/next.ts
+function toCommand(action) {
+  return `ralphctl ${action.group} ${action.subCommand}`;
+}
+function computePayload(data) {
+  if (!data) {
+    return { sprint: null, action: null, reason: "no-sprint" };
+  }
+  const sprint = { id: data.sprint.id, name: data.sprint.name, status: data.sprint.status };
+  if (data.sprint.status === "closed") {
+    return { sprint, action: null, reason: "sprint-closed" };
+  }
+  const next = getNextAction(data);
+  if (!next) {
+    return { sprint, action: null, reason: "all-done" };
+  }
+  return {
+    sprint,
+    action: { command: toCommand(next), label: next.label, description: next.description },
+    reason: "action-ready"
+  };
+}
+function renderPorcelain(payload) {
+  if (payload.action) {
+    console.log(payload.action.command);
+    return;
+  }
+  console.log("");
+}
+function renderHuman(payload) {
+  log.newline();
+  if (payload.reason === "no-sprint") {
+    console.log(`  ${colors.muted(icons.inactive)} ${colors.muted("No current sprint.")}`);
+    console.log(`  ${colors.muted(icons.tip)} ${colors.muted("Create one to get started:")}`);
+    console.log(`    ${colors.highlight("ralphctl sprint create")}`);
+    log.newline();
+    return;
+  }
+  if (!payload.sprint) return;
+  const sprintLine = `${icons.sprint} ${colors.highlight(payload.sprint.name)}  ${formatSprintStatus(payload.sprint.status)}`;
+  console.log(`  ${sprintLine}`);
+  if (payload.reason === "sprint-closed") {
+    console.log(`  ${colors.muted(icons.info)} ${colors.muted("Sprint is closed. Start a new one:")}`);
+    console.log(`    ${colors.highlight("ralphctl sprint create")}`);
+    log.newline();
+    return;
+  }
+  if (payload.reason === "all-done") {
+    console.log(`  ${colors.success(icons.success)} ${colors.success("Nothing left to do.")}`);
+    log.newline();
+    return;
+  }
+  const action = payload.action;
+  if (!action) return;
+  console.log(`  ${colors.muted(icons.tip)} ${colors.muted(action.label + ":")} ${colors.muted(action.description)}`);
+  console.log(`    ${colors.highlight(action.command)}`);
+  log.newline();
+}
+async function nextCommand(options = {}) {
+  const data = await loadDashboardData();
+  const payload = computePayload(data);
+  if (options.json) {
+    console.log(JSON.stringify(payload));
+    return;
+  }
+  if (options.porcelain) {
+    renderPorcelain(payload);
+    return;
+  }
+  renderHuman(payload);
+}
+
+// src/integration/cli/commands/next/register.ts
+function registerNextCommands(program2) {
+  program2.command("next").description("Suggest the next workflow action for the current sprint").option("--porcelain", "Print only the suggested command (for shell/tmux integration)").option("--json", "Emit a machine-readable JSON payload").action(async (options) => {
+    await nextCommand(options);
+  });
+}
+
 // src/application/entrypoint.ts
 setSharedDeps(createSharedDeps());
 var program = new Command();
@@ -603,6 +690,12 @@ registerDashboardCommands(program);
 registerConfigCommands(program);
 registerCompletionCommands(program);
 registerDoctorCommands(program);
+registerNextCommands(program);
+function isQuietCommand(argv) {
+  const cmd = argv[2];
+  if (cmd === "next" && (argv.includes("--porcelain") || argv.includes("--json"))) return true;
+  return false;
+}
 async function main() {
   if (process.env["COMP_CWORD"] && process.env["COMP_POINT"] && process.env["COMP_LINE"]) {
     const { handleCompletionRequest } = await import("./handle-BBAZJ44Y.mjs");
@@ -612,7 +705,7 @@ async function main() {
   const isBare = argv.length <= 2;
   const isInteractive = argv[2] === "interactive";
   if (isBare || isInteractive) {
-    const { mountInkApp } = await import("./mount-U7QXVB5Q.mjs");
+    const { mountInkApp } = await import("./mount-2N6H5CWA.mjs");
     const { fallback } = await mountInkApp({ initialView: "repl" });
     if (!fallback) return;
     printBanner();
@@ -623,10 +716,10 @@ async function main() {
     return;
   }
   if (argv[2] === "sprint" && argv[3] === "start") {
-    const { parseSprintStartArgs } = await import("./start-WG7VMEB2.mjs");
+    const { parseSprintStartArgs } = await import("./start-IUDCXIEA.mjs");
     const parsed = parseSprintStartArgs(argv.slice(4));
     if (parsed.ok) {
-      const { mountInkApp } = await import("./mount-U7QXVB5Q.mjs");
+      const { mountInkApp } = await import("./mount-2N6H5CWA.mjs");
       const { getSharedDeps } = await import("./bootstrap-FMHG6DRY.mjs");
       let sprintId;
       try {
@@ -644,7 +737,7 @@ async function main() {
       }
     }
   }
-  printBanner();
+  if (!isQuietCommand(argv)) printBanner();
   await program.parseAsync(argv);
 }
 main().catch((err) => {

package/dist/{mount-U7QXVB5Q.mjs → mount-2N6H5CWA.mjs}

@@ -54,6 +54,7 @@ import {
   taskReorderCommand,
   taskShowCommand,
   taskStatusCommand,
+  taskWhyCommand,
   ticketEditCommand,
   ticketListCommand,
   ticketRefineCommand,
@@ -61,7 +62,7 @@ import {
   ticketShowCommand,
   useCurrentPrompt,
   validateConfigValue
-} from "./chunk-EPDR6VO5.mjs";
+} from "./chunk-SM4GGZSU.mjs";
 import {
   PromptCancelledError,
   projectAddCommand
@@ -108,7 +109,7 @@ import {
   sprintStartCommand,
   updateTaskStatus,
   withSuspendedTui
-} from "./chunk-CSC4TBJB.mjs";
+} from "./chunk-3HJNVQ7N.mjs";
 import {
   addTicket,
   allRequirementsApproved,
@@ -554,6 +555,7 @@ function buildTaskSubMenu(ctx) {
   items.push(titled("VIEW"));
   items.push({ name: "List", value: "list", description: "List all tasks" });
   items.push({ name: "Next", value: "next", description: "Get next task" });
+  items.push({ name: "Why Blocked?", value: "why", description: "Explain why a task is blocked" });
   items.push(blank());
   items.push(titled("MANAGE"));
   items.push({ name: "Add", value: "add", description: "Add a new task" });
@@ -1035,9 +1037,27 @@ var commandMap = {
     show: () => sprintShowCommand([]),
     context: () => sprintContextCommand([]),
     current: () => sprintCurrentCommand(["-"]),
-    refine: () => sprintRefineCommand([]),
+    refine: async () => {
+      const mode = await getPrompt().select({
+        message: "How should refinement run?",
+        choices: [
+          { label: "Interactive \u2014 approve requirements for each ticket", value: "interactive" },
+          { label: "Auto \u2014 AI drafts requirements without prompts", value: "auto" }
+        ]
+      });
+      await sprintRefineCommand(mode === "auto" ? ["--auto"] : []);
+    },
     ideate: () => sprintIdeateCommand([]),
-    plan: () => sprintPlanCommand([]),
+    plan: async () => {
+      const mode = await getPrompt().select({
+        message: "How should planning run?",
+        choices: [
+          { label: "Interactive \u2014 pick affected repos manually", value: "interactive" },
+          { label: "Auto \u2014 AI explores all repos autonomously", value: "auto" }
+        ]
+      });
+      await sprintPlanCommand(mode === "auto" ? ["--auto", "--all-paths"] : []);
+    },
     start: () => sprintStartCommand([]),
     requirements: () => sprintRequirementsCommand([]),
     health: () => sprintHealthCommand(),
@@ -1062,6 +1082,7 @@ var commandMap = {
     show: () => taskShowCommand([]),
     status: () => taskStatusCommand([]),
     next: () => taskNextCommand(),
+    why: () => taskWhyCommand(),
     reorder: () => taskReorderCommand([]),
     remove: () => taskRemoveCommand([])
   },
@@ -1977,6 +1998,7 @@ function initialState() {
     running: /* @__PURE__ */ new Set(),
     blocked: /* @__PURE__ */ new Set(),
     activity: /* @__PURE__ */ new Map(),
+    currentStep: /* @__PURE__ */ new Map(),
     summary: null,
     error: null,
     rateLimit: null
@@ -2038,7 +2060,16 @@ function ExecuteView({ sprintId, executionOptions }) {
     const fresh = signalEvents.slice(processedCountRef.current);
     processedCountRef.current = signalEvents.length;
     setState((prev) => reduceEvents(prev, fresh));
-  }, [signalEvents]);
+    if (fresh.some((e) => e.type === "task-finished")) {
+      void (async () => {
+        try {
+          const tasks = await shared.persistence.getTasks(sprintId);
+          setState((s) => ({ ...s, tasks }));
+        } catch {
+        }
+      })();
+    }
+  }, [signalEvents, shared, sprintId]);
   const [closePromptRun, setClosePromptRun] = useState8(false);
   useEffect8(() => {
     if (!done) return;
@@ -2092,6 +2123,11 @@ function ExecuteView({ sprintId, executionOptions }) {
         activityByTask: state.activity
       }
     ) }),
+    !done && state.currentStep.size > 0 ? /* @__PURE__ */ jsx18(Box17, { marginTop: spacing.section, flexDirection: "column", children: Array.from(state.currentStep.entries()).map(([taskId, label]) => {
+      const task = state.tasks.find((t) => t.id === taskId);
+      const taskName = task?.name ?? taskId.slice(0, 8);
+      return /* @__PURE__ */ jsx18(Spinner, { label: `${taskName} ${glyphs.emDash} ${label}` }, taskId);
+    }) }) : null,
     /* @__PURE__ */ jsx18(Box17, { marginTop: spacing.section, children: /* @__PURE__ */ jsx18(LogTail, { events: logEvents }) }),
     state.error ? /* @__PURE__ */ jsx18(Box17, { marginTop: spacing.section, children: /* @__PURE__ */ jsxs16(Text16, { color: inkColors.error, children: [
       glyphs.cross,
@@ -2123,10 +2159,24 @@ function ExecuteView({ sprintId, executionOptions }) {
     ] }) : null
   ] });
 }
+var STEP_LABELS = {
+  "branch-preflight": "Verifying branch\u2026",
+  "contract-negotiate": "Writing contract\u2026",
+  "mark-in-progress": "Starting\u2026",
+  "execute-task": "Running Claude\u2026",
+  "store-verification": "Storing verification\u2026",
+  "post-task-check": "Running post-task check\u2026",
+  "evaluate-task": "Evaluating\u2026",
+  "mark-done": "Finalizing\u2026"
+};
+function labelForStep(stepName) {
+  return STEP_LABELS[stepName] ?? stepName;
+}
 function reduceEvents(state, events) {
   const running = new Set(state.running);
   const blocked = new Set(state.blocked);
   const activity = new Map(state.activity);
+  const currentStep = new Map(state.currentStep);
   let rateLimit = state.rateLimit;
   for (const event of events) {
     switch (event.type) {
@@ -2135,10 +2185,22 @@ function reduceEvents(state, events) {
         break;
       case "task-finished":
         running.delete(event.taskId);
+        activity.delete(event.taskId);
+        currentStep.delete(event.taskId);
         if (event.status === "blocked" || event.status === "failed") {
           blocked.add(event.taskId);
         }
         break;
+      case "task-step":
+        if (event.phase === "start") {
+          activity.set(event.taskId, labelForStep(event.stepName));
+          currentStep.set(event.taskId, labelForStep(event.stepName));
+        } else {
+          if (currentStep.get(event.taskId) === labelForStep(event.stepName)) {
+            currentStep.delete(event.taskId);
+          }
+        }
+        break;
       case "rate-limit-paused":
         rateLimit = { pausedSince: event.timestamp, delayMs: event.delayMs };
         break;
@@ -2161,7 +2223,7 @@ function reduceEvents(state, events) {
       }
     }
   }
-  return { ...state, running, blocked, activity, rateLimit };
+  return { ...state, running, blocked, activity, currentStep, rateLimit };
 }
 
 // src/integration/ui/tui/views/dashboard-view.tsx
@@ -2436,6 +2498,15 @@ function RefinePhaseView({ sprintId }) {
   useEffect10(() => {
     void loadSprint();
   }, [loadSprint]);
+  useEffect10(() => {
+    if (!state.running) return;
+    const handle = setInterval(() => {
+      void loadSprint();
+    }, 1e3);
+    return () => {
+      clearInterval(handle);
+    };
+  }, [state.running, loadSprint]);
   const runRefine = useCallback5(async () => {
     setState((s) => ({ ...s, running: true, error: null, records: [] }));
     try {
@@ -3470,7 +3541,8 @@ var STEP_LABEL = {
   fetching: "Fetching issue data\u2026",
   title: "Awaiting ticket title\u2026",
   description: "Awaiting ticket description\u2026",
-  saving: "Saving ticket\u2026"
+  saving: "Saving ticket\u2026",
+  another: "Add another ticket?"
 };
 function isValidUrl(value) {
   try {
@@ -3505,40 +3577,52 @@ function TicketAddView() {
         setPhase({ kind: "no-project" });
         return;
       }
-      setPhase({ kind: "running", step: "link" });
-      const link = await prompt.input({
-        message: "Issue link (optional):",
-        validate: (v) => {
-          const trimmed = v.trim();
-          if (trimmed.length === 0) return true;
-          return isValidUrl(trimmed) ? true : "Must be a valid URL (or leave blank)";
+      let count = 0;
+      while (true) {
+        setPhase({ kind: "running", step: "link" });
+        const link = await prompt.input({
+          message: "Issue link (optional):",
+          validate: (v) => {
+            const trimmed = v.trim();
+            if (trimmed.length === 0) return true;
+            return isValidUrl(trimmed) ? true : "Must be a valid URL (or leave blank)";
+          }
+        });
+        const trimmedLink = link.trim();
+        let prefill = null;
+        if (trimmedLink.length > 0) {
+          setPhase({ kind: "running", step: "fetching" });
+          prefill = tryFetchIssue(trimmedLink);
+        }
+        setPhase({ kind: "running", step: "title" });
+        const title = await prompt.input({
+          message: "Title:",
+          default: prefill?.title,
+          validate: (v) => v.trim().length > 0 ? true : "Title is required"
+        });
+        setPhase({ kind: "running", step: "description" });
+        const description = await prompt.editor({
+          message: "Description (recommended)",
+          default: prefill?.body
+        });
+        setPhase({ kind: "running", step: "saving" });
+        const trimmedDescription = description?.trim() ?? "";
+        const ticket = await addTicket({
+          title: title.trim(),
+          description: trimmedDescription.length > 0 ? trimmedDescription : void 0,
+          link: trimmedLink.length > 0 ? trimmedLink : void 0
+        });
+        count++;
+        setPhase({ kind: "running", step: "another" });
+        const another = await prompt.confirm({
+          message: `Add another ticket? (${String(count)} added)`,
+          default: true
+        });
+        if (!another) {
+          setPhase({ kind: "done", ticket, project, prefilled: prefill !== null, count });
+          return;
         }
-      });
-      const trimmedLink = link.trim();
-      let prefill = null;
-      if (trimmedLink.length > 0) {
-        setPhase({ kind: "running", step: "fetching" });
-        prefill = tryFetchIssue(trimmedLink);
       }
-      setPhase({ kind: "running", step: "title" });
-      const title = await prompt.input({
-        message: "Title:",
-        default: prefill?.title,
-        validate: (v) => v.trim().length > 0 ? true : "Title is required"
-      });
-      setPhase({ kind: "running", step: "description" });
-      const description = await prompt.editor({
-        message: "Description (recommended)",
-        default: prefill?.body
-      });
-      setPhase({ kind: "running", step: "saving" });
-      const trimmedDescription = description?.trim() ?? "";
-      const ticket = await addTicket({
-        title: title.trim(),
-        description: trimmedDescription.length > 0 ? trimmedDescription : void 0,
-        link: trimmedLink.length > 0 ? trimmedLink : void 0
-      });
-      setPhase({ kind: "done", ticket, project, prefilled: prefill !== null });
     }
   });
   const hints = useMemo12(() => phase.kind === "running" ? HINTS_RUNNING6 : HINTS_DONE6, [phase.kind]);
@@ -3570,21 +3654,23 @@ function renderBody6(phase) {
       );
     case "error":
       return /* @__PURE__ */ jsx31(ResultCard, { kind: "error", title: "Could not add ticket", lines: [phase.message] });
-    case "done":
+    case "done": {
+      const title = phase.count > 1 ? `${String(phase.count)} tickets added` : phase.prefilled ? "Ticket added (prefilled from issue)" : "Ticket added";
       return /* @__PURE__ */ jsx31(
         ResultCard,
         {
           kind: "success",
-          title: phase.prefilled ? "Ticket added (prefilled from issue)" : "Ticket added",
+          title,
           fields: [
-            ["ID", phase.ticket.id],
-            ["Title", phase.ticket.title],
+            ["Last ID", phase.ticket.id],
+            ["Last title", phase.ticket.title],
             ["Project", `${phase.project.displayName} (${phase.project.name})`],
             ["Status", `requirement: ${phase.ticket.requirementStatus}`]
           ],
           nextSteps: [{ action: "Refine requirements", description: "Home \u2192 Next: Refine Requirements" }]
         }
       );
+    }
   }
 }
 

package/dist/prompts/sprint-feedback.md

@@ -31,7 +31,10 @@ something entirely new (create a file, add a feature, tweak a script), do exactl
    it passes. If no check script is configured, skip this step.
 4. **Output verification results** — Wrap any verification output in `<task-verified>...</task-verified>`. If you
    skipped step 3, emit `<task-verified>no check script configured; change applied</task-verified>`.
-5. **Signal completion** — Output `<task-complete>` once the change is applied and verification (if any) passed.
+5. **Commit your work** — Stage the modified files and create a git commit with a descriptive message summarising the
+   feedback you implemented. The harness refuses to mark the task done with a dirty working tree.
+6. **Signal completion** — Output `<task-complete>` once the change is applied, verification (if any) passed, and the
+   commit has landed.
 
 Only signal `<task-blocked>reason</task-blocked>` if the feedback is literally impossible to carry out (e.g., asks
 you to edit a file in a repository you don't have access to). Ambiguity is **not** a blocker — make a reasonable
@@ -42,6 +45,8 @@ interpretation and proceed.
 - **The feedback is the authoritative instruction** — implement it even if it seems unrelated to the completed tasks.
 - **Do the smallest change that fully satisfies the feedback** — no speculative refactors, no adjacent cleanup.
 - **Make the edits — don't just describe them** — the harness does not apply edits for you; you must write the files.
+- **Must commit** — Create a git commit before signaling completion. Uncommitted changes leave the sprint branch dirty
+  and block sprint close.
 
 </constraints>
 

package/dist/prompts/task-evaluation.md

@@ -21,6 +21,11 @@ These verification criteria are the pre-agreed definition of "done" — your pri
 
 ## Review Protocol
 
+**You are a reviewer — do not edit files.** If you believe a fix is needed, emit `<evaluation-failed>` with a concrete
+critique; the harness will resume the generator to apply the fix. Do not run `git stash`, do not edit tests, do not
+create commits. Your tools are read-only: `git status`, `git log`, `git diff`, file reads, and running existing check
+scripts. Any write operation is a protocol violation.
+
 You are working in this project directory:
 
 ```
@@ -37,7 +42,8 @@ Run deterministic checks first — these are cheap, fast, and authoritative.
 
 1. **Run the check script** (if provided above) — this is the same gate the harness uses post-task. If it fails, the
    implementation fails regardless of how good the code looks. Record the output.
-2. **Run `git status`** — uncommitted changes may indicate incomplete work
+2. **Run `git status`** — the tree MUST be clean. Uncommitted changes from the generator are a Completeness failure;
+   uncommitted changes from you are a protocol violation.
 3. **Run `git log --oneline -10`** — identify which commits belong to this task
 
 Computational results are ground truth. If the check script fails, stop early — the implementation does not pass.

package/dist/{start-WG7VMEB2.mjs → start-IUDCXIEA.mjs}

@@ -2,7 +2,7 @@
 import {
   parseSprintStartArgs,
   sprintStartCommand
-} from "./chunk-CSC4TBJB.mjs";
+} from "./chunk-3HJNVQ7N.mjs";
 import "./chunk-JOQO4HMM.mjs";
 import "./chunk-CFUVE2BP.mjs";
 import "./chunk-747KW2RW.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code & GitHub Copilot across repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",