A riffle — the shallow stretch where a stream quickens over rocks — is where scattered ideas collide, speed up, and get honestly tested.
Yeoul is a file-based harness for running deliberation → pre-registration → autonomous work loops with integrity gates that resist self-deception and premature closure. It is the practice layer on top of a measurement-discipline primitive (pre-registration + a tamper-evident ledger): the primitive answers "is this claim honest?"; Yeoul answers "how do I run a disciplined idea loop end to end?"
⚠️ Work in progress — not yet released. This README is a positioning draft, not a launch page.
git clone https://github.com/mirror-stack/yeoul
cd yeoul
export PATH="$PWD/bin:$PATH" # the CLI: yeoul-new, arc-open, arc-close, ralph, status, …
setup/install.sh # installs mirror-stack (sealing primitive) + yeoul-mcp, prints MCP configRegister both MCP servers with your client (Claude Desktop/Code — merge setup/mcp-servers.json):
{ "mcpServers": {
"mirror-stack": { "command": "mirror-stack-mcp" },
"yeoul": { "command": "yeoul-mcp" }
} }mirror-stack is optional — without it, sealing degrades to a no-op and everything else still runs
(setup/install.sh --no-mirror-stack).
Try it with no agent and no compute — just the structure and the gates:
examples/demo.sh # full lifecycle: scaffold → arc → 2-phase KILL close → dev handoff → verify-gate
tests/test_gates.sh # assertion-based smoke test of every gateNew to the method? Read docs/METHODOLOGY.md, then paste
docs/BOOTSTRAP_PROMPT.md into your agent to configure the practice.
- Is: a small set of shell scripts + templates + a method for opening a multi-role deliberation arc, judging convergence under runaway guards, closing it honestly (blank-refusal + a KILL-defense checklist), and handing off to a machine-verified development loop.
- Is not: a novel multi-agent framework. The orchestration is deliberately unremarkable — the value is the gates, not the debate. Research shows more debate rounds do not improve answer quality; Yeoul's round/token/no-progress guards exist because deliberation drifts, not because it self-corrects.
- Gate-1 (prior-art) — reject or re-frame an idea early if existing work already covers it.
- Kill-condition first — a spec without a falsifier is untestable; seal it before spending compute.
- 2-phase close — closing drafts a summary; it only seals once the blanks are filled.
- KILL-defense 5-check — a "failed" verdict cannot be sealed until anchor-reproduction, ≥2 independent angles, implementation-defect ruled out, catalog cross-check, and verbatim kill-wording are all recorded.
- Sealed-condition cross-check — if a pre-registered kill-condition is linked to the arc, closing always
has to answer it, whatever the close is labelled. Otherwise closing as
convergedwould switch off the only signal the closing agent did not write. A seal that no longer resolves is refused, not skipped. - Verify-gated dev loop — each automated development round advances one TODO item and may only check it off after its own machine verification command exits 0, re-run by the harness rather than reported by the agent. Items without a verify command are refused — including checked ones, so deleting the clause is not a way out. (A verify command that cannot fail is still a hole: that part is on the author.)
| Layer | What | Where |
|---|---|---|
| Primitive | pre-registration + tamper-evident ledger | (optional dependency — the mirror-stack) |
| Practice | deliberation arcs, gates, dev handoff | this repo |
The mirror-stack dependency is optional: without it, sealing degrades to a no-op and everything else runs.
- The autonomous development loop ("Ralph"-style) is the least-validated, most-commodity part; its safety comes from the machine-verification gate, not the loop itself. Do not treat it as a proven technique.
- No claim here is that Yeoul improves research outcomes. The claim is narrower: it makes honest discipline the default and hard-to-skip, which is exactly what current autonomous-research systems lack.