ralphctl 0.7.3 → 0.8.0

package/dist/prompts/refine/template.md

@@ -10,16 +10,11 @@ focused questions, and stop when acceptance criteria are unambiguous.
 
 ## Output target
 
-When approved by the user, write your final markdown body to this file:
+When approved by the user, emit your final markdown body in the `refined-ticket` signal's `body`
+field, written into `signals.json` per the Output contract section at the bottom of this prompt.
+The harness reads the validated signal and stores its `body` on the ticket aggregate.
 
-```
-{{OUTPUT_FILE}}
-```
-
-Write a single markdown document — no JSON wrapper, no commentary, no code fence around the
-document body. The harness reads this file verbatim and stores it on the ticket aggregate.
-
-The expected document shape is at the bottom of this prompt under "Output format".
+The expected markdown shape for the `body` is at the bottom of this prompt under "Output format".
 
 <constraints>
 
@@ -44,6 +39,16 @@ The expected document shape is at the bottom of this prompt under "Output format
 
 {{ISSUE_CONTEXT}}
 
+## Prior progress on this sprint
+
+`progress.md` at the sprint root records every prior task-attempt on this sprint — decisions made, changes
+shipped, learnings recorded. Read it before refining; honor prior decisions. The journal body as of right
+now:
+
+{{PRIOR_PROGRESS}}
+
+If the block above is empty, no prior progress has been recorded yet on this sprint.
+
 ## Protocol
 
 ### Step 1 — Analyse the ticket (think first)
@@ -61,8 +66,10 @@ Then identify, in order:
 
 ### Step 2 — Interview the user
 
-Ask focused questions one at a time using `AskUserQuestion`, starting with the most critical
-gap. Work through these dimensions in priority order; skip any the ticket already nails down.
+Ask focused questions one at a time as **structured multiple-choice** prompts — one question
+with a header, 2–4 labelled options, and a one-line description per option. Start with the most
+critical gap and work through the dimensions below in priority order; skip any the ticket already
+nails down.
 
 **Dimension A — Problem and scope.** What problem are we solving and for whom? What is in
 scope vs explicitly out of scope? What is deferred to future work?
@@ -85,15 +92,17 @@ limits. Phrase as observable constraints, not implementation hints.
 
 #### Asking clarifying questions
 
-Use `AskUserQuestion` with 2–4 options per question:
+Every question is a structured multiple-choice prompt with 2–4 options. Use whichever interactive
+question-asking tool your runtime exposes (Claude Code uses `AskUserQuestion`; other runtimes have
+equivalents) — the shape stays the same:
 
 - First option = your recommendation (label ends with " (Recommended)").
 - Descriptions explain trade-offs or implications.
 - Ask one question at a time.
 - Labels: 1–5 words (UI rendering constraint).
 - Headers: 12 characters or fewer (UI rendering constraint).
-- `multiSelect: true` when choices are not mutually exclusive.
-- Users automatically get an "Other" option — do not add your own.
+- Allow multiple selections when choices are not mutually exclusive.
+- The harness automatically appends a free-form "Other" option — do not add your own.
 
 #### Example interactions
 
@@ -148,7 +157,7 @@ should we split?"
 Present the complete requirements in readable markdown. Use proper headers, bullets, and
 formatting. Make it easy to scan.
 
-Then ask for approval using `AskUserQuestion`:
+Then ask for approval as a structured multiple-choice prompt:
 
 ```
 Question: "Does this look correct? Any changes needed?"
@@ -164,7 +173,7 @@ Iterate until approved.
 
 ### Step 5 — Pre-output quality check
 
-Before writing to file, 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 + edge / error cases.
@@ -174,16 +183,12 @@ Before writing to file, verify ALL of these are true:
 - [ ] Given/When/Then format used where it fits.
 - [ ] Multi-topic tickets use numbered headings (`# 1.`, `# 2.`, …) with `---` dividers.
 
-### Step 6 — Write to file
-
-Once approved AND every checklist item is true, write the markdown body to:
-
-```
-{{OUTPUT_FILE}}
-```
+### Step 6 — Write `signals.json`
 
-Write the markdown document only — no JSON wrapper, no surrounding fence, no chat commentary
-after the write.
+Once approved AND every checklist item is true, write the validated `refined-ticket` signal into
+`signals.json` as documented in the Output contract section at the bottom of this prompt. The
+markdown body goes into the signal's `body` field verbatim — no JSON wrapper inside the body, no
+surrounding code fence.
 
 ## Output format
 
@@ -249,6 +254,8 @@ separate them with `---`:
 ## Failure modes
 
 If, after the interview, you determine the ticket cannot be refined as stated (contradictory
-requirements, missing information you cannot extract from the user), still write to
-`{{OUTPUT_FILE}}` with whatever you have, ending with a final section explaining the gap.
-Do not silently invent requirements.
+requirements, missing information you cannot extract from the user), still emit the
+`refined-ticket` signal with whatever you have, ending the body with a final section explaining
+the gap. Do not silently invent requirements.
+
+{{OUTPUT_CONTRACT_SECTION}}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ralphctl",
-  "version": "0.7.3",
-  "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code & GitHub Copilot across repositories",
+  "version": "0.8.0",
+  "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code, GitHub Copilot, and OpenAI Codex across repositories",
   "homepage": "https://github.com/lukas-grigis/ralphctl",
   "type": "module",
   "license": "MIT",

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

@@ -1,14 +0,0 @@
-<signals>
-
-Emit exactly one of the verdict signals below at the end of your evaluation. The harness records this as the
-authoritative outcome and resumes the generator with the critique on failure.
-
-- `<evaluation-passed>` — Every dimension scored 4 or 5; the implementation matches the specification.
-- `<evaluation-failed>critique</evaluation-failed>` — At least one dimension scored 1, 2, or 3. The critique is
-  the actionable summary the generator will see — be specific about what is wrong and what needs to change. Do
-  not write generic praise or hedged language; the critique must point at concrete files, lines, or behaviours.
-
-Per-dimension findings belong in your markdown body above the verdict signal so a human reviewer can audit your
-reasoning. The signal itself is the verdict only.
-
-</signals>

package/dist/prompts/_partials/signals-task.md

@@ -1,26 +0,0 @@
-<signals>
-
-Use these signals to communicate task outcome to the harness. The harness parses your output for these tags; nothing
-else in your message is treated as a control signal.
-
-- `<task-verified>output</task-verified>` — Records the verification commands you ran and their output. Required
-  before completion so the harness has on-disk evidence of what passed.
-- `<task-complete>` — Marks the task as done. Emit ONLY after `<task-verified>` and only when every declared step
-  has been completed and every verification command passes.
-- `<task-blocked>reason</task-blocked>` — Marks the task as blocked. Use when you cannot proceed: missing
-  dependency, ambiguous step, pre-existing failure, scope mismatch with the ticket. Be concrete in the reason —
-  the harness surfaces this verbatim to the operator.
-
-Optional progress signals you may emit during long-running work:
-
-- `<progress>short summary</progress>` — A one-line status update; the harness streams these to the live UI.
-- `<note>text</note>` — Incidental observations that future tasks should be aware of (patterns, gotchas).
-- `<change>text</change>` — A concrete change you made during this task. Granular ("added X", "renamed Y to Z", "deleted Z"). The harness appends these inline to the task's section in `progress.md`.
-- `<learning>text</learning>` — Non-obvious project knowledge worth carrying across tasks (a hidden constraint, an undocumented convention, a gotcha you hit and resolved). The harness pins these under `## Learnings` at the top of `progress.md` so future tasks see them. Use sparingly; only the kind of insight you'd want a fresh agent to read first.
-- `<decision>text</decision>` — An architectural or design choice with rationale ("chose path A over B because <reason>"). Higher signal than `<learning>`. The harness pins these under `## Decisions` in `progress.md`. Use only for choices a future maintainer would want explained.
-
-Commit message — the harness owns the commit; you propose the wording (emit on every turn that produced edits):
-
-- `<commit-message><subject>type(scope): imperative present tense, ≤72 chars</subject><body>WHY this change, what was considered, follow-ups — wrap lines at 72 chars; multiple paragraphs allowed</body></commit-message>` — Proposed message for the per-task `git commit` the harness runs after this turn. **Emit this on every task that touched a file.** The subject is required and should follow a Conventional Commits shape (`feat(scope): …`, `fix(scope): …`, `refactor(scope): …`, `chore(scope): …`, `docs(scope): …`). The body is required for anything beyond a trivial rename — explain WHY the change exists, what alternatives you considered, what follow-ups remain. The diff already shows the what; your body adds the reasoning a reviewer or future maintainer can't recover from the diff alone. Emit exactly one `<commit-message>` per turn; if you emit multiple, only the last one is used. Falling through to the default `task(<id>): <name>` produces uninformative history — omit only on pure-investigation turns that wrote nothing.
-
-</signals>