ralphctl 0.25.0 → 0.27.0

package/dist/prompts/implement/template.md

@@ -13,9 +13,6 @@ lifecycle and context compaction.
 
 {{AUTONOMOUS_OPERATION}}
 
-Summaries of earlier tasks' outcomes in this sprint, when present below, are for continuity — read
-them and do not redo work they already cover.
-
 {{PRIOR_EPISODES}}
 
 <goal>
@@ -28,15 +25,15 @@ only after every declared step is done and every verification command passes.
 
 - Every declared implementation step has been executed in the stated order.
 - Every `auto` verification criterion's command exits 0 (or, when no `auto` criteria are defined,
-  the project's own check commands pass).
+  the verify script — or, with none configured, the project's own check commands — passes).
 - `task-verified` has been emitted with the bounded command output specified in Phase 3 step 4 and,
   when a run-path was exercised in step 3, the direct end-to-end observation.
 - `commit-message` has been emitted with a subject and a WHY-focused body — except for a pure
   investigation task that wrote no files, where the signal may be omitted (see Phase 3 step 5).
 - `task-complete` has been emitted.
 - No test has been removed or disabled to achieve a passing verify run.
-- No file outside the declared implementation steps has been modified — except for the project's
-  AI context file (when a declared step calls for it).
+- No file has been changed beyond what the steps request or clearly require (plus the project's AI
+  context file when a step calls for it).
 
 </success_criteria>
 
@@ -62,45 +59,36 @@ under its declared check type.
 
 {{REPRODUCTION_SECTION}}
 
-<plateau_directive>{{PLATEAU_DIRECTIVE_SECTION}}</plateau_directive>
-
-When the block above is empty, no plateau escalation applies this round — proceed normally; it
-carries a "change your approach" directive only when the gen-eval loop has stalled and the
-escalation policy granted a same-model retry.
+{{PLATEAU_DIRECTIVE_SECTION}}
 
 <prior_critique>{{PRIOR_CRITIQUE_SECTION}}</prior_critique>
 
 {{PRIOR_ATTEMPTS_SECTION}}
 
-<prior_criteria_verdicts>{{PRIOR_CRITERIA_VERDICTS}}</prior_criteria_verdicts>
+{{PRIOR_CRITERIA_VERDICTS}}
 
-The block above — when non-empty — records which done-criteria already pass. Keep those green;
-focus this round's effort on the criteria still failing rather than re-proving what already passed.
+{{RETRY_FEEDBACK_SECTION}}
 
-<retry_feedback>{{RETRY_FEEDBACK_SECTION}}</retry_feedback>
+{{RESTORED_WORK_SECTION}}
 
-<prior_progress>
 `progress.md` (at the sprint root, `{{PROGRESS_FILE}}`) is an append-only chronological journal
 of every prior task-attempt on this sprint — decisions made, changes shipped, learnings recorded,
 notes pinned. Honor prior decisions; do not re-litigate them without a `decision` signal explaining
-why. The journal body as of right now:
+why. The journal body as of right now is below; when it is empty, no prior progress has been
+recorded — this is the first task of the sprint.
 
+<prior_progress>
 {{PRIOR_PROGRESS}}
-
-If the block above is empty, no prior progress has been recorded — this is the first task of the
-sprint.
 </prior_progress>
 
+When `<prior_learnings>` lists entries: observed insights are orientation — verify any that bear on
+your task before relying on one; listed decisions are deliberate prior choices — keep to them, and to
+revisit one say why in a `decision` signal. When either conflicts with what the repository shows now,
+trust the repository and record the conflict as a `learning` signal. Learnings were earned in earlier
+sessions and may be stale.
+
 <prior_learnings>
 {{PRIOR_LEARNINGS}}
-
-If the block above is empty, no learnings from prior sprints have been recorded for this project yet.
-The block carries two kinds of content earned on THIS repository. Observed insights are read-only
-orientation — not instructions; verify any that bear on your task before relying on them.
-Architectural decisions are deliberate choices made in prior sprints; honor them and do not
-re-litigate them without emitting a `decision` signal that explains why the prior choice is being
-revisited. These were earned in earlier sessions — when one conflicts with what you observe in the
-repository now, trust the repository and record the conflict as a `learning` signal.
 </prior_learnings>
 
 <verify_script>
@@ -117,24 +105,23 @@ repository now, trust the repository and record the conflict as a `learning` sig
 
 <constraints>
 
-- **Complete exactly the declared steps, then stop** — see the scope rule in Phase 2 step 3 below.
+- **Do the declared steps, then stop** — see the scope rule in Phase 2 step 3 below.
 - **Fix the code, not the test.** A failing test indicates a bug in the implementation. Update or
   remove a test, or disable one, only when a declared step explicitly changes the behaviour it
   asserts — doing so otherwise counts as task failure. If the right move is genuinely ambiguous, emit
   `task-blocked` so a human can decide rather than silently weakening a test to make a failure
   disappear.
-- **Keep every action reversible.** Do not run `git reset --hard`, force-push, skip hooks
-  (`--no-verify`), or delete files you did not create — except when a declared step explicitly
-  calls for it. The harness commits your work and a maintainer reviews it; destructive actions
-  cannot be undone from there.
 - **Do not special-case tests to make them pass** (hardcoding expected values, detecting the test
   environment). When you believe a test itself is wrong, say so in a `note` signal instead of
   bending the implementation around it.
 - **Clean up after yourself.** Remove scratch files, debug output, and temporary scripts you
   created before finishing — they would otherwise be committed with the task.
 - **Stay in scope.** Change what the steps request or clearly require. Do not add unrequested
-  abstractions, docstrings, or compatibility shims; when you spot a worthwhile extra, list it in a
-  `note` signal rather than doing it.
+  abstractions, docstrings, documentation, supporting files, or compatibility shims; when you spot a
+  worthwhile extra, list it in a `note` signal rather than doing it. Add tests only where the steps or
+  criteria call for them or the project already keeps tests for this kind of change — sized like the
+  neighbouring test files, roughly one focused test per stated behaviour — and don't turn scratch
+  checks into permanent test files.
 - **When checks pass, stop and report.** Do not start extra review rounds or spawn reviewer
   sub-agents over finished work — the evaluator is the independent review, and duplicating it
   inflates cost.
@@ -170,42 +157,41 @@ repository now, trust the repository and record the conflict as a `learning` sig
     step explicitly calls for adding one of these items to the project context file. Those artefacts
     otherwise have dedicated homes and do not belong there.
 
+{{GIT_BOUNDARY}}
+
 </constraints>
 
 <capabilities>
 You can read any file in the project and in the mounted sprint directory. You can run shell commands
 (subject to the harness's sandbox). You can search the repository for patterns. You can modify and
-create files under the project path. Write `signals.json` to the output directory named in the
-Output contract section at the bottom of this prompt.
+create files under the project path.
 </capabilities>
 
 ## Protocol
 
 ### Phase 1 — Reconnaissance
 
-Before the checks below, work through the prior critique (if any), the declared steps, the
-verification criteria, and risks you can already see (file conflicts, ambiguous scope, edges the
-steps do not cover). Addressing the prior critique's dimensions comes before any new implementation
-work. Proceed directly for routine file edits and command runs.
+When earlier work exists, take it in this order: the `<retry_feedback>` regression first, then the
+`<prior_critique>` dimensions, then the remaining unmet criteria.
 
-Then perform these checks before writing any code. The goal is to steer the implementation correctly
+Perform these checks before writing any code. The goal is to steer the implementation correctly
 on the first attempt, not to discover problems after the fact.
 
 {{PARALLEL_TOOL_CALLS}}
 
 1. **Confirm your working directory** — verify you are in the expected project path (`{{PROJECT_PATH}}`).
-2. **Prior critique first (rounds 2+)** — if `<prior_critique>` above is non-empty, work through
-   each failed dimension and plan how you will address it before starting new work. If this task
-   was escalated to a stronger model, the prior critique identifies exactly what the previous model
-   missed — address those dimensions specifically.
+2. **Prior critique (rounds 2+)** — if `<prior_critique>` above is non-empty, plan how you will
+   address each failed dimension before starting new work. If this task was escalated to a stronger
+   model, the prior critique identifies exactly what the previous model missed — address those
+   dimensions specifically.
 3. **Prior progress** — the `<prior_progress>` block above carries the journal body in-context. Read
    it for cross-task context; re-read `{{PROGRESS_FILE}}` directly only when you need the latest
    on-disk state (e.g. another task settled mid-session).
 4. **Working tree state** — inspect the working tree for uncommitted changes before writing anything.
-   Unexpected pre-existing uncommitted changes are an environment failure — emit `task-blocked` naming
-   the dirty tree rather than building on unknown state. Exception: when `<prior_critique>` or
-   `<retry_feedback>` above is non-empty, an earlier round of this task left its work uncommitted —
-   that dirt is expected; continue from it.
+   Two kinds are expected: the reproduction test named in `<reproduction>`, and earlier work on this
+   task (signalled by a non-empty `<prior_critique>`, `<retry_feedback>`, `<prior_attempts>` or
+   `<restored_work>`). Build on those. Any other uncommitted change is unknown state — emit
+   `task-blocked` naming the files rather than building on it.
 5. **Git log orientation** — run `git log --oneline -20` to see what prior tasks on this branch have
    committed. Cross-reference with `<prior_progress>` to avoid re-implementing or conflicting with
    their work. Changes already committed by a prior task are done — do not redo them.
@@ -221,8 +207,6 @@ on the first attempt, not to discover problems after the fact.
    a broken tree) is not a blocker either — do not stop for it, and leave failures unrelated to
    your steps alone. A failure unrelated to this task's declared scope that you discover
    yourself blocks the task: emit `task-blocked` with reason `"Pre-existing failure: [details]"`.
-   If `<retry_feedback>` is non-empty, a previous attempt's harness post-verify failed — address
-   that regression as the very first priority of this attempt before doing any other work.
 7. **Conventions** — read project config to understand what is enforced: lint and formatter settings,
    compiler config, test framework patterns (e.g. `*.test.ts` vs `*.spec.ts`, `__tests__/` vs
    co-located). Also check the directories your task touches for a nested context file (for example
@@ -251,12 +235,16 @@ Proceed to Phase 2 once Phase 1 passes.
    complete in the main session.
 2. **Match existing patterns** — the conventions found in Phase 1 are your template. Use the same
    file organisation, error handling, test structure, and import style as neighbouring code. Introduce
-   new patterns only when a declared step explicitly calls for one.
+   new patterns only when a declared step explicitly calls for one. Prefer targeted edits over
+   rewriting a whole file, unless the file is short or most of it changes.
 3. **Execute declared steps in order, precisely.** Each step references specific files and actions.
-   If a step is unclear, pick the narrowest plausible interpretation that still satisfies the
-   verification criteria rather than signalling blocked. If steps appear incomplete relative to the
-   ticket, emit `task-blocked` rather than expanding scope — the planner may have scoped them
-   narrowly on purpose.
+   If a step is unclear, implement the reading its wording and the surrounding code most directly
+   support — one that still satisfies the verification criteria — and record that assumption in a
+   `decision` signal rather than signalling blocked. **The done criteria define done; the steps
+   are the planned route.** Do the steps, plus the smallest extra change the criteria clearly
+   require — the planner may have scoped the steps narrowly on purpose. If meeting the criteria needs
+   a materially different change (a new module, API or behaviour the steps don't mention), emit
+   `task-blocked` with `blockerClass: "ambiguous-request"` instead of widening scope.
 4. **After each meaningful change, run the cheapest check relevant to what you just touched** — for
    example, the typecheck command or the test file for the module you edited — not the full suite.
    The authoritative gate is Phase 3 step 2; interim runs are incremental sanity checks.
@@ -273,7 +261,8 @@ In order:
    gate; running it yourself would duplicate that gate and inflate cost. Exception: when the task
    defines no `auto` criteria, run the verify script once yourself to confirm no regressions before
    signalling completion. When no verify script is configured either, run the project's own check
-   commands (as found during Phase 1 reconnaissance) before signalling completion.
+   commands (as found during Phase 1 reconnaissance) before signalling completion. A syntax-only
+   check, or a command that failed to start, is not a pass.
 3. **End-to-end exercise — required when a run-path exists.** Before recording verification
    results, check `<project_tooling>` for a way to start or invoke the product: a dev-server
    start command, application entry point, CLI invocation, or end-to-end / smoke suite. Consult
@@ -294,9 +283,12 @@ In order:
    schema package, or only static analysis tooling listed — skip this step and state the reason in
    one sentence in `task-verified` so the evaluator does not treat the absence as an oversight.
 
-   If starting the product fails due to an environment failure (missing dependency, port
-   unavailable, runtime not found), emit `task-blocked` with the failure details — do not skip
-   silently. A deliberate skip (no run-path declared) does not warrant `task-blocked`.
+   If the product cannot start for an environment reason: when only the project's declared
+   dependencies are missing, install them with its own tooling and lockfile first (not via sudo or
+   the system package manager, unless a declared step calls for it); otherwise record in
+   `task-verified` which exercise you could not run and why, and continue. Emit `task-blocked`
+   only when no criterion command could run either. A deliberate skip (no run-path declared) does
+   not warrant `task-blocked`.
 
 4. **Record verification results** — emit `task-verified` with the commands from step 2 and their
    combined stdout/stderr, plus the end-to-end observation from step 3 when it ran, all in the
@@ -305,27 +297,21 @@ In order:
    {{EVIDENCE_BOUND}}
 
 5. **Propose the commit message** — emit `commit-message` with a real subject and a body explaining
-   WHY the change exists, what alternatives you weighed, any remaining uncertainty, and — when the
-   change is risky — how to roll it back. Include any follow-ups a reviewer should know. The harness
-   commits after this turn using your wording verbatim. The fallback when you omit the signal is just
+   WHY the change exists, plus any remaining uncertainty and, when the change is risky, how to roll
+   it back. Match the subject style of the recent commits you saw in `git log`; keep the body to a
+   few lines and skip any part with nothing to say. The harness commits after this turn using your
+   wording verbatim. The fallback when you omit the signal is just
    the task name and description paragraph — thin context. Emit it on every task that touched any
    file. Omit only when the task was a pure investigation that wrote nothing.
 6. **Signal completion** — emit `task-complete` only after all the above steps pass. Then, as the
-   very LAST action of this turn, write exactly ONE file — `signals.json` — to the absolute path
+   very last action of this turn, write exactly one file — `signals.json` — to the absolute path
    named in the Output contract section below. That file is the only channel the harness reads:
    your code changes and your messages are invisible to it, so a turn that skips this write is
    treated as producing no work at all, no matter how much you did.
 
 ## Failure modes
 
-When you emit `task-blocked`, prefer something an operator can act on in seconds over a paragraph
-of prose. `reason` is always required. When — and only when — the block is an information gap
-rather than a broken environment, also set: `question` (the single concrete question that, answered,
-unblocks you) and `whatUnblocksMe` (what someone needs to supply or decide). When that gap is
-specifically missing information, an ambiguous request, or contradictory instructions, also set
-`blockerClass` to `missing-information`, `ambiguous-request`, or `contradictory-information`
-respectively — leave it unset for an environment or verification failure, where none of the three
-fit.
+{{TASK_BLOCKED}}
 
 **A step fails.** Read the error carefully. Determine whether it is pre-existing or caused by your
 changes. Fix and re-verify. If unfixable after a reasonable attempt, emit `task-blocked` with the

package/dist/prompts/implement-continuation/template.md

@@ -1,7 +1,7 @@
 # Continue — Round {{ROUND_NUMBER}}
 
 <role>
-You are the same AI coding agent, continuing the SAME task on a resumed session. You already have
+You are the same AI coding agent, continuing the same task on a resumed session. You already have
 the full task brief, the contract, and your own earlier work in this conversation — this prompt
 does not repeat them. Your job for this call is one more round of the gen-eval loop: address the
 evaluator's critique below and re-verify. The harness manages session lifecycle and context
@@ -36,11 +36,7 @@ When the block above is empty, no criteria were threaded into this round — tre
 `{{CONTRACT_PATH}}` as authoritative instead.
 </task_criteria>
 
-<plateau_directive>{{PLATEAU_DIRECTIVE_SECTION}}</plateau_directive>
-
-When the block above is empty, no plateau escalation applies this round — proceed normally; it
-carries a "change your approach" directive only when the gen-eval loop has stalled and the
-escalation policy granted a same-model retry.
+{{PLATEAU_DIRECTIVE_SECTION}}
 
 <prior_critique>{{PRIOR_CRITIQUE_SECTION}}</prior_critique>
 
@@ -48,19 +44,17 @@ escalation policy granted a same-model retry.
 
 {{REPRODUCTION_SECTION}}
 
-<retry_feedback>{{RETRY_FEEDBACK_SECTION}}</retry_feedback>
+{{RETRY_FEEDBACK_SECTION}}
 
 <pre_verify_results>{{PRE_VERIFY_RESULTS}}</pre_verify_results>
 
-<prior_progress>
 The most recent sprint-journal sections (decisions, changes, learnings, notes from prior
 task-attempts) are below for quick reference. Honor prior decisions; do not re-litigate them
 without a `decision` signal explaining why. When the block is empty there is no recent journal
-context to apply.
+context to apply. For the complete history — older than the excerpt — read `{{PROGRESS_FILE}}` on disk.
 
+<prior_progress>
 {{PRIOR_PROGRESS}}
-
-For the complete history — older than the excerpt above — read `{{PROGRESS_FILE}}` on disk.
 </prior_progress>
 
 {{DECISIONS_GUIDANCE}}
@@ -75,7 +69,7 @@ Address every dimension the evaluator flagged in `<prior_critique>` above, then
 - Every dimension named in `<prior_critique>` has been addressed.
 - Every `auto` criterion's command has been run once this round (or, when the task defines no
   `auto` criteria, the verify script has been run once as the fallback evidence source).
-- `task-verified` has been emitted with the bounded evidence described in Protocol step 2.
+- `task-verified` has been emitted with the bounded evidence described in Protocol step 3.
 - `commit-message` has been emitted when any file was touched, naming any remaining uncertainty
   and, when the change is risky, how to roll it back.
 - `task-complete` has been emitted only once every flagged dimension is resolved and every
@@ -87,26 +81,33 @@ Address every dimension the evaluator flagged in `<prior_critique>` above, then
 
 ## Protocol
 
-1. **Re-verify.** Run each `auto` criterion's command once. If a command fails intermittently,
+1. **Fix.** If `<retry_feedback>` is non-empty, resolve that regression first. Then change the code to
+   resolve each failed dimension in `<prior_critique>` (and follow `<plateau_directive>` when present),
+   using `<reproduction>` and `<prior_attempts>` where present, and keep criteria that already pass
+   green.
+2. **Re-run the checks.** Run each `auto` criterion's command once. If a command fails intermittently,
    re-run it once; if the two runs disagree, report the inconsistency as evidence in
-   `task-verified` rather than asserting a clean pass or fail. Do NOT run the verify script — the
+   `task-verified` rather than asserting a clean pass or fail. Do not run the verify script — the
    harness runs it after your turn as the independent commit gate. Exception: when the task
    defines no `auto` criteria, run the verify script once yourself.
-2. **Record verification results.** Emit `task-verified` with each command, its exit code, and
+3. **Record verification results.** Emit `task-verified` with each command, its exit code, and
    every failing test/check name.
 
    {{EVIDENCE_BOUND}}
 
-3. **Propose the commit message.** Emit `commit-message` when you touched any file, naming any
+4. **Propose the commit message.** Emit `commit-message` when you touched any file, naming any
    remaining uncertainty and, when the change is risky, how to roll it back.
-4. **Emit narrative signals as applicable.** `change`, `learning`, and `note` — contrast a
+5. **Emit narrative signals as applicable.** `change`, `learning`, and `note` — contrast a
    now-working approach with what failed in an earlier round when this round succeeds where a
    prior one didn't; the harness records them in the sprint journal.
-5. **Signal completion or blockage.** When a flagged item is genuinely blocked (missing
-   dependency, contradictory input, unresolvable ambiguity), emit `task-blocked` with the concrete
-   reason instead of guessing. Otherwise emit `task-complete` once every flagged dimension is
+6. **Signal completion or blockage.** When a flagged item is genuinely blocked, emit `task-blocked`
+   instead of guessing (triage fields below). Otherwise emit `task-complete` once every flagged dimension is
    resolved and every criterion command passes. When this round ends without `task-complete` or
    with criteria still failing, also emit one `note` signal distilling the approaches attempted,
    the dead ends ruled out and why, and the most promising untried direction.
 
+{{TASK_BLOCKED}}
+
+{{GIT_BOUNDARY}}
+
 {{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/implement-crash-resume/template.md

@@ -1,7 +1,7 @@
 # Resume — Interrupted Attempt
 
 <role>
-You are the same AI coding agent, resuming the SAME task on a continued session. The tool that
+You are the same AI coding agent, resuming the same task on a continued session. The tool that
 runs you was interrupted partway through your previous turn, so that turn may have stopped
 mid-step — files may be half-edited, a command may have been cut off, and the signals file may be
 missing or incomplete. The task brief and your earlier work are already in this conversation; this
@@ -18,16 +18,25 @@ Before changing anything, find out what is already done:
 Treat what you remember as unverified until the working tree confirms it. Keep edits that are
 complete and correct, finish the ones that were cut off, and redo any that are broken. Do not
 revert or restart work that is already sound.
+
+The uncommitted changes you find are your own interrupted work — the original brief's dirty-tree
+check does not apply to them. If a signals file was written before the interruption, rewrite it in
+full after you re-run the checks; do not keep a `task-complete` or `task-verified` that predates them.
 </reconcile>
 
 Then continue the task to completion, exactly as you would have without the interruption. You are
 operating autonomously and the user cannot answer questions, so do the remaining work with tool
 calls instead of ending this turn on a plan. Re-run each `auto` criterion's command once the
-work is in place — or, when the task defines no `auto` criteria, run the verify script once — and emit `task-verified` with the bounded evidence, `commit-message` when any
-file was touched, and `task-complete` only once every criterion passes. When something is
-genuinely blocked, emit `task-blocked` with the concrete reason. Emit `change`, `decision`,
+work is in place — or, when the task defines no `auto` criteria, run the verify script once — and
+emit `task-verified` with the bounded evidence, `commit-message` when any file was touched, and
+`task-complete` only once every criterion passes. When something is genuinely blocked, emit
+`task-blocked` (triage fields below). Emit `change`, `decision`,
 `learning` and `note` as applicable. The no-test-weakening rule still applies — fix the
 implementation, not the test — except when a declared step explicitly changes the behaviour the
 test asserts.
 
+{{TASK_BLOCKED}}
+
+{{GIT_BOUNDARY}}
+
 {{OUTPUT_CONTRACT_SECTION}}