ralphctl 0.22.0 → 0.24.0

package/dist/prompts/readiness/template.md

@@ -15,12 +15,16 @@ bottom of this prompt.
 
 <success_criteria>
 
-- `agents-md-proposal` signal emitted with `tag: "{{WIRE_TAG}}"` and a non-empty `content` field.
+- `agents-md-proposal` signal emitted with `tag: "{{WIRE_TAG}}"`. `content` is non-empty when
+  `<existing_context_file>` is empty (a fresh file); with an existing file it holds only additions and may be
+  an empty string when there is nothing to add.
 - Every tech-stack claim in `content` is backed by a quoted file path or file content, not inferred.
-- `content` follows the length guidance for `{{CURRENT_TOOL}}` in `<target_file_conventions>`
-  below — the exact target and ceiling are provider-specific.
-- When an existing context file is supplied in `<existing_context_file>`, `content` starts with that body
-  verbatim — byte-for-byte, unchanged, in the same order — before any additions.
+- The resulting file follows the length guidance for `{{CURRENT_TOOL}}` in `<target_file_conventions>`
+  below — the exact target and ceiling are provider-specific. The ceiling applies to the existing file plus
+  your additions, so count the existing lines and keep additions within the remaining room.
+- When an existing context file is supplied in `<existing_context_file>`, `content` holds ONLY the new H2
+  sections to append — never the existing body; the harness appends them and keeps the existing file
+  byte-for-byte.
 - Setup and verify skill proposals, when emitted, cite only commands that resolve in this specific repo
   (shell commands verified against manifest files, not assumed from language defaults).
 - `signals.json` is valid JSON and passes the harness schema check.
@@ -38,8 +42,6 @@ bottom of this prompt.
 </target_file_conventions>
 </inputs>
 
-{{HARNESS_CONTEXT}}
-
 <constraints>
 
 **Read-only scope.** Read configuration and metadata files only — `package.json`, `pyproject.toml`,
@@ -71,12 +73,12 @@ for genuinely surprising rules — overuse erodes their meaning.
 - Credentials, user-specific paths, or commands that touch remote services.
 - Standard language conventions the agent already knows.
 
-**Existing-context rule (fires when `<existing_context_file>` carries a body, not the sentinel line).**
-The supplied prose is authoritative. The `agents-md-proposal` signal's `content` MUST contain the existing
-body byte-for-byte verbatim at the start, in the original order, with no rewording, summarising, or
-reformatting. Append proposed additions as new H2 sections at the bottom only. Do not modify, prune, or
-merge into existing sections. When you have nothing to add, still emit the `agents-md-proposal` signal with
-the existing body unchanged.
+**Existing-context rule (fires when `<existing_context_file>` is non-empty; an empty one means no file exists yet — emit a fresh body).**
+The supplied prose is authoritative and the harness preserves it byte-for-byte. The `agents-md-proposal`
+signal's `content` MUST contain only your additions, as new H2 sections — do not repeat, reword, or
+summarise the existing body, and do not modify, prune, or merge into existing sections; the harness appends
+`content` after the existing file. When you have nothing to add, still emit the `agents-md-proposal` signal
+with an empty `content` string.
 
 **Script safety (applies to setup and verify skill bodies).** Every command you document must resolve in
 this repo. Cite a setup command only when its manifest file is present (a `package.json` install command
@@ -132,8 +134,9 @@ not what is typical for the apparent stack.
 Draft each surviving section against the inclusion test. Drop any section an experienced engineer could
 derive from the manifest or directory tree.
 
-When `<existing_context_file>` carries a body (not the "no existing file" sentinel), the existing prose
-comes first, byte-for-byte. Your additions go as new H2 sections at the bottom — never inline or merged.
+When `<existing_context_file>` is non-empty (empty means no file exists yet), the harness keeps the
+existing prose first, byte-for-byte. Your `content` is only the additions — new H2 sections, never inline or
+merged into existing ones.
 
 ### Phase 4 — Output
 
@@ -151,7 +154,7 @@ Do not invent stack claims without evidence.
 ### Signal semantics
 
 - `agents-md-proposal` — REQUIRED. `tag` MUST equal `"{{WIRE_TAG}}"`. `content` is the project context
-  file body.
+  file body — or, when `<existing_context_file>` is non-empty, only the new sections to append to it.
 - `setup-skill-proposal` — optional. Multi-paragraph markdown body describing the project's setup
   convention. The harness lands it as `setup/SKILL.md`. Omit entirely when no setup skill is warranted.
 - `verify-skill-proposal` — optional. Same shape as the setup skill but for verification (typecheck /

package/dist/prompts/refine/template.md

@@ -37,13 +37,11 @@ If `<prior_progress>` is empty, no prior work has been recorded for this sprint
 If the `<context>` block above is empty or absent, no upstream issue body was available.
 </inputs>
 
-{{HARNESS_CONTEXT}}
-
 <constraints>
-- MUST stay implementation-agnostic. Frame requirements as observable behaviour ("user can filter by
+- Stay implementation-agnostic. Frame requirements as observable behaviour ("user can filter by
   date range"), not technical decisions ("add a SQL WHERE clause"). The planner that runs after you
   needs maximum flexibility on HOW; your job is WHAT.
-- MUST NOT explore the repository. No source files are mounted in this session — only the output
+- Do not explore the repository — no source files are mounted in this session; only the output
   directory is writable. If a question requires source context, note it in the requirements body
   as an open question requiring repo investigation.
 - One concern per question. Combining "what should it do AND how should it look" forces a fuzzy
@@ -63,7 +61,7 @@ ticket omits.
 
 Then identify, in order:
 
-1. What is already clear and does NOT need clarification.
+1. What is already clear and doesn't need clarification.
 2. What is ambiguous, missing, or underspecified.
 3. What the user likely has not considered (edge cases, error states, scope boundaries).
 
@@ -138,7 +136,7 @@ Header: "Formats"
 multiSelect: true
 Options:
   - "CSV (Recommended)" — "Universal compatibility; simple structure."
-  - "JSON (Recommended)" — "API-friendly; structured data."
+  - "JSON" — "API-friendly; structured data."
   - "PDF" — "Human-readable reports; requires additional library."
 ```
 
@@ -148,10 +146,9 @@ Stop asking questions once every item in the Step 5 pre-output quality checklist
 
 ### Step 4 — Present requirements for approval
 
-Present the complete requirements in readable markdown. Use proper headers, bullets, and formatting.
-Make it easy to scan.
+{{APPROVAL_GATE}}
 
-Then ask for approval:
+The approval question:
 
 ```
 Question: "Does this look correct? Any changes needed?"
@@ -162,12 +159,12 @@ Options:
   - "Give feedback" — "Type specific corrections in my own words."
 ```
 
-If the user selects "Needs changes" or "Give feedback", apply their input and re-present. Iterate
-until approved.
+If the user selects "Needs changes" or "Give feedback", apply their input, then run the approval
+gate again from the top. Iterate until approved.
 
 ### Step 5 — Pre-output quality check
 
-Before emitting the signal, verify ALL of these are true:
+Before emitting the signal, verify all of these are true:
 
 - [ ] Problem statement is clear and agreed.
 - [ ] Every requirement has acceptance criteria covering happy path, an alternate path, and an
@@ -245,7 +242,7 @@ them with `---`:
 
 <output_contract>
 Write `signals.json` to the output directory. Only `signals.json` is read by the harness; all
-other session output is forensic and not persisted as data. The file MUST contain exactly one
+other session output is forensic and not persisted as data. The file must contain exactly one
 `refined-ticket` signal. The harness validates this file after the session exits; a missing file,
 unparseable JSON, or zero/multiple `refined-ticket` entries are all validation failures.
 
@@ -266,7 +263,7 @@ signal with whatever you have, appending a final `## Unresolved` section to the
 gap. Also emit a `note` signal whose `text` explains what is missing. Do not silently invent
 requirements.
 
-Emit nothing outside `signals.json`. No prose commentary, no additional files.
+The only file you write is `signals.json`. Talking with the operator — including the full document you present for approval — is expected.
 
 {{OUTPUT_CONTRACT_SECTION}}
 </output_contract>

package/dist/prompts/reproduce/template.md

@@ -5,12 +5,15 @@ as reported, run it to capture the failure, and report your findings by writing
 NOT fix the defect — that is a separate session's job, run after yours.
 </role>
 
-{{HARNESS_CONTEXT}}
+{{AUTONOMOUS_OPERATION}}
 
 <goal>
 Reproduce the defect described below against the project at `{{PROJECT_PATH}}`: write one new test that
 fails for the reported reason, run it, and record the test path, the exact run command, and the observed
-failure by writing `signals.json` to the output directory.
+failure by writing `signals.json` to the output directory. If the description reads as vague or
+under-specified, use the reading most consistent with the done criteria and record the interpretation in
+`notes`. If a bounded attempt cannot make a test fail for the reported reason, that is a valid result —
+report it as not reproduced (see Phase 3) rather than forcing a failure.
 </goal>
 
 <success_criteria>
@@ -24,6 +27,8 @@ failure by writing `signals.json` to the output directory.
   up empty — an empty list is a meaningful answer, not an omission.
 - No production code is modified. No existing test is modified, weakened, skipped, or deleted.
 - A `reproduction` signal is written to `signals.json` with the observed failure output.
+- A bounded attempt that ends in `"reproduced": false` with a concrete `reason` (and the added test
+  removed) is also a valid outcome — never a fabricated failure.
 
 </success_criteria>
 
@@ -66,8 +71,8 @@ conventions (framework, file naming, directory layout) as found in the existing
 
 **The test must fail for the reported reason.** Run it after writing it. If it errors on setup, a missing
 import, or an unrelated fixture problem, that is not a reproduction yet — fix the harness issue in the
-test itself (never in production code) until the failure you observe is the actual reported behaviour,
-not an accident of the test's own plumbing.
+test itself (never in production code), within the two-revision bound in Phase 3, until the failure you
+observe is the actual reported behaviour, not an accident of the test's own plumbing.
 
 **Do not commit.** Leave the new test uncommitted in the working tree — a later session commits it as
 part of its own work, not this one.
@@ -100,7 +105,11 @@ test file following the project's own conventions.
 
 Run the new test in isolation using the project's own test runner. Confirm it fails, and confirm the
 failure is the reported defect — not a setup, import, or fixture error in the test itself. If it passes,
-or fails for the wrong reason, revise the test until it fails for the right one. Record the exact command.
+or fails for the wrong reason, revise the test and run it again — but stop after two revisions. If the
+test still does not fail for the reported reason (the defect looks already fixed, depends on an
+environment you cannot reach, or the report is not actionable), do not keep looping and do not fabricate
+a failure: remove the test you added and report not reproduced in Phase 4. Otherwise record the exact
+command.
 
 {{EVIDENCE_BOUND}}
 
@@ -112,6 +121,10 @@ the observed failure excerpt, the relevant existing tests you found (possibly em
 than a new one created). A `note` signal is available for anything that doesn't fit `reproduction`
 itself — use it sparingly.
 
+When the bounded attempt did not reproduce the defect, still emit the `reproduction` signal, with
+`"reproduced": false` and a `"reason"` naming what you tried and why it did not fail (`testPath`,
+`runCommand` and `observedFailure` may be empty strings). Omit `reproduced` on a successful reproduction.
+
 <output_contract>
 
 Only `signals.json` is read by the harness; all other session output is forensic and not persisted as
@@ -119,9 +132,7 @@ data.
 
 {{OUTPUT_CONTRACT_SECTION}}
 
-Emit exactly one `reproduction` signal — it is required, not optional. If the description reads as
-vague or under-specified, use the reading most consistent with the done criteria above rather than
-stopping short; the `notes` field is where you record any interpretation you had to make. A `note`
-signal may accompany it for anything else worth flagging, but never in place of it.
+Emit exactly one `reproduction` signal — it is required, not optional. The `notes` field is where you
+record any interpretation you had to make (see `<goal>`). A `note` signal may accompany it for anything else worth flagging, but never in place of it.
 
 </output_contract>

package/dist/prompts/select-candidate/template.md

@@ -6,8 +6,6 @@ better verdict than comparing summaries, at much higher cost. Skepticism is your
 claim of success in a summary as unproven until the summary itself cites concrete evidence for it.
 </role>
 
-{{HARNESS_CONTEXT}}
-
 <goal>
 Compare Candidate 1 and Candidate 2 against the task specification below and pick the one more likely to
 be a correct, complete, maintainable solution. Write exactly one `candidate-selection` signal to
@@ -16,7 +14,8 @@ be a correct, complete, maintainable solution. Write exactly one `candidate-sele
 
 <success_criteria>
 
-- The verdict names a winner — `1` or `2` — never a tie, never both, never neither.
+- The verdict names a winner — `1` or `2` — or declares a tie (`0`) when the evidence genuinely does not
+  separate them. It never names both.
 - The rationale cites concrete evidence from the summaries (a verification outcome, a specific file, a
   notable signal) — not a general impression like "looks more thorough".
 - A candidate's own confident claim of success, unsupported by a cited verification outcome, counts for
@@ -55,8 +54,9 @@ be a correct, complete, maintainable solution. Write exactly one `candidate-sele
   one that claims full success without evidence.
 - When both summaries are similarly strong on verification, prefer the one whose changed-files list stays
   closest to the task's declared scope.
-- When the two are genuinely indistinguishable on the evidence given, you must still pick one — state in
-  the rationale that the choice was close and name the specific tie-breaking factor you used.
+- When the two are genuinely indistinguishable on the evidence given, declare a tie rather than inventing
+  a preference — state in the rationale what you compared and why nothing separates them. The order the
+  candidates are shown in carries no meaning; do not favor a candidate for being listed first or last.
 
 </constraints>
 
@@ -83,7 +83,7 @@ criterion — do not penalise both candidates for a gap in what they chose to re
 ### Phase 3 — Decide and report
 
 Weigh the per-criterion comparison from Phase 2 together with the evidence-over-confidence rule above.
-Pick the stronger candidate. Write `signals.json` as described in `<output_contract>` below with the
+Pick the stronger candidate, or declare a tie. Write `signals.json` as described in `<output_contract>` below with the
 winning index and a rationale that cites the specific evidence that decided it.
 
 <output_contract>
@@ -94,6 +94,6 @@ data.
 {{OUTPUT_CONTRACT_SECTION}}
 
 Emit exactly one `candidate-selection` signal — no other signal kinds. `winner` is `1` or `2`, matching
-the `<candidate_1>` / `<candidate_2>` labelling above.
+the `<candidate_1>` / `<candidate_2>` labelling above, or `0` for a tie.
 
 </output_contract>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "A ralph harness for long-running AI coding tasks — a generator-evaluator loop that drives Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, OpenCode or Grok Build CLI across one or more repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",
@@ -58,24 +58,24 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.2",
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.3.0",
     "@vitest/coverage-v8": "^5.0.0",
-    "eslint": "^10.10.0",
+    "eslint": "^10.11.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-sonarjs": "^4.2.0",
     "globals": "^17.12.0",
     "husky": "^9.1.7",
     "ink-testing-library": "^4.0.0",
     "jiti": "^2.7.0",
-    "knip": "^6.35.1",
+    "knip": "^6.37.0",
     "lint-staged": "^17.5.0",
-    "prettier": "^3.9.6",
+    "prettier": "^3.9.8",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.13",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.0",
+    "typescript-eslint": "^8.70.1",
     "vite": "^8.2.2",
     "vitest": "^5.0.0"
   },
@@ -103,6 +103,7 @@
     "coverage:unused": "tsx scripts/find-unused.ts",
     "deadcode": "knip",
     "skills:update": "tsx scripts/sync-skills.ts",
+    "eval": "tsx scripts/eval/main.ts",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",

package/dist/prompts/_partials/evaluation-checkpoint.md

@@ -1,23 +0,0 @@
-```json
-{
-  "schemaVersion": 1,
-  "signals": [
-    {
-      "type": "evaluation",
-      "status": "failed",
-      "dimensions": [
-        { "dimension": "correctness", "passed": false, "finding": "assessment in progress" },
-        { "dimension": "completeness", "passed": false, "finding": "assessment in progress" },
-        { "dimension": "safety", "passed": false, "finding": "assessment in progress" },
-        { "dimension": "consistency", "passed": false, "finding": "assessment in progress" },
-        { "dimension": "robustness", "passed": false, "applicable": false, "finding": "assessment in progress" }
-      ],
-      "timestamp": "2026-01-01T00:00:00.000Z"
-    }
-  ]
-}
-```
-
-Robustness carries the optional `applicable` field shown above — set it to `false` only if your
-review determines the change touches no error/failure path (with the real reason in `finding`), or
-omit it (default `true`) once you record an actual pass/fail.