ralphctl 0.21.0 → 0.23.0

package/dist/prompts/implement/template.md

@@ -11,6 +11,8 @@ lifecycle and context compaction.
 
 {{HARNESS_CONTEXT}}
 
+{{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.
 
@@ -62,6 +64,10 @@ under its declared check type.
 
 <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.
+
 <prior_critique>{{PRIOR_CRITIQUE_SECTION}}</prior_critique>
 
 {{PRIOR_ATTEMPTS_SECTION}}
@@ -138,7 +144,11 @@ repository now, trust the repository and record the conflict as a `learning` sig
   - Include only what an unfamiliar engineer would get wrong without being told. Redundant context
     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.
+  - Match the length and structure of a comparable context file already in this ecosystem (this
+    project's own file if it has one, or the convention for the format the active provider reads)
+    rather than a fixed line or heading count — the right size is provider- and project-dependent.
+    Absent a comparable example, keep it short and skimmable: a handful of top-level sections, no
+    deep nesting.
   - Never embed secrets or credentials — those belong in `.env` files or a secret manager, never a
     committed context file, with no exception.
   - Never embed slash commands, hooks, MCP server config, or IDE settings — except when a declared
@@ -150,8 +160,8 @@ repository now, trust the repository and record the conflict as a `learning` sig
 <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 specified in
-`<output_contract>`.
+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.
 </capabilities>
 
 ## Protocol
@@ -166,6 +176,8 @@ work. Proceed directly for routine file edits and command runs.
 Then 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
@@ -204,11 +216,11 @@ on the first attempt, not to discover problems after the fact.
    changing any code. A fix you cannot first reproduce is a guess; re-run the same repro in Phase 3
    to confirm it now passes.
 
-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. From here on, after roughly every five tool actions, restate
-in one line which phase you are in and which acceptance criteria remain — a long session drifts
-without this anchor.
+Before writing any code, confirm against the contract at `{{CONTRACT_PATH}}` — not against your
+memory of it — which declared steps and acceptance criteria remain unmet, using `<prior_critique>`
+and `<prior_criteria_verdicts>` above as your starting point. From here on, re-confirm against that
+same contract, rather than your own recollection, whenever you are about to report progress or are
+unsure how much of the task remains — a long session drifts without this anchor.
 
 Proceed to Phase 2 once Phase 1 passes.
 
@@ -269,10 +281,10 @@ In order:
 
 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.
+   `output` field. Include each command, its exit code, and every failing test/check name.
+
+   {{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
@@ -287,6 +299,15 @@ In order:
 
 ## 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.
+
 **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
 concrete failure as the `reason`.
@@ -296,14 +317,18 @@ test-weakening rule in `<constraints>`). If pre-existing: emit `task-blocked` wi
 `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.
+`reason: "Missing dependency: [what is missing and which task should produce it]"`,
+`blockerClass: "missing-information"`, a `question` naming exactly what is missing, and
+`whatUnblocksMe` naming which task or artifact must land first. Do NOT stub or mock the missing piece.
 
-**Scope seems wrong.** See the scope rule in Phase 2 step 3 above — emit `task-blocked` rather than
-expanding scope.
+**Scope seems wrong.** See the scope rule in Phase 2 step 3 above — emit `task-blocked` with
+`blockerClass: "ambiguous-request"`, a `question` asking which scope was intended, and
+`whatUnblocksMe` naming the decision that would resolve it, rather than expanding scope.
 
 **Cannot complete** — environment failure, contradictory input, or unresolvable ambiguity: emit
-`task-blocked` with a concrete reason and stop. Do not invent plausible-looking output.
+`task-blocked` with a concrete reason and stop. For contradictory input specifically, also set
+`blockerClass: "contradictory-information"` and use `question` / `whatUnblocksMe` to name the
+conflicting instructions and what would resolve them. 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

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

@@ -10,21 +10,38 @@ compaction.
 
 {{HARNESS_CONTEXT}}
 
+{{AUTONOMOUS_OPERATION}}
+
 <session_context>
 This is a continuation turn — the brief, the contract, and your prior rounds are already in this
-conversation's history. If this session somehow lacks that prior context (a resumed thread that
-did not carry forward), re-read these on-disk files before acting — they are reachable via the
-mounted directories:
+conversation's history. The done-criteria in `<task_criteria>` below and the no-test-weakening rule
+in `<success_criteria>` below are restated every round regardless of what the conversation already
+carries, so a compacted or cold-resumed session is never left missing them. If this session lacks
+the REST of that prior context (a resumed thread that did not carry forward), re-read these on-disk
+files before acting — they are reachable via the mounted directories:
 
 - task contract — `{{CONTRACT_PATH}}`
 - sprint journal — `{{PROGRESS_FILE}}` (append-only history of every prior task-attempt)
 
-Read them only when the prior context is missing; when the conversation already carries the brief,
-proceed directly to the critique below.
+Read them only when the prior context is missing beyond what is restated below; when the
+conversation already carries the brief, proceed directly to the critique.
 </session_context>
 
+<task_criteria>
+The done-criteria this task is graded against:
+
+{{VERIFICATION_CRITERIA_SECTION}}
+
+When the block above is empty, no criteria were threaded into this round — treat the contract at
+`{{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.
+
 <prior_critique>{{PRIOR_CRITIQUE_SECTION}}</prior_critique>
 
 {{PRIOR_ATTEMPTS_SECTION}}
@@ -49,26 +66,47 @@ For the complete history — older than the excerpt above — read `{{PROGRESS_F
 {{DECISIONS_GUIDANCE}}
 
 <goal>
-Address every dimension the evaluator flagged in `<prior_critique>`, then 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 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, naming any
-remaining uncertainty and, when the change is risky, how to roll it back, 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 — 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. 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.
+Address every dimension the evaluator flagged in `<prior_critique>` above, then re-verify against
+`<task_criteria>` above.
 </goal>
 
+<success_criteria>
+
+- 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.
+- `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
+  criterion command passes.
+- No test has been removed, disabled, or weakened to reach a pass — fix the implementation, not
+  the test — except when a declared step explicitly changes the behaviour the test asserts.
+
+</success_criteria>
+
+## Protocol
+
+1. **Re-verify.** 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
+   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
+   every failing test/check name.
+
+   {{EVIDENCE_BOUND}}
+
+3. **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
+   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
+   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.
+
 {{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/plan/template.md

@@ -38,6 +38,51 @@ and search them to understand the codebase, but write nothing into them. The onl
 may write in this session is `signals.json` in your output directory.
 </session_topology>
 
+<inputs>
+
+## Sprint context
+
+<sprint_context>{{SPRINT_CONTEXT}}</sprint_context>
+
+## Approved tickets
+
+<approved_tickets>{{APPROVED_TICKETS}}</approved_tickets>
+
+## Selected repositories
+
+<repositories>{{REPOSITORIES}}</repositories>
+
+All paths above are fixed — repository selection is not part of this session. Every
+repository has equal weight; do not favour any one when assigning tasks.
+
+## Prior progress on this sprint
+
+`progress.md` at the sprint root records every prior task-attempt on this sprint
+chronologically. Read it before planning; honour prior decisions and avoid re-litigating
+them.
+
+<prior_progress>{{PRIOR_PROGRESS}}</prior_progress>
+
+If `<prior_progress>` is empty, no prior progress has been recorded on this sprint.
+
+<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>
+
+If `<existing_tasks>` is empty, this is a fresh plan — there is nothing to replace.
+
+</inputs>
+
 <constraints>
 - **Read-only on all repositories** — read and search repository files to understand
   existing patterns, but do not modify, create, or delete any file inside them. No
@@ -86,36 +131,15 @@ The `tasksJson` payload conforms to:
 {{SCHEMA}}
 ```
 
-Each task entry uses these fields:
+{{TASK_FIELDS}}
+
+Plan tasks additionally carry:
 
-- **`id`** — short string for `blockedBy` references (e.g. `"T1"`, `"api-shape"`).
-- **`name`** — imperative, short.
-- **`description`** — optional longer-form context.
-- **`projectPath`** — absolute path matching one of the repositories listed in
-  `<repositories>`.
 - **`ticketRef`** — the ticket UUID from `<approved_tickets>`. Required. A task that
   doesn't trace to an approved ticket is a planning error — surface it as a question
   instead. Some tickets also show an **External reference** line (e.g. `#123`, `!456`,
   `PROJ-7`); that value is informational only — always set `ticketRef` to the UUID, never
   the external reference.
-- **`steps`** — concrete implementation steps in order.
-- **`verificationCriteria`** — structured criteria the evaluator grades PASS / FAIL. Each
-  entry is an object: `{ id, assertion, check, command? }`.
-  - `id` is stable within the task (e.g. `"C1"`). The evaluator cites it verbatim.
-  - `assertion` is the human-readable check.
-  - `check` is either `"auto"` (run `command`) or `"manual"` (inspect code and cite a
-    specific location).
-  - `command` is REQUIRED when `check === "auto"` and MUST be omitted when
-    `check === "manual"`. Use the project's own commands — read the project's AI context
-    file or manifest for the exact verification command this repository expects.
-- **`blockedBy`** — `id`s of earlier tasks that must complete first.
-- **`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 ticket requires a zero-downtime schema change that the five
-  floor dimensions cannot score on their own. Cap: 2–3 per task; hard max 6.
 
 If you cannot produce a sound plan, emit the `task-plan` signal with `tasksJson` set to:
 
@@ -140,30 +164,12 @@ by a different AI agent using only the verification criteria and the codebase.
 - **Independence** — implementable without waiting on other tasks (unless declared via
   `blockedBy`).
 - **Pattern reference** — steps reference existing similar code the agent should follow.
-  </task_qualities>
-
-### Task Sizing
-
-The unit is one coherent feature or vertical slice — a change that can be picked up cold,
-implemented in a single session, and verified end-to-end against its criteria.
 
-**Do not split when:**
+</task_qualities>
 
-- A utility and its first caller would be separated — create-and-use is always one task, unless the utility already exists in the codebase or a prior task in this plan produces it.
-- A feature and its tests would be separated.
-- The same pattern applies across N call sites — it is one refactor, not N tasks.
-
-**Do split when:**
-
-- Two chunks are independent (different `projectPath`, or independent files with no shared
-  contract).
-- A clean, verifiable boundary exists partway through (e.g. schema + migration land first,
-  then consumer wiring — the schema is independently testable).
-- The change spans multiple repositories — one task per repo, connected via `blockedBy`.
+### Task Sizing
 
-**Soft ceiling, not a target:** if a task will touch more than ~10 files or ~500 lines of
-meaningful change AND a natural split point exists, split it. No natural split point? Keep
-it whole.
+{{TASK_SIZING}}
 
 Too granular — should be one task, not three:
 
@@ -179,17 +185,6 @@ Right size:
 ### Anti-Patterns
 
 - Separate tasks for "create utility" and "integrate utility" — merge create+use into one.
-- One task per file modification — group by logical change, not by file.
-- `blockedBy` chains for trivial reasons — false chains obscure the real dependency
-  structure.
-- Micro-refactoring tasks (add directive, remove import) — fold into the task that needs
-  them.
-- **Ending steps with "run the verification commands" or "run all the checks."** Verification
-  belongs in `verificationCriteria` — the harness and the evaluator execute it. A final step
-  that re-runs the full suite only duplicates the post-task gate and inflates generator
-  cost. Exception: a step MAY run a specific check when a later step depends on its output
-  (e.g. "run the migration dry-run and confirm the schema diff before writing the rollback
-  script").
 
 ### Dependency Graph
 
@@ -297,51 +292,6 @@ Good — precise steps with file paths and pattern references:
 }
 ```
 
-<inputs>
-
-## Sprint context
-
-<sprint_context>{{SPRINT_CONTEXT}}</sprint_context>
-
-## Approved tickets
-
-<approved_tickets>{{APPROVED_TICKETS}}</approved_tickets>
-
-## Selected repositories
-
-<repositories>{{REPOSITORIES}}</repositories>
-
-All paths above are fixed — repository selection is not part of this session. Every
-repository has equal weight; do not favour any one when assigning tasks.
-
-## Prior progress on this sprint
-
-`progress.md` at the sprint root records every prior task-attempt on this sprint
-chronologically. Read it before planning; honour prior decisions and avoid re-litigating
-them.
-
-<prior_progress>{{PRIOR_PROGRESS}}</prior_progress>
-
-If `<prior_progress>` is empty, no prior progress has been recorded on this sprint.
-
-<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>
-
-If `<existing_tasks>` is empty, this is a fresh plan — there is nothing to replace.
-
-</inputs>
-
 ## Protocol
 
 Before producing any output, map each ticket onto repositories, identify natural task boundaries,
@@ -433,7 +383,7 @@ re-present the full plan and dependency graph, then re-ask the same structured a
 question. Iterate until the user picks "Approved, write it". Only after that approval
 proceed to Step 5.
 
-### Step 5 — Validate before output
+**Step 5 — Validate before output.**
 
 {{VALIDATION_CHECKLIST}}
 

package/dist/prompts/readiness/template.md

@@ -9,7 +9,8 @@ install, or otherwise mutating commands. The harness owns execution.
 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
 optional `setup-skill-proposal`, `verify-skill-proposal`, `skill-suggestions`, and `note` signals where
-warranted. Write all signals to the `signals.json` path described in `<output_contract>`.
+warranted. Write all signals to the `signals.json` path described in the Output contract section at the
+bottom of this prompt.
 </goal>
 
 <success_criteria>
@@ -55,12 +56,9 @@ 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>` below — the target and
+**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.
 
-**Structure caps.** Exactly one H1; at most 7 H2 sections; no H4 or deeper headings. Prefer bullets and
-short sentences.
-
 **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`)
 for genuinely surprising rules — overuse erodes their meaning.
@@ -94,10 +92,6 @@ search the repository for file names or content patterns, and run read-only insp
 nothing except `signals.json`; never run build, install, or otherwise mutating commands.
 </capabilities>
 
-<output_contract>
-{{OUTPUT_CONTRACT_SECTION}}
-</output_contract>
-
 ## Recommended context-file sections
 
 Include only sections that carry signal for this specific repo:
@@ -143,26 +137,31 @@ comes first, byte-for-byte. Your additions go as new H2 sections at the bottom
 
 ### Phase 4 — Output
 
-Write `signals.json` to the path described in `<output_contract>` with the signals listed there. Do not
-emit prose commentary outside the signal file.
+Write `signals.json` to the path named in the Output contract section below, with the signals described
+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.
 
-## Signal summary
-
-1. `agents-md-proposal` — REQUIRED. `tag` MUST equal `"{{WIRE_TAG}}"`. `content` is the project context
-   file body.
-2. `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.
-3. `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.
-4. `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.
-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.
+<output_contract>
+{{OUTPUT_CONTRACT_SECTION}}
+
+### Signal semantics
+
+- `agents-md-proposal` — REQUIRED. `tag` MUST equal `"{{WIRE_TAG}}"`. `content` is the project context
+  file body.
+- `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
+  characterised.
+- `learning` — optional. A durable insight worth recording beyond this session (e.g. a
+  non-obvious convention the inspection uncovered), in its `text` field.
+
+</output_contract>

package/dist/prompts/reproduce/template.md

@@ -100,9 +100,9 @@ test file following the project's own conventions.
 
 Run the new test in isolation using the project's own test runner. Confirm it fails, and confirm the
 failure is the reported defect — not a setup, import, or fixture error in the test itself. If it passes,
-or fails for the wrong reason, revise the test until it fails for the right one. Record the exact command
-and a bounded excerpt of the failing output — roughly the last 50 lines is enough to show the decisive
-failure.
+or fails for the wrong reason, revise the test until it fails for the right one. Record the exact command.
+
+{{EVIDENCE_BOUND}}
 
 ### Phase 4 — Report
 

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

@@ -1,6 +1,6 @@
 ---
 name: ralphctl-alignment
-description: Cross-phase skill — establish a shared understanding of what will and will not be done before producing output. Restate the input back to the user, surface assumptions, name non-goals, and agree before you write. For an input that is still a raw, unshaped idea needing multiple candidate directions before one is chosen, run the ralphctl-idea-refinement skill first when it is installed in this session; alignment then confirms whichever direction comes out of it.
+description: Cross-phase skill — establish a shared understanding of what will and will not be done before producing output. Restates the input back to the user, surfaces assumptions, names non-goals, and reaches agreement before drafting output. Use before writing criteria, tasks, or code whenever the input's scope has not yet been confirmed. For an input that is still a raw, unshaped idea needing multiple candidate directions before one is chosen, run the ralphctl-idea-refinement skill first when it is installed in this session; alignment then confirms whichever direction comes out of it.
 ---
 
 # Alignment
@@ -21,8 +21,9 @@ the whole change.
 - **Plan** — confirm the planner's read of the requirements before generating tasks. Repo selection, scope
   boundaries, and dependency assumptions all need to land before task decomposition starts.
 - **Execute** — re-read the task spec's verification criteria before writing code. The contract is the
-  arbiter; if your read of it differs from what's written, surface the conflict in a `<note>` rather than
-  guessing.
+  arbiter; if your read of it differs from what's written, surface the conflict rather than guessing —
+  write a `note` signal in `signals.json` when the prompt's output-contract section lists it, otherwise
+  fold the conflict into the required signal's own fields.
 
 ## What to do
 

package/dist/skills/ralphctl-cherny-workflow/SKILL.md

@@ -31,7 +31,7 @@ demonstrated or rolled back while it is still small.
 - Before each step, know its check: the test that should pass, the command that should exit cleanly, the behaviour that should be observable. A step without a check is not ready to execute.
 - Run the check immediately after the step — never accumulate several unverified steps, because a late failure then points at all of them at once.
 - Prefer the narrowest check that can falsify the step (one test file, one build target, one focused run) over broad suites; breadth comes at the end, and the harness owns the final post-task verify gate.
-- When no automated check exists for a step, create the smallest one that would fail if the step were wrong — or state explicitly in a `<note>` signal that the step is unverified and why.
+- When no automated check exists for a step, create the smallest one that would fail if the step were wrong — or state explicitly that the step is unverified and why, as a `note` signal in `signals.json` when the prompt's output-contract section lists it, otherwise inside the required signal's own fields.
 
 ## Small verified increments
 
@@ -41,7 +41,7 @@ demonstrated or rolled back while it is still small.
 
 ## Compounding corrections
 
-- When you discover a project-specific gotcha — a convention that contradicted your instinct, a command that behaves unexpectedly, a fix for a recurring failure — record it as a `<learning>` signal so it persists beyond this session.
+- When you discover a project-specific gotcha — a convention that contradicted your instinct, a command that behaves unexpectedly, a fix for a recurring failure — record it so it persists beyond this session: write a `learning` signal in `signals.json` when the prompt's output-contract section lists it, otherwise fold it into the required signal's own fields.
 - The habit mirrors how Cherny's team maintains their agent-facing project docs: every observed mistake becomes a written correction, so the same steering is never needed twice.
 - Record the correction at the moment you learn it — deferred notes don't get written; the exception is mid-verification, where finishing the check comes first.
 
@@ -58,4 +58,4 @@ demonstrated or rolled back while it is still small.
 - [ ] The executed steps match the settled plan — or the plan was explicitly revised along the way.
 - [ ] Every step's check ran and passed at the time the step was made.
 - [ ] The final diff reads as a sequence of intentional increments, with nothing unexplained.
-- [ ] Any durable gotcha discovered this session was recorded as a `<learning>` signal.
+- [ ] Any durable gotcha discovered this session was recorded per the Compounding Corrections guidance above.