etch-loop 0.1.0__py3-none-any.whl

etch/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

etch/agent.py

@@ -0,0 +1,91 @@
+"""Claude agent subprocess runner."""
+
+import subprocess
+import threading
+from collections.abc import Callable
+
+
+class AgentError(Exception):
+    """Raised when the agent subprocess fails or is unavailable."""
+
+
+def run(
+    prompt: str,
+    verbose: bool = False,
+    tick_callback: Callable[[str], None] | None = None,
+) -> str:
+    """Run the Claude agent with the given prompt piped to stdin.
+
+    Launches `claude -p --dangerously-skip-permissions` as a subprocess,
+    pipes `prompt` to its stdin, and returns the full stdout.
+
+    Args:
+        prompt: The prompt text to send to Claude.
+        verbose: If True, streams output to terminal in addition to capturing it.
+        tick_callback: Optional callable called with each line of output as it
+                       arrives. Used by display layer for streaming updates.
+
+    Returns:
+        The full stdout output from the agent as a string.
+
+    Raises:
+        AgentError: If `claude` is not found, or exits with a non-zero code.
+    """
+    cmd = ["claude", "-p", "--dangerously-skip-permissions"]
+
+    try:
+        process = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError:
+        raise AgentError(
+            "claude executable not found. "
+            "Is Claude Code installed? Run: npm install -g @anthropic-ai/claude-code"
+        )
+    except OSError as exc:
+        raise AgentError(f"Failed to launch claude: {exc}") from exc
+
+    # Write prompt to stdin and close it
+    try:
+        process.stdin.write(prompt)
+        process.stdin.close()
+    except BrokenPipeError as exc:
+        raise AgentError(f"Failed to write prompt to claude stdin: {exc}") from exc
+
+    output_lines: list[str] = []
+    lock = threading.Lock()
+
+    def read_stdout() -> None:
+        assert process.stdout is not None
+        for line in process.stdout:
+            with lock:
+                output_lines.append(line)
+            if verbose:
+                print(line, end="", flush=True)
+            if tick_callback is not None:
+                tick_callback(line)
+
+    reader = threading.Thread(target=read_stdout, daemon=True)
+    reader.start()
+    reader.join()
+
+    process.wait()
+
+    # Capture stderr for error reporting
+    stderr_output = ""
+    if process.stderr:
+        stderr_output = process.stderr.read().strip()
+
+    if process.returncode != 0:
+        detail = stderr_output or "(no stderr)"
+        raise AgentError(
+            f"claude exited with code {process.returncode}: {detail}"
+        )
+
+    return "".join(output_lines)

etch/cli.py

@@ -0,0 +1,90 @@
+"""CLI entry points for etch-loop."""
+
+from __future__ import annotations
+
+import importlib.resources
+import shutil
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from etch import display, loop
+
+app = typer.Typer(
+    name="etch",
+    help="Run Claude Code in a fix-break loop, hunting for edge cases.",
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+)
+
+_TEMPLATES = ["ETCH.md", "BREAK.md"]
+
+
+@app.command()
+def init() -> None:
+    """Copy ETCH.md and BREAK.md templates into the current directory."""
+    for filename in _TEMPLATES:
+        dest = Path.cwd() / filename
+
+        if dest.exists():
+            display.print_init_skip(filename)
+            continue
+
+        try:
+            # Python 3.9+ traversable API
+            pkg_templates = importlib.resources.files("etch") / "templates" / filename
+            content = pkg_templates.read_text(encoding="utf-8")
+            dest.write_text(content, encoding="utf-8")
+            display.print_init_ok(filename)
+        except (FileNotFoundError, ModuleNotFoundError, TypeError) as exc:
+            display.print_error(f"Could not copy {filename}: {exc}")
+
+
+@app.command()
+def run(
+    prompt: str = typer.Option(
+        "./ETCH.md",
+        "--prompt",
+        help="Path to the fixer prompt file (ETCH.md).",
+        show_default=True,
+    ),
+    max_iterations: int = typer.Option(
+        20,
+        "--max-iterations",
+        "-n",
+        help="Maximum number of fix-break cycles.",
+        show_default=True,
+        min=1,
+    ),
+    no_commit: bool = typer.Option(
+        False,
+        "--no-commit",
+        help="Skip git commits after fixer runs.",
+        is_flag=True,
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the fixer prompt and exit without running.",
+        is_flag=True,
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Stream agent output to the terminal.",
+        is_flag=True,
+    ),
+) -> None:
+    """Run the fix-break loop against the current repository."""
+    try:
+        loop.run(
+            prompt_path=prompt,
+            max_iterations=max_iterations,
+            no_commit=no_commit,
+            dry_run=dry_run,
+            verbose=verbose,
+        )
+    except KeyboardInterrupt:
+        display.print_interrupted()
+        raise typer.Exit(code=130)

etch/display.py

@@ -0,0 +1,389 @@
+"""Rich-based terminal UI for etch-loop."""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from rich.columns import Columns
+from rich.console import Console, ConsoleOptions, RenderableType, RenderResult
+from rich.live import Live
+from rich.panel import Panel
+from rich.segment import Segment
+from rich.style import Style
+from rich.table import Table
+from rich.text import Text
+
+from etch import __version__
+
+# ── Palette ──────────────────────────────────────────────────────────────────
+BG = "#0a0a0a"
+FG = "#e8e8e8"
+DIM = "#555555"
+AMBER = "#d4a547"
+GREEN = "#7aba78"
+RED = "#c96a6a"
+BORDER = "#1e1e1e"
+
+# ── Symbols (ASCII only) ──────────────────────────────────────────────────────
+SYM_RUN = ">"
+SYM_OK = "+"
+SYM_FAIL = "x"
+SYM_NEUTRAL = "-"
+
+SCAN_WIDTH = 40
+SCAN_BLOCK = "▓▒ "  # 3-char block
+SCAN_FILL = "░"
+TICK_MS = 80
+
+
+# ── ScanBar renderable ────────────────────────────────────────────────────────
+
+
+class ScanBar:
+    """A Rich renderable that renders one frame of the scan animation.
+
+    The bar is SCAN_WIDTH chars wide, filled with SCAN_FILL (░).
+    A 3-char SCAN_BLOCK (▓▒ ) slides left-to-right, wrapping at the end.
+    Rendered in amber.
+    """
+
+    def __init__(self, tick: int) -> None:
+        self.tick = tick
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        width = SCAN_WIDTH
+        block = SCAN_BLOCK
+        block_len = len(block)
+        pos = self.tick % width
+
+        bar = list(SCAN_FILL * width)
+        for i, ch in enumerate(block):
+            idx = (pos + i) % width
+            bar[idx] = ch
+
+        yield Segment("".join(bar), Style(color=AMBER))
+
+
+# ── Log entry dataclass ───────────────────────────────────────────────────────
+
+
+@dataclass
+class _LogEntry:
+    """One line in the scrolling log."""
+
+    symbol: str
+    phase: str
+    status: str
+    detail: str | RenderableType
+    color: str
+    running: bool = False
+    tick: int = 0
+
+
+# ── EtchDisplay ──────────────────────────────────────────────────────────────
+
+
+class EtchDisplay:
+    """Manages the Rich Live layout for the etch-loop run."""
+
+    def __init__(self, target: str = "") -> None:
+        self._console = Console(style=f"on {BG}")
+        self._target = target
+        self._entries: list[_LogEntry] = []
+        self._stats: dict[str, Any] = {
+            "iterations": 0,
+            "fixes": 0,
+            "issues": 0,
+            "start": time.monotonic(),
+        }
+        self._live: Live | None = None
+        self._tick = 0
+        self._ticker_stop = threading.Event()
+        self._ticker_thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    # ── Public lifecycle ──────────────────────────────────────────────────────
+
+    def __enter__(self) -> "EtchDisplay":
+        self._live = Live(
+            self._render(),
+            console=self._console,
+            refresh_per_second=15,
+            transient=False,
+        )
+        self._live.__enter__()
+        self._start_ticker()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self._stop_ticker()
+        if self._live is not None:
+            self._live.__exit__(*args)
+
+    # ── Iteration / phase API ─────────────────────────────────────────────────
+
+    def start_iteration(self, n: int) -> None:
+        """Add an iteration header line to the log."""
+        with self._lock:
+            self._stats["iterations"] = n
+            self._entries.append(
+                _LogEntry(
+                    symbol=SYM_NEUTRAL,
+                    phase=f"iteration {n}",
+                    status="",
+                    detail="",
+                    color=DIM,
+                )
+            )
+        self._refresh()
+
+    def start_phase(self, phase: str) -> None:
+        """Add a 'running' line with scan animation for the given phase."""
+        with self._lock:
+            self._entries.append(
+                _LogEntry(
+                    symbol=SYM_RUN,
+                    phase=phase,
+                    status="running",
+                    detail=ScanBar(self._tick),
+                    color=AMBER,
+                    running=True,
+                    tick=self._tick,
+                )
+            )
+        self._refresh()
+
+    def finish_phase(
+        self,
+        phase: str,
+        status: str,
+        detail: str,
+        duration: float,
+        success: bool = True,
+    ) -> None:
+        """Replace the last running line for `phase` with a finished result."""
+        color = GREEN if success else RED
+        symbol = SYM_OK if success else SYM_FAIL
+        dur_str = f"{duration:.1f}s"
+
+        with self._lock:
+            # Find the last running entry for this phase and replace it
+            for i in range(len(self._entries) - 1, -1, -1):
+                entry = self._entries[i]
+                if entry.phase == phase and entry.running:
+                    self._entries[i] = _LogEntry(
+                        symbol=symbol,
+                        phase=phase,
+                        status=status,
+                        detail=detail,
+                        color=color,
+                        running=False,
+                    )
+                    break
+        self._refresh()
+
+    def record_fix(self) -> None:
+        """Increment the fix counter."""
+        with self._lock:
+            self._stats["fixes"] += 1
+
+    def record_issue(self) -> None:
+        """Increment the breaker-issues counter."""
+        with self._lock:
+            self._stats["issues"] += 1
+
+    def print_summary(self, stats: dict[str, Any]) -> None:
+        """Print the final done/stopped/interrupted panel."""
+        self._stop_ticker()
+        if self._live is not None:
+            self._live.stop()
+
+        reason = stats.get("reason", "done")
+        elapsed = stats.get("elapsed", 0.0)
+        iterations = stats.get("iterations", 0)
+        fixes = stats.get("fixes", 0)
+        issues = stats.get("issues", 0)
+
+        elapsed_str = _format_elapsed(elapsed)
+
+        if reason == "clear":
+            title_color = GREEN
+            title = f"[{GREEN}]+ all clear[/{GREEN}]"
+        elif reason == "interrupted":
+            title_color = AMBER
+            title = f"[{AMBER}]- interrupted[/{AMBER}]"
+        elif reason == "max_iterations":
+            title_color = AMBER
+            title = f"[{AMBER}]- stopped (max iterations)[/{AMBER}]"
+        elif reason == "no_changes":
+            title_color = GREEN
+            title = f"[{GREEN}]+ clean — fixer found nothing[/{GREEN}]"
+        else:
+            title_color = FG
+            title = f"[{FG}]done[/{FG}]"
+
+        body = (
+            f"[{DIM}]iterations[/{DIM}] [{FG}]{iterations}[/{FG}]   "
+            f"[{DIM}]fixes[/{DIM}] [{FG}]{fixes}[/{FG}]   "
+            f"[{DIM}]breaker issues[/{DIM}] [{FG}]{issues}[/{FG}]   "
+            f"[{DIM}]{elapsed_str} elapsed[/{DIM}]"
+        )
+
+        panel = Panel(
+            body,
+            title=title,
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+        self._console.print(panel)
+
+    # ── Rendering ─────────────────────────────────────────────────────────────
+
+    def _render(self) -> RenderableType:
+        """Build the full Live renderable."""
+        with self._lock:
+            entries = list(self._entries)
+            tick = self._tick
+            stats = dict(self._stats)
+
+        elapsed = time.monotonic() - stats["start"]
+
+        # Build log table
+        log_table = Table.grid(padding=(0, 1))
+        log_table.add_column(width=2)  # symbol
+        log_table.add_column(width=10)  # phase
+        log_table.add_column(width=12)  # status
+        log_table.add_column()  # detail
+
+        for entry in entries:
+            if entry.running:
+                detail_render: RenderableType = ScanBar(tick)
+            else:
+                detail_render = Text(str(entry.detail), style=Style(color=DIM))
+
+            sym_text = Text(entry.symbol, style=Style(color=entry.color))
+            phase_text = Text(entry.phase, style=Style(color=entry.color))
+            status_text = Text(entry.status, style=Style(color=DIM))
+
+            log_table.add_row(sym_text, phase_text, status_text, detail_render)
+
+        # Header
+        title_str = f"etch loop v{__version__}"
+        if self._target:
+            title_str += f"  {self._target}"
+
+        # Stats footer
+        elapsed_str = _format_elapsed(elapsed)
+        footer = (
+            f"[{DIM}]iterations[/{DIM}] [{FG}]{stats['iterations']}[/{FG}]   "
+            f"[{DIM}]fixes[/{DIM}] [{FG}]{stats['fixes']}[/{FG}]   "
+            f"[{DIM}]breaker issues[/{DIM}] [{FG}]{stats['issues']}[/{FG}]   "
+            f"[{DIM}]{elapsed_str} elapsed[/{DIM}]"
+        )
+
+        panel = Panel(
+            log_table,
+            title=f"[{AMBER}]{title_str}[/{AMBER}]",
+            subtitle=footer,
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+        return panel
+
+    def _refresh(self) -> None:
+        if self._live is not None:
+            self._live.update(self._render())
+
+    # ── Ticker thread ─────────────────────────────────────────────────────────
+
+    def _start_ticker(self) -> None:
+        self._ticker_stop.clear()
+        self._ticker_thread = threading.Thread(
+            target=self._ticker_loop, daemon=True
+        )
+        self._ticker_thread.start()
+
+    def _stop_ticker(self) -> None:
+        self._ticker_stop.set()
+        if self._ticker_thread is not None:
+            self._ticker_thread.join(timeout=1.0)
+            self._ticker_thread = None
+
+    def _ticker_loop(self) -> None:
+        while not self._ticker_stop.is_set():
+            with self._lock:
+                self._tick += 1
+            self._refresh()
+            time.sleep(TICK_MS / 1000.0)
+
+
+# ── Standalone print helpers (used outside Live context) ──────────────────────
+
+_console = Console(style=f"on {BG}")
+
+
+def print_dry_run(prompt_text: str) -> None:
+    """Print the prompt in a panel for --dry-run mode."""
+    _console.print(
+        Panel(
+            Text(prompt_text, style=Style(color=FG)),
+            title=f"[{AMBER}]dry run — prompt preview[/{AMBER}]",
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+    )
+
+
+def print_interrupted() -> None:
+    """Print interrupted notice."""
+    _console.print(
+        Panel(
+            Text("Run interrupted by user.", style=Style(color=AMBER)),
+            title=f"[{AMBER}]- interrupted[/{AMBER}]",
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+    )
+
+
+def print_error(message: str) -> None:
+    """Print an error panel."""
+    _console.print(
+        Panel(
+            Text(message, style=Style(color=RED)),
+            title=f"[{RED}]x error[/{RED}]",
+            border_style=Style(color=BORDER),
+            style=Style(bgcolor=BG),
+        )
+    )
+
+
+def print_init_ok(filename: str) -> None:
+    """Print a success line for etch init."""
+    _console.print(f"[{GREEN}]{SYM_OK}[/{GREEN}]  [{FG}]{filename}[/{FG}]")
+
+
+def print_init_skip(filename: str) -> None:
+    """Print a skip line for etch init (file already exists)."""
+    _console.print(
+        f"[{AMBER}]{SYM_NEUTRAL}[/{AMBER}]  [{DIM}]{filename} already exists, skipping[/{DIM}]"
+    )
+
+
+# ── Utilities ─────────────────────────────────────────────────────────────────
+
+
+def _format_elapsed(seconds: float) -> str:
+    """Format elapsed seconds as '2m 14s' or '45s'."""
+    seconds = max(0.0, seconds)
+    mins = int(seconds // 60)
+    secs = int(seconds % 60)
+    if mins > 0:
+        return f"{mins}m {secs}s"
+    return f"{secs}s"

etch/git.py

@@ -0,0 +1,101 @@
+"""Git subprocess utilities."""
+
+import subprocess
+
+
+class GitError(Exception):
+    """Raised when a git operation fails."""
+
+
+def has_changes() -> bool:
+    """Check whether the working tree has uncommitted changes.
+
+    Runs `git diff --quiet HEAD` and interprets the exit code:
+      0  — no changes
+      1  — changes present
+      other — git error
+
+    Returns:
+        True if there are uncommitted changes, False otherwise.
+
+    Raises:
+        GitError: If git is not available or returns an unexpected error.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--quiet", "HEAD"],
+            capture_output=True,
+        )
+    except FileNotFoundError:
+        raise GitError("git executable not found. Is git installed?")
+    except OSError as exc:
+        raise GitError(f"Failed to run git: {exc}") from exc
+
+    if result.returncode == 0:
+        return False
+    if result.returncode == 1:
+        return True
+
+    # Non-zero, non-one exit code — could mean no commits yet, check with status
+    # Fallback: check via git status --porcelain
+    try:
+        status = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+        )
+    except OSError as exc:
+        raise GitError(f"Failed to run git status: {exc}") from exc
+
+    if status.returncode != 0:
+        stderr = result.stderr.decode(errors="replace").strip()
+        raise GitError(f"git diff failed (exit {result.returncode}): {stderr}")
+
+    return bool(status.stdout.strip())
+
+
+def commit(message: str) -> None:
+    """Stage all changes and create a commit.
+
+    Args:
+        message: The commit message.
+
+    Raises:
+        GitError: If staging or committing fails.
+    """
+    if not message or not message.strip():
+        raise GitError("Commit message must not be empty.")
+
+    # Stage all changes
+    try:
+        add_result = subprocess.run(
+            ["git", "add", "-A"],
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        raise GitError("git executable not found. Is git installed?")
+    except OSError as exc:
+        raise GitError(f"Failed to run git add: {exc}") from exc
+
+    if add_result.returncode != 0:
+        stderr = add_result.stderr.strip()
+        raise GitError(f"git add -A failed (exit {add_result.returncode}): {stderr}")
+
+    # Create commit
+    try:
+        commit_result = subprocess.run(
+            ["git", "commit", "-m", message],
+            capture_output=True,
+            text=True,
+        )
+    except OSError as exc:
+        raise GitError(f"Failed to run git commit: {exc}") from exc
+
+    if commit_result.returncode != 0:
+        stderr = commit_result.stderr.strip()
+        stdout = commit_result.stdout.strip()
+        detail = stderr or stdout
+        raise GitError(
+            f"git commit failed (exit {commit_result.returncode}): {detail}"
+        )

etch/loop.py

@@ -0,0 +1,182 @@
+"""Core fix-break loop logic."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from etch import agent, display, git, prompt, signals
+from etch.agent import AgentError
+from etch.git import GitError
+from etch.prompt import PromptError
+
+
+def run(
+    prompt_path: str | Path,
+    max_iterations: int = 20,
+    no_commit: bool = False,
+    dry_run: bool = False,
+    verbose: bool = False,
+) -> None:
+    """Run the fix-break loop.
+
+    Args:
+        prompt_path:    Path to ETCH.md (fixer prompt).
+        max_iterations: Maximum number of fix-break cycles to run.
+        no_commit:      If True, skip git commits after fixer runs.
+        dry_run:        If True, print the prompt and exit without running.
+        verbose:        If True, stream agent output to the terminal.
+    """
+    prompt_path = Path(prompt_path)
+
+    # ── Load fixer prompt ──────────────────────────────────────────────────────
+    try:
+        prompt_text = prompt.load(prompt_path)
+    except PromptError as exc:
+        display.print_error(str(exc))
+        return
+
+    # ── Dry run ───────────────────────────────────────────────────────────────
+    if dry_run:
+        display.print_dry_run(prompt_text)
+        return
+
+    # ── Load breaker prompt early to fail fast ────────────────────────────────
+    try:
+        break_text = prompt.load_break(prompt_path)
+    except PromptError as exc:
+        display.print_error(str(exc))
+        return
+
+    start_time = time.monotonic()
+    stats: dict = {
+        "iterations": 0,
+        "fixes": 0,
+        "issues": 0,
+        "reason": "done",
+        "elapsed": 0.0,
+    }
+
+    with display.EtchDisplay(target=str(prompt_path.parent)) as disp:
+        for iteration in range(1, max_iterations + 1):
+            stats["iterations"] = iteration
+            disp.start_iteration(iteration)
+
+            # ── Fixer phase ───────────────────────────────────────────────────
+            disp.start_phase("fixer")
+            fixer_start = time.monotonic()
+            try:
+                _fixer_output = agent.run(prompt_text, verbose=verbose)
+            except AgentError as exc:
+                disp.finish_phase(
+                    "fixer",
+                    status="error",
+                    detail=str(exc),
+                    duration=time.monotonic() - fixer_start,
+                    success=False,
+                )
+                stats["reason"] = "agent_error"
+                break
+
+            fixer_duration = time.monotonic() - fixer_start
+
+            # ── Check for changes ─────────────────────────────────────────────
+            try:
+                changed = git.has_changes()
+            except GitError as exc:
+                disp.finish_phase(
+                    "fixer",
+                    status="error",
+                    detail=str(exc),
+                    duration=fixer_duration,
+                    success=False,
+                )
+                stats["reason"] = "git_error"
+                break
+
+            if not changed:
+                disp.finish_phase(
+                    "fixer",
+                    status="no changes",
+                    detail="nothing to fix",
+                    duration=fixer_duration,
+                    success=True,
+                )
+                stats["reason"] = "no_changes"
+                break
+
+            # ── Commit ────────────────────────────────────────────────────────
+            commit_msg = f"fix(edge): iteration {iteration}"
+            if not no_commit:
+                try:
+                    git.commit(commit_msg)
+                except GitError as exc:
+                    disp.finish_phase(
+                        "fixer",
+                        status="commit error",
+                        detail=str(exc),
+                        duration=fixer_duration,
+                        success=False,
+                    )
+                    stats["reason"] = "git_error"
+                    break
+
+            disp.record_fix()
+            stats["fixes"] += 1
+            disp.finish_phase(
+                "fixer",
+                status="committed" if not no_commit else "changed",
+                detail=commit_msg,
+                duration=fixer_duration,
+                success=True,
+            )
+
+            # ── Breaker phase ─────────────────────────────────────────────────
+            disp.start_phase("breaker")
+            breaker_start = time.monotonic()
+            try:
+                breaker_output = agent.run(break_text, verbose=verbose)
+            except AgentError as exc:
+                disp.finish_phase(
+                    "breaker",
+                    status="error",
+                    detail=str(exc),
+                    duration=time.monotonic() - breaker_start,
+                    success=False,
+                )
+                stats["reason"] = "agent_error"
+                break
+
+            breaker_duration = time.monotonic() - breaker_start
+            signal = signals.parse(breaker_output)
+            finding = signals.extract_finding(breaker_output)
+
+            if signal == "clear":
+                disp.finish_phase(
+                    "breaker",
+                    status="all clear",
+                    detail=finding or "no issues found",
+                    duration=breaker_duration,
+                    success=True,
+                )
+                stats["reason"] = "clear"
+                break
+            else:
+                disp.record_issue()
+                stats["issues"] += 1
+                disp.finish_phase(
+                    "breaker",
+                    status="issues",
+                    detail=finding or "issues found",
+                    duration=breaker_duration,
+                    success=False,
+                )
+                stats["reason"] = "issues"
+                # Continue to next iteration
+
+        else:
+            # Loop exhausted without break
+            stats["reason"] = "max_iterations"
+
+        stats["elapsed"] = time.monotonic() - start_time
+        disp.print_summary(stats)

etch/prompt.py

@@ -0,0 +1,75 @@
+"""Prompt file loading utilities."""
+
+from pathlib import Path
+
+
+class PromptError(Exception):
+    """Raised when a prompt file cannot be loaded or is invalid."""
+
+
+def load(path: str | Path) -> str:
+    """Load and return the content of a prompt file.
+
+    Args:
+        path: Path to the prompt file.
+
+    Returns:
+        File contents as a string.
+
+    Raises:
+        PromptError: If the file does not exist or is empty.
+    """
+    p = Path(path)
+    if not p.exists():
+        raise PromptError(f"Prompt file not found: {p}")
+    if not p.is_file():
+        raise PromptError(f"Prompt path is not a file: {p}")
+
+    content = p.read_text(encoding="utf-8")
+    if not content.strip():
+        raise PromptError(f"Prompt file is empty: {p}")
+
+    return content
+
+
+def load_break(path: str | Path | None = None) -> str:
+    """Load and return the content of BREAK.md.
+
+    Searches in order:
+    1. The explicit path if provided
+    2. Same directory as the provided path (treating it as ETCH.md location)
+    3. Current working directory
+
+    Args:
+        path: Optional path. If this is ETCH.md, looks for BREAK.md alongside it.
+              If this is the BREAK.md path directly, loads it directly.
+
+    Returns:
+        File contents as a string.
+
+    Raises:
+        PromptError: If BREAK.md cannot be found or is empty.
+    """
+    candidates: list[Path] = []
+
+    if path is not None:
+        p = Path(path)
+        # If caller passed BREAK.md directly
+        if p.name.upper() == "BREAK.MD":
+            candidates.append(p)
+        else:
+            # Treat path as ETCH.md — look for BREAK.md alongside it
+            candidates.append(p.parent / "BREAK.md")
+
+    # Always fall back to cwd
+    candidates.append(Path.cwd() / "BREAK.md")
+
+    for candidate in candidates:
+        if candidate.exists() and candidate.is_file():
+            content = candidate.read_text(encoding="utf-8")
+            if not content.strip():
+                raise PromptError(f"BREAK.md is empty: {candidate}")
+            return content
+
+    searched = ", ".join(str(c) for c in candidates)
+    raise PromptError(f"BREAK.md not found. Searched: {searched}")

etch/signals.py

@@ -0,0 +1,78 @@
+"""Signal parsing for breaker agent output."""
+
+_TOKEN_CLEAR = "ETCH_ALL_CLEAR"
+_TOKEN_ISSUES = "ETCH_ISSUES_FOUND"
+
+
+def parse(output: str) -> str:
+    """Parse breaker agent output for control tokens.
+
+    Returns the signal corresponding to whichever token appears first.
+    If both appear, the earlier one wins. If neither appears, returns
+    "issues" as a fail-safe.
+
+    Returns:
+        "clear"  — ETCH_ALL_CLEAR found (and appears before ETCH_ISSUES_FOUND)
+        "issues" — ETCH_ISSUES_FOUND found, appears first, or neither found
+    """
+    if not isinstance(output, str):
+        return "issues"
+
+    clear_pos = output.find(_TOKEN_CLEAR)
+    issues_pos = output.find(_TOKEN_ISSUES)
+
+    if clear_pos == -1 and issues_pos == -1:
+        # Fail-safe: no token found → assume issues
+        return "issues"
+
+    if clear_pos == -1:
+        return "issues"
+
+    if issues_pos == -1:
+        return "clear"
+
+    # Both found — whichever appears first wins
+    if clear_pos < issues_pos:
+        return "clear"
+    return "issues"
+
+
+def extract_finding(output: str) -> str:
+    """Extract first meaningful line before the signal token.
+
+    Returns the first non-empty, non-header line that appears before
+    the signal token, or an empty string if nothing useful is found.
+    """
+    if not isinstance(output, str) or not output.strip():
+        return ""
+
+    # Find the position of either token
+    clear_pos = output.find(_TOKEN_CLEAR)
+    issues_pos = output.find(_TOKEN_ISSUES)
+
+    # Determine the cutoff point (use whichever token appears first)
+    cutoff = len(output)
+    if clear_pos >= 0 and issues_pos >= 0:
+        cutoff = min(clear_pos, issues_pos)
+    elif clear_pos >= 0:
+        cutoff = clear_pos
+    elif issues_pos >= 0:
+        cutoff = issues_pos
+
+    text_before = output[:cutoff].strip()
+    if not text_before:
+        return ""
+
+    lines = text_before.splitlines()
+    for line in reversed(lines):
+        stripped = line.strip()
+        # Skip empty lines, markdown headers, and separator lines
+        if not stripped:
+            continue
+        if stripped.startswith("#"):
+            continue
+        if all(c in "-=*_" for c in stripped):
+            continue
+        return stripped
+
+    return ""

etch/templates/BREAK.md

@@ -0,0 +1,21 @@
+# BREAK — breaker prompt
+
+You are an adversarial code reviewer. Your job is to find what the fixer missed.
+
+## Your mission
+
+- Review recent changes and the surrounding code
+- Think like someone trying to make this code fail
+- Look for: newly introduced bugs, assumptions the fixer made, edge cases still unhandled, subtle regressions
+
+## Rules
+
+1. DO NOT edit any files — read only
+2. Report your findings clearly, one per line
+3. End your output with EXACTLY one of these tokens on its own line:
+   - `ETCH_ISSUES_FOUND` — if you found anything worth fixing
+   - `ETCH_ALL_CLEAR` — if the code looks solid
+
+## Scope
+
+Same scope as the fixer: [edit to match ETCH.md scope]

etch/templates/ETCH.md

@@ -0,0 +1,29 @@
+# ETCH — fixer prompt
+
+You are a surgical code reviewer focused on edge cases and robustness.
+
+## Your mission
+
+Scan the codebase for:
+- Unhandled edge cases and boundary conditions
+- Missing null/None/empty checks
+- Unhandled exceptions and error paths
+- Off-by-one errors
+- Race conditions or unsafe concurrent access
+- Missing input validation at system boundaries
+
+## Rules
+
+1. Fix only what you find — do not refactor, rename, or reorganize
+2. One logical fix per commit (the harness will commit for you)
+3. Do not add comments explaining what you fixed
+4. If you find nothing, make no changes
+
+## Scope
+
+Focus on: [edit this to narrow your scope, e.g. "src/auth/", "the payment module"]
+
+## Commit format
+
+The harness commits automatically. Each commit will be:
+  fix(edge): <short description of what was fixed>

etch_loop-0.1.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: etch-loop
+Version: 0.1.0
+Summary: Run Claude Code in a fix-break loop until your codebase is clean
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: rich
+Requires-Dist: typer
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# etch-loop

etch_loop-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+etch/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+etch/agent.py,sha256=7TE6VG2sVdQBtGBAPmYtja9z2F61xZgKVpmljoayzY4,2727
+etch/cli.py,sha256=RBK16A7zesQ0xlcnGq5p3uMstxe2aBr4eeIPZpoPtBg,2391
+etch/display.py,sha256=tMyjVpYlw3N0kC-YeumziOrcHHBMh9e_2fCjaVUjr2I,13040
+etch/git.py,sha256=fBZwwQl1ovCt767R4qtogwTpV5BzMM2skefyWRc7v1k,2941
+etch/loop.py,sha256=PgzXJ-pEe0Azg63yEGAkdXBdAyn9mrmFNeRsCJBNKR0,6794
+etch/prompt.py,sha256=qWgSM1-Fmsntn1Jf8Ck5RamaBvDVDv5yrhq6seLBRJM,2158
+etch/signals.py,sha256=0-l1VwDY17QxI_NbqhbT-AR2Ag644pzI-ie0mU-JPqU,2257
+etch/templates/BREAK.md,sha256=oGfEEOUWGKcQRarMN_GbxVViYeDP7b8Lum0-jAkKQEE,682
+etch/templates/ETCH.md,sha256=oQ2FqE7wIbBFFPzNlHSr62odo5Zepbxmb_r48TZOqM0,823
+etch_loop-0.1.0.dist-info/METADATA,sha256=hUpSB4e8u9-Uw94KIp-NtGFvn6gf0V6mnWDf9S_L1kA,316
+etch_loop-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+etch_loop-0.1.0.dist-info/entry_points.txt,sha256=t3DxkZSkD0j3q5NLI54hh-ArdOOven0OUy0dp_fIi_U,38
+etch_loop-0.1.0.dist-info/RECORD,,

etch_loop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

etch_loop-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+etch = etch.cli:app