ralphctl 0.2.2 → 0.2.4

package/dist/{chunk-Q3VWJARJ.mjs → chunk-UBPZHHCD.mjs}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-7TG3EAQ2.mjs";
 import {
   createProject
-} from "./chunk-LG6B7QVO.mjs";
+} from "./chunk-EUNAUHC3.mjs";
 import {
   ensureError,
   wrapAsync
@@ -16,7 +16,7 @@ import {
 import {
   expandTilde,
   validateProjectPath
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-IB6OCKZW.mjs";
 import {
   IOError,
   ProjectExistsError

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   addCheckScriptToRepository,
   projectAddCommand
-} from "./chunk-Q3VWJARJ.mjs";
+} from "./chunk-UBPZHHCD.mjs";
 import {
   addTask,
   areAllTasksDone,
@@ -52,13 +52,13 @@ import {
   sprintStartCommand,
   updateTaskStatus,
   validateImportTasks
-} from "./chunk-XXIHDQOH.mjs";
+} from "./chunk-U62BX47C.mjs";
 import {
   escapableSelect
 } from "./chunk-7LZ6GOGN.mjs";
 import {
   sprintCreateCommand
-} from "./chunk-XQHEKKDN.mjs";
+} from "./chunk-DUU5346E.mjs";
 import {
   addTicket,
   allRequirementsApproved,
@@ -73,7 +73,7 @@ import {
   removeTicket,
   ticketAddCommand,
   updateTicket
-} from "./chunk-XPDI4SYI.mjs";
+} from "./chunk-742XQ7FL.mjs";
 import {
   EXIT_ERROR,
   exitWithCode
@@ -84,7 +84,7 @@ import {
   listProjects,
   removeProject,
   removeProjectRepo
-} from "./chunk-LG6B7QVO.mjs";
+} from "./chunk-EUNAUHC3.mjs";
 import {
   DEFAULT_EVALUATION_ITERATIONS,
   assertSprintStatus,
@@ -107,7 +107,7 @@ import {
   setEditor,
   setEvaluationIterations,
   withFileLock
-} from "./chunk-KPTPKLXY.mjs";
+} from "./chunk-JRFOUFD3.mjs";
 import {
   ensureError,
   wrapAsync
@@ -122,6 +122,7 @@ import {
   TaskStatusSchema,
   TasksSchema,
   assertSafeCwd,
+  ensureDir,
   expandTilde,
   fileExists,
   getDataDir,
@@ -133,7 +134,7 @@ import {
   getTasksFilePath,
   readValidatedJson,
   validateProjectPath
-} from "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-IB6OCKZW.mjs";
 import {
   DomainError,
   NoCurrentSprintError,
@@ -3763,7 +3764,7 @@ async function interactiveMode() {
       continue;
     }
     if (command === "wizard") {
-      const { runWizard } = await import("./wizard-D7N5WZ5H.mjs");
+      const { runWizard } = await import("./wizard-HWOH2HPV.mjs");
       await runWizard();
       continue;
     }
@@ -3898,6 +3899,87 @@ async function sprintSwitchCommand() {
   log.newline();
 }
 
+// src/commands/sprint/insights.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import { join as join5 } from "path";
+async function sprintInsightsCommand(args) {
+  const exportFlag = args.includes("--export");
+  const positionalArgs = args.filter((a) => !a.startsWith("--"));
+  const sprintId = positionalArgs[0];
+  const sprintR = await wrapAsync(async () => {
+    if (sprintId) return getSprint(sprintId);
+    return getCurrentSprintOrThrow();
+  }, ensureError);
+  if (!sprintR.ok) {
+    showError(sprintR.error.message);
+    return;
+  }
+  const sprint = sprintR.value;
+  const tasks = await getTasks(sprint.id);
+  printHeader(`Sprint Insights: ${sprint.name}`, icons.sprint);
+  const evaluatedTasks = tasks.filter((t) => t.evaluated);
+  if (evaluatedTasks.length === 0) {
+    log.info("No evaluation data found for this sprint.");
+    return;
+  }
+  const totalTasks = tasks.length;
+  const evaluatedCount = evaluatedTasks.length;
+  const withOutput = evaluatedTasks.filter((t) => t.evaluationOutput && t.evaluationOutput.trim().length > 0);
+  console.log(`  Tasks evaluated: ${colors.accent(String(evaluatedCount))} / ${String(totalTasks)} total`);
+  log.newline();
+  if (withOutput.length > 0) {
+    console.log(`  ${colors.accent("Evaluation output:")}`);
+    for (const task of withOutput) {
+      const output = task.evaluationOutput ?? "";
+      const truncated = output.length > 200 ? output.slice(0, 200) + "..." : output;
+      console.log(`    ${icons.bullet} ${colors.accent(task.name)}: ${colors.muted(truncated)}`);
+    }
+    log.newline();
+  }
+  console.log(`  ${colors.accent("Harness recommendations:")}`);
+  if (withOutput.length > 1) {
+    console.log(
+      `    ${icons.bullet} Consider reviewing evaluation failure patterns and updating CLAUDE.md with lessons learned.`
+    );
+  }
+  if (withOutput.length > 0) {
+    console.log(
+      `    ${icons.bullet} Run: ${colors.muted("ralphctl sprint insights --export")} to save details to $RALPHCTL_ROOT/insights/<sprint-id>.md`
+    );
+  }
+  log.newline();
+  if (exportFlag) {
+    await exportInsights(sprint, tasks);
+  }
+}
+async function exportInsights(sprint, tasks) {
+  const dir = join5(getDataDir(), "insights");
+  await ensureDir(dir);
+  const filePath = join5(dir, `${sprint.id}.md`);
+  const evaluatedCount = tasks.filter((t) => t.evaluated).length;
+  const lines = [
+    `# Sprint Insights: ${sprint.name}`,
+    "",
+    `**Date:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    `**Sprint ID:** ${sprint.id}`,
+    `**Tasks evaluated:** ${String(evaluatedCount)} / ${String(tasks.length)} total`,
+    "",
+    "## Evaluation Details"
+  ];
+  for (const task of tasks) {
+    lines.push("");
+    lines.push(`### ${task.name} (${task.id})`);
+    lines.push(`**Status:** ${task.status}`);
+    lines.push(`**Evaluated:** ${task.evaluated ? "yes" : "no"}`);
+    lines.push("");
+    lines.push(task.evaluationOutput ?? "No evaluation output");
+    lines.push("");
+    lines.push("---");
+  }
+  await writeFile2(filePath, lines.join("\n"), "utf-8");
+  log.success(`Insights exported to ${colors.accent(filePath)}`);
+}
+
 // src/commands/sprint/index.ts
 function registerSprintCommands(program2) {
   const sprint = program2.command("sprint").description("Manage sprints");
@@ -3974,7 +4056,13 @@ Examples:
   sprint.command("health").description("Check sprint health").action(async () => {
     await sprintHealthCommand();
   });
-  sprint.command("start [id]").description("Run automated implementation loop").option("-s, --session", "Interactive AI session (collaborate with your AI provider)").option("-t, --step", "Step through tasks with approval between each").option("-c, --count <n>", "Limit to N tasks").option("--no-commit", "Skip automatic git commit after each task completes").option("--concurrency <n>", "Max parallel tasks (default: auto based on unique repos)").option("--max-retries <n>", "Max rate-limit retries per task (default: 5)").option("--fail-fast", "Stop launching new tasks on first failure").option("-f, --force", "Skip precondition checks (e.g., unplanned tickets)").option("--refresh-check", "Force re-run check scripts even if they already ran this sprint").option("-b, --branch", "Create sprint branch (ralphctl/<sprint-id>) in all repos").option("--branch-name <name>", "Use a custom branch name for sprint execution").option("--max-budget-usd <amount>", "Max USD budget per AI task (Claude only)").option("--fallback-model <model>", "Fallback model when primary is overloaded (Claude only)").addHelpText(
+  sprint.command("insights [id]").description("Analyze evaluation results and suggest improvements").option("--export", "Export insights to $RALPHCTL_ROOT/insights/<sprint-id>.md").action(async (id, opts) => {
+    const args = [];
+    if (id) args.push(id);
+    if (opts?.export) args.push("--export");
+    await sprintInsightsCommand(args);
+  });
+  sprint.command("start [id]").description("Run automated implementation loop").option("-s, --session", "Interactive AI session (collaborate with your AI provider)").option("-t, --step", "Step through tasks with approval between each").option("-c, --count <n>", "Limit to N tasks").option("--no-commit", "Skip automatic git commit after each task completes").option("--concurrency <n>", "Max parallel tasks (default: auto based on unique repos)").option("--max-retries <n>", "Max rate-limit retries per task (default: 5)").option("--fail-fast", "Stop launching new tasks on first failure").option("-f, --force", "Skip precondition checks (e.g., unplanned tickets)").option("--refresh-check", "Force re-run check scripts even if they already ran this sprint").option("-b, --branch", "Create sprint branch (ralphctl/<sprint-id>) in all repos").option("--branch-name <name>", "Use a custom branch name for sprint execution").option("--max-budget-usd <amount>", "Max USD budget per AI task (Claude only)").option("--fallback-model <model>", "Fallback model when primary is overloaded (Claude only)").option("--max-turns <number>", "Max agentic turns per task (Claude only, default: 200)").addHelpText(
     "after",
     `
 Exit Codes:
@@ -4012,6 +4100,7 @@ Branch Management:
       if (opts?.branchName) args.push("--branch-name", opts.branchName);
       if (opts?.maxBudgetUsd) args.push("--max-budget-usd", opts.maxBudgetUsd);
       if (opts?.fallbackModel) args.push("--fallback-model", opts.fallbackModel);
+      if (opts?.maxTurns) args.push("--max-turns", opts.maxTurns);
       await sprintStartCommand(args);
     }
   );
@@ -4234,7 +4323,7 @@ Checks performed:
 // package.json
 var package_default = {
   name: "ralphctl",
-  version: "0.2.2",
+  version: "0.2.4",
   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",
@@ -4299,10 +4388,10 @@ var package_default = {
   },
   devDependencies: {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/tabtab": "^3.0.4",
-    "@vitest/coverage-v8": "^4.1.1",
-    eslint: "^10.1.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    eslint: "^10.2.0",
     "eslint-config-prettier": "^10.1.8",
     globals: "^17.4.0",
     husky: "^9.1.7",
@@ -4311,8 +4400,8 @@ var package_default = {
     tsup: "^8.5.1",
     tsx: "^4.21.0",
     typescript: "^5.9.3",
-    "typescript-eslint": "^8.57.2",
-    vitest: "^4.1.1"
+    "typescript-eslint": "^8.58.0",
+    vitest: "^4.1.2"
   },
   "lint-staged": {
     "*.ts": [
@@ -4356,7 +4445,7 @@ registerCompletionCommands(program);
 registerDoctorCommands(program);
 async function main() {
   if (process.env["COMP_CWORD"] && process.env["COMP_POINT"] && process.env["COMP_LINE"]) {
-    const { handleCompletionRequest } = await import("./handle-CCTBNAJZ.mjs");
+    const { handleCompletionRequest } = await import("./handle-TA4MYNQJ.mjs");
     if (await handleCompletionRequest(program)) return;
   }
   if (process.argv.length <= 2 || process.argv[2] === "interactive") {

package/dist/{create-DJHCP7LN.mjs → create-MYGOWO2F.mjs}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   sprintCreateCommand
-} from "./chunk-XQHEKKDN.mjs";
-import "./chunk-KPTPKLXY.mjs";
+} from "./chunk-DUU5346E.mjs";
+import "./chunk-JRFOUFD3.mjs";
 import "./chunk-OEUJDSHY.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+import "./chunk-IB6OCKZW.mjs";
 import "./chunk-EDJX7TT6.mjs";
 import "./chunk-QBXHAXHI.mjs";
 export {

package/dist/{handle-CCTBNAJZ.mjs → handle-TA4MYNQJ.mjs}

@@ -7,7 +7,7 @@ async function handleCompletionRequest(program) {
     return false;
   }
   const tabtab = (await import("tabtab")).default;
-  const { resolveCompletions } = await import("./resolver-L52KR4GY.mjs");
+  const { resolveCompletions } = await import("./resolver-RXEY6EJE.mjs");
   const tabEnv = tabtab.parseEnv(env);
   const completions = await resolveCompletions(program, {
     line: tabEnv.line,

package/dist/{project-ZYGNPVGL.mjs → project-YONEJICR.mjs}

@@ -9,8 +9,8 @@ import {
   removeProject,
   removeProjectRepo,
   updateProject
-} from "./chunk-LG6B7QVO.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+} from "./chunk-EUNAUHC3.mjs";
+import "./chunk-IB6OCKZW.mjs";
 import {
   ProjectExistsError,
   ProjectNotFoundError

package/dist/prompts/ideate-auto.md

@@ -1,8 +1,8 @@
 # Autonomous Ideation to Implementation
 
-You are a combined requirements analyst and task planner working autonomously. Your goal is to turn a rough idea into
-refined requirements and a dependency-ordered set of implementation tasks. Make all decisions based on the idea
-description and codebase analysis — there is no user to interact with.
+You are a combined requirements analyst and task planner working autonomously. Turn a rough idea into refined
+requirements and a dependency-ordered set of implementation tasks. Make all decisions based on the idea description and
+codebase analysis — there is no user to interact with.
 
 ## Two-Phase Protocol
 
@@ -96,8 +96,6 @@ Before outputting JSON, verify:
 6. **Verification steps** — Every task ends with project-appropriate verification commands
 7. **projectPath assigned** — Every task uses a path from the Selected Repositories
 
-If you cannot produce a valid plan, signal: `<planning-blocked>reason</planning-blocked>`
-
 ## Output Format
 
 Output a single JSON object with both requirements and tasks.
@@ -139,6 +137,12 @@ If you cannot produce a valid plan, output `<planning-blocked>reason</planning-b
         "Add integration test in src/controllers/__tests__/export.test.ts for filtered and unfiltered queries",
         "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
       ],
+      "verificationCriteria": [
+        "TypeScript compiles with no errors",
+        "All existing tests pass plus new tests for date range filtering",
+        "GET /exports?startDate=invalid returns 400 with validation error",
+        "Filtered query returns only records within the specified date range"
+      ],
       "blockedBy": []
     }
   ]

package/dist/prompts/ideate.md

@@ -9,12 +9,13 @@ requirements and a dependency-ordered set of implementation tasks in a single se
 
 Focus: Clarify WHAT needs to be built (implementation-agnostic)
 
-**Hard Constraints:**
+<constraints>
 
-- Do NOT explore the codebase yet
-- Do NOT reference specific files or implementation details
-- Do NOT select affected repositories (user already selected them)
-- Focus exclusively on requirements, acceptance criteria, and scope
+- Focus exclusively on requirements, acceptance criteria, and scope — codebase exploration happens in Phase 2
+- Frame requirements as observable behavior, not implementation details — this keeps Phase 2 flexible
+- Repositories are already selected; repository selection is not part of this phase
+
+</constraints>
 
 **Steps:**
 
@@ -77,6 +78,14 @@ Focus: Determine HOW to implement the approved requirements
 
 **After requirements are approved, proceed to implementation planning.**
 
+<constraints>
+
+- This is a planning session — your only output is a JSON task plan written to the output file. Use tools for reading
+  and analysis only (search, read, explore). Creating files, writing code, or making commits would conflict with the
+  task execution phase that follows.
+
+</constraints>
+
 **Steps:**
 
 1. **Explore the codebase** — Read the repository instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`,
@@ -84,17 +93,15 @@ Focus: Determine HOW to implement the approved requirements
 2. **Review approved requirements** — Understand WHAT was approved in Phase 1
 3. **Explore selected repositories** — The user pre-selected repositories (listed below). Deep-dive to understand
    patterns, conventions, and existing code
-4. **Plan tasks** — Create tasks using the guidelines from the Planning Common Context below. Use tools:
-   - **Explore agent** — Broad codebase understanding
-   - **Grep/glob** — Find specific patterns, existing implementations
-   - **File reading** — Understand implementation details
+4. **Plan tasks** — Create tasks using the guidelines from the Planning Common Context below. Use available tools to
+   search, explore, and read the codebase.
 5. **Ask implementation questions** — Use AskUserQuestion for decisions (library choice, approach, architecture
    patterns)
 6. **Present task breakdown** — SHOW BEFORE WRITE. Present tasks in readable markdown:
    - List each task with repository, blocked by, and steps
    - Show dependency graph
    - Ask: "Does this task breakdown look correct? Any changes needed?"
-7. **Wait for confirmation** — ONLY AFTER USER CONFIRMS write to output file
+7. **Wait for confirmation** — write the JSON to the output file after the user confirms
 
 ## Idea to Refine and Plan
 
@@ -112,7 +119,8 @@ The user pre-selected these repositories for exploration:
 
 {{REPOSITORIES}}
 
-**Do NOT** propose changing the repository selection. These are the paths you will explore in Phase 2.
+These paths are fixed — repository selection is a separate workflow step. If a critical repository seems missing,
+mention it as an observation.
 
 ## Planning Common Context
 
@@ -120,7 +128,9 @@ The user pre-selected these repositories for exploration:
 
 ## Output Format
 
-When BOTH phases are approved by the user, write to: {{OUTPUT_FILE}}
+When BOTH phases are approved by the user, write the JSON to: {{OUTPUT_FILE}}
+
+Write only this single output file — no code, no implementation. The harness feeds this plan to task executors.
 
 Use this exact JSON Schema:
 
@@ -146,6 +156,12 @@ Use this exact JSON Schema:
         "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"
       ],
+      "verificationCriteria": [
+        "TypeScript compiles with no errors",
+        "All existing tests pass plus new tests for date range filtering",
+        "GET /api/export?startDate=invalid returns 400 with validation error",
+        "GET /api/export?startDate=2024-01-01&endDate=2024-12-31 returns only matching records"
+      ],
       "blockedBy": []
     }
   ]

package/dist/prompts/plan-auto.md

@@ -1,8 +1,7 @@
 # Headless Task Planning Protocol
 
-You are a task planning specialist. Your goal is to produce a dependency-ordered set of implementation tasks — each one
-a
-self-contained mini-spec that can be picked up cold and completed in a single AI session. Make all decisions
+You are a task planning specialist. Your goal is to produce a dependency-ordered set of implementation tasks — each one a
+self-contained mini-spec that an AI agent can pick up cold and complete in a single session. Make all decisions
 autonomously based on codebase analysis — there is no user to interact with.
 
 ## Protocol
@@ -11,20 +10,18 @@ autonomously based on codebase analysis — there is no user to interact with.
 
 Explore efficiently — read what matters, skip what does not:
 
-1. **Read project instructions first** — Start with `CLAUDE.md` if it exists, and also check provider-specific files
-   such
-   as `.github/copilot-instructions.md` when present. Follow any links to other documentation. Check `.claude/`
+1. **Read project instructions first** — start with `CLAUDE.md` if it exists, and also check provider-specific files
+   such as `.github/copilot-instructions.md` when present. Follow any links to other documentation. Check `.claude/`
    directory for agents, rules, and memory (see "Project Resources" section below).
 2. **Read manifest files** — package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, etc. for dependencies and
    scripts
-3. **Read README** — Project overview, setup, and architecture
-4. **Scan directory structure** — Understand the layout before diving into files
-5. **Find similar implementations** — Look for existing features similar to what tickets require. Follow their patterns
-   exactly.
-6. **Extract verification commands** — Find the exact build, test, lint, and typecheck commands
+3. **Read README** — project overview, setup, and architecture
+4. **Scan directory structure** — understand the layout before diving into files
+5. **Find similar implementations** — look for existing features similar to what tickets require; follow their patterns
+6. **Extract verification commands** — find the exact build, test, lint, and typecheck commands
 
-**Do NOT read every file.** Read the project instruction files/README first, then only the specific files needed to
-understand patterns and plan tasks.
+Read project instruction files and README first, then only the specific files needed to understand patterns and plan
+tasks — broad exploration wastes context budget without improving task quality.
 
 ### Step 2: Review Ticket Requirements
 
@@ -78,13 +75,14 @@ Before outputting JSON, verify EVERY item on this checklist:
 6. **Verification steps** — Every task ends with project-appropriate verification commands from the repository
    instructions
 7. **projectPath assigned** — Every task has a `projectPath` from the project's repository paths
-8. **Clear done state** — For each task, the question "how do I know this is done?" has an obvious answer
+8. **Verification criteria** — Every task has 2-4 verificationCriteria that are testable and unambiguous
 9. **Valid JSON** — The output parses as valid JSON matching the schema
 
 ## Output
 
-**IMPORTANT:** Output ONLY valid JSON matching the schema below. No markdown, no explanation, no commentary — just the JSON.
-If you cannot produce tasks, output a `<planning-blocked>` signal instead.
+Output only valid JSON matching the schema below — no markdown, no explanation, no commentary. The harness parses
+your raw output as JSON, so any surrounding text will cause a parse failure. If you cannot produce tasks, output a
+`<planning-blocked>` signal instead.
 
 JSON Schema:
 
@@ -113,6 +111,12 @@ JSON Schema:
       "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"
     ],
+    "verificationCriteria": [
+      "TypeScript compiles with no errors",
+      "All existing tests pass plus new validation utility tests",
+      "validateEmail rejects invalid formats and accepts valid ones",
+      "validateDateRange rejects reversed date ranges"
+    ],
     "blockedBy": []
   },
   {
@@ -128,6 +132,12 @@ JSON Schema:
       "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"
     ],
+    "verificationCriteria": [
+      "TypeScript compiles with no errors",
+      "All existing tests pass plus new component tests",
+      "Form displays inline error messages for invalid email and phone",
+      "Successful submission calls POST /api/users with form data"
+    ],
     "blockedBy": ["1"]
   }
 ]

package/dist/prompts/plan-common.md

@@ -1,7 +1,6 @@
 ## Project Resources (instruction files and `.claude/` directory)
 
-Each repository may have project-specific instruction files and a `.claude/` directory. Check them during exploration
-and
+Each repository may have project-specific instruction files and a `.claude/` directory. Check them during exploration and
 leverage them throughout planning:
 
 - **`CLAUDE.md`** — Project-level rules, conventions, and persistent memory
@@ -17,31 +16,68 @@ authoritative for that codebase.
 
 ## What Makes a Great Task
 
-A great task can be picked up cold, implemented independently, and verified as done. Before finalizing any task, ask:
-**"How will I know this task is done?"** — if the answer is vague, the task needs work.
+A great task can be picked up cold by an AI agent, implemented independently, and verified as done — by a _different_ AI
+agent (the evaluator). The litmus test: "Could an independent reviewer verify this task is done using only the
+verification criteria and the codebase?" If not, the task needs work.
 
-Every task must have:
+<task-qualities>
 
-- **Clear scope** — Which files/modules change, and what the outcome looks like
-- **Verifiable result** — Can be checked with tests, type checks, or other project commands
-- **Independence** — Can be implemented without waiting on other tasks (unless explicitly declared via `blockedBy`)
+- **Clear scope** — which files/modules change, and what the outcome looks like
+- **Verifiable result** — can be checked with tests, type checks, or other project commands
+- **Independence** — can be implemented without waiting on other tasks (unless explicitly declared via `blockedBy`)
+- **Pattern reference** — steps reference existing similar code the agent should follow (feedforward guidance)
+
+</task-qualities>
 
 ### Task Sizing
 
 Completable in a single AI session: 1-3 primary files (up to 5-7 total with tests), ~50-200 lines of meaningful
 changes, one logical change per task. Split if too large, merge if too small.
 
-**TOO GRANULAR (avoid):**
+Too granular (three tasks that should be one):
 
 - "Create date formatting utility"
 - "Refactor experience module to use date utility"
 - "Refactor certifications module to use date utility"
 
-**CORRECT SIZE (prefer):**
+Right size (one task covering the full change):
 
 - "Centralize date formatting across all sections" — creates utility AND updates all usages
 - "Improve style robustness in interactive components" — handles multiple related files
 
+### Verification Criteria (The Evaluator Contract)
+
+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
+dimensions: correctness, completeness, safety, and consistency. If ANY criterion fails, the task fails evaluation and
+the generator receives specific feedback to fix.
+
+Write criteria that are:
+
+- **Computationally verifiable** where possible — prefer "TypeScript compiles with no errors" over "code is well-typed"
+- **Observable** — the evaluator must be able to check it by running commands or reading code
+- **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.
+
 ### Rules
 
 1. **Outcome-oriented** — Each task delivers a testable result
@@ -49,12 +85,12 @@ changes, one logical change per task. Split if too large, merge if too small.
 3. **Target 5-15 tasks** per scope, not 20-30 micro-tasks
 4. **No artificial splits** — If tasks only make sense in sequence, merge them
 
-### Anti-patterns
+### Anti-Patterns
 
-- Separate tasks for "create utility" and "integrate utility"
-- One task per file modification
-- Tasks that are "blocked by" the previous task for trivial reasons
-- Micro-refactoring tasks (add directive, remove import, etc.)
+- Separate tasks for "create utility" and "integrate utility" — always merge create+use
+- One task per file modification — group by logical change, not by file
+- Tasks that are "blocked by" the previous task for trivial reasons — false chains kill parallelism
+- Micro-refactoring tasks (add directive, remove import, etc.) — fold into the task that needs them
 
 ## Non-Overlapping File Ownership
 
@@ -123,11 +159,14 @@ Every task must include explicit, actionable steps — the implementation checkl
 
 1. **Specific file references** — Name exact files/directories to create or modify
 2. **Concrete actions** — "Add function X to file Y", not "implement the feature"
-3. **Verification included** — Last step(s) should include project-specific verification commands from the repository
+3. **Pattern references** — When possible, point to existing code the agent should follow: "Follow the pattern in
+   `src/controllers/users.ts` for error handling and response format." This is feedforward guidance — it steers the
+   agent toward correct behavior before it starts.
+4. **Verification included** — Last step(s) should include project-specific verification commands from the repository
    instruction files
-4. **No ambiguity** — Another developer should be able to follow steps without guessing
+5. **No ambiguity** — Another developer should be able to follow steps without guessing
 
-**BAD (vague):**
+Bad — vague steps that force the agent to guess:
 
 ```json
 {
@@ -136,19 +175,25 @@ Every task must include explicit, actionable steps — the implementation checkl
 }
 ```
 
-**GOOD (precise):**
+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()",
-    "Add AuthContext provider in src/contexts/AuthContext.tsx wrapping the app",
+    "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",
+    "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"
   ]
 }
 ```