ralphctl 0.16.0 → 0.17.1

package/dist/prompts/ideate/template.md

@@ -110,7 +110,9 @@ Skip any dimension the idea description already resolves.
 
 Ask focused questions one at a time. For each question, present it as a structured interactive prompt with
 a header, 2–4 labelled options, and your recommendation first. Use whichever interactive question
-capability your runtime exposes. Work through the dimensions above in priority order.
+capability your runtime exposes. 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. Work
+through the dimensions above in priority order.
 
 Stop asking when ALL of the following are true:
 
@@ -127,10 +129,11 @@ and Edge Cases. Then ask:
 
 ```
 Question: "Does this look correct? Any changes needed?"
-Header: "Phase 1 — Requirements approval"
+Header: "Requirements"
 Options:
-  - "Approved — proceed to planning"
-  - "Needs changes — I'll describe what to adjust"
+  - "Approved" — "Proceed to planning."
+  - "Needs changes" — "I'll describe what to adjust."
+  - "Give feedback" — "Type specific corrections in my own words."
 ```
 
 Iterate until approved. Record the approved requirements text for the `requirements` field of
@@ -189,6 +192,21 @@ For each task, provide:
     inspection. Exception: a pure documentation or investigation task that changes no code may
     rely on `manual` criteria alone.
 - **`blockedBy`** — array of `id` strings that must complete before this task starts.
+- **`extraDimensions`** — optional kebab-case evaluator dimensions beyond the five floor dimensions
+  (correctness, completeness, safety, consistency, robustness). Attach an extra dimension ONLY when an
+  acceptance criterion explicitly demands a measurable property that no floor dimension covers AND no
+  manual criterion already encodes it. When in doubt, omit — the floor dimensions are almost always
+  sufficient. Example of a justified attachment: `migration-safety` when the requirement demands a
+  zero-downtime schema change that the five floor dimensions cannot score on their own. Cap: 2–3 per
+  task; hard max 6.
+
+**Task sizing (brief):** size each task as one coherent feature — a vertical slice a single AI session
+can implement and verify end-to-end. Do not split a utility from its first caller, or a feature from its
+tests — those stay one task. Split when two chunks touch different repositories, or when a natural,
+independently verifiable boundary exists partway through (e.g. schema lands before consumer wiring).
+Avoid `blockedBy` chains for trivial reasons, one task per file, or micro-refactor tasks — fold those
+into the task that needs them. Soft ceiling, not a target: if a task would touch more than ~10 files or
+~500 lines of meaningful change AND a natural split point exists, split it; otherwise keep it whole.
 
 For genuinely contested implementation decisions (library choice, architecture), ask the user a
 structured multiple-choice question before finalising those tasks. Do not ask about routine questions
@@ -201,10 +219,11 @@ dependencies, and a short summary. Show the dependency order. Then ask:
 
 ```
 Question: "Does this task breakdown look correct? Any changes needed?"
-Header: "Phase 2 — Task plan approval"
+Header: "Task plan"
 Options:
-  - "Approved — write signals.json"
-  - "Needs changes — I'll describe what to adjust"
+  - "Approved, write it" — "Write signals.json."
+  - "Needs changes" — "I'll describe what to adjust."
+  - "Give feedback" — "Type specific corrections in my own words."
 ```
 
 Iterate until approved. If rejected, revise and re-present from Step 2.2 — Phase 1 approval stands
@@ -239,18 +258,20 @@ The `outputJson` field is a JSON-encoded string. When decoded it has exactly two
 
 **Required signals:** exactly one `ideated-tickets`.
 
-**Optional signals** (emit when relevant):
+**Optional signals** (emit when relevant). Each carries its prose in a `text` field — never
+`body`; the output contract below shows the exact shape:
 
 - `note` — for status updates or observations worth surfacing.
 - `learning` — for non-obvious repo facts discovered during exploration.
-- `decision` — for architectural choices made during planning (body capped at 500 chars).
+- `decision` — for architectural choices made during planning.
 
 Emit nothing else. No prose responses, no explanatory comments outside the signals file.
 
 **Failure mode.** If you cannot produce a plan (contradictory requirements, missing context that the user
 cannot resolve interactively): emit one `ideated-tickets` signal with `requirements` set to whatever you
-have gathered and `tasks` set to `[]`. Emit one `note` signal with `reason` set to one of:
-`missing-input`, `contradictory-input`, or `environment-failure`. Then stop — do not invent tasks.
+have gathered and `tasks` set to `[]`. Also emit one `note` signal whose `text` starts with one of:
+`missing-input`, `contradictory-input`, or `environment-failure`, followed by a short explanation. Then
+stop — do not invent tasks.
 
 {{OUTPUT_CONTRACT_SECTION}}
 </output_contract>

package/dist/prompts/implement/template.md

@@ -11,6 +11,9 @@ lifecycle and context compaction.
 
 {{HARNESS_CONTEXT}}
 
+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>
@@ -24,8 +27,8 @@ 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).
-- `task-verified` has been emitted with the verbatim command output and, when a run-path was
-  exercised in step 3, the direct end-to-end observation.
+- `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.
@@ -39,9 +42,7 @@ only after every declared step is done and every verification command passes.
 
 <inputs>
 
-## Task
-
-# {{TASK_NAME}}
+## {{TASK_NAME}}
 
 **Task ID:** `{{TASK_ID}}`
 **Project Path:** `{{PROJECT_PATH}}`
@@ -63,6 +64,9 @@ under its declared check type.
 
 <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>{{RETRY_FEEDBACK_SECTION}}</retry_feedback>
 
 <prior_progress>
@@ -85,7 +89,8 @@ The block carries two kinds of content earned on THIS repository. Observed insig
 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.
+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>
@@ -102,15 +107,12 @@ revisited.
 
 <constraints>
 
-- **Complete exactly the declared steps, then stop.** Skipping steps, improvising, or modifying
-  files outside the declared set spreads scope across tasks and breaks the dependency contract the
-  planner laid out.
-- **Fix the code, not the test.** A failing test indicates a bug in the implementation. Update tests
-  only when a declared step explicitly changes the asserted behaviour. If the right move is genuinely
-  ambiguous, emit `task-blocked` so a human can decide — do not silently weaken a test to make a
-  failure disappear.
-- **Removing or disabling existing tests is unacceptable** — except when a declared step explicitly
-  changes the behaviour the test asserts. Removing a test to make verify pass counts as task failure.
+- **Complete exactly 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.
 - **Do not write to the progress file.** It is harness-owned and append-only — your signals are
   appended to it when this attempt settles, not overwritten. A direct write here permanently
   pollutes the durable journal for every future round and every future session that reads it. Emit
@@ -128,7 +130,7 @@ revisited.
   - Preserve existing prose verbatim. Add new sections at the bottom; do not rewrite or paraphrase
     what is already there. The file is a contract — silent reflows surprise reviewers.
   - Include only what an unfamiliar engineer would get wrong without being told. Redundant context
-    measurably reduces agent success rate.
+    measurably raises cost without improving agent success.
   - Be specific and verifiable. "Use 2-space indentation" beats "format properly".
   - Stay under 200 lines, max 7 H2 sections, no H4+. Adherence degrades past these limits.
   - Never embed slash commands, hooks, MCP server config, IDE settings, secrets, or credentials —
@@ -148,7 +150,7 @@ create files under the project path. Write `signals.json` to the output director
 
 ### Phase 1 — Reconnaissance
 
-Before starting Phase 1, work through the prior critique (if any), the declared steps, the
+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.
@@ -165,12 +167,18 @@ on the first attempt, not to discover problems after the fact.
    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.
 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.
 6. **Environment** — review `<verify_script>` and `<pre_verify_results>` above. If
    `<pre_verify_results>` is non-empty, the harness already verified the baseline — review those
-   results instead of re-running. If `<pre_verify_results>` is empty and no verify script is
+   results instead of re-running. If `<pre_verify_results>` is empty and a verify script IS
+   configured (e.g. the first task of a fresh setup), run it once yourself to establish the
+   baseline before changing anything. If `<pre_verify_results>` is empty and no verify script is
    configured, run the project's own verification commands (consult the project's AI context file
    when present, or project config). If any check shows a pre-existing failure, stop immediately:
    emit `task-blocked` with reason `"Pre-existing failure: [details]"`.
@@ -178,11 +186,16 @@ on the first attempt, not to discover problems after the fact.
    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).
+   co-located). Also check the directories your task touches for a nested context file (for example
+   a nested `AGENTS.md`) — the nearest file wins for local conventions.
 8. **Existing patterns** — search for code similar to what you need to build. Matching existing
    patterns is the single most important feedforward control — it prevents introducing new conventions
    that conflict with neighbours.
 
+Before writing any code, restate in your working notes — three to five lines, not part of any
+signal — the task goal, the acceptance criteria, and the specific facts from the prior progress or
+learnings above that you will rely on.
+
 Proceed to Phase 2 once Phase 1 passes.
 
 ### Phase 2 — Implementation
@@ -208,13 +221,14 @@ Proceed to Phase 2 once Phase 1 passes.
 In order:
 
 1. **Confirm all steps done** — every declared step has been completed.
-2. **Run each `auto` criterion's command once** and fix any failures before proceeding. Do NOT run
-   the verify script from `<verify_script>` — the harness runs it after your turn as the
-   independent commit 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.
+2. **Run each `auto` criterion's command once** and fix any failures before proceeding. 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 from `<verify_script>` — the harness runs it after your turn as the independent commit
+   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.
 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
@@ -239,9 +253,12 @@ In order:
    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`.
 
-4. **Record verification results** — emit `task-verified` with the verbatim commands and their
-   combined stdout/stderr output from step 2, plus the end-to-end observation from step 3 when
-   it ran, all in the `output` field.
+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
+   `output` field. Include each command, its exit code, every failing
+   test/check name, and roughly the last 50 lines of output per command; when a command's output
+   exceeds that, write the full log to a file in your session working directory — never inside
+   the repository — and cite its path instead of pasting the rest.
 5. **Propose the commit message** — emit `commit-message` with a real subject and a body explaining
    WHY the change exists, what alternatives you weighed, and any follow-ups a reviewer should know.
    The harness commits after this turn using your wording verbatim. The fallback when you omit the
@@ -259,30 +276,25 @@ In order:
 changes. Fix and re-verify. If unfixable after a reasonable attempt, emit `task-blocked` with the
 concrete failure as the `reason`.
 
-**Tests break.** Determine whether your changes or a pre-existing issue caused the failure. Fix the
-implementation, not the test. If pre-existing: emit `task-blocked` with
+**Tests break.** Determine whether your changes or a pre-existing issue caused the failure (see the
+test-weakening rule in `<constraints>`). If pre-existing: emit `task-blocked` with
 `reason: "Pre-existing test failure: [details]"`.
 
 **Blocked by another task.** Emit `task-blocked` with
 `reason: "Missing dependency: [what is missing and which task should produce it]"`. Do NOT stub or
 mock the missing piece.
 
-**Scope seems wrong.** Declared steps take priority over project patterns when they conflict — the
-planner may have scoped them narrowly on purpose. If the steps force a clear pattern violation or
-seem genuinely incomplete relative to the ticket, emit `task-blocked` rather than expanding scope.
+**Scope seems wrong.** See the scope rule in Phase 2 step 3 above — emit `task-blocked` rather than
+expanding scope.
 
-**Cannot complete** — environment failure, contradictory input, or unresolvable ambiguity: emit a
-single `note` signal with the reason and stop. Do not invent plausible-looking output.
+**Cannot complete** — environment failure, contradictory input, or unresolvable ambiguity: emit
+`task-blocked` with a concrete reason and stop. Do not invent plausible-looking output.
+
+**Round ends without `task-complete`, or with criteria still failing.** Emit one `note` signal
+distilling the approaches you attempted, the dead ends you ruled out and why, and the most
+promising untried direction — this is what the next round or the next escalated session starts
+from, not a blank slate.
 
 {{DECISIONS_GUIDANCE}}
 
 {{OUTPUT_CONTRACT_SECTION}}
-
-## References
-
-- Anthropic agent-memory guidance — empirical basis for the 200-line / 7-H2 caps and the
-  adherence-degradation finding.
-- Anthropic coding-agent best practices — source of the "no slash commands / hooks / MCP / IDE
-  settings in the project context file" rule.
-- Gloaguen et al., _Evaluating AGENTS.md_ (arXiv 2602.11988) — redundant context measurably
-  reduces agent success rate.

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

@@ -46,15 +46,23 @@ For the complete history — older than the excerpt above — read `{{PROGRESS_F
 
 <goal>
 Address every dimension the evaluator flagged in `<prior_critique>`, then run each `auto`
-criterion's command once. 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. Emit `task-verified` with the verbatim command output, propose a
-`commit-message` when you touched any file, and emit `task-complete` only after every flagged
-dimension is resolved and every criterion command passes. Removing or disabling a test to make
-verify pass counts as task failure — fix the implementation, not the test. When a flagged item is
-genuinely blocked (missing dependency, contradictory input, unresolvable ambiguity), emit
-`task-blocked` with the concrete reason instead of guessing. Emit `change`, `learning`, and
-`note` signals as applicable — the harness records them in the sprint journal.
+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 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. Emit `task-verified` with each command, its exit code, every failing
+test/check name, and roughly the last 50 lines of output per command — when a command's output
+exceeds that, write the full log to a file in your session working directory (never inside the
+repository) and cite its path — propose a `commit-message` when you touched any file, and emit
+`task-complete` only after every flagged dimension is resolved and every criterion command
+passes. Removing or disabling a test to make verify pass counts as task failure — fix the
+implementation, not the test — except when a declared step explicitly changes the behaviour the
+test asserts. When a flagged item is genuinely blocked (missing dependency, contradictory input,
+unresolvable ambiguity), emit `task-blocked` with the concrete reason instead of guessing. Emit
+`change`, `learning`, and `note` signals as applicable — the harness records them in the sprint
+journal. 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.
 </goal>
 
 {{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/plan/template.md

@@ -29,8 +29,8 @@ Produce a dependency-ordered task array and write it as a `task-plan` signal to
 </success_criteria>
 
 <session_topology>
-Your working directory for this session is the per-sprint plan unit root
-(`<sprintDir>/plan/<run-slug>/`). You are NOT running inside any project repository.
+Your working directory for this session is a harness-managed session directory — you are NOT
+running inside any project repository.
 
 The project repositories listed under `<repositories>` are mounted as read-only sources
 you can explore — each one has equal access weight; no single repository is primary. Read
@@ -332,6 +332,8 @@ them; do not re-litigate a prior decision without surfacing why in the plan.
 
 <existing_tasks>{{EXISTING_TASKS}}</existing_tasks>
 
+If `<existing_tasks>` is empty, this is a fresh plan — there is nothing to replace.
+
 </inputs>
 
 ## Protocol
@@ -344,7 +346,9 @@ and sequence dependencies.
 Read the repositories mounted under `<repositories>` to:
 
 1. Read repo instruction files (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`)
-   when present.
+   when present. Also check major subdirectories for nested context files (for example a
+   nested `AGENTS.md`) — note directory-local conventions in the plan when they differ from
+   the root.
 2. Skim project structure and manifests (`package.json`, `pyproject.toml`, etc.).
 3. Run `git log --oneline -20` per repository so you don't plan tasks that re-implement
    already-landed work.
@@ -368,7 +372,9 @@ Draft the plan first, before writing JSON.
 
 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.
+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.
 
 Good questions:
 
@@ -431,4 +437,11 @@ Once the user has answered "Approved, write it" in Step 4 AND every checklist it
 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.
 
+**Optional signals** (emit when relevant). Each carries its prose in a `text` field — never
+`body`; the output contract below shows the exact shape:
+
+- `note` — for status updates or observations worth surfacing.
+- `learning` — for non-obvious repo facts discovered during exploration.
+- `decision` — for architectural choices made during planning.
+
 {{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/readiness/template.md

@@ -1,7 +1,8 @@
 <role>
 You are an AI coding agent performing a one-shot, read-only repository inventory. Your sole job for this call
 is to produce a project context file proposal that the harness writes to the target path after operator
-review. You do not modify files, run shell commands, or make commits — the harness owns execution.
+review. Write nothing except `signals.json`; run only read-only inspection commands — never build,
+install, or otherwise mutating commands. The harness owns execution.
 </role>
 
 <goal>
@@ -15,8 +16,8 @@ warranted. Write all signals to the `signals.json` path described in `<output_co
 
 - `agents-md-proposal` signal emitted with `tag: "{{WIRE_TAG}}"` and a non-empty `content` field.
 - Every tech-stack claim in `content` is backed by a quoted file path or file content, not inferred.
-- `content` targets 80–200 lines and MUST NOT exceed the hard line cap named for
-  `{{CURRENT_TOOL}}` in `<target_file_conventions>` below — the exact ceiling is provider-specific.
+- `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.
 - Setup and verify skill proposals, when emitted, cite only commands that resolve in this specific repo
@@ -54,9 +55,8 @@ 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.** Target 80–200 lines in the produced context file body. The hard line cap is
-provider-specific — read the exact ceiling from `<target_file_conventions>` below and never exceed it.
-Brevity is a feature — the file is read fresh on every AI session.
+**Output length.** Follow the length guidance in `<target_file_conventions>` below — the target and
+any ceiling are provider-specific. Brevity is a feature — the file is read fresh on every AI session.
 
 **Structure caps.** Exactly one H1; at most 7 H2 sections; no H4 or deeper headings. Prefer bullets and
 short sentences.
@@ -90,8 +90,8 @@ shell line per step — chain with `&&`, not `;`, so the runner stops at the fir
 
 <capabilities>
 You can read files anywhere in `{{REPOSITORY_PATH}}` — limit yourself to the inspection scope above. You can
-search the repository for file names or content patterns. You MUST NOT run shell commands or write files
-other than `signals.json`.
+search the repository for file names or content patterns, and run read-only inspection commands. Write
+nothing except `signals.json`; never run build, install, or otherwise mutating commands.
 </capabilities>
 
 <output_contract>
@@ -147,7 +147,8 @@ Write `signals.json` to the path described in `<output_contract>` with the signa
 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 with reason `missing-input` and stop.
+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.
 
 ## Signal summary
@@ -162,3 +163,5 @@ Do not invent stack claims without evidence.
    `["typescript-strict"]`).
 5. `note` — optional. One short observation. MUST be the only signal emitted when the repo cannot be
    characterised.
+6. `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

@@ -7,8 +7,9 @@ from any earlier session is assumed; read `<prior_progress>` below to orient you
 
 <goal>
 Produce a single `refined-ticket` signal written to `signals.json` in the output directory. The
-signal's `body` field carries the approved requirements markdown. Success = the body is operator-
-approved, covers the happy path plus edge/error cases, and contains no implementation details.
+signal's `body` field carries the approved requirements markdown. Success = the body is
+operator-approved, covers the happy path plus edge/error cases, and contains no implementation
+details.
 </goal>
 
 <success_criteria>
@@ -28,12 +29,12 @@ approved, covers the happy path plus edge/error cases, and contains no implement
 <inputs>
 <ticket>{{TICKET}}</ticket>
 
-<issue_context>{{ISSUE_CONTEXT}}</issue_context>
+{{ISSUE_CONTEXT}}
 
 <prior_progress>{{PRIOR_PROGRESS}}</prior_progress>
 
 If `<prior_progress>` is empty, no prior work has been recorded for this sprint yet.
-If `<issue_context>` is empty, no upstream issue body was available.
+If the `<context>` block above is empty or absent, no upstream issue body was available.
 </inputs>
 
 {{HARNESS_CONTEXT}}
@@ -43,8 +44,8 @@ If `<issue_context>` is empty, no upstream issue body was available.
   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
-  directory is writable. If a question requires source context, capture it under `proposed_default`
-  as "requires repo investigation".
+  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
   answer to both — ask each dimension separately.
 - Honor prior decisions in `<prior_progress>`. Do not re-open a dimension the sprint has already
@@ -58,7 +59,7 @@ If `<issue_context>` is empty, no upstream issue body was available.
 ### Step 1 — Analyse the ticket
 
 Before producing any output, work through what is clear, what is ambiguous, and what edge cases the
-ticket omits. Only `signals.json` is read by the harness.
+ticket omits.
 
 Then identify, in order:
 
@@ -143,13 +144,7 @@ Options:
 
 ### Step 3 — Stop interviewing
 
-Stop when ALL of these are true:
-
-1. The problem statement is clear and agreed.
-2. Every functional requirement has at least one acceptance criterion.
-3. Scope boundaries (in / out / deferred) are explicit.
-4. Major edge cases and error states are addressed.
-5. Two engineers reading these requirements would build the same thing.
+Stop asking questions once every item in the Step 5 pre-output quality checklist would pass.
 
 ### Step 4 — Present requirements for approval
 
@@ -249,9 +244,10 @@ them with `---`:
 ```
 
 <output_contract>
-Write `signals.json` to the output directory. 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.
+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
+`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.
 
 Permitted signal kinds:
 

package/dist/skills/ralphctl-abstraction-first/SKILL.md

@@ -7,7 +7,7 @@ description: Cross-phase skill — design the shape of the change (entities, bou
 
 > Concept
 >
-> from [Martin Fowler — "Abstraction-First"](https://martinfowler.com/articles/structured-prompt-driven/abstraction-first.html).
+> from [SPDD (Zhang & Xia, martinfowler.com) — "Abstraction-First"](https://martinfowler.com/articles/structured-prompt-driven/abstraction-first.html).
 > Adapted for ralphctl's three phases.
 
 The shape of the change comes before the words that describe it. Name the entities, the boundaries, and the

package/dist/skills/ralphctl-alignment/SKILL.md

@@ -5,7 +5,7 @@ description: Cross-phase skill — establish a shared understanding of what will
 
 # Alignment
 
-> Concept from [Martin Fowler — "Alignment"](https://martinfowler.com/articles/structured-prompt-driven/alignment.html).
+> Concept from [SPDD (Zhang & Xia, martinfowler.com) — "Alignment"](https://martinfowler.com/articles/structured-prompt-driven/alignment.html).
 > Adapted for ralphctl's three phases.
 
 The fastest way to ship the wrong thing is to start producing output before you have agreed on what is being

package/dist/skills/ralphctl-iterative-review/SKILL.md

@@ -7,7 +7,7 @@ description: Cross-phase skill — treat AI output as a controlled feedback loop
 
 > Concept
 >
-> from [Martin Fowler — "Iterative Review"](https://martinfowler.com/articles/structured-prompt-driven/iterative-review.html).
+> from [SPDD (Zhang & Xia, martinfowler.com) — "Iterative Review"](https://martinfowler.com/articles/structured-prompt-driven/iterative-review.html).
 > Adapted for ralphctl's three phases.
 
 One-shot generation looks fast and is slow. The cheap review you skipped at iteration N becomes the expensive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphctl",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "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",