[PR #186] feat(loops): refactor scratchpad configuration to support per-hat set… #185

New issue

Open

opened 2026-02-27 10:22:38 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 10:22:38 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/mikeyobrien/ralph-orchestrator/pull/186
Author: @luisherranz
Created: 2/24/2026
Status: 🔄 Open

Base: main ← Head: feat/per-hat-scratchpad

📝 Commits (2)

047b5d0 feat(loops): refactor scratchpad configuration to support per-hat settings
abb75e4 feat(loops): enhance scratchpad path resolution for per-hat overrides and add iteration tracking

📊 Changes

15 files changed (+1052 additions, -113 deletions)

View changed files

📝 crates/ralph-cli/src/doctor.rs (+1 -0)
📝 crates/ralph-cli/src/loop_runner.rs (+8 -8)
📝 crates/ralph-cli/src/main.rs (+25 -22)
📝 crates/ralph-core/src/config.rs (+418 -11)
📝 crates/ralph-core/src/diagnostics/integration_tests.rs (+1 -1)
📝 crates/ralph-core/src/event_loop/mod.rs (+101 -13)
📝 crates/ralph-core/src/event_loop/tests.rs (+9 -6)
📝 crates/ralph-core/src/hatless_ralph.rs (+379 -38)
📝 crates/ralph-core/src/instructions.rs (+5 -1)
📝 crates/ralph-core/src/lib.rs (+2 -2)
📝 crates/ralph-core/src/preflight.rs (+2 -2)
📝 docs/advanced/architecture.md (+3 -3)
📝 docs/concepts/memories-and-tasks.md (+2 -0)
📝 docs/guide/agents.md (+4 -2)
📝 docs/guide/configuration.md (+92 -4)

📄 Description

Summary

Closes https://github.com/mikeyobrien/ralph-orchestrator/issues/174.

Refactors the scratchpad configuration from a plain string path (core.scratchpad: "...") into a structured ScratchpadConfig type with enabled and path fields, and adds per-hat scratchpad overrides so each hat can use a custom scratchpad path, disable scratchpad entirely, or inherit the global setting.

Introduces ScratchpadConfig struct with custom serde deserializers supporting both legacy plain-string and structured object YAML formats (backwards-compatible)
Adds optional scratchpad field to HatConfig with resolution order: hat override > core.scratchpad > defaults
Updates prompt generation in HatlessRalph to conditionally suppress all scratchpad-related sections (ORIENTATION, SCRATCHPAD, STATE MANAGEMENT, WORKFLOW, EVENT WRITING) when scratchpad is disabled
Updates EventLoop to resolve per-hat scratchpad config before each iteration, skip scratchpad injection/verification when disabled, and fall back to global scratchpad for guidance persistence
Adds solo-mode safety guard that force-enables scratchpad when no hats are defined (scratchpad is the only continuity mechanism in solo mode)
Updates documentation for configuration, architecture, agents, and memories-and-tasks guides

Test plan

cargo test -p ralph-core passes (includes 20+ new tests for scratchpad config parsing, resolution, prompt generation, and edge cases)
cargo test passes across all crates
Verify legacy core.scratchpad: "path" string format still works (backwards-compatible deserialization)
Verify structured core.scratchpad: { enabled: true, path: "..." } format works
Verify hat-level scratchpad overrides (plain string, structured, disabled, absent/inherit)
Verify prompts omit all scratchpad references when enabled: false
Verify prompts use custom path when hat specifies one
Verify solo mode forces scratchpad enabled when no hats defined

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/mikeyobrien/ralph-orchestrator/pull/186 **Author:** [@luisherranz](https://github.com/luisherranz) **Created:** 2/24/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/per-hat-scratchpad` --- ### 📝 Commits (2) - [`047b5d0`](https://github.com/mikeyobrien/ralph-orchestrator/commit/047b5d0ebb91481f03ae67eb7695c66ceb1e6912) feat(loops): refactor scratchpad configuration to support per-hat settings - [`abb75e4`](https://github.com/mikeyobrien/ralph-orchestrator/commit/abb75e4c6619ffa1fc1648a38e2062470b6aebc8) feat(loops): enhance scratchpad path resolution for per-hat overrides and add iteration tracking ### 📊 Changes **15 files changed** (+1052 additions, -113 deletions) <details> <summary>View changed files</summary> 📝 `crates/ralph-cli/src/doctor.rs` (+1 -0) 📝 `crates/ralph-cli/src/loop_runner.rs` (+8 -8) 📝 `crates/ralph-cli/src/main.rs` (+25 -22) 📝 `crates/ralph-core/src/config.rs` (+418 -11) 📝 `crates/ralph-core/src/diagnostics/integration_tests.rs` (+1 -1) 📝 `crates/ralph-core/src/event_loop/mod.rs` (+101 -13) 📝 `crates/ralph-core/src/event_loop/tests.rs` (+9 -6) 📝 `crates/ralph-core/src/hatless_ralph.rs` (+379 -38) 📝 `crates/ralph-core/src/instructions.rs` (+5 -1) 📝 `crates/ralph-core/src/lib.rs` (+2 -2) 📝 `crates/ralph-core/src/preflight.rs` (+2 -2) 📝 `docs/advanced/architecture.md` (+3 -3) 📝 `docs/concepts/memories-and-tasks.md` (+2 -0) 📝 `docs/guide/agents.md` (+4 -2) 📝 `docs/guide/configuration.md` (+92 -4) </details> ### 📄 Description ## Summary Closes https://github.com/mikeyobrien/ralph-orchestrator/issues/174. Refactors the scratchpad configuration from a plain string path (`core.scratchpad: "..."`) into a structured `ScratchpadConfig` type with `enabled` and `path` fields, and adds per-hat scratchpad overrides so each hat can use a custom scratchpad path, disable scratchpad entirely, or inherit the global setting. - Introduces `ScratchpadConfig` struct with custom serde deserializers supporting both legacy plain-string and structured object YAML formats (backwards-compatible) - Adds optional `scratchpad` field to `HatConfig` with resolution order: hat override > `core.scratchpad` > defaults - Updates prompt generation in `HatlessRalph` to conditionally suppress all scratchpad-related sections (ORIENTATION, SCRATCHPAD, STATE MANAGEMENT, WORKFLOW, EVENT WRITING) when scratchpad is disabled - Updates `EventLoop` to resolve per-hat scratchpad config before each iteration, skip scratchpad injection/verification when disabled, and fall back to global scratchpad for guidance persistence - Adds solo-mode safety guard that force-enables scratchpad when no hats are defined (scratchpad is the only continuity mechanism in solo mode) - Updates documentation for configuration, architecture, agents, and memories-and-tasks guides ## Test plan - [ ] `cargo test -p ralph-core` passes (includes 20+ new tests for scratchpad config parsing, resolution, prompt generation, and edge cases) - [ ] `cargo test` passes across all crates - [ ] Verify legacy `core.scratchpad: "path"` string format still works (backwards-compatible deserialization) - [ ] Verify structured `core.scratchpad: { enabled: true, path: "..." }` format works - [ ] Verify hat-level `scratchpad` overrides (plain string, structured, disabled, absent/inherit) - [ ] Verify prompts omit all scratchpad references when `enabled: false` - [ ] Verify prompts use custom path when hat specifies one - [ ] Verify solo mode forces scratchpad enabled when no hats defined --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>