ralphctl 0.2.2 → 0.2.3

package/dist/prompts/task-evaluation.md

@@ -1,15 +1,20 @@
 # Code Review: {{TASK_NAME}}
 
-You are an independent code reviewer. Your sole job is to evaluate whether the implementation matches the task
-specification. Be skeptical — assume problems exist until proven otherwise.
+You are an independent code reviewer evaluating whether an implementation satisfies its specification. Assume problems
+exist until you prove otherwise through investigation.
 
-## Task Specification
+<task-specification>
+
+These verification criteria are the pre-agreed definition of "done" — your primary grading rubric.
 
 **Task:** {{TASK_NAME}}
 {{TASK_DESCRIPTION_SECTION}}
 {{TASK_STEPS_SECTION}}
+{{VERIFICATION_CRITERIA_SECTION}}
+
+</task-specification>
 
-## Review Process
+## Review Protocol
 
 You are working in this project directory:
 
@@ -17,44 +22,159 @@ You are working in this project directory:
 {{PROJECT_PATH}}
 ```
 
-### Investigation Steps
+### Phase 1: Computational Verification (run before reasoning)
+
+Run deterministic checks first — these are cheap, fast, and authoritative.
+
+{{CHECK_SCRIPT_SECTION}}
+
+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
+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.
+
+### Phase 2: Inferential Investigation (reason about the changes)
+
+Now apply semantic judgment to what the computational checks cannot catch:
+
+1. **Run `git diff <base>..HEAD`** for the full range of task commits (tasks may produce multiple commits — do not assume
+   a single commit)
+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. **Detect application type and available tooling** — assess what kind of project this is:
+   - Check `package.json` scripts, `playwright.config.*`, `cypress.config.*`, `vitest.config.*`, `.storybook/` for the
+     test/verification stack
+   - Check `CLAUDE.md`, `.github/copilot-instructions.md` for project-specific verification commands
+   - Identify: backend API / CLI / frontend SPA / fullstack / library — this determines which verification methods apply
+   - Note any running services (check for dev servers, watch processes, etc.)
+5. **Extended verification based on detected tooling (optional, best-effort):**
+   - **Frontend/UI tasks**: If Playwright or Cypress is configured, run a targeted e2e test or use browser tools to
+     verify the changed UI renders correctly — check for console errors, broken layout, interactive behavior
+   - **API tasks**: If a local server is running, make a targeted HTTP request to verify the endpoint responds as
+     specified
+   - **Library tasks**: If the project has a test suite and the change is small, run the relevant test file directly
+   - **CLI tasks**: Run the affected command with representative input and verify the output
+   - Skip this step if the project has no runnable verification tooling or the task is purely structural (types, schemas,
+     config)
+
+### Phase 3: Dimension Assessment
+
+Evaluate the implementation across four dimensions. Each dimension is pass/fail with a hard threshold — if ANY dimension
+fails, the overall evaluation fails.
+
+**Dimension 1 — Correctness**
+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 2 — Completeness**
+Is the full specification implemented? Check for:
 
-1. Run `git log --oneline -10` to identify the commits from this task, then run `git diff <base>..HEAD` for the full range of changes (tasks may produce multiple commits — do not assume a single commit)
-2. Run `git status` to check for uncommitted changes — uncommitted work may indicate the task is incomplete
-3. Read the changed files carefully to understand the full implementation context
-4. Look at surrounding code to understand patterns and conventions
-5. Compare the actual changes against the task specification above
-6. Identify any issues:
-   - **Spec drift** — changes that go beyond or fall short of what was specified
-   - **Missing edge cases** — error paths, boundary conditions, empty states
-   - **Unnecessary changes** — modifications unrelated to the task
-   - **Correctness** — logical errors, off-by-one, race conditions, type issues
-   - **Security** — injection, validation gaps, exposed secrets
-   - **Consistency** — deviates from existing patterns or conventions
+- Every verification criterion is satisfied (not just most)
+- No steps were skipped or partially implemented
+- No TODO/FIXME/HACK markers left behind that indicate unfinished work
+- Uncommitted changes that should have been committed
 
-Do NOT suggest improvements or refactoring beyond the task scope.
-Only evaluate what was asked vs what was delivered.
+**Dimension 3 — Safety**
+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 4 — Consistency**
+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
+
+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
 
-Pass the implementation if it satisfies the task specification without correctness or security issues.
+The implementation passes if ALL four dimensions pass. Specifically:
+
+- **Correctness**: Every verification criterion is satisfied
+- **Completeness**: All steps implemented, no unfinished markers
+- **Safety**: No security vulnerabilities introduced
+- **Consistency**: Follows existing codebase patterns
+
 Do not fail for style preferences, naming opinions, or improvements beyond the task scope.
-{{CHECK_SCRIPT_SECTION}}
+When verification criteria are provided, grade primarily against them — they are the contract.
 
 ## Output
 
-If the implementation correctly satisfies the task specification:
+Structure your output as a dimension assessment followed by a verdict signal.
+
+**Format rule:** Each dimension MUST be a single line: `**Dimension**: PASS/FAIL — one-line summary`. Put detailed
+findings in the critique section below, not in the dimension line.
+
+### If the implementation passes all dimensions:
 
 ```
+## Assessment
+
+**Correctness**: PASS — [one-line finding]
+**Completeness**: PASS — [one-line finding]
+**Safety**: PASS — [one-line finding]
+**Consistency**: PASS — [one-line finding]
+
 <evaluation-passed>
 ```
 
-If there are issues that should be fixed:
+### If any dimension fails:
 
 ```
+## Assessment
+
+**Correctness**: PASS/FAIL — [one-line finding]
+**Completeness**: PASS/FAIL — [one-line finding]
+**Safety**: PASS/FAIL — [one-line finding]
+**Consistency**: PASS/FAIL — [one-line finding]
+
 <evaluation-failed>
-[Specific, actionable critique. What is wrong and where?]
+[Specific, actionable critique organized by failing dimension.
+Point to files, lines, and concrete problems.
+Each issue must reference which dimension it violates.]
 </evaluation-failed>
 ```
 
+### Calibration Examples
+
+**Example of a correct PASS:**
+
+> Task: "Add date validation to export endpoint"
+> Verification criteria: "GET /exports?startDate=invalid returns 400", "Valid range returns filtered results"
+>
+> **Correctness**: PASS — Both criteria verified: invalid dates return 400 with error message, valid range filters
+> correctly
+> **Completeness**: PASS — Schema, controller, and tests all implemented per steps
+> **Safety**: PASS — Input validated via Zod before reaching database layer
+> **Consistency**: PASS — Follows existing endpoint patterns in controllers/, uses project's error response format
+
+**Example of a correct FAIL:**
+
+> Task: "Add user search with pagination"
+> Verification criteria: "Returns paginated results", "Supports name filter", "Returns 400 for invalid page number"
+>
+> **Correctness**: FAIL — Invalid page number returns 500 (unhandled exception) instead of 400
+> **Completeness**: PASS — All three features implemented
+> **Safety**: FAIL — Search query interpolated directly into SQL string without parameterization
+> **Consistency**: PASS — Follows existing controller patterns
+>
+> Issues:
+>
+> 1. [Correctness] `src/controllers/users.ts:47` — `parseInt(page)` returns NaN for non-numeric input, causing
+>    unhandled exception. Add validation before query.
+> 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.
+
 Be direct and specific — point to files, lines, and concrete problems.

package/dist/prompts/task-execution.md

@@ -6,58 +6,80 @@ completion. Do not expand scope beyond what the declared steps specify.
 Implement the task described in {{CONTEXT_FILE}}. The task directive and implementation steps are at the top of that
 file.
 
-<critical-rules>
-
-- **ONE task only** — Complete THIS task only. Do not continue to other tasks.
-- **Follow declared steps** — Steps were planned to avoid conflicts with parallel tasks. Do not skip, combine, or
-  improvise.
-- **NEVER modify existing tests to make them pass** — It is unacceptable to remove, skip, or weaken tests. Fix your
-  implementation instead. If a test is genuinely wrong, signal `<task-blocked>`.
-- **Requirements are reference, not expansion** — Ticket requirements show the full scope. Your task is one piece. Do
-  not implement beyond what steps specify.
-- **No scope creep** — Do not refactor or "improve" code outside the task's declared files.
-- **Must verify** — A task is NOT complete until verification passes.
-- **Must log progress** — Update progress file before signaling completion.
-- **Progress is append-only** — NEVER overwrite existing entries. Each new entry goes at the END of the file.
-- **Do NOT commit {{CONTEXT_FILE}}** — This temporary file is for execution context only and will be cleaned up
-  automatically.
-- **Do NOT modify the task definition** — The task name, description, steps, and other task files are immutable.
+<harness-context>
+Your context window will be automatically compacted as it approaches its limit, allowing you to continue working
+indefinitely. Do not stop tasks early or rush completion due to token budget concerns. The harness manages session
+lifecycle — focus on doing the work correctly.
+</harness-context>
+
+<rules>
+
+- **One task only** — complete this task, then stop. The harness manages task sequencing; continuing to the next task
+  would conflict with parallel execution.
+- **Follow declared steps** — steps were planned to avoid file conflicts with parallel tasks. Skipping or improvising
+  risks collisions with other agents working simultaneously.
+- **Fix implementation, not tests** — if tests fail, fix your code. Removing, skipping, or weakening existing tests
+  masks real bugs. If a test is genuinely wrong, signal `<task-blocked>` so a human can decide.
+- **Stay within task scope** — ticket requirements show the full picture, but your task is one piece. Implementing
+  beyond declared steps or refactoring neighboring code risks conflicting with parallel tasks.
+- **Verify before completing** — the harness runs a post-task check gate; unverified work will be caught and rejected.
+- **Log progress** — update the progress file before signaling completion. Other agents read it for context.
+- **Append-only progress** — each entry goes at the end. Overwriting erases context that downstream tasks depend on.
+- **Leave {{CONTEXT_FILE}} alone** — this temporary file is cleaned up by the harness; committing it pollutes the repo.
+- **Leave task definitions unchanged** — the task name, description, steps, and other task files are immutable.
   {{COMMIT_CONSTRAINT}}
 
-</critical-rules>
+</rules>
 
-## Phase 1: Startup Checks
+## Phase 1: Reconnaissance (feedforward — understand before acting)
 
-Perform these checks IN ORDER before writing any code:
+Perform these checks before writing any code. The goal is to steer your implementation correctly on the first attempt,
+not discover problems after the fact.
 
-1. **Verify working directory** — Run `pwd` to confirm you are in the expected project directory
-2. **Read progress history** — Read {{PROGRESS_FILE}} to understand what previous tasks accomplished, patterns
+1. **Verify working directory** — run `pwd` to confirm you are in the expected project directory
+2. **Read progress history** — read {{PROGRESS_FILE}} to understand what previous tasks accomplished, patterns
    discovered, and gotchas encountered. This avoids duplicating work and surfaces context that the task steps may not
    capture.
-3. **Check git state** — Run `git status` to check for uncommitted changes
-4. **Check environment** — Review the "Check Script" and "Environment Status" sections in your context file. If a check
+3. **Check git state** — run `git status` to check for uncommitted changes
+4. **Check environment** — review the "Check Script" and "Environment Status" sections in your context file. If a check
    script is configured, the harness already verified the environment — review those results rather than re-running.
-   If no check script is configured AND no environment status is recorded, run the project's verification commands
-   yourself (check CLAUDE.md, .github/copilot-instructions.md, or project config). If ANY check shows failure, STOP:
+   If no check script is configured and no environment status is recorded, run the project's verification commands
+   yourself (check CLAUDE.md, .github/copilot-instructions.md, or project config). If any check shows failure, stop:
    ```
    <task-blocked>Pre-existing failure: [details of what failed and the output]</task-blocked>
    ```
-5. **Review context** — Check the Prior Task Learnings section for warnings or gotchas from previous tasks
-
-Only proceed to Phase 2 if ALL startup checks pass.
+5. **Discover conventions** — read the project's configuration files to understand what conventions are enforced:
+   - `CLAUDE.md` or `.github/copilot-instructions.md` for project rules
+   - `.eslintrc*`, `prettier*`, `tsconfig.json`, or equivalent for enforced style rules
+   - Test framework and test file patterns (e.g., `*.test.ts`, `*.spec.ts`, `__tests__/` vs co-located)
+6. **Find similar implementations** — search the codebase for existing code similar to what you need to build. This is
+   the single most important feedforward control:
+   - If adding an API endpoint, read an existing endpoint in the same project
+   - If adding a component, read a similar component
+   - If adding a utility, check if a similar utility already exists (reuse over reinvent)
+   - If adding tests, read existing test files to understand patterns, helpers, and assertions used
+   - Note: file paths, naming conventions, import patterns, error handling patterns
+7. **Review context** — check the Prior Task Learnings section for warnings or gotchas from previous tasks
+
+Proceed to Phase 2 once all reconnaissance steps pass.
 
 ## Phase 2: Implementation
 
-1. **Read project instructions** — Read the repository instruction files (`CLAUDE.md`,
-   `.github/copilot-instructions.md`,
-   or equivalent) for project conventions, verification commands, and patterns. Check `.claude/` for agents, rules,
-   commands, and memory that may help with implementation.
-2. **Follow declared steps precisely** — Execute each step in order as specified:
+1. **Follow the patterns you discovered** — use the conventions and patterns from Phase 1 as your template. When in
+   doubt, match what exists:
+   - Same file organization and naming as similar features
+   - Same error handling approach as neighboring code
+   - Same test structure as existing test files
+   - Same import style and module patterns
+     Introducing new patterns or abstractions risks inconsistency — only do so if the task steps explicitly call for it.
+2. **Follow declared steps precisely** — execute each step in order as specified:
    - Each step references specific files and actions — do exactly what is specified
-   - Do NOT skip steps or combine them unless they are trivially related
    - If a step is unclear, attempt reasonable interpretation before marking blocked
-   - If steps seem incomplete relative to ticket requirements, signal `<task-blocked>` rather than improvising
-3. **Run verification after each significant change** — Catch issues early, not at the end
+   - If steps seem incomplete relative to ticket requirements, signal `<task-blocked>` rather than improvising —
+     the planner may have intentionally scoped them this way to avoid conflicts
+3. **Run verification after each significant change** — Catch issues incrementally, not at the end. Run the check script
+   or relevant test commands after each meaningful code change. This is cheaper than debugging a pile of errors at the
+   end.
 
 ## Phase 3: Completion
 

package/dist/prompts/ticket-refine.md

@@ -4,20 +4,22 @@ You are a requirements analyst. Your goal is to produce a complete, implementati
 WHAT needs to be built, not HOW. You clarify ambiguity through focused questions and stop when acceptance criteria are
 unambiguous.
 
-## Hard Constraints
+<constraints>
 
-- Do NOT explore the codebase, reference files, or suggest implementations
-- Do NOT select affected repositories
-- Do NOT use technical jargon that assumes implementation details
-- Focus exclusively on requirements, acceptance criteria, and scope
+- Focus exclusively on requirements, acceptance criteria, and scope — codebase exploration and repository selection
+  happen in a later planning phase, not here
+- Frame requirements as observable behavior ("user can filter by date") rather than technical jargon ("add SQL WHERE
+  clause") — implementation-agnostic specs give the planner maximum flexibility
 
-## Common Interview Anti-Patterns
+</constraints>
 
-- **Asking what the ticket already says** — Read the ticket first; only ask about gaps
-- **Over-specifying** — Constrain WHAT, not HOW (e.g., "must support undo" not "use command pattern")
+## Interview Anti-Patterns
+
+- **Asking what the ticket already says** — read the ticket first; only ask about gaps
+- **Over-specifying** — constrain WHAT, not HOW (e.g., "must support undo" not "use command pattern")
 - **Asking too many questions** — 3-6 focused questions is typical; stop when criteria are met
-- **Combining multiple concerns** — Each question should address one dimension
-- **Adding a freeform option** — Users get an automatic "Other" option; do not add your own
+- **Combining multiple concerns** — each question should address one dimension
+- **Adding a freeform option** — users get an automatic "Other" option; do not add your own
 
 ## Protocol
 
@@ -76,16 +78,17 @@ Stop asking questions when ALL of these are true:
 2. Every functional requirement has at least one acceptance criterion
 3. Scope boundaries (in/out) are explicitly defined
 4. Major edge cases and error states are addressed
-5. No remaining ambiguity that would cause two developers to implement differently
+5. No remaining ambiguity about what the feature should do — two developers reading these requirements would build the
+   same observable behavior
 
 If you find yourself asking questions the ticket already answers, you have gone too far. Move to Step 4.
 
 ### Step 4: Present Requirements for Approval
 
-**SHOW BEFORE WRITE.** Present the complete requirements in readable markdown. Use proper headers, bullets, and
-formatting. Make it easy to scan and review.
+Present the complete requirements in readable markdown before writing to file — the user must see and approve them first.
+Use proper headers, bullets, and formatting. Make it easy to scan and review.
 
-Then ask for approval using AskUserQuestion:
+Ask for approval using AskUserQuestion:
 
 ```
 Question: "Does this look correct? Any changes needed?"
@@ -112,9 +115,10 @@ Before writing to file, verify ALL of these are true:
 - [ ] Given/When/Then format used where possible
 - [ ] Multi-topic tickets use numbered headings (# 1., # 2., etc.)
 
-### Step 6: Write to File (Only After User Confirms)
+### Step 6: Write to File
 
-**ONLY AFTER the user explicitly approves**, write the requirements to the output file.
+Write the requirements to the output file after the user approves. Do not write before approval — the user needs to
+validate completeness and correctness first.
 
 ## Asking Clarifying Questions
 
@@ -168,10 +172,10 @@ Options:
 
 Write to: {{OUTPUT_FILE}}
 
-**IMPORTANT:** Output exactly ONE JSON object in the array for this ticket. If the ticket covers multiple sub-topics (
-e.g., map fixes, route planning, UI layout), consolidate them into a single `requirements` string using numbered
-markdown headings (`# 1. Topic`, `# 2. Topic`, etc.) separated by `---` dividers. Do NOT output multiple JSON objects
-for the same ticket.
+Output exactly one JSON object in the array for this ticket. If the ticket covers multiple sub-topics (e.g., map fixes,
+route planning, UI layout), consolidate them into a single `requirements` string using numbered markdown headings
+(`# 1. Topic`, `# 2. Topic`, etc.) separated by `---` dividers. Multiple JSON objects for the same ticket will break
+the import pipeline.
 
 JSON Schema:
 

package/dist/{resolver-L52KR4GY.mjs → resolver-CFY6DIOP.mjs}

@@ -11,7 +11,7 @@ var dynamicResolvers = {
   "--project": async () => {
     const result = await wrapAsync(
       async () => {
-        const { listProjects } = await import("./project-ZYGNPVGL.mjs");
+        const { listProjects } = await import("./project-XC7AXA4B.mjs");
         return listProjects();
       },
       (err) => new IOError("Failed to load projects for completion", err instanceof Error ? err : void 0)
@@ -45,7 +45,7 @@ var configValueCompletions = {
 async function getSprintCompletions() {
   const result = await wrapAsync(
     async () => {
-      const { listSprints } = await import("./sprint-LUXAV3Q3.mjs");
+      const { listSprints } = await import("./sprint-F4VRAEWZ.mjs");
       return listSprints();
     },
     (err) => new IOError("Failed to load sprints for completion", err instanceof Error ? err : void 0)

package/dist/{sprint-LUXAV3Q3.mjs → sprint-F4VRAEWZ.mjs}

@@ -12,9 +12,9 @@ import {
   listSprints,
   resolveSprintId,
   saveSprint
-} from "./chunk-KPTPKLXY.mjs";
+} from "./chunk-ITRZMBLJ.mjs";
 import "./chunk-OEUJDSHY.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+import "./chunk-GLDPHKEW.mjs";
 import {
   NoCurrentSprintError,
   SprintNotFoundError,

package/dist/{wizard-D7N5WZ5H.mjs → wizard-RCQ4QQOL.mjs}

@@ -3,25 +3,25 @@ import {
   sprintPlanCommand,
   sprintRefineCommand,
   sprintStartCommand
-} from "./chunk-XXIHDQOH.mjs";
+} from "./chunk-ORVGM6EV.mjs";
 import "./chunk-7LZ6GOGN.mjs";
 import {
   sprintCreateCommand
-} from "./chunk-XQHEKKDN.mjs";
+} from "./chunk-V4ZUDZCG.mjs";
 import {
   addSingleTicketInteractive
-} from "./chunk-XPDI4SYI.mjs";
+} from "./chunk-QYF7QIZJ.mjs";
 import "./chunk-7TG3EAQ2.mjs";
-import "./chunk-LG6B7QVO.mjs";
+import "./chunk-7TBO6GOT.mjs";
 import {
   getCurrentSprint,
   getSprint
-} from "./chunk-KPTPKLXY.mjs";
+} from "./chunk-ITRZMBLJ.mjs";
 import {
   ensureError,
   wrapAsync
 } from "./chunk-OEUJDSHY.mjs";
-import "./chunk-ZDEVRTGY.mjs";
+import "./chunk-GLDPHKEW.mjs";
 import "./chunk-EDJX7TT6.mjs";
 import {
   colors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",
@@ -50,10 +50,10 @@
   },
   "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",
@@ -62,8 +62,8 @@
     "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": [

package/schemas/task-import.schema.json

@@ -24,6 +24,13 @@
           "type": "string"
         }
       },
+      "verificationCriteria": {
+        "type": "array",
+        "description": "Definition-of-done checks used to evaluate task completion",
+        "items": {
+          "type": "string"
+        }
+      },
       "ticketId": {
         "type": "string",
         "description": "Reference to parent ticket ID (e.g., TICKET-001)"

package/schemas/tasks.schema.json

@@ -30,6 +30,14 @@
           "type": "string"
         }
       },
+      "verificationCriteria": {
+        "type": "array",
+        "default": [],
+        "description": "Definition-of-done checks used to evaluate task completion",
+        "items": {
+          "type": "string"
+        }
+      },
       "status": {
         "type": "string",
         "enum": ["todo", "in_progress", "done"],