ralphctl 0.4.0 → 0.4.2

package/dist/{chunk-MRN3Z2XC.mjs → chunk-GL7MKLLS.mjs}

@@ -52,7 +52,7 @@ import {
   updateTask,
   updateTaskStatus,
   validateImportTasks
-} from "./chunk-JYCGQA2D.mjs";
+} from "./chunk-TKPTT2UG.mjs";
 import {
   fetchIssueFromUrl,
   formatIssueContext,
@@ -177,7 +177,7 @@ import {
 // package.json
 var package_default = {
   name: "ralphctl",
-  version: "0.4.0",
+  version: "0.4.2",
   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",

package/dist/{chunk-JYCGQA2D.mjs → chunk-TKPTT2UG.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) => {
@@ -2823,6 +2871,14 @@ function createPerTaskPipeline(deps, useCase, options = {}) {
         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 }))
   ]);
 }
@@ -4183,9 +4239,12 @@ function composePrompt(template, substitutions) {
   }
   return result;
 }
+var CHECK_GATE_EXAMPLE = "Run the project's check gate \u2014 all pass (omit this step when the project has no check script)";
 function buildPlanCommon(projectToolingSection) {
   return composePrompt(loadPartial("plan-common"), {
-    PROJECT_TOOLING: projectToolingSection
+    PLAN_COMMON_EXAMPLES: loadPartial("plan-common-examples"),
+    PROJECT_TOOLING: projectToolingSection,
+    CHECK_GATE_EXAMPLE
   });
 }
 function buildPlannerBase(projectToolingSection) {
@@ -4193,7 +4252,8 @@ function buildPlannerBase(projectToolingSection) {
     HARNESS_CONTEXT: loadPartial("harness-context"),
     COMMON: buildPlanCommon(projectToolingSection),
     VALIDATION: loadPartial("validation-checklist"),
-    SIGNALS: loadPartial("signals-planning")
+    SIGNALS: loadPartial("signals-planning"),
+    CHECK_GATE_EXAMPLE
   };
 }
 function buildInteractivePrompt(context, outputFile, schema, projectToolingSection) {
@@ -4212,9 +4272,13 @@ function buildAutoPrompt(context, schema, projectToolingSection) {
   });
 }
 function buildTaskExecutionPrompt(progressFilePath, noCommit, contextFileName, projectToolingSection = "") {
-  const template = loadTemplate("task-execution");
-  const commitStep = noCommit ? "" : "\n   - **Before continuing:** Create a git commit with a descriptive message for the changes made.";
-  const commitConstraint = noCommit ? "" : "- **Must commit** \u2014 Create a git commit before signaling completion.\n";
+  let template = loadTemplate("task-execution");
+  if (noCommit) {
+    template = template.replace(/^[ \t]*\{\{COMMIT_STEP\}\}\n/m, "\n");
+    template = template.replace(/^[ \t]*\{\{COMMIT_CONSTRAINT\}\}\n/m, "");
+  }
+  const commitStep = noCommit ? "" : "   - **Before continuing:** Create a git commit with a descriptive message for the changes made.";
+  const commitConstraint = noCommit ? "" : "- **Must commit** \u2014 Create a git commit before signaling completion.";
   return composePrompt(template, {
     HARNESS_CONTEXT: loadPartial("harness-context"),
     SIGNALS: loadPartial("signals-task"),
@@ -4227,11 +4291,16 @@ function buildTaskExecutionPrompt(progressFilePath, noCommit, contextFileName, p
 }
 function buildTicketRefinePrompt(ticketContent, outputFile, schema, issueContext = "") {
   const template = loadTemplate("ticket-refine");
+  const issueContextSection = issueContext ? `<context>
+
+${issueContext}
+
+</context>` : "";
   return composePrompt(template, {
     TICKET: ticketContent,
     OUTPUT_FILE: outputFile,
     SCHEMA: schema,
-    ISSUE_CONTEXT: issueContext
+    ISSUE_CONTEXT: issueContextSection
   });
 }
 function buildIdeatePrompt(ideaTitle, ideaDescription, projectName, repositories, outputFile, schema, projectToolingSection) {
@@ -4260,9 +4329,10 @@ function renderExtraDimensions(extras) {
     return { section: "", passBar: "", assessment: "" };
   }
   const section = extras.map(
-    (name, i) => `
-**Dimension ${String(5 + i)} \u2014 ${name}**
+    (name) => `
+<dimension name="${name}" floor="false">
 Additional task-specific dimension flagged by the planner. Apply judgment to whether the implementation satisfies this dimension given the task's verification criteria and steps.
+</dimension>
 `
   ).join("");
   const passBar = extras.map((name) => `
@@ -5217,6 +5287,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}`;
 }
@@ -5276,6 +5365,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/cli.mjs

@@ -41,7 +41,7 @@ import {
   ticketRefineCommand,
   ticketRemoveCommand,
   ticketShowCommand
-} from "./chunk-MRN3Z2XC.mjs";
+} from "./chunk-GL7MKLLS.mjs";
 import {
   projectAddCommand
 } from "./chunk-D2YGPLIV.mjs";
@@ -55,7 +55,7 @@ import "./chunk-NUYQK5MN.mjs";
 import {
   getTasks,
   sprintStartCommand
-} from "./chunk-JYCGQA2D.mjs";
+} from "./chunk-TKPTT2UG.mjs";
 import {
   truncate
 } from "./chunk-JOQO4HMM.mjs";
@@ -705,7 +705,7 @@ async function main() {
   const isBare = argv.length <= 2;
   const isInteractive = argv[2] === "interactive";
   if (isBare || isInteractive) {
-    const { mountInkApp } = await import("./mount-XMN3S4W6.mjs");
+    const { mountInkApp } = await import("./mount-ISHZM36X.mjs");
     const { fallback } = await mountInkApp({ initialView: "repl" });
     if (!fallback) return;
     printBanner();
@@ -716,10 +716,10 @@ async function main() {
     return;
   }
   if (argv[2] === "sprint" && argv[3] === "start") {
-    const { parseSprintStartArgs } = await import("./start-D35SOXMM.mjs");
+    const { parseSprintStartArgs } = await import("./start-76JKJQIH.mjs");
     const parsed = parseSprintStartArgs(argv.slice(4));
     if (parsed.ok) {
-      const { mountInkApp } = await import("./mount-XMN3S4W6.mjs");
+      const { mountInkApp } = await import("./mount-ISHZM36X.mjs");
       const { getSharedDeps } = await import("./bootstrap-FMHG6DRY.mjs");
       let sprintId;
       try {

package/dist/{mount-XMN3S4W6.mjs → mount-ISHZM36X.mjs}

@@ -62,7 +62,7 @@ import {
   ticketShowCommand,
   useCurrentPrompt,
   validateConfigValue
-} from "./chunk-MRN3Z2XC.mjs";
+} from "./chunk-GL7MKLLS.mjs";
 import {
   PromptCancelledError,
   projectAddCommand
@@ -109,7 +109,7 @@ import {
   sprintStartCommand,
   updateTaskStatus,
   withSuspendedTui
-} from "./chunk-JYCGQA2D.mjs";
+} from "./chunk-TKPTT2UG.mjs";
 import {
   addTicket,
   allRequirementsApproved,

package/dist/prompts/ideate-auto.md

@@ -11,6 +11,27 @@ When finished, emit a signal from the `<signals>` block below.
 
 ## Two-Phase Protocol
 
+### Phase 0: Think Before Writing
+
+Before emitting any JSON, write your reasoning in a `<thinking>…</thinking>` block. Use it to interrogate the idea —
+surface hidden assumptions, identify the real user problem, sketch requirements, and reason about which repositories
+and dependencies the work touches. Explicit reasoning produces sharper output than jumping straight to JSON.
+
+The harness's JSON extractor skips everything before the first `{`, so the `<thinking>` block is stripped
+automatically — but the JSON object itself must still be emitted without markdown fences or commentary after it.
+
+```
+<thinking>
+The idea says "webhook notifications" but doesn't say which events. Reviewing the API, the natural candidates are
+task-status transitions. Scope = status-change webhooks only; other event types are out of scope.
+Acceptance: POST to configured URL with JSON payload on task status change; retries on 5xx.
+…
+</thinking>
+{
+  … JSON object …
+}
+```
+
 ### Phase 1: Refine Requirements (WHAT)
 
 Analyze the idea and produce complete, implementation-agnostic requirements:
@@ -87,6 +108,8 @@ If you cannot produce a valid plan, signal the issue instead of outputting incom
 
 - `<planning-blocked>reason</planning-blocked>`
 
+<context>
+
 ## Idea to Implement
 
 **Title:** {{IDEA_TITLE}}
@@ -107,6 +130,8 @@ You have access to these repositories:
 
 {{COMMON}}
 
+</context>
+
 {{VALIDATION}}
 
 ## Output Format
@@ -148,7 +173,7 @@ If you cannot produce a valid plan, output `<planning-blocked>reason</planning-b
         "Update src/repositories/export.ts findExports() to add WHERE clause for date filtering",
         "Add unit tests in src/schemas/__tests__/date-range.test.ts covering valid ranges, invalid formats, and reversed dates",
         "Add integration test in src/controllers/__tests__/export.test.ts for filtered and unfiltered queries",
-        "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
+        "{{CHECK_GATE_EXAMPLE}}"
       ],
       "verificationCriteria": [
         "TypeScript compiles with no errors",

package/dist/prompts/ideate.md

@@ -118,6 +118,8 @@ Focus: Determine HOW to implement the approved requirements
 
 {{VALIDATION}}
 
+<context>
+
 ## Idea to Refine and Plan
 
 **Title:** {{IDEA_TITLE}}
@@ -141,6 +143,8 @@ mention it as an observation.
 
 {{COMMON}}
 
+</context>
+
 ## Output Format
 
 When BOTH phases are approved by the user, write the JSON to: {{OUTPUT_FILE}}
@@ -169,7 +173,7 @@ Use this exact JSON Schema:
         "Update ExportController.getExport() in src/controllers/export.ts to parse and validate date range params",
         "Add date range filtering to ExportRepository.findRecords() in src/repositories/export.ts",
         "Write tests in src/controllers/__tests__/export.test.ts for: no dates, valid range, invalid range, start > end",
-        "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
+        "{{CHECK_GATE_EXAMPLE}}"
       ],
       "verificationCriteria": [
         "TypeScript compiles with no errors",

package/dist/prompts/plan-auto.md

@@ -12,6 +12,27 @@ When finished, emit a signal from the `<signals>` block below.
 
 ## Protocol
 
+### Step 0: Think Before Writing
+
+Before emitting any JSON, write your reasoning in a `<thinking>…</thinking>` block. Use it to work through the problem
+— map tickets to repositories, reason about dependencies, identify risks, and decide on task boundaries. Explicit
+reasoning produces sharper plans than jumping straight to output.
+
+The harness's JSON extractor skips everything before the first `[`, so the `<thinking>` block is stripped
+automatically — but the JSON array itself must still be emitted without markdown fences or commentary after it.
+
+```
+<thinking>
+Ticket 1 touches both the API and the worker repo — split into two tasks with a blockedBy edge.
+The shared schema change must land first so the worker can import it.
+Verification criterion for the API task: a contract test against the new schema.
+…
+</thinking>
+[
+  { … JSON array … }
+]
+```
+
 ### Step 1: Explore the Project
 
 Scope exploration to what will change the plan — read instruction files first, then only the specific files you need
@@ -55,10 +76,14 @@ The sprint contains:
 - **Existing Tasks**: Tasks from a previous planning run (your output replaces all existing tasks)
 - **Projects**: Each ticket belongs to a project which may have multiple repository paths
 
+<context>
+
 {{CONTEXT}}
 
 {{COMMON}}
 
+</context>
+
 ### Step 5: Handle Blockers
 
 If you cannot produce a valid task breakdown, signal the issue instead of outputting incomplete JSON:
@@ -73,6 +98,9 @@ If you cannot produce a valid task breakdown, signal the issue instead of output
 
 ## Output
 
+Your output MAY begin with a `<thinking>…</thinking>` block — the harness's JSON extractor skips everything before the
+first `[`. The JSON array itself must still be emitted without markdown fences or surrounding prose.
+
 Output only the JSON document matching the schema below — the harness parses your raw output directly as JSON, so emit
 it without markdown fences, commentary, or surrounding prose. If you cannot produce tasks, output a
 `<planning-blocked>` signal instead.
@@ -102,7 +130,7 @@ JSON Schema:
     "steps": [
       "Create src/utils/validation.ts with validateEmail(), validatePhone(), validateDateRange()",
       "Add corresponding unit tests in src/utils/__tests__/validation.test.ts covering valid inputs, invalid inputs, and edge cases (empty strings, unicode)",
-      "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
+      "{{CHECK_GATE_EXAMPLE}}"
     ],
     "verificationCriteria": [
       "TypeScript compiles with no errors",
@@ -123,7 +151,7 @@ JSON Schema:
       "Wire up validation from src/utils/validation.ts with inline error messages",
       "Add form submission handler that calls POST /api/users",
       "Write component tests in src/components/__tests__/RegistrationForm.test.ts for valid submission, validation errors, and API failure",
-      "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
+      "{{CHECK_GATE_EXAMPLE}}"
     ],
     "verificationCriteria": [
       "TypeScript compiles with no errors",

package/dist/prompts/plan-common-examples.md

@@ -0,0 +1,82 @@
+<examples>
+
+The illustrations below are non-normative — they show good/bad shapes for the rules stated in `plan-common.md`. Use
+them as calibration, not templates to copy literally.
+
+## Verification Criteria — good vs bad
+
+> **Good criteria (verifiable, unambiguous):**
+>
+> - "TypeScript compiles with no errors"
+> - "All existing tests pass plus new tests for the added feature"
+> - "GET /api/users returns 200 with paginated user list"
+> - "GET /api/users?page=-1 returns 400 with validation error"
+> - "Component renders without console errors in browser"
+> - "Playwright e2e: login flow completes without errors" _(UI tasks with Playwright configured)_
+
+> **Bad criteria (vague, not independently verifiable):**
+>
+> - "Code is clean and well-structured"
+> - "Error handling is appropriate"
+> - "Performance is acceptable"
+
+## Dependency Graph — good vs bad
+
+### Good Dependency Graph
+
+```
+Task 1: Add shared validation utilities       (no deps)
+Task 2: Implement user registration form       (blockedBy: [1])
+Task 3: Implement user profile editor          (blockedBy: [1])
+Task 4: Add form submission analytics          (blockedBy: [2, 3])
+```
+
+Tasks 2 and 3 run in parallel (both depend only on 1). Task 4 waits for both.
+
+### Bad Dependency Graph
+
+```
+Task 1: Add validation utilities               (no deps)
+Task 2: Implement registration form            (blockedBy: [1])
+Task 3: Implement profile editor               (blockedBy: [2])  <-- WRONG
+Task 4: Add submission analytics               (blockedBy: [3])  <-- WRONG
+```
+
+Task 3 does not actually need Task 2 — it only needs Task 1. This creates a false serial chain that prevents parallel
+execution.
+
+## Precise Steps — good vs bad
+
+Bad — vague steps that force the agent to guess:
+
+```json
+{
+  "name": "Add user authentication",
+  "steps": ["Implement auth", "Add tests", "Update docs"]
+}
+```
+
+Good — precise steps with file paths and pattern references:
+
+```json
+{
+  "name": "Add user authentication",
+  "projectPath": "/Users/dev/my-app",
+  "steps": [
+    "Create auth service in src/services/auth.ts with login(), logout(), getCurrentUser() — follow the pattern in src/services/user.ts for error handling and return types",
+    "Add AuthContext provider in src/contexts/AuthContext.tsx wrapping the app — follow existing ThemeContext pattern",
+    "Create useAuth hook in src/hooks/useAuth.ts exposing auth state and actions",
+    "Add ProtectedRoute wrapper component in src/components/ProtectedRoute.tsx",
+    "Write unit tests in src/services/__tests__/auth.test.ts — follow test patterns in src/services/__tests__/user.test.ts",
+    "{{CHECK_GATE_EXAMPLE}}"
+  ],
+  "verificationCriteria": [
+    "TypeScript compiles with no errors",
+    "All existing tests pass plus new auth tests",
+    "ProtectedRoute redirects unauthenticated users to /login",
+    "useAuth hook exposes isAuthenticated, user, login, and logout"
+  ]
+}
+```
+
+</examples>

package/dist/prompts/plan-common.md

@@ -1,17 +1,22 @@
 ## Project Resources
 
-Each repository may ship with project-specific instruction files at its root and a `.claude/` configuration directory.
-Read them during exploration and reference them throughout planning:
+During exploration, check for project instruction files if present. Treat whichever files exist as authoritative for
+that codebase; skip silently when absent.
+
+**Instruction files (any ecosystem):**
+
+- **`CLAUDE.md` / `AGENTS.md`** — when present: project-level rules, conventions, and persistent memory
+- **`.github/copilot-instructions.md`** — when present: GitHub Copilot-specific repository instructions
+- **`README.md`** and manifest files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, …) — setup,
+  scripts, and dependencies
+
+**Claude-specific configuration (only when the repo has a `.claude/` directory):**
 
-- **`CLAUDE.md` / `AGENTS.md`** — project-level rules, conventions, and persistent memory
-- **`.github/copilot-instructions.md`** — GitHub Copilot-specific repository instructions, when present
 - **`.mcp.json`** — MCP servers the project ships with (Playwright, database inspection, etc.)
 - **`.claude/agents/`** — subagent definitions for Task-tool delegation
 - **`.claude/skills/`** — custom skills invokable with the Skill tool for project-specific workflows
 - **`.claude/settings.json`** / **`.claude/settings.local.json`** — tool permissions, model preferences, hooks
 
-When repository instruction files exist, treat their instructions as authoritative for that codebase.
-
 ## What Makes a Great Task
 
 A great task can be picked up cold by an AI agent, implemented independently, and verified as done — by a _different_ AI
@@ -63,6 +68,8 @@ Right size (one task covering the full change):
 
 ### Verification Criteria (The Evaluator Contract)
 
+_See the `<examples>` block at the end of this page for good/bad pairs._
+
 Every task must include a `verificationCriteria` array — these are the **done contract** between the generator (task
 executor) and the evaluator (independent reviewer). The evaluator grades each criterion as pass/fail across four
 floor dimensions: correctness, completeness, safety, and consistency. If ANY dimension fails, the task fails
@@ -86,21 +93,6 @@ Write criteria that are:
 - **Unambiguous** — two reviewers would agree on pass/fail
 - **Outcome-oriented** — describe WHAT is true when done, not HOW to get there
 
-> **Good criteria (verifiable, unambiguous):**
->
-> - "TypeScript compiles with no errors"
-> - "All existing tests pass plus new tests for the added feature"
-> - "GET /api/users returns 200 with paginated user list"
-> - "GET /api/users?page=-1 returns 400 with validation error"
-> - "Component renders without console errors in browser"
-> - "Playwright e2e: login flow completes without errors" _(UI tasks with Playwright configured)_
-
-> **Bad criteria (vague, not independently verifiable):**
->
-> - "Code is clean and well-structured"
-> - "Error handling is appropriate"
-> - "Performance is acceptable"
-
 Aim for 2-4 criteria per task. Include at least one criterion that is computationally checkable (test pass, type check,
 lint clean). For **UI/frontend tasks**, if the project has Playwright configured, add a browser-verifiable criterion —
 the evaluator will attempt visual verification using Playwright or browser tools when the project supports it.
@@ -108,7 +100,8 @@ the evaluator will attempt visual verification using Playwright or browser tools
 ### Guidelines
 
 1. **Outcome-oriented** — Each task delivers a testable result
-2. **Merge create+use** — Never separate "create X" from "use X" — that is one task
+2. **Merge create+use** — Keep "create X" and "use X" in one task — except when a stable contract makes them
+   independently testable (e.g. schema + migration lands first, consumer wiring lands after)
 3. **Let scope drive task count** — do not aim for a specific number. Fewer, larger coherent tasks beat many
    micro-tasks; split only when parallelism or a clean boundary justifies it
 4. **Merge serial chains** — If tasks only make sense when run in sequence, fold them into one task
@@ -134,6 +127,8 @@ the evaluator will attempt visual verification using Playwright or browser tools
 
 ## Dependency Graph
 
+_See the `<examples>` block at the end of this page for good/bad pairs._
+
 Tasks execute in dependency order — foundations before dependents.
 
 ### Guidelines
@@ -143,29 +138,6 @@ Tasks execute in dependency order — foundations before dependents.
 3. **Maximize parallelism** — Only add `blockedBy` when there is a real code dependency
 4. **Validate the DAG** — No cycles; earlier tasks cannot depend on later ones
 
-### Good Dependency Graph
-
-```
-Task 1: Add shared validation utilities       (no deps)
-Task 2: Implement user registration form       (blockedBy: [1])
-Task 3: Implement user profile editor          (blockedBy: [1])
-Task 4: Add form submission analytics          (blockedBy: [2, 3])
-```
-
-Tasks 2 and 3 run in parallel (both depend only on 1). Task 4 waits for both.
-
-### Bad Dependency Graph
-
-```
-Task 1: Add validation utilities               (no deps)
-Task 2: Implement registration form            (blockedBy: [1])
-Task 3: Implement profile editor               (blockedBy: [2])  <-- WRONG
-Task 4: Add submission analytics               (blockedBy: [3])  <-- WRONG
-```
-
-Task 3 does not actually need Task 2 — it only needs Task 1. This creates a false serial chain that prevents parallel
-execution.
-
 **Dependency test**: For each `blockedBy` entry, ask: "Does this task literally use code produced by the blocker?" If
 not, remove the dependency.
 
@@ -177,10 +149,14 @@ Each task must specify which repository it executes in via `projectPath`:
 2. **Split by repo** — If a ticket affects multiple repos, create separate tasks per repo with dependencies
 3. **Use exact paths** — `projectPath` must be one of the absolute paths from the project's Repositories section
 
-Never create a task that modifies files in multiple repos — split it.
+Split cross-repo work into one task per repo with `blockedBy` — except when atomicity is genuinely required (a
+single commit must land in both repos to avoid broken state), in which case flag the task and surface the need for
+human coordination.
 
 ## Precise Step Declarations
 
+_See the `<examples>` block at the end of this page for good/bad pairs._
+
 Every task must include explicit, actionable steps — the implementation checklist.
 
 ### Step Requirements
@@ -194,38 +170,6 @@ Every task must include explicit, actionable steps — the implementation checkl
    instruction files
 5. **No ambiguity** — Another developer should be able to follow steps without guessing
 
-Bad — vague steps that force the agent to guess:
-
-```json
-{
-  "name": "Add user authentication",
-  "steps": ["Implement auth", "Add tests", "Update docs"]
-}
-```
-
-Good — precise steps with file paths and pattern references:
-
-```json
-{
-  "name": "Add user authentication",
-  "projectPath": "/Users/dev/my-app",
-  "steps": [
-    "Create auth service in src/services/auth.ts with login(), logout(), getCurrentUser() — follow the pattern in src/services/user.ts for error handling and return types",
-    "Add AuthContext provider in src/contexts/AuthContext.tsx wrapping the app — follow existing ThemeContext pattern",
-    "Create useAuth hook in src/hooks/useAuth.ts exposing auth state and actions",
-    "Add ProtectedRoute wrapper component in src/components/ProtectedRoute.tsx",
-    "Write unit tests in src/services/__tests__/auth.test.ts — follow test patterns in src/services/__tests__/user.test.ts",
-    "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
-  ],
-  "verificationCriteria": [
-    "TypeScript compiles with no errors",
-    "All existing tests pass plus new auth tests",
-    "ProtectedRoute redirects unauthenticated users to /login",
-    "useAuth hook exposes isAuthenticated, user, login, and logout"
-  ]
-}
-```
-
 Use actual file paths discovered during exploration. Reference the repository instruction files for verification
 commands.
 
@@ -234,6 +178,10 @@ commands.
 Start with an action verb (Add, Create, Update, Fix, Refactor, Remove, Migrate). Include the feature/concept, not files.
 Keep under 60 characters. Avoid vague verbs (Improve, Enhance, Handle).
 
+See `<examples>` below for concrete good/bad pairs.
+
+{{PLAN_COMMON_EXAMPLES}}
+
 ## Delegation to Available Tooling
 
 The "Project Tooling" section below (when present) lists subagents, skills, and MCP servers detected in the target

package/dist/prompts/plan-interactive.md

@@ -72,7 +72,7 @@ before the plan is finalized.
    **Steps:**
    1. Create src/utils/csvExport.ts with column formatters for date, number, and string types
    2. Add unit tests in src/utils/__tests__/csvExport.test.ts covering empty data, special characters, and large datasets
-   3. Run `pnpm typecheck && pnpm lint && pnpm test` — all pass
+   3. Run the project's check/test/build gate — all pass
    ```
 
 2. **Show the dependency graph** — Make it obvious which tasks run in parallel vs sequentially, and why each dependency
@@ -123,10 +123,14 @@ The sprint contains:
 - **Existing Tasks**: Tasks from a previous planning run (your output replaces all existing tasks)
 - **Projects**: Each ticket belongs to a project which may have multiple repository paths
 
+<context>
+
 {{CONTEXT}}
 
 {{COMMON}}
 
+</context>
+
 ### Repository Assignment
 
 Repositories have been pre-selected by the user. Only create tasks targeting these repositories — the harness executes
@@ -166,7 +170,7 @@ Use this exact JSON Schema:
     "Update ExportController.getExport() in src/controllers/export.ts to parse and validate date range params",
     "Add date range filtering to ExportRepository.findRecords() in src/repositories/export.ts",
     "Write tests in src/controllers/__tests__/export.test.ts for: no dates, valid range, invalid range, start > end",
-    "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
+    "{{CHECK_GATE_EXAMPLE}}"
   ],
   "verificationCriteria": [
     "TypeScript compiles with no errors",

package/dist/prompts/sprint-feedback.md

@@ -19,19 +19,26 @@ something entirely new (create a file, add a feature, tweak a script), do exactl
 
 ## User Feedback — Implement this
 
+<task-specification>
+
 {{FEEDBACK}}
 
+</task-specification>
+
 ## Protocol
 
 1. **Parse the feedback as an instruction** — Identify the concrete change(s) requested. If it says "create X", create
    X. If it says "change Y", change Y. Do not ask for clarification unless the instruction is genuinely contradictory.
 2. **Implement the change** — Create or edit the files required to satisfy the feedback. Make the smallest change that
    fully carries out the instruction.
-3. **Run verification** — If the project has a check script (e.g., `pnpm test`, `pnpm typecheck`), run it and confirm
-   it passes. If no check script is configured, skip this step.
+3. **Run verification** — If the project has a check script (test, typecheck, lint, or build command), run it and
+   confirm 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 +49,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.
@@ -52,10 +58,16 @@ Now apply semantic judgment to what the computational checks cannot catch:
 2. **Read the changed files carefully** — understand the full implementation, not just the diff.
 3. **Read surrounding code** — check that the implementation follows existing patterns and conventions.
 4. **Augment the Project Tooling section above** — the section lists detected subagents, skills, and MCP servers.
-   Additionally skim `package.json` scripts, `playwright.config.*`, `cypress.config.*`, `vitest.config.*`, `.storybook/`,
-   `CLAUDE.md`, and `.github/copilot-instructions.md` for the test/verification stack and any conventions the section
-   didn't surface. Note which application type this is (backend API / CLI / frontend SPA / fullstack / library) — it
-   determines which verification methods apply.
+   Additionally skim repository config for the test/verification stack and any conventions the section didn't surface.
+   Note which application type this is (backend API / CLI / frontend SPA / fullstack / library) — it determines which
+   verification methods apply.
+
+   <examples>
+   Representative files to scan when present — not an exhaustive list, adapt to the ecosystem:
+   `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `playwright.config.*`, `cypress.config.*`,
+   `vitest.config.*`, `.storybook/`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`.
+   </examples>
+
 5. **Run extended verification when the detected tooling makes it cheap and deterministic:**
    - **Frontend/UI tasks** — if Playwright or Cypress is configured, run a targeted e2e test or use a browser MCP to
      verify the changed UI renders correctly (console errors, layout, interactive behaviour).
@@ -72,14 +84,15 @@ Evaluate the implementation across the dimensions below. Each dimension is pass/
 dimension fails, the overall evaluation fails. The first four are the floor — every task is graded on them. The
 planner may have flagged additional task-specific dimensions; when present, they are graded on top of the floor.
 
-**Dimension 1 — Correctness**
+<dimension name="Correctness" floor="true">
 Does the implementation do what the specification says? Check for:
 
 - Logical errors, off-by-one, race conditions, type issues
 - Behavior matches each verification criterion (grade each one explicitly)
 - Edge cases handled where specified
+  </dimension>
 
-**Dimension 2 — Completeness**
+<dimension name="Completeness" floor="true">
 Is the full specification implemented? Check for:
 
 - Every verification criterion is satisfied (not just most)
@@ -87,25 +100,29 @@ Is the full specification implemented? Check for:
 - No TODO/FIXME/HACK markers left behind that indicate unfinished work
 - Uncommitted changes that look like incomplete work (WIP diffs, stashed edits) — committing is expected unless the
   task's contract says otherwise
+  </dimension>
 
-**Dimension 3 — Safety**
+<dimension name="Safety" floor="true">
 Are there security or reliability issues? Check for:
 
 - Injection vulnerabilities (SQL, command, XSS)
 - Validation gaps on external input
 - Exposed secrets, hardcoded credentials
 - Unsafe error handling that leaks internals
+  </dimension>
 
-**Dimension 4 — Consistency**
+<dimension name="Consistency" floor="true">
 Does the implementation fit the codebase? Check for:
 
 - Follows existing patterns and conventions (naming, structure, error handling)
 - Uses existing utilities instead of reinventing them
 - No unnecessary changes outside the task scope — spec drift
 - Test patterns match the project's existing test style
+  </dimension>
   {{EXTRA_DIMENSIONS_SECTION}}
-  Evaluate only what was asked vs what was delivered — suggesting improvements beyond the task scope creates noise that
-  distracts from the actual pass/fail decision.
+
+Evaluate only what was asked vs what was delivered — suggesting improvements beyond the task scope creates noise that
+distracts from the actual pass/fail decision.
 
 ### Pass Bar
 
@@ -159,6 +176,8 @@ Each issue must reference which dimension it violates.]
 
 ### Calibration Examples
 
+<examples>
+
 **Example of a correct PASS:**
 
 > Task: "Add date validation to export endpoint"
@@ -187,6 +206,8 @@ Each issue must reference which dimension it violates.]
 > 2. [Safety] `src/repositories/users.ts:23` — `WHERE name LIKE '%${query}%'` is SQL injection. Use parameterized
 >    query: `WHERE name LIKE $1` with `%${query}%` as parameter.
 
+</examples>
+
 Be direct and specific — point to files, lines, and concrete problems.
 
 {{SIGNALS}}

package/dist/prompts/task-execution.md

@@ -15,16 +15,17 @@ When finished, emit a signal from the `<signals>` block below.
 - **Respect task boundaries** — complete exactly the declared steps for this one task, then stop. Other agents may be
   working on neighboring tasks in parallel; skipping steps, improvising, or editing files outside the declared set
   causes merge conflicts with their work.
-- **Prefer fixing the code over the test** — a failing test usually indicates a bug in the implementation. Update a
-  test only when the declared steps intentionally change the behaviour it asserts (e.g. a regression fix, a contract
-  change). Do not remove, skip, or weaken a test to make a failure go away — that masks real bugs. If the right move
-  is genuinely ambiguous, signal `<task-blocked>` so a human can decide.
+- **Prefer fixing the code over the test** — a failing test usually indicates a bug in the implementation. Update
+  tests only when the declared steps intentionally change the asserted behaviour (e.g. a contract change, a regression
+  fix). If the right move is genuinely ambiguous, signal `<task-blocked>` so a human can decide — do not silently
+  weaken a test to make a failure go away.
 - **Verify before completing** — the harness runs a post-task check gate; unverified work will be caught and rejected.
 - **Append progress, never overwrite** — append each progress entry at the end of the progress file. Overwriting
   erases context that downstream tasks depend on.
 - **Leave {{CONTEXT_FILE}} and task definitions alone** — the context file is cleaned up by the harness (committing it
   pollutes the repo); the task name, description, steps, and other task files are immutable.
-  {{COMMIT_CONSTRAINT}}
+
+{{COMMIT_CONSTRAINT}}
 
 </constraints>
 
@@ -93,7 +94,8 @@ Complete these steps IN ORDER:
 1. **Confirm all steps done** — Every task step has been completed
 2. **Run ALL verification commands** — Execute every verification command (see Check Script section in the context file
    or project instructions). Fix any failures before proceeding. The harness runs the check script as a post-task
-   gate — your task is not marked done unless it passes.{{COMMIT_STEP}}
+   gate — your task is not marked done unless it passes.
+   {{COMMIT_STEP}}
 3. **Update progress file** — Append to {{PROGRESS_FILE}} using this format:
 
    ```markdown
@@ -142,17 +144,15 @@ Complete these steps IN ORDER:
    - The WHERE clause builder in src/repositories/base.ts can be extended for future filters
    ```
 
-4. **Output verification results:**
+4. **Output verification results** — use the actual commands the harness ran; the examples below are illustrative:
 
 <!-- prettier-ignore -->
 ```
 <task-verified>
-$ pnpm typecheck
-No type errors
-$ pnpm lint
-No lint errors
-$ pnpm test
-47 tests passed
+$ <check-command-1>
+<output>
+$ <check-command-2>
+<output>
 </task-verified>
 ```
 

package/dist/prompts/ticket-refine.md

@@ -223,10 +223,14 @@ The `ref` field should match either:
 - The ticket's internal ID
 - The exact ticket title
 
+<task-specification>
+
 ## Ticket to Refine
 
 {{TICKET}}
 
+</task-specification>
+
 {{ISSUE_CONTEXT}}
 
 ---

package/dist/prompts/validation-checklist.md

@@ -1,3 +1,5 @@
+<validation-checklist>
+
 ## Pre-Output Validation
 
 Before writing the JSON output, verify EVERY item:
@@ -12,3 +14,5 @@ Before writing the JSON output, verify EVERY item:
 8. **`projectPath` assigned** — every task uses a path from the available repositories
 9. **Verification criteria** — every task has 2-4 `verificationCriteria` that are testable and unambiguous
 10. **Raw JSON output** — the output is valid JSON matching the schema exactly; the harness parses the output directly as JSON, so emit it without markdown fences, commentary, or surrounding prose
+
+</validation-checklist>

package/dist/{start-D35SOXMM.mjs → start-76JKJQIH.mjs}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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",