ralphctl 0.25.0 → 0.27.0

package/dist/prompts/select-candidate/template.md

@@ -35,11 +35,11 @@ be a correct, complete, maintainable solution. Write exactly one `candidate-sele
 </task_specification>
 
 <candidate_1>
-{{CANDIDATE_A_SUMMARY}}
+{{CANDIDATE_1_SUMMARY}}
 </candidate_1>
 
 <candidate_2>
-{{CANDIDATE_B_SUMMARY}}
+{{CANDIDATE_2_SUMMARY}}
 </candidate_2>
 
 <constraints>
@@ -47,11 +47,18 @@ be a correct, complete, maintainable solution. Write exactly one `candidate-sele
 - Judge only from `<candidate_1>` and `<candidate_2>` above — do not attempt to read either candidate's
   actual diff, branch, or working tree, even if you have the technical means to. The two summaries are
   the entire evidence base by design.
-- Weigh a cited verification outcome (a command that was run, a test that passed or failed, an endpoint
-  that was exercised) above an unverified narrative claim of completion.
-- A summary that reports its own verification as failed or partial is not automatically the loser — a
-  candidate that honestly reports a partial result and is closer to the acceptance criteria can still beat
-  one that claims full success without evidence.
+- Each summary has the same fields. `Verify outcome` and `Diff` are measured by the harness: the outcome is
+  the result of the project's verify script on that candidate's tree (`success`, `failed`, `skipped` when no
+  verify script is configured, or `spawn-error` when the script could not start), followed in parentheses by
+  an attribution against the pre-task baseline — `clean` (passed and was passing before), `regressed`
+  (passed before, fails now), `baseline-broken` (was already failing and still is), `fixed-baseline` (was
+  failing, now passes). A green script shows existing checks pass, not that the task's criteria are met.
+  `Proposed commit`, `Changes claimed` (the last 5) and `Notes` (the last 3) are the candidate's own words.
+- Weigh a measured verify outcome, and a command or test result a candidate cites, above
+  an unverified narrative claim of completion.
+- A candidate whose verify outcome failed is not automatically the loser — one that failed on a baseline
+  problem, or that is closer to the acceptance criteria, can still beat one that claims full success
+  without evidence.
 - When both summaries are similarly strong on verification, prefer the one whose changed-files list stays
   closest to the task's declared scope.
 - When the two are genuinely indistinguishable on the evidence given, declare a tie rather than inventing
@@ -70,9 +77,9 @@ evidence base. The only file you write is `signals.json`, to the output director
 
 ### Phase 1 — Read both summaries
 
-Read `<task_specification>`, then both candidate summaries in full before forming any preliminary
-judgment. Note, for each candidate: what it attempted, what its verification outcome claims, which files
-it touched, and any other notable signal worth weighing (warnings, notes, learnings).
+Read `<task_specification>` and both candidate summaries in full before forming any
+judgment, weighing for each candidate what it attempted, its verify outcome, which files it touched, and
+its notes and claimed changes.
 
 ### Phase 2 — Compare against the task
 

package/dist/skills/ralphctl-api-and-interface-design/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ralphctl-api-and-interface-design
+description: Interface-design discipline for any surface one piece of code exposes to another — network endpoints, library exports, module boundaries, CLI flags and exit codes, file and message formats. Contract first, one consistent error model, validation at the trust boundary, additive change over breaking change, and every observable behaviour treated as a commitment (Hyrum's law). Use when designing a new interface, changing an existing one, or planning work that crosses a module or service boundary.
+license: MIT
+---
+
+# API and Interface Design
+
+> Adapted from [addyosmani/agent-skills — "API and Interface Design"](https://github.com/addyosmani/agent-skills)
+> (MIT). Adapted for ralphctl's harness contract.
+
+Good interfaces make the right use easy and the wrong use hard. This applies to every surface where one
+piece of code talks to another: a network API, a library's exports, a module boundary inside one
+repository, a CLI's flags and exit codes, a file or message format. The guidance is language-neutral —
+express it in the project's own idiom and with its own typing or schema mechanism.
+
+## When this applies
+
+- **Plan** — when a ticket adds or changes an interface, make the contract its own task or the first step
+  of one, and put its shape in the verification criteria: inputs, outputs, error cases, and what existing
+  consumers must keep seeing. Name who consumes the interface today.
+- **Execute** — define the contract before the body, and check every change to an existing interface
+  against its current consumers before making it. When reviewing, a breaking change the task did not ask
+  for is a finding even when the new code is correct.
+
+## Every observable behaviour is a commitment
+
+Hyrum's law: with enough consumers, everything observable gets depended on — field order, error message
+text, default values, timing, undocumented quirks. So:
+
+- Expose deliberately. Anything a caller can observe is something you may have to keep.
+- Keep implementation details out of the interface — storage ids, internal layout, stack traces in errors.
+- Tests are necessary but not sufficient: a "safe" change still breaks a consumer that relies on behaviour
+  no test pins. Search for real consumers before changing what they can see.
+
+## Core principles
+
+### Contract first
+
+Write the interface — names, input and output shapes, error cases, invariants — before the
+implementation. The contract is the spec; the body follows it. Separate what a caller provides from what
+the system returns: generated fields (ids, timestamps) appear only in the output shape.
+
+### One error model, everywhere
+
+Pick one way to report failure and use it on every operation: the same envelope or error type, a stable
+machine-readable code, a human-readable message, optional detail. Map failure classes consistently —
+invalid input, not authenticated, not permitted, not found, conflict, internal. When some operations
+throw, others return an empty value, and others return an error object, the caller cannot predict
+behaviour. Internal failures never expose internals.
+
+### Validate at the boundary, trust inside
+
+Validate where untrusted data enters: request handlers, argument parsing, config and environment loading,
+responses from third-party services, files the code did not write. After validation, internal code
+trusts the types and does not re-validate. Third-party responses are untrusted — check shape and content
+before using them in logic, rendering, or decisions. For the full trust-boundary treatment, see
+ralphctl-security-and-hardening when installed.
+
+### Prefer addition over modification
+
+- Add optional fields, new operations, and new variants a consumer can ignore.
+- Do not change a field's type, remove or rename a field, or narrow what was previously accepted.
+- When a breaking change is unavoidable, treat it as a migration (ralphctl-deprecation-and-migration when
+  installed), not an in-place edit.
+- Extend one live version rather than forking a second one consumers must choose between.
+
+### Predictable names and shapes
+
+Follow the conventions the project already uses for this kind of surface, identically across every
+operation: casing, resource naming, boolean prefixes, time and id formats. Model variants as an explicit
+tagged union or discriminated record rather than a bag of optional fields. Where the language allows,
+give each kind of id its own type so one cannot be passed for another. List operations paginate (a limit
+plus a stable order or cursor) from the start; partial updates change only the fields provided.
+
+### Retry safety
+
+A state-changing operation either honours an idempotency key or is documented as unsafe to retry. When
+it honours one:
+
+- Derive the key from the intent (client-supplied, or an immutable id of the thing being done), never per
+  attempt — a fresh random value or a timestamp makes every retry a new effect.
+- Claim the key atomically — a uniqueness constraint or a single compare-and-set. A check followed by an
+  act is a race.
+- Reject the same key arriving with a different payload instead of replaying the first response.
+- Decide on purpose what an in-flight duplicate gets: rejected, a bounded wait, or a pending status.
+- A timeout is a third outcome — unknown. Record the intent before the side effect so it can be resolved.
+- Keep keys longer than the longest path that can re-deliver the same request.
+
+## Common rationalisations
+
+| Rationalisation                            | Reality                                                                                   |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| "Nobody uses that undocumented behaviour"  | If it is observable, someone depends on it. Treat it as a commitment.                     |
+| "We'll pin the contract down later"        | The contract is the documentation. Define it first; the implementation follows it.        |
+| "Internal interfaces don't need contracts" | Internal consumers are still consumers. Contracts are what let them change independently. |
+| "We don't need pagination yet"             | Adding it once a list has grown is a breaking change.                                     |
+| "Accepting the idempotency key is enough"  | Accepting it tells clients retries are safe; storing it against the result makes it so.   |
+
+## Red flags
+
+- An operation that returns different shapes depending on conditions.
+- Inconsistent error formats across one interface.
+- Validation scattered through internal code instead of at the boundary.
+- A field changed, renamed, or removed in place.
+- A list operation without pagination.
+- Third-party responses used without validation.
+- A lookup-then-insert idempotency check, or a key regenerated on every attempt.
+
+## Self-check
+
+- [ ] Every operation has explicit input and output shapes and named error cases.
+- [ ] One error model across the whole interface.
+- [ ] Validation happens at the boundary only.
+- [ ] Changes to an existing interface are additive, or handled as a migration.
+- [ ] Naming matches the conventions the project already uses.
+- [ ] The retry behaviour of every state-changing operation is a deliberate choice.

package/dist/skills/ralphctl-code-review-and-quality/SKILL.md

@@ -7,7 +7,9 @@ license: MIT
 # Code Review and Quality
 
 > Concept from [addyosmani/agent-skills — "Code Review and Quality"](https://github.com/addyosmani/agent-skills),
-> MIT License. Adapted for ralphctl's evaluator role and review flow.
+> MIT License. Adapted for ralphctl's evaluator role and review flow. The smell baseline draws on
+> [mattpocock/skills](https://github.com/mattpocock/skills) and the concrete-case and expected-load rules on
+> [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) (both MIT).
 
 One-shot generation looks fast and is slow. Catching a correctness, architecture, or security problem at the
 seam between two changes is cheap; catching it at the end of a 200-line diff — or after the post-task gate
@@ -57,6 +59,10 @@ Can another engineer understand this code without the author explaining it?
 - Could this be done in fewer lines? (1 000 lines where 100 suffice is a failure.)
 - Are abstractions earning their complexity? Do not generalise until the third use case.
 - Are there dead code artefacts: no-op variables, backwards-compat shims, or `// removed` comments?
+- **Is a new conditional bolted onto an unrelated flow?** That is a design smell, not a nit — push the logic
+  into its own helper, state, or policy instead of tangling an existing path.
+- **Do repeated conditionals on the same shape appear?** They signal a missing model or dispatcher. A
+  "temporary" branch is usually permanent debt.
 
 ### 3. Architecture
 
@@ -67,6 +73,16 @@ Does the change fit the system's design?
 - Is there code duplication that should be shared?
 - Are dependencies flowing in the right direction — no circular dependencies?
 - Is the abstraction level appropriate — not over-engineered, not too coupled?
+- **Does this refactor reduce complexity or just relocate it?** Count the concepts a reader must hold to
+  follow the change. If a "cleaner" version leaves that count unchanged, it is not cleaner — prefer the
+  restructuring that makes whole branches, modes, or layers disappear over one that re-centralises the same
+  logic. Prefer deleting an abstraction to polishing it.
+- **Is feature-specific logic leaking into a shared or general-purpose module?** Keep logic in its owning
+  layer, reuse the existing canonical helper instead of a near-duplicate, and do not normalise architectural
+  drift.
+- **Are type boundaries explicit?** Question gratuitous untyped escape hatches, optional fields, casts, and
+  silent fallbacks that paper over an unclear invariant — making the boundary explicit often makes the
+  surrounding control flow simpler.
 
 ### 4. Security
 
@@ -91,6 +107,47 @@ Does the change introduce performance problems?
 - Any missing pagination on list endpoints?
 - Any large objects created in hot paths?
 
+Judge scale against the expected load, found in the repository (README, deploy configuration): a script one
+person runs is not a service under concurrent traffic. Check-then-write races, work every process repeats,
+collections that only grow, and per-process state that must be shared are findings at the load that
+triggers them — say which load you assumed.
+
+## Structural Remedies
+
+When you flag a structural problem, propose the move — not just the problem. A finding that only says "this
+is complex" leaves the generator or author guessing. Reach for a named restructuring:
+
+- **Replace a chain of conditionals** with a typed model or an explicit dispatcher.
+- **Collapse duplicate branches** into a single clearer flow.
+- **Separate orchestration from business logic** so each reads on its own.
+- **Move feature-specific logic** out of a shared module into the module that owns the concept.
+- **Reuse the canonical helper** instead of a bespoke near-duplicate.
+- **Make a type boundary explicit** so downstream branching disappears.
+- **Delete a pass-through wrapper** that adds indirection without clarifying the API.
+- **Extract a helper, or split a large file** into focused modules.
+
+Prefer the remedy that removes moving pieces over one that spreads the same complexity around.
+
+## Smell Baseline
+
+On top of whatever the project documents, a fixed set of code smells (Fowler, _Refactoring_) applies even
+where a repository documents nothing. Each is a labelled judgement call ("possible Feature Envy") at Minor or
+Nit, never a hard violation. A documented project standard that endorses the pattern overrides the smell, and
+anything tooling already enforces is skipped.
+
+- **Mysterious Name** — the name does not say what it does or holds → rename; no honest name means murky design.
+- **Duplicated Code** — the same logic shape in several hunks or files → extract it once.
+- **Feature Envy** — a function that works on another module's data more than its own → move it there.
+- **Data Clumps** — the same few values always travel together → give them one type.
+- **Primitive Obsession** — a string or number standing in for a domain concept → give the concept a type.
+- **Repeated Switches** — the same branching on the same type in several places → one dispatch both share.
+- **Shotgun Surgery** — one logical change forces scattered edits → gather what changes together.
+- **Divergent Change** — one module edited for several unrelated reasons → split by reason.
+- **Speculative Generality** — hooks, parameters, or abstractions for needs nobody has → delete them.
+- **Message Chains** — callers walking a long chain of navigation → hide the walk behind one call.
+- **Middle Man** — a layer that mostly delegates → call the real target directly.
+- **Refused Bequest** — an implementer ignoring most of what it inherits → compose instead of inheriting.
+
 ## Severity Vocabulary
 
 Label every finding with its severity so the generator or author knows what is required versus optional:
@@ -105,6 +162,12 @@ Label every finding with its severity so the generator or author knows what is r
 Using explicit severity prevents treating all findings as equally urgent — a nit should not consume the
 same budget as a Critical.
 
+**Presumptive structural findings.** Raise each of these as at least Minor and propose the simpler design;
+escalate to Major only when the change actively makes the structure worse: a refactor that relocates
+complexity instead of reducing it; a change that pushes a file past a healthy size with no decomposition;
+feature logic added to a shared module; a near-duplicate of an existing canonical helper; a silent fallback
+that hides an unclear invariant.
+
 ## Review Process
 
 ### Step 1: Understand the Context
@@ -124,6 +187,12 @@ Tests reveal intent and coverage:
 - Are edge cases covered?
 - Would the tests catch a regression if the code changed?
 
+Answer the last question by experiment, not by reading, when your session may edit the working tree (the
+generator): invert one condition the change adds (drop a negation, swap `&&` for `||`), run the focused
+test, then restore the file from a copy. A mutation that stays green is a finding — name the missing test
+case. When your session is read-only (the evaluator), reason through the same inversion and name the test
+case that would be missing as a finding.
+
 ### Step 3: Review the Implementation
 
 Walk through the code with the five axes in mind. For each file changed:
@@ -153,6 +222,11 @@ section names the exact file and shape):
   the severity of each finding) in the evaluator's output as directed by the task prompt — not in a
   separate file or report, and not as a `decision` signal.
 
+**Lead with what matters.** Order findings by leverage: correctness and security first, then structural
+regressions and missed simplifications, then everything else. Do not bury a real issue under cosmetic nits —
+a few high-conviction findings beat a long list. If you have one structural problem and ten nits, the
+structural problem _is_ the review.
+
 Do not write a standalone review report to a file. The harness's signal pipeline and the evaluator's
 structured output are the authoritative record.
 
@@ -178,6 +252,11 @@ Small, focused changes are easier to review, faster to evaluate, and safer to fo
 ~1000 lines changed  → Too large. Split it.
 ```
 
+**Watch file size, not just diff size.** A small diff can still push a file past a healthy boundary —
+around 1 000 _total_ lines in a single file (distinct from the ~1 000 _changed_-lines threshold above) is a
+common inspection signal, not a hard cap. When a change materially grows an already-large file, ask whether
+to extract helpers, subcomponents, or modules _first_, before piling more on. Decompose, then add.
+
 **What counts as "one change":** A single self-contained modification that addresses one thing, includes
 related tests, and keeps the system functional after submission.
 
@@ -208,11 +287,30 @@ Before adding any dependency:
 
 Prefer the standard library and existing utilities over new dependencies. Every dependency is a liability.
 
+**Upgrading an existing dependency** is a code change like any other, and the riskiest upgrades are bulk
+"bump deps" changes. Review them with the same discipline:
+
+- **Read the changelog, not just the version number.** Semver is a promise the maintainer may not have
+  kept — a "patch" can carry a behavioural change. For a major bump, read the migration notes and find what
+  breaks.
+- **One dependency per change** (or a small related group). When a bulk bump breaks the build, you lose which
+  package did it; a single-package change makes the cause obvious and the revert clean.
+- **Let the tests decide.** The upgrade is verified by a green check before _and_ after, not by "it
+  installed." If coverage around the dependency's behaviour is thin, that gap is the real finding — add a
+  test first.
+- **Mind the transitive graph.** Review the lockfile diff, not just the dependency manifest; a single direct
+  bump can pull in dozens of indirect changes.
+- **Keep the lockfile honest.** Keep it in the change, review its diff, and never hand-edit it — the lockfile
+  is what actually pins what ships.
+
 ## Honesty in Review
 
 Whether reviewing code you wrote, code a generator produced, or a human's change:
 
 - Do not rubber-stamp. "Looks fine" without evidence of review helps no one.
+- Back every correctness, security, or scale finding with a concrete case — this input or situation leads to
+  this wrong result — and re-read the lines to confirm it: the caller exists, the value can really be empty,
+  the code really is unused. No case, no finding. Structural findings follow the presumptive rules above.
 - Do not soften real issues. "This might be a minor concern" when it is a bug that will hit production is
   misleading.
 - Quantify problems when possible. "This N+1 query will add ~50 ms per item in the list" is better than
@@ -224,13 +322,17 @@ Whether reviewing code you wrote, code a generator produced, or a human's change
 
 ## Common Rationalisations
 
-| Rationalisation                       | Reality                                                                                                                    |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| "It works, that's good enough"        | Working code that is unreadable, insecure, or architecturally wrong creates debt that compounds.                           |
-| "I wrote it, so I know it is correct" | Authors are blind to their own assumptions.                                                                                |
-| "We will clean it up later"           | Later rarely comes. The review is the quality gate — use it.                                                               |
-| "AI-generated code is probably fine"  | AI code needs more scrutiny, not less. It is confident and plausible, even when wrong.                                     |
-| "The tests pass, so it is good"       | Tests are necessary but not sufficient. They do not catch architecture problems, security issues, or readability concerns. |
+| Rationalisation                            | Reality                                                                                                                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "It works, that's good enough"             | Working code that is unreadable, insecure, or architecturally wrong creates debt that compounds.                                                                                |
+| "I wrote it, so I know it is correct"      | Authors are blind to their own assumptions.                                                                                                                                     |
+| "We will clean it up later"                | Later rarely comes. The review is the quality gate — use it.                                                                                                                    |
+| "AI-generated code is probably fine"       | AI code needs more scrutiny, not less. It is confident and plausible, even when wrong.                                                                                          |
+| "The tests pass, so it is good"            | Tests are necessary but not sufficient. They do not catch architecture problems, security issues, or readability concerns.                                                      |
+| "The refactor makes it cleaner"            | Relocating complexity is not reducing it. If the reader still holds the same number of concepts, the structure did not improve — look for the version where branches disappear. |
+| "It is only a small addition to this file" | Small diffs still push files past a healthy size and bolt branches onto unrelated flows. Judge the resulting structure, not the diff size.                                      |
+| "It is just a version bump"                | A bump is a behaviour change you did not write. Read the changelog; semver does not guarantee no breakage.                                                                      |
+| "Upgrade everything at once to save time"  | A bulk bump that breaks the build hides which package did it. One dependency per change keeps the cause and the revert clean.                                                   |
 
 ## Review Checklist
 
@@ -243,6 +345,9 @@ Before signalling completion or a passing evaluator verdict, run through:
 - [ ] Names are clear and consistent with project conventions.
 - [ ] No unnecessary complexity.
 - [ ] Follows existing architectural patterns.
+- [ ] Refactors reduce complexity rather than relocate it.
+- [ ] No feature logic in shared modules; touched files stay within a healthy size.
+- [ ] Dependency upgrades (if any) were checked against their changelog and the lockfile diff.
 - [ ] No secrets in code; input validated at boundaries.
 - [ ] No N+1 patterns or unbounded operations.
 - [ ] Findings surfaced per Step 4's signal guidance, with severity labels intact.
@@ -255,3 +360,9 @@ Before signalling completion or a passing evaluator verdict, run through:
 - No regression tests alongside a bug fix.
 - Review comments without severity labels — makes it unclear what is required versus optional.
 - Accepting "I will fix it later" — it rarely happens.
+- A refactor that moves code around without reducing the number of concepts a reader must hold.
+- A change that grows an already-large file instead of decomposing it.
+- New conditionals scattered into unrelated code paths (a missing abstraction).
+- A bespoke helper that duplicates an existing canonical one, or feature logic placed in a shared module.
+- A bulk dependency bump with no changelog review and no per-package isolation.
+- A lockfile change that is hand-edited or accepted without reviewing its diff.

package/dist/skills/ralphctl-code-simplification/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ralphctl-code-simplification
+description: Behaviour-preserving simplification of existing code — understand why the code exists before changing it, then reduce nesting, unclear names, duplication, dead code, and needless indirection one step at a time with the existing tests unchanged and green after each. Use when a task asks to refactor or clean up working code, or when code you just made work is heavier than it needs to be; for keeping a new change small from the start, see ralphctl-surgical-simplicity and ralphctl-ponytail when installed.
+license: MIT
+---
+
+# Code Simplification
+
+> Adapted from [addyosmani/agent-skills — "Code Simplification"](https://github.com/addyosmani/agent-skills)
+> (MIT). Adapted for ralphctl's harness contract.
+
+Simplify by reducing complexity while preserving behaviour exactly. The goal is not fewer lines — it is
+code a new reader understands faster than the original. Every simplification passes one test: would
+someone new to this code follow the result more easily?
+
+## When this applies
+
+- **Execute** — when the task asks for a refactor or cleanup, and after a change works, on the code that
+  change touched. Simplification outside the task's scope is a finding to surface, not an edit to make —
+  record it in a `note` signal when the prompt's output-contract section lists it; otherwise fold it into
+  the required signal's own fields.
+
+**When not to use:** the code is already clear; you do not yet understand what it does; the simpler form
+is measurably slower on a hot path; the module is about to be replaced.
+
+## Principles
+
+1. **Preserve behaviour exactly.** Same outputs for every input, same errors, same side effects and their
+   order. The existing tests pass without modification. If you are not sure a change preserves
+   behaviour, do not make it.
+2. **Follow the project's conventions.** Read the project's context file when present and the
+   neighbouring code; simplification that breaks local consistency is churn.
+3. **Clarity over cleverness.** A chain of nested conditional expressions becomes early returns or a
+   lookup; a dense chained transform with inline logic becomes a named intermediate step.
+4. **Keep the balance.** Do not inline a helper that gives a concept its name, merge unrelated logic into
+   one function, or remove an abstraction that exists for testability. Line count is not the measure.
+5. **Scope to what changed.** Default to the code the task touched.
+
+## The process
+
+### 1. Understand before touching (Chesterton's fence)
+
+Before changing or removing anything, know why it exists: its responsibility, its callers and callees,
+its edge cases and error paths, the tests that pin its behaviour, and why it might have been written this
+way (a performance constraint, a platform quirk, history visible in `git log` or `git blame`). If you
+cannot answer these, read more first.
+
+### 2. Find concrete opportunities
+
+| Pattern                              | Simplification                                        |
+| ------------------------------------ | ----------------------------------------------------- |
+| Nesting three or more levels deep    | Guard clauses or an extracted, well-named condition   |
+| A long function doing several jobs   | Split by job, never by line count                     |
+| Boolean flag parameters              | Separate functions, or a named options value          |
+| The same condition in several places | One named predicate                                   |
+| Generic or misleading names          | Names that describe the content or the real behaviour |
+| A comment explaining _what_          | Delete it; keep comments that explain _why_           |
+| Duplicated logic                     | One shared function                                   |
+| Dead code                            | Remove it, after confirming nothing reaches it        |
+| A wrapper that only forwards         | Call the underlying function directly                 |
+| An abstraction with one variant      | The direct approach                                   |
+
+### 3. Apply one change at a time
+
+Make one simplification, run the focused tests, and continue only when they are green; when they fail,
+undo that step and reconsider. Never batch several simplifications into one untested change — when
+something breaks, you need to know which one did it. Keep refactoring and behaviour change apart: a
+refactor task adds no behaviour, and a feature task does not absorb a broad refactor. For a change
+touching many sites, prefer a mechanical transform (a structured search-and-replace or a codemod the
+project already uses) over hand edits.
+
+### 4. Judge the whole
+
+Compare before and after: is the result genuinely easier to follow, consistent with the codebase, and a
+clean reviewable diff? If not, undo it. Not every attempt succeeds.
+
+## Common rationalisations
+
+| Rationalisation                          | Reality                                                                           |
+| ---------------------------------------- | --------------------------------------------------------------------------------- |
+| "Fewer lines is always simpler"          | A one-line nested conditional is not simpler than five readable lines.            |
+| "I'll quickly tidy this unrelated code"  | Unscoped cleanup inflates the diff and risks regressions you did not intend.      |
+| "This abstraction might be useful later" | Speculative abstractions are complexity without value. Remove it; re-add on need. |
+| "The tests needed a small tweak"         | A simplification that needs test changes probably changed behaviour.              |
+
+## Red flags
+
+- Tests modified to make a "simplification" pass.
+- A "simplified" version that is longer or harder to follow.
+- Renames that follow your preference rather than the project's conventions.
+- Error handling removed because it "looked noisy".
+- Simplifying code you do not fully understand.
+
+## Self-check
+
+- [ ] The existing tests pass without modification.
+- [ ] No error handling was removed or weakened.
+- [ ] The result follows the project's conventions.
+- [ ] No dead code was left behind (unused imports, unreachable branches).
+- [ ] The diff stays inside the task's scope.

package/dist/skills/ralphctl-codebase-design/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ralphctl-codebase-design
+description: Shared vocabulary and tests for module design — deep modules (much behaviour behind a small interface), seams placed where behaviour actually varies, the deletion test for pass-through layers, and the interface as the test surface. Use when planning module boundaries, deciding where a seam or abstraction belongs, judging whether a layer earns its keep, or making code easier to test through its interface.
+license: MIT
+---
+
+# Codebase Design
+
+> Adapted from [mattpocock/skills — "Codebase Design"](https://github.com/mattpocock/skills) (MIT).
+> Adapted for ralphctl's harness contract.
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable
+through that interface. The aim is leverage for callers, locality for maintainers, and testability for
+everyone. Reason with the vocabulary below; in code and in signals, keep the project's own terms when it
+has established ones.
+
+## When this applies
+
+- **Plan** — when splitting work, prefer tasks that deepen one module behind a small interface over tasks
+  that spread one concept across several shallow ones. When a task introduces a seam, name it in the
+  steps along with what varies across it.
+- **Execute** — whenever you add a module, an interface, or an abstraction. When reviewing, apply the
+  deletion test and the one-adapter rule below to every new layer.
+
+## Vocabulary
+
+- **Module** — anything with an interface and an implementation, at any scale: a function, a type, a
+  package, a slice spanning several layers.
+- **Interface** — everything a caller must know to use the module correctly: the type signature, plus its
+  invariants, ordering constraints, error modes, required configuration, and performance characteristics.
+- **Implementation** — the code inside the module.
+- **Depth** — leverage at the interface: how much behaviour a caller or test can exercise per unit of
+  interface it has to learn. **Deep** when much sits behind little; **shallow** when the interface is
+  nearly as complex as what it hides.
+- **Seam** (Michael Feathers) — a place where behaviour can be altered without editing in that place; the
+  location where a module's interface lives. Where to put the seam is its own decision.
+- **Adapter** — a concrete thing that satisfies an interface at a seam. It names a role, not a size.
+- **Leverage** — what callers gain from depth: more capability per thing they learn.
+- **Locality** — what maintainers gain from depth: change, bugs, and knowledge concentrated in one place.
+  Fix once, fixed everywhere.
+
+## Principles
+
+- **Depth is a property of the interface.** A deep module can be built from small, swappable internal
+  parts; they are just not part of its interface. It may have internal seams for its own tests as well as
+  the external seam callers use.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If
+  the complexity reappears across many callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. Needing to test past the
+  interface means the module is the wrong shape.
+- **One adapter is a hypothetical seam; two adapters is a real one.** Introduce a seam only where
+  something actually varies across it — a second implementation, or a test fake standing in for slow or
+  non-deterministic infrastructure.
+
+When designing an interface, ask: can it have fewer operations, simpler parameters, more hidden inside?
+Before committing to one shape, sketch two or three genuinely different interfaces for the same job and
+compare them on depth, locality, and where the seam falls.
+
+## Designing for testability
+
+- **Accept dependencies instead of creating them.** A function that receives its payment gateway or
+  clock can be tested with a fake; one that constructs the real thing internally cannot.
+- **Return results instead of producing side effects.** Computing a discount and returning it is testable
+  by assertion; mutating a shared total in place is testable only by inspection.
+- **Keep the surface small.** Fewer operations mean fewer tests; fewer parameters mean simpler setup.
+
+## Rejected framings
+
+- **Depth as a ratio of implementation lines to interface lines** — it rewards padding the implementation.
+  Depth here means leverage.
+- **"Interface" as only a language keyword or a list of public methods** — too narrow; every fact a caller
+  must know is part of it.
+- **"Boundary"** for a seam — overloaded with domain-driven design's bounded context. Say seam or
+  interface.
+
+## Red flags
+
+- A module whose interface mirrors its implementation one-to-one.
+- A wrapper that only forwards calls.
+- An interface with exactly one implementation and no test fake — a seam nothing varies across.
+- A test that reaches past the interface into internals.
+- One concept spread across several shallow modules that must always change together.

package/dist/skills/ralphctl-debugging-and-error-recovery/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: ralphctl-debugging-and-error-recovery
-description: Systematic root-cause debugging. Use when tests fail, builds break, or behaviour does not match expectations. Follow stop-the-line → reproduce → localize → reduce → root-cause → guard-with-regression-test → verify, not guessing; the reproduction and regression steps follow the same red-green discipline as ralphctl-test-driven-development.
+description: Systematic root-cause debugging. Use when tests fail, builds break, something that worked before broke, or behaviour does not match expectations — when you need to figure out what broke and why. Follow stop-the-line → reproduce → localize → reduce → root-cause → guard-with-regression-test → verify, not guessing; the reproduction and regression steps follow the same red-green discipline as ralphctl-test-driven-development.
 license: MIT
 ---
 
 # Debugging and Error Recovery
 
-> Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT).
-> Adapted for ralphctl's harness contract.
+> Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT), with the
+> feedback-loop, ranked-hypothesis, and tagged-log practices drawn from
+> [mattpocock/skills](https://github.com/mattpocock/skills) (MIT). Adapted for ralphctl's harness contract.
 
 Systematic debugging with structured triage. When something breaks, stop adding features, preserve
 evidence, and follow a structured process to find and fix the root cause. Guessing wastes time. The
@@ -32,7 +33,7 @@ When anything unexpected happens:
 6. **Resume** only after the fix is verified with the project's narrow check gate.
 
 Do not push past a failing test or broken build to work on the next feature. Errors compound — a
-bug at Step 3 that goes unfixed makes Steps 4–10 wrong.
+bug at Step 3 that goes unfixed makes Steps 4–6 wrong.
 
 ## The Triage Checklist
 
@@ -42,6 +43,15 @@ Work through these steps in order. Do not skip steps.
 
 Make the failure happen reliably. If you cannot reproduce it, you cannot fix it with confidence.
 
+**Build a tight, red-capable loop before forming any theory.** When your session can run commands, the
+first deliverable is one command you have already run that drives the real code path and asserts the
+exact reported symptom — a failing test at the seam that reaches the bug, a script with a fixture input, a
+captured payload replayed through the code, the same input run through the old and new versions. Tight
+means fast (seconds) and deterministic, or for a flaky bug a pinned, high reproduction rate. Reading code
+to build a theory before that command exists is the failure this step prevents. When no loop can be built
+in this session, list what you tried and what would make it possible rather than guessing — in a `note`
+signal when the prompt's output-contract section lists it, otherwise in the required signal's own fields.
+
 When a bug is non-reproducible, work through these branches:
 
 - **Timing-dependent** — add timestamps to logs near the suspected area; try with artificial delays to widen race windows; run under load or concurrency to increase collision probability.
@@ -79,7 +89,12 @@ Create the minimal failing case:
 
 A minimal reproduction makes the root cause obvious and prevents fixing symptoms instead of causes.
 
-### Step 4: Fix the Root Cause
+### Step 4: Hypothesise, then Fix the Root Cause
+
+Before testing any explanation, write down three to five ranked hypotheses — a single one anchors on the
+first plausible idea. Each must be falsifiable: "if X is the cause, changing Y makes the symptom disappear".
+A hypothesis with no prediction is a hunch; sharpen it or drop it. Test them in rank order against the
+loop, changing one variable at a time.
 
 Fix the underlying issue, not the symptom.
 
@@ -149,6 +164,9 @@ when the prompt's output-contract section lists it, otherwise in the required si
 
 Add logging only when it helps. Remove it when done.
 
+- **Tag temporary logs** with one unique prefix (for example `[DEBUG-a4f2]`), so removal is a single
+  search. Untagged temporary logs survive into the diff; search for the prefix and remove every hit
+  before you signal the work complete.
 - **When to add** — you cannot localize the failure to a specific line; the issue is intermittent; the fix involves multiple interacting components.
 - **When to remove** — the bug is fixed and a regression test guards against recurrence; the log is only useful during development.
 - **Permanent instrumentation (keep)** — error boundaries with error reporting; API error logging with request context; performance metrics at key user flows.