ralphctl 0.25.0 → 0.27.0

package/dist/prompts/plan/template.md

@@ -51,6 +51,8 @@ write in this session is `signals.json` in your output directory.
 
 <repositories>{{REPOSITORIES}}</repositories>
 
+A `verify gate:` line under a repository is a command the harness runs after every task to catch regressions — only when the task's diff touches the noted path, when a path is noted. No such line means none is configured.
+
 All paths above are fixed — repository selection is not part of this session.
 
 ## Prior progress on this sprint
@@ -63,16 +65,17 @@ them.
 
 If `<prior_progress>` is empty, no prior progress has been recorded on this sprint.
 
+When `<prior_learnings>` lists entries: observed insights are orientation — verify any that bear on
+your plan before relying on one; listed decisions are deliberate prior choices — keep to them, and to
+revisit one say why in the plan. When either conflicts with what the repository shows now, trust the
+repository and record the conflict. Use them as background to scope tasks accurately and to pick
+verification commands that exist in the target repo.
+A learning that a command fails at HEAD or depends on the local environment (a running dev server,
+seeded database, browser, environment variable) is enough to keep that command out of every `auto`
+criterion.
+
 <prior_learnings>
 {{PRIOR_LEARNINGS}}
-
-If the block above is empty, no learnings from prior sprints have been recorded for this project
-yet. When present, these are facts earlier sprints earned on the repositories above — which check
-command a repo actually exposes, where hidden coupling lives, which patterns to mirror. Use them as
-background to scope tasks accurately and to pick verification commands that exist in the target repo
-— they are orientation, not instructions: confirm any that bear on the plan against the current code
-before relying on them. Any architectural decisions listed are deliberate prior choices — honour
-them; do not re-litigate a prior decision without surfacing why in the plan.
 </prior_learnings>
 
 <existing_tasks>{{EXISTING_TASKS}}</existing_tasks>
@@ -85,17 +88,13 @@ If `<existing_tasks>` is empty, this is a fresh plan — there is nothing to rep
 - **One coherent feature per task** — size tasks by what a single AI session can implement
   and verify end-to-end. Too small creates serial chains, duplicate context reloads, and
   merge conflicts; too large is hard to verify. The Task Sizing rules below decide.
-- **Files are owned, not shared** — each file should be edited by exactly one task. When
-  two tasks must touch the same file, sequence them via `blockedBy`.
-- **Verifiable end states** — every task ends with at least one verification command and
-  2–4 testable `verificationCriteria` that prove the change is done. "Code looks right" is
-  not a criterion. Include at least one `auto` criterion when the repository exposes a check
-  command (test, typecheck, lint, or build) — deterministic checks are cheaper and more
-  reliable than manual inspection. Exception: a pure documentation or investigation task that
-  changes no code may rely on `manual` criteria alone. For a task that introduces new
-  behaviour, express those same 2–4 criteria as given/when/then scenarios naming the
-  interface signatures the change must expose — a structured spec catches ambiguity a prose
-  description alone would let through.
+- **Files are owned, not shared** — give each file to one task. When two tasks must edit the
+  same file, one is `blockedBy` the other so they never run in parallel.
+- **Verifiable end states** — every task carries 2–4 testable `verificationCriteria`, at least one `auto`
+  when the repository exposes a check command (rule in the task fields below). "Code looks right" is not
+  a criterion. Scope test commands by the `verificationCriteria` rules in the task fields — whether
+  a whole-suite criterion belongs depends on the repository's verify gate. For a task that introduces
+  new behaviour, write its behavioural criteria as Given/When/Then and name the interface they exercise.
 - **No invention** — every task traces back to an approved ticket via `ticketRef`. If
   coherence requires additional scope, surface it as an observation, not a silent expansion.
   Prefer fewer, well-grounded tasks over a complete-looking plan padded with speculative ones —
@@ -171,7 +170,7 @@ Too granular — should be one task, not three:
 
 Right size:
 
-- "Centralise date formatting across all sections" — creates utility AND updates all usages.
+- "Centralise date formatting across all sections" — creates utility and updates all usages.
 - "Improve style robustness in interactive components" — handles multiple related files.
 
 ### Dependency Graph
@@ -181,12 +180,12 @@ Tasks execute in dependency order — foundations before dependents.
 1. **Foundation first** — shared utilities, types, schemas before anything that uses them.
 2. **Declare all dependencies** — use `blockedBy` to enforce order; reference each blocker
    by its `id`. Do not rely on array position alone.
-3. **Avoid false dependencies** — only add `blockedBy` when there is a real code
-   dependency.
+3. **Avoid false dependencies** — only add `blockedBy` for a real code dependency or a
+   shared file.
 4. **Validate the DAG** — no cycles; earlier tasks cannot depend on later ones.
 
-**Dependency test:** for each `blockedBy` entry, ask: "Does this task literally use code
-produced by the blocker?" If not, remove the dependency.
+**Dependency test:** keep a `blockedBy` entry only if this task uses code the blocker produces, or
+edits a file the blocker also edits; otherwise remove it.
 
 ### Examples (calibration, not templates)
 
@@ -195,25 +194,32 @@ above.
 
 **Verification Criteria — good vs bad**
 
-Good criteria (structured, verifiable):
+Good criteria (structured, verifiable; values illustrative):
 
 ```json
 "verificationCriteria": [
-  { "id": "C1", "assertion": "TypeScript compiles with no errors", "check": "auto", "command": "<project's typecheck command>" },
-  { "id": "C2", "assertion": "All existing tests pass plus new tests for the added feature", "check": "auto", "command": "<project's test command>" },
+  { "id": "C1", "assertion": "The project type-checks with no errors", "check": "auto", "command": "<project's typecheck command>" },
+  { "id": "C2", "assertion": "The new pagination tests in tests/users/pagination.test.ts pass", "check": "auto", "command": "<project's test command scoped to tests/users/pagination.test.ts>" },
   { "id": "C3", "assertion": "GET /api/users?page=-1 returns 400 with a validation error body", "check": "manual" }
 ]
 ```
 
-Notes: use the project's own typecheck / test / lint command for `auto` criteria — never
-hardcode a package manager. Use `manual` for behavioural assertions the evaluator must
-inspect in code.
+Scope test commands to the tests the task adds or changes (file path, test-name filter, or tag),
+and keep or drop a project-wide regression criterion by the verify-gate rules in the task fields.
+Use `manual` for behavioural assertions the evaluator must inspect in code.
 
 Bad criteria (vague, not independently verifiable):
 
 - `{ "assertion": "Code is clean and well-structured", "check": "manual" }`
 - `{ "assertion": "Error handling is appropriate", "check": "manual" }`
-- Bare strings (e.g. `"TypeScript compiles"`) — the structured object is required.
+- `{ "assertion": "The full test suite passes, including the new specs", "check": "auto", "command": "<project's full test command>" }`
+  when the repository's verify gate already runs that suite after every task — one pre-existing
+  failure anywhere makes this impossible to pass without editing tests the task doesn't own.
+  Exception: a task whose stated purpose is to make that suite pass.
+- `{ "assertion": "The end-to-end suite passes", "check": "auto", "command": "<project's e2e command>" }`
+  — whatever the verify gate runs, one stale or environment-dependent spec anywhere in the suite
+  blocks the task; scope the command to the spec files the task adds or changes instead.
+- Bare strings (e.g. `"The project type-checks"`) — the structured object is required.
 
 **Dependency Graph — good vs bad**
 
@@ -248,11 +254,12 @@ Bad — vague steps that force the agent to guess:
 }
 ```
 
-Good — precise steps with file paths and pattern references:
+Good — precise steps with file paths and pattern references (shape only, values illustrative):
 
 ```json
 {
   "name": "Add user authentication",
+  "ticketRef": "<ticket-uuid>",
   "projectPath": "/absolute/path/to/repo",
   "steps": [
     "Create auth service in src/services/auth.ts with login(), logout(), getCurrentUser() — follow the error handling and return-type pattern in src/services/user.ts",
@@ -264,27 +271,32 @@ Good — precise steps with file paths and pattern references:
   "verificationCriteria": [
     {
       "id": "C1",
-      "assertion": "TypeScript compiles with no errors",
+      "assertion": "The project type-checks with no errors",
       "check": "auto",
       "command": "<project's typecheck command>"
     },
     {
       "id": "C2",
-      "assertion": "All existing tests pass plus new auth tests",
+      "assertion": "The new auth service tests pass",
       "check": "auto",
-      "command": "<project's test command>"
+      "command": "<project's test command scoped to src/services/__tests__/auth.test.ts>"
+    },
+    {
+      "id": "C3",
+      "assertion": "Given an unauthenticated visitor, when they open a protected route, then they are redirected to /login",
+      "check": "manual"
     },
-    { "id": "C3", "assertion": "ProtectedRoute redirects unauthenticated users to /login", "check": "manual" },
-    { "id": "C4", "assertion": "useAuth hook exposes isAuthenticated, user, login, and logout", "check": "manual" }
+    {
+      "id": "C4",
+      "assertion": "Given a signed-in user, when the app asks for the current auth state, then it reports the user and offers login and logout actions",
+      "check": "manual"
+    }
   ]
 }
 ```
 
 ## Protocol
 
-Before producing any output, map each ticket onto repositories, identify natural task boundaries,
-and sequence dependencies.
-
 ### Step 1 — Explore the repositories
 
 Read the repositories mounted under `<repositories>` to:
@@ -297,10 +309,10 @@ Read the repositories mounted under `<repositories>` to:
 3. Run `git log --oneline -20` per repository so you don't plan tasks that re-implement
    already-landed work.
 4. Find similar implementations to mirror existing patterns.
-5. Extract verification commands (build, test, lint, typecheck).
+5. Extract verification commands (build, test, lint, typecheck), how to run the test runner
+   against one file, name, or tag, and which subset CI gates on when CI filters (e.g. a tag or grep).
 
-Remember: you are in the per-sprint plan unit root, not inside any repository. Use the
-repository paths from `<repositories>` as the roots for all file reads and searches.
+Use the repository paths from `<repositories>` as the roots for all file reads and searches.
 
 ### Step 2 — Map tickets to tasks
 
@@ -310,15 +322,13 @@ For each approved ticket, decide:
 - Where the natural task boundaries are.
 - Which tasks must complete before others (`blockedBy`).
 
-Draft the plan first, before writing JSON.
+Draft the plan before writing any JSON.
 
 ### Step 3 — Interview the user
 
-For genuinely contested decisions, ask the user a structured multiple-choice question — one
-at a time, 2–4 labelled options per question, recommendation as the first option. Use your
-runtime's interactive question capability to present the question. Labels are 1–5 words;
-headers are 12 characters or fewer (UI rendering constraints). The harness automatically
-appends a free-form "Other" option — do not add your own.
+For genuinely contested decisions, ask the user a structured multiple-choice question.
+
+{{QUESTION_FORMAT}}
 
 Good questions:
 
@@ -334,7 +344,13 @@ Bad questions:
 - Trivial choices derivable from project conventions ("which test runner?" — read the
   config).
 
-### Step 4 — Present the plan for review
+### Step 4 — Validate before presenting
+
+Draft the plan, then check it against this list before the operator sees it.
+
+{{VALIDATION_CHECKLIST}}
+
+### Step 5 — Present the plan for review
 
 {{APPROVAL_GATE}}
 
@@ -347,6 +363,7 @@ dependency exists:
 **Ticket:** {ticket title}
 **Repository:** {projectPath}
 **Depends on:** {none | task ids}
+**Extra evaluator dimensions:** {none | list}
 **Description:** ...
 
 **Steps:**
@@ -359,8 +376,8 @@ dependency exists:
 - ... (check type, command)
 ```
 
-The approval question goes last, via a structured multiple-choice prompt — do not ask in prose ("does
-this look right?"). Prose answers are ambiguous and the harness cannot act on them.
+The approval question goes last, as a structured multiple-choice question (or the numbered-list fallback
+in `<approval-gate>`) — not an open prose question like "does this look right?", whose answer is ambiguous.
 
 - **Question:** "Does this task breakdown look correct?"
 - **Options:**
@@ -368,21 +385,15 @@ this look right?"). Prose answers are ambiguous and the harness cannot act on th
   - "Needs changes" — I'll describe what to adjust.
   - "Give feedback" — Type specific corrections in my own words.
 
-If the user picks "Needs changes" or "Give feedback", apply their input, revise the tasks,
-run the approval gate again with the full plan and dependency order, then re-ask the same
-structured approval question. Iterate until the user picks "Approved, write it". Step 5 runs the same checklist the gate asked you
-to apply before presenting; treat it as a confirmation. If it forces any change, run the approval gate
-again before writing.
-
-**Step 5 — Validate before output.**
-
-{{VALIDATION_CHECKLIST}}
+If the user picks "Needs changes" or "Give feedback", apply their input, revise the tasks, re-check the
+Step 4 list, run the approval gate again with the full plan and dependency order, then re-ask the same
+structured approval question. Iterate until the user picks "Approved, write it".
 
 ### Step 6 — Write `signals.json`
 
-Once the user has answered "Approved, write it" in Step 4 AND every checklist item above is
-satisfied, write the `task-plan` signal into `signals.json` per the output contract below.
-The task array goes into the signal's `tasksJson` field as a JSON-encoded string.
+Once the user has answered "Approved, write it" in Step 5, write the `task-plan` signal into
+`signals.json` per the output contract below. The task array goes into the signal's `tasksJson` field
+as a JSON-encoded string.
 
 **Optional signals** (emit when relevant). Each carries its prose in a `text` field — never
 `body`; the output contract below shows the exact shape:

package/dist/prompts/readiness/template.md

@@ -5,6 +5,8 @@ review. Write nothing except `signals.json`; run only read-only inspection comma
 install, or otherwise mutating commands. The harness owns execution.
 </role>
 
+{{ONE_SHOT_OPERATION}}
+
 <goal>
 Inspect the repository at `{{REPOSITORY_PATH}}` and emit an `agents-md-proposal` signal whose `content`
 field is the project context file body the harness will write for the `{{CURRENT_TOOL}}` provider. Emit
@@ -15,15 +17,15 @@ bottom of this prompt.
 
 <success_criteria>
 
-- `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.
+- `agents-md-proposal` signal emitted. `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 — unless you cannot characterise the repository (see the Output phase).
 - Every tech-stack claim in `content` is backed by a quoted file path or file content, not inferred.
 - 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
+  below — the exact target is provider-specific. The target 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, not 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).
@@ -46,7 +48,10 @@ bottom of this prompt.
 
 **Read-only scope.** Read configuration and metadata files only — `package.json`, `pyproject.toml`,
 `Cargo.toml`, `go.mod`, `Makefile`, `mise.toml`, `.tool-versions`, `.github/workflows/*.yml`, `README.md`,
-top-level `scripts/` entries, `flake.nix`. Do not read source trees, test directories, vendored or generated
+top-level `scripts/` entries, `flake.nix`. Also read other tools' context files and onboarding docs when
+present — `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursor/rules/`, `.grok/rules/`,
+`.claude/rules/`, `CONTRIBUTING.md` — and do not restate or contradict them; when they disagree with a
+manifest, mention it in a `note`. Do not read source trees, test directories, vendored or generated
 directories. Do not write any file other than `signals.json` in `<outputDir>`.
 
 **Evidence requirement.** For each tech-stack claim in the context file body, quote the file that
@@ -58,14 +63,14 @@ with this repo would get it wrong without being told. Anything an agent can deri
 existing docs does not belong in the context file — redundant context measurably reduces agent success.
 Lean is better than comprehensive.
 
-**Output length.** Follow the length guidance in `<target_file_conventions>` above — the target and
-any ceiling are provider-specific. Brevity is a feature — the file is read fresh on every AI session.
+**Output length.** Follow the length guidance in `<target_file_conventions>` above — the target is
+provider-specific. Brevity is a feature — the file is read fresh on every AI session.
 
 **Specificity rule.** Every rule must be specific and verifiable. Replace vague guidance ("write clean code")
-with concrete checks ("run `make test` before committing"). Reserve emphasis tokens (`IMPORTANT`, `YOU MUST`)
+with concrete checks ("run `make test` before committing"). Reserve emphasis tokens (all-caps warnings)
 for genuinely surprising rules — overuse erodes their meaning.
 
-**Do NOT include:**
+**Leave out:**
 
 - Tool-specific slash commands, hooks, subagent definitions, MCP server configurations, IDE settings.
 - Long tutorials, file-by-file descriptions, or generic engineering wisdom.
@@ -75,7 +80,7 @@ for genuinely surprising rules — overuse erodes their meaning.
 
 **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
+signal's `content` holds 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.
@@ -86,6 +91,10 @@ only when `package.json` exists; a `requirements.txt` install only when that fil
 only when the language's manifest exists). Reject pipe-to-shell patterns, `eval`, and `rm -rf`. Prefer one
 shell line per step — chain with `&&`, not `;`, so the runner stops at the first failure.
 
+{{SKILL_BODY_RULES}}
+
+Each skill body is saved as its own skill file, so a short title heading at the top is fine.
+
 </constraints>
 
 <capabilities>
@@ -116,12 +125,9 @@ A short, accurate file beats a long, padded one.
 
 ### Phase 1 — Inspection
 
-Before reading files, outline your plan: list which artefacts from `<detected_artefacts>` you will actually
-read, the project's apparent shape (language, package manager, monorepo vs single repo), and the candidate
-sections you would consider including.
-
-Then read the configuration and metadata files in scope. Do not read source trees, test directories, vendored
-directories, or generated output.
+Decide which artefacts from `<detected_artefacts>` to read and what shape the project has (language,
+package manager, monorepo vs single repo), then read the configuration and metadata files in scope. Do not
+read source trees, test directories, vendored directories, or generated output.
 
 ### Phase 2 — Evidence mapping
 
@@ -145,24 +151,27 @@ there. Do not emit prose commentary outside the signal file.
 
 If you cannot characterise the repository (e.g. the repo is empty, no manifest files are readable, the
 inspection scope yields no evidence), emit a single `note` signal whose `text` starts with `missing-input`,
-followed by a short explanation, and stop.
-Do not invent stack claims without evidence.
+followed by a short explanation, instead of an `agents-md-proposal`, and stop. Do not invent stack claims
+without evidence.
 
 <output_contract>
 {{OUTPUT_CONTRACT_SECTION}}
 
 ### Signal semantics
 
-- `agents-md-proposal` — REQUIRED. `tag` MUST equal `"{{WIRE_TAG}}"`. `content` is the project context
-  file body — or, when `<existing_context_file>` is non-empty, only the new sections to append to it.
+- `agents-md-proposal` — required, except in the cannot-characterise case above. Set `tag` to
+  `"{{WIRE_TAG}}"`, whatever tag the example shows. `content` is the project context file body — or, when
+  `<existing_context_file>` is non-empty, only the new sections to append to it. The contract example shows
+  the shape for a fresh file.
 - `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 /
   lint / test). Omit entirely when the project has no canonical verify command.
-- `skill-suggestions` — optional. `names` is a list of kebab-case bundled skill names to link (e.g.
-  `["typescript-strict"]`). Each name becomes a directory name, so it must be lowercase alphanumeric
-  with single hyphens — no paths, no separators, no spaces. The harness silently drops any other name.
-- `note` — optional. One short observation. MUST be the only signal emitted when the repo cannot be
+- `skill-suggestions` — optional. `names` is a list of kebab-case bundled skill names to link (the contract
+  example's names are placeholders — suggest only names you have evidence exist). Each name becomes a
+  directory name, so it must be lowercase alphanumeric with single hyphens — no paths, no separators, no
+  spaces. The harness silently drops any other name.
+- `note` — optional. One short observation. It is also the only signal to emit when the repo cannot be
   characterised.
 - `learning` — optional. A durable insight worth recording beyond this session (e.g. a
   non-obvious convention the inspection uncovered), in its `text` field.

package/dist/prompts/refine/template.md

@@ -15,12 +15,13 @@ details.
 <success_criteria>
 
 - The problem statement names the user and the observable behaviour they need.
-- Every acceptance criterion covers at least one happy-path scenario, one alternate path, and one
-  error or edge case.
+- Each acceptance criterion has a happy-path scenario plus every alternate or error case the behaviour
+  actually has — usually 2–5 Given/When/Then bullets; no invented alternate paths.
 - Scope boundaries (in scope / out of scope / deferred) are explicit.
 - Two engineers reading the requirements would build the same thing.
-- No implementation detail appears anywhere in the body (no technology names, no architecture
-  choices, no database terms).
+- No implementation choices appear in the body (architecture, storage, libraries) — unless the
+  technology is itself the user-visible requirement or the ticket names it (a file format, a supported
+  platform, an external API).
 - `signals.json` is written exactly once, contains exactly one `refined-ticket` signal, and parses
   as valid JSON.
 
@@ -56,10 +57,7 @@ If the `<context>` block above is empty or absent, no upstream issue body was av
 
 ### Step 1 — Analyse the ticket
 
-Before producing any output, work through what is clear, what is ambiguous, and what edge cases the
-ticket omits.
-
-Then identify, in order:
+Before asking anything, identify, in order:
 
 1. What is already clear and doesn't need clarification.
 2. What is ambiguous, missing, or underspecified.
@@ -70,9 +68,9 @@ anything.
 
 ### Step 2 — Interview the user
 
-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 dimensions below in priority order; skip any the ticket already answers.
+Ask focused questions, one at a time as structured multiple-choice questions (format below). Start with
+the most critical gap and work through the dimensions in priority order; skip any the ticket already
+answers.
 
 **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?
@@ -82,9 +80,10 @@ explicitly out of scope? What is deferred to future work?
 - Good: "User can filter results by date range."
 - Bad: "Add a SQL `WHERE` clause for date filtering."
 
-**Dimension C — Acceptance criteria.** Each criterion covers multiple scenarios, not just the happy
-path. Use Given/When/Then phrasing. Include the happy path, alternate paths (different input states
-or roles), and error/edge cases. Each scenario must be independently verifiable from the outside.
+**Dimension C — Acceptance criteria.** Use Given/When/Then phrasing, each scenario independently
+verifiable from the outside. Each criterion has a happy-path scenario plus every alternate or error case
+the behaviour actually has — usually 2–5 bullets; don't invent an alternate path the behaviour does not
+have.
 
 **Dimension D — Edge cases and error states.** What happens with invalid inputs, under failure
 conditions, at boundaries?
@@ -94,16 +93,7 @@ Phrase as observable constraints, not implementation hints.
 
 #### Asking clarifying questions
 
-Every question is a structured multiple-choice prompt with 2–4 options. Ask one question at a time.
-Use the interactive question capability your runtime provides to present structured choices — the
-shape is:
-
-- First option = your recommendation (label ends with " (Recommended)").
-- Descriptions explain trade-offs or implications.
-- Labels: 1–5 words (UI rendering constraint).
-- Headers: 12 characters or fewer (UI rendering constraint).
-- Allow multiple selections when choices are not mutually exclusive.
-- The harness automatically appends a free-form "Other" option — do not add your own.
+{{QUESTION_FORMAT}}
 
 #### Example interactions
 
@@ -133,16 +123,26 @@ Options:
 ```
 Question: "The ticket says 'support multiple formats'. Which formats are required for the initial release?"
 Header: "Formats"
-multiSelect: true
+Choices: not mutually exclusive — let the operator pick several
 Options:
   - "CSV (Recommended)" — "Universal compatibility; simple structure."
   - "JSON" — "API-friendly; structured data."
-  - "PDF" — "Human-readable reports; requires additional library."
+  - "PDF" — "Human-readable reports."
 ```
 
-### Step 3 — Stop interviewing
+### Step 3 — Check before presenting
 
-Stop asking questions once every item in the Step 5 pre-output quality checklist would pass.
+Stop interviewing once every item below is true, then check the requirements against it before the
+operator sees them:
+
+- [ ] Problem statement is clear and agreed.
+- [ ] Every requirement has acceptance criteria: a happy path plus each alternate or error case the
+      behaviour actually has.
+- [ ] Scope boundaries are explicit (what's in AND what's out).
+- [ ] Edge cases and error states are addressed.
+- [ ] No implementation choices appear (unless the technology is itself the requirement).
+- [ ] Given/When/Then format used where it fits.
+- [ ] Multi-topic tickets use numbered headings (`# 1.`, `# 2.`, …) with `---` dividers.
 
 ### Step 4 — Present requirements for approval
 
@@ -159,27 +159,14 @@ Options:
   - "Give feedback" — "Type specific corrections in my own words."
 ```
 
-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:
-
-- [ ] Problem statement is clear and agreed.
-- [ ] Every requirement has acceptance criteria covering happy path, an alternate path, and an
-      error or edge case.
-- [ ] Scope boundaries are explicit (what's in AND what's out).
-- [ ] Edge cases and error states are addressed.
-- [ ] No implementation details appear.
-- [ ] Given/When/Then format used where it fits.
-- [ ] Multi-topic tickets use numbered headings (`# 1.`, `# 2.`, …) with `---` dividers.
+If the user selects "Needs changes" or "Give feedback", apply their input, re-check the Step 3 list, then
+run the approval gate again from the top. Iterate until approved.
 
-### Step 6 — Write `signals.json`
+### Step 5 — Write `signals.json`
 
-Once approved AND every checklist item is true, write the `refined-ticket` signal into `signals.json`
-as documented in `<output_contract>` below. The markdown body goes into the signal's `body` field
-verbatim — no JSON wrapper inside the body, no surrounding code fence.
+Once approved, write the `refined-ticket` signal into `signals.json` as documented in
+`<output_contract>` below. The markdown body goes into the signal's `body` field verbatim — no JSON
+wrapper inside the body, no surrounding code fence.
 
 ## Output format
 
@@ -208,7 +195,7 @@ verbatim — no JSON wrapper inside the body, no surrounding code fence.
 - **Given** {alternate precondition}, **When** {action}, **Then** {alternate result}
 - **Given** {error/edge case}, **When** {action}, **Then** {graceful handling}
 
-(Repeat for each AC. 2–5 scenario bullets per AC covering happy / alternate / error.)
+(Repeat for each AC. Keep the happy-path bullet; add one bullet per alternate or error case the behaviour has.)
 
 ## Edge cases
 
@@ -254,8 +241,8 @@ Field names differ by kind — match the `signals.json` shape below exactly:
 - `note` (OPTIONAL) — narrative annotation in its `text` field; use sparingly for facts worth surfacing to the operator.
 - `learning` (OPTIONAL) — a non-obvious finding about the ticket, in its `text` field, worth recording in the sprint
   log.
-- `decision` (OPTIONAL) — a scope or design decision made during the interview, in its `text` field (keep it
-  concise — roughly 500 characters).
+- `decision` (OPTIONAL) — a scope or design decision made during the interview, in its `text` field (one or two
+  sentences).
 
 **Failure mode.** If, after the interview, the ticket cannot be refined as stated — due to
 contradictory requirements or information you cannot extract from the user — emit the `refined-ticket`

package/dist/prompts/reproduce/template.md

@@ -1,12 +1,14 @@
 <role>
 You are a senior engineer reproducing a reported defect before anyone attempts to fix it. This is a
-single-shot investigation: you write exactly ONE new failing test that demonstrates the defect exactly
+single-shot investigation: you write exactly one new failing test that demonstrates the defect exactly
 as reported, run it to capture the failure, and report your findings by writing `signals.json`. You do
-NOT fix the defect — that is a separate session's job, run after yours.
+not fix the defect — that is a separate session's job, run after yours.
 </role>
 
 {{AUTONOMOUS_OPERATION}}
 
+{{GIT_BOUNDARY}}
+
 <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
@@ -63,15 +65,15 @@ session needs to see the test fail on a clean checkout, exactly as you left it.
 
 **Locate relevant tests first.** Before writing anything, search the existing test suite for tests that
 already exercise the affected area — the same module, the same code path, or a similar prior defect.
-Name every one you judge relevant in `relevantTests`, even when the search comes up empty.
+Name every one you judge relevant in `relevantTests`.
 
 **Write exactly one new test.** Prefer adding a case to an existing, clearly-relevant test file over
 creating a new one — this keeps the reproduction close to related coverage. Match the project's own test
 conventions (framework, file naming, directory layout) as found in the existing suite.
 
 **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), within the two-revision bound in Phase 3, until the failure you
+import, or an unrelated fixture problem, that is not a reproduction yet — fix the problem in the test's
+own setup (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
@@ -108,8 +110,8 @@ failure is the reported defect — not a setup, import, or fixture error in the
 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.
+a failure: remove the test case you added — edit it out and leave the rest of the file as it was —
+and report not reproduced in Phase 4. Otherwise record the exact command.
 
 {{EVIDENCE_BOUND}}