etch-loop 0.5.4__tar.gz → 0.6.0__tar.gz

etch_loop-0.6.0/.gitignore

@@ -0,0 +1 @@
+etch-loop/

etch_loop-0.6.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: etch-loop
+Version: 0.6.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
+
+```
+  ███████╗████████╗ ██████╗██╗  ██╗
+  ██╔════╝╚══██╔══╝██╔════╝██║  ██║
+  █████╗     ██║   ██║     ███████║
+  ██╔══╝     ██║   ██║     ██╔══██║
+  ███████╗   ██║   ╚██████╗██║  ██║
+  ╚══════╝   ╚═╝    ╚═════╝╚═╝  ╚═╝  loop
+```
+
+> Run Claude Code in a scan-fix-break loop until your codebase is clean.
+
+---
+
+```
+╭───────────────────────── etch loop v0.5.5  my-project ─────────────────────────╮
+│ -  iteration  1                                                                 │
+│ x  scanner    issues found   3 bugs — null deref auth.py:42, off-by-one...     │
+│ +  fixer      committed      fixed 3 issues — null guard in auth.py, bounds... │
+│ x  breaker    issues         unguarded access still reachable in session.py     │
+│ -  iteration  2                                                                 │
+│ +  scanner    all clear      no confirmed bugs found                            │
+│ +  runner     all clear      wrote 4 tests, all 31 passed                      │
+╰───────────────── iterations 2   fixes 1   breaker issues 1   3m 12s elapsed ───╯
+```
+
+---
+
+## install
+
+```bash
+uv tool install etch-loop
+```
+
+Or with pip:
+
+```bash
+pip install etch-loop
+```
+
+## usage
+
+```bash
+etch init                        # analyze codebase, write prompt files to etch-loop/
+etch run                         # start the loop
+etch run "the auth module"       # focus on a specific area
+etch run -n 5                    # max 5 iterations
+etch run --no-commit             # fix without committing
+etch run --no-git                # disable all git operations
+etch run --dry-run               # preview prompt, don't run
+etch run --verbose               # stream full Claude output
+```
+
+---
+
+## how it works
+
+Each iteration runs four phases: **scan → fix → break**, then once everything is clean: **run**.
+
+### 1. Scanner
+Reads the codebase and produces a precise list of confirmed bugs — file paths, line numbers, one-line descriptions. Only genuine issues, no style notes.
+
+### 2. Fixer
+Receives the scanner's list and fixes exactly those issues. Commits each fix with a summary message. Does not refactor or touch code unrelated to the reported bugs.
+
+### 3. Breaker
+Adversarially reviews only the files the fixer just changed, looking for anything introduced or missed. If it finds nothing, the loop stops clean. If it finds issues, the next iteration's scanner re-checks those specific spots to confirm what's actually still broken.
+
+### 4. Runner *(final step)*
+Runs only when the loop exits cleanly. Writes targeted tests for what was changed, runs the full test suite, then deletes the test files it created. Reports pass/fail.
+
+```
+loop exits clean
+       │
+       ▼
+   [ runner ]  →  writes tests  →  runs suite  →  cleans up  →  ETCH_ALL_CLEAR
+```
+
+Each agent writes a short `<etch_summary>` that appears directly in the terminal dashboard. The fixer's summary doubles as the git commit message.
+
+---
+
+## etch init
+
+`etch init` runs Claude against your codebase, detects languages and structure, then writes four prompt files tailored to your project into an `etch-loop/` subfolder. No placeholders to fill in.
+
+```
+╭─ etch init v0.5.5 ────────────────────────────────╮
+│ >  analyzing   ░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░   │
+│ +  analyzed codebase                               │
+│ +  etch-loop/SCAN.md                               │
+│ +  etch-loop/ETCH.md                               │
+│ +  etch-loop/BREAK.md                              │
+│ +  etch-loop/RUN.md                                │
+╰────────────────────────────────────────────────────╯
+```
+
+| File | Purpose |
+|---|---|
+| `etch-loop/SCAN.md` | Scanner prompt — what to look for and how to report findings |
+| `etch-loop/ETCH.md` | Fixer prompt — surgical fixes only, no refactoring |
+| `etch-loop/BREAK.md` | Breaker prompt — adversarial review of changed files |
+| `etch-loop/RUN.md` | Runner prompt — write tests, run suite, clean up |
+
+All four files are editable. The `etch-loop/` directory is excluded from analysis so etch never reads its own files as part of your codebase.
+
+Run reports are saved to `etch-loop/etch-reports/` after each run.
+
+---
+
+## reports
+
+After every run, a markdown report is saved to `etch-loop/etch-reports/`:
+
+```
+etch-loop/etch-reports/etch-report-2026-03-10-15-31.md
+```
+
+It contains the full iteration log — what each phase found, what was fixed, and runner results.
+
+---
+
+## requirements
+
+- Python 3.11+
+- [`claude`](https://claude.ai/code) CLI installed and authenticated
+- A git repository (optional — use `--no-git` to skip all git operations)

etch_loop-0.6.0/README.md

@@ -0,0 +1,126 @@
+```
+  ███████╗████████╗ ██████╗██╗  ██╗
+  ██╔════╝╚══██╔══╝██╔════╝██║  ██║
+  █████╗     ██║   ██║     ███████║
+  ██╔══╝     ██║   ██║     ██╔══██║
+  ███████╗   ██║   ╚██████╗██║  ██║
+  ╚══════╝   ╚═╝    ╚═════╝╚═╝  ╚═╝  loop
+```
+
+> Run Claude Code in a scan-fix-break loop until your codebase is clean.
+
+---
+
+```
+╭───────────────────────── etch loop v0.5.5  my-project ─────────────────────────╮
+│ -  iteration  1                                                                 │
+│ x  scanner    issues found   3 bugs — null deref auth.py:42, off-by-one...     │
+│ +  fixer      committed      fixed 3 issues — null guard in auth.py, bounds... │
+│ x  breaker    issues         unguarded access still reachable in session.py     │
+│ -  iteration  2                                                                 │
+│ +  scanner    all clear      no confirmed bugs found                            │
+│ +  runner     all clear      wrote 4 tests, all 31 passed                      │
+╰───────────────── iterations 2   fixes 1   breaker issues 1   3m 12s elapsed ───╯
+```
+
+---
+
+## install
+
+```bash
+uv tool install etch-loop
+```
+
+Or with pip:
+
+```bash
+pip install etch-loop
+```
+
+## usage
+
+```bash
+etch init                        # analyze codebase, write prompt files to etch-loop/
+etch run                         # start the loop
+etch run "the auth module"       # focus on a specific area
+etch run -n 5                    # max 5 iterations
+etch run --no-commit             # fix without committing
+etch run --no-git                # disable all git operations
+etch run --dry-run               # preview prompt, don't run
+etch run --verbose               # stream full Claude output
+```
+
+---
+
+## how it works
+
+Each iteration runs four phases: **scan → fix → break**, then once everything is clean: **run**.
+
+### 1. Scanner
+Reads the codebase and produces a precise list of confirmed bugs — file paths, line numbers, one-line descriptions. Only genuine issues, no style notes.
+
+### 2. Fixer
+Receives the scanner's list and fixes exactly those issues. Commits each fix with a summary message. Does not refactor or touch code unrelated to the reported bugs.
+
+### 3. Breaker
+Adversarially reviews only the files the fixer just changed, looking for anything introduced or missed. If it finds nothing, the loop stops clean. If it finds issues, the next iteration's scanner re-checks those specific spots to confirm what's actually still broken.
+
+### 4. Runner *(final step)*
+Runs only when the loop exits cleanly. Writes targeted tests for what was changed, runs the full test suite, then deletes the test files it created. Reports pass/fail.
+
+```
+loop exits clean
+       │
+       ▼
+   [ runner ]  →  writes tests  →  runs suite  →  cleans up  →  ETCH_ALL_CLEAR
+```
+
+Each agent writes a short `<etch_summary>` that appears directly in the terminal dashboard. The fixer's summary doubles as the git commit message.
+
+---
+
+## etch init
+
+`etch init` runs Claude against your codebase, detects languages and structure, then writes four prompt files tailored to your project into an `etch-loop/` subfolder. No placeholders to fill in.
+
+```
+╭─ etch init v0.5.5 ────────────────────────────────╮
+│ >  analyzing   ░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░   │
+│ +  analyzed codebase                               │
+│ +  etch-loop/SCAN.md                               │
+│ +  etch-loop/ETCH.md                               │
+│ +  etch-loop/BREAK.md                              │
+│ +  etch-loop/RUN.md                                │
+╰────────────────────────────────────────────────────╯
+```
+
+| File | Purpose |
+|---|---|
+| `etch-loop/SCAN.md` | Scanner prompt — what to look for and how to report findings |
+| `etch-loop/ETCH.md` | Fixer prompt — surgical fixes only, no refactoring |
+| `etch-loop/BREAK.md` | Breaker prompt — adversarial review of changed files |
+| `etch-loop/RUN.md` | Runner prompt — write tests, run suite, clean up |
+
+All four files are editable. The `etch-loop/` directory is excluded from analysis so etch never reads its own files as part of your codebase.
+
+Run reports are saved to `etch-loop/etch-reports/` after each run.
+
+---
+
+## reports
+
+After every run, a markdown report is saved to `etch-loop/etch-reports/`:
+
+```
+etch-loop/etch-reports/etch-report-2026-03-10-15-31.md
+```
+
+It contains the full iteration log — what each phase found, what was fixed, and runner results.
+
+---
+
+## requirements
+
+- Python 3.11+
+- [`claude`](https://claude.ai/code) CLI installed and authenticated
+- A git repository (optional — use `--no-git` to skip all git operations)

{etch_loop-0.5.4 → etch_loop-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "etch-loop"
-version = "0.5.4"
+version = "0.6.0"
 requires-python = ">=3.11"
 description = "Run Claude Code in a fix-break loop until your codebase is clean"
 readme = "README.md"

etch_loop-0.6.0/src/etch/__init__.py

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

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/agent.py

@@ -59,7 +59,7 @@ def run(
         try:
             process.stdin.write(prompt)
             process.stdin.close()
-        except OSError as exc:
+        except (OSError, ValueError) as exc:
             stdin_exc.append(exc)
 
     stdin_writer = threading.Thread(target=write_stdin, daemon=True)
@@ -67,18 +67,24 @@ def run(
     stdin_writer.join(timeout=30)
     if stdin_writer.is_alive():
         process.kill()
-        process.wait()
+        try:
+            process.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            pass
         try:
             process.stdin.close()
-        except OSError:
+        except (OSError, ValueError):
             pass
         raise AgentError("Timed out writing prompt to claude stdin")
     if stdin_exc:
         process.kill()
-        process.wait()
+        try:
+            process.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            pass
         try:
             process.stdin.close()
-        except OSError:
+        except (OSError, ValueError):
             pass
         raise AgentError(f"Failed to write prompt to claude stdin: {stdin_exc[0]}") from stdin_exc[0]
 
@@ -107,7 +113,10 @@ def run(
     reader.join(timeout=timeout)
     if reader.is_alive():
         process.kill()
-        process.wait()
+        try:
+            process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            pass
         stderr_reader.join(timeout=10)
         if stderr_reader.is_alive():
             with lock:
@@ -118,7 +127,10 @@ def run(
         process.wait(timeout=10)
     except subprocess.TimeoutExpired:
         process.kill()
-        process.wait()
+        try:
+            process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            pass
         raise AgentError("claude subprocess timed out waiting for exit")
 
     stderr_reader.join(timeout=10)

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/analyze.py

@@ -50,6 +50,7 @@ _FRAMEWORK_HINTS: dict[str, str] = {
 _SKIP_DIRS = {
     ".git", "node_modules", "__pycache__", ".venv", "venv", "env",
     "dist", "build", ".next", "target", "vendor", ".cache",
+    "etch-loop",  # etch metadata — never part of the codebase being analyzed
 }
 
 
@@ -173,7 +174,7 @@ For each issue, include the file path, line number (if known), and a one-line de
 ## Rules
 
 1. DO NOT edit any files — read only
-   **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
+   **DO NOT read any file inside `etch-loop/`** — those are etch tool config files, not your codebase
 2. Only report issues you are confident are genuine bugs — not observations, not style, not "could be cleaner"
 3. If something is already handled correctly, do NOT report it — even if the handling is unusual
 4. If you are unsure whether something is a bug, leave it out
@@ -214,7 +215,7 @@ Scan the codebase for:
 
 ## Rules
 
-0. **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
+0. **DO NOT read or edit any file inside `etch-loop/`** — those are etch tool config files. Editing them corrupts the tool and is never a valid fix.
 1. Fix only what you find — do not refactor, rename, or reorganize
 2. Do not add comments explaining what you fixed
 3. If you find nothing, make no changes
@@ -257,7 +258,7 @@ Be adversarial — think like someone actively trying to make this code fail.
 ## Rules
 
 1. DO NOT edit any files — read only
-   **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
+   **DO NOT read any file inside `etch-loop/`** — those are etch tool config files, not your codebase
 2. Report your findings clearly, one per line
 3. Before the signal token, write your summary in this exact format — it appears directly in the terminal:
    `<etch_summary>2 issues — unguarded empty list in sorter.py:14, exception swallowed in loader.py:67</etch_summary>`

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/cli.py

@@ -93,6 +93,12 @@ def run(
         help="Stream agent output to the terminal.",
         is_flag=True,
     ),
+    user: bool = typer.Option(
+        False,
+        "--user",
+        help="Add a user-perspective lens: scanner and breaker also look for realistic user inputs and sequences that the code doesn't handle.",
+        is_flag=True,
+    ),
 ) -> None:
     """Run the fix-break loop against the current repository.
 
@@ -111,6 +117,7 @@ def run(
             dry_run=dry_run,
             verbose=verbose,
             focus=focus,
+            user=user,
         )
     except KeyboardInterrupt:
         display.print_interrupted()

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/loop.py

@@ -11,6 +11,25 @@ from etch.git import GitError
 from etch.prompt import PromptError, load_scan
 
 
+_USER_PERSPECTIVE = """
+## User perspective (additional lens)
+
+Also think about this code from the perspective of a real end user interacting with it.
+What inputs, sequences, or behaviors would a realistic user trigger that the code doesn't handle?
+
+Look for:
+- Empty, whitespace-only, or missing inputs where the code assumes content
+- Inputs at the edges of what the interface allows (very long strings, zero, negative numbers)
+- Unexpected but valid orderings of operations (calling things out of sequence)
+- Malformed or non-UTF-8 data coming from files, network, or user input
+- Concurrent use (two users/processes doing the same thing simultaneously)
+- Users who skip optional steps, then trigger code that assumed they ran
+- Realistic typos or near-valid inputs that bypass validation
+
+Report only cases where the code would actually fail or behave incorrectly — not hypothetical misuse.
+"""
+
+
 def run(
     prompt_path: str | Path,
     max_iterations: int = 20,
@@ -19,6 +38,7 @@ def run(
     dry_run: bool = False,
     verbose: bool = False,
     focus: str | None = None,
+    user: bool = False,
 ) -> None:
     """Run the scan-fix-break loop."""
     prompt_path = Path(prompt_path)
@@ -60,6 +80,10 @@ def run(
         scan_text += f"\n\n## User focus\n\nConcentrate on: {focus}\n"
         break_text += f"\n\n## User focus\n\nConcentrate your adversarial review on: {focus}\n"
 
+    if user:
+        scan_text += _USER_PERSPECTIVE
+        break_text += _USER_PERSPECTIVE
+
     start_time = time.monotonic()
     stats: dict = {
         "iterations": 0,
@@ -178,6 +202,17 @@ def run(
 
             # ── Commit ────────────────────────────────────────────────────────
             if no_git or changed:
+                _raw_summary = (
+                    signals.extract_summary(_fixer_output)
+                    or signals.extract_commit_message(_fixer_output, fallback="")
+                )
+                if no_git and (not _raw_summary or _raw_summary.lower().startswith("nothing")):
+                    disp.finish_phase("fixer", status="no changes", detail="nothing to fix",
+                                      duration=fixer_duration, success=True)
+                    iter_entry["fixer"] = {"status": "no changes", "detail": "nothing to fix"}
+                    stats["reason"] = "stalled" if last_breaker_signal == "issues" else "no_changes"
+                    iteration_log.append(iter_entry)
+                    break
                 fixer_summary = (
                     signals.extract_summary(_fixer_output)
                     or signals.extract_commit_message(_fixer_output, fallback="")

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/prompt.py

@@ -27,8 +27,8 @@ def load(path: str | Path) -> str:
 
     try:
         content = p.read_text(encoding="utf-8")
-    except FileNotFoundError:
-        raise PromptError(f"Prompt file not found: {p}")
+    except OSError as e:
+        raise PromptError(f"Cannot read prompt file: {p}: {e}") from e
     if not content.strip():
         raise PromptError(f"Prompt file is empty: {p}")
 
@@ -71,7 +71,7 @@ def load_break(path: str | Path | None = None) -> str:
         if candidate.exists() and candidate.is_file():
             try:
                 content = candidate.read_text(encoding="utf-8")
-            except FileNotFoundError:
+            except OSError:
                 continue
             if not content.strip():
                 raise PromptError(f"BREAK.md is empty: {candidate}")
@@ -105,7 +105,7 @@ def load_run(path: str | Path | None = None) -> str | None:
         if candidate.exists() and candidate.is_file():
             try:
                 content = candidate.read_text(encoding="utf-8")
-            except FileNotFoundError:
+            except OSError:
                 continue
             if not content.strip():
                 raise PromptError(f"RUN.md is empty: {candidate}")
@@ -137,7 +137,7 @@ def load_scan(path: str | Path | None = None) -> str:
         if candidate.exists() and candidate.is_file():
             try:
                 content = candidate.read_text(encoding="utf-8")
-            except FileNotFoundError:
+            except OSError:
                 continue
             if not content.strip():
                 raise PromptError(f"SCAN.md is empty: {candidate}")

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/templates/BREAK.md

@@ -18,7 +18,7 @@ Be adversarial — think like someone actively trying to make this code fail.
 ## Rules
 
 1. DO NOT edit any files — read only
-   **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
+   **DO NOT read any file inside `etch-loop/`** — those are etch tool config files, not your codebase
 2. Report your findings clearly, one per line
 3. Before the signal token, write your summary in this exact format — it appears directly in the terminal:
    `<etch_summary>2 issues — unguarded empty list in sorter.py:14, exception swallowed in loader.py:67</etch_summary>`

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/templates/ETCH.md

@@ -14,7 +14,7 @@ Scan the codebase for:
 
 ## Rules
 
-0. **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
+0. **DO NOT read or edit any file inside `etch-loop/`** — those are etch tool config files. Editing them corrupts the tool and is never a valid fix.
 1. Fix only what you find — do not refactor, rename, or reorganize
 2. Do not add comments explaining what you fixed
 3. If you find nothing, make no changes

{etch_loop-0.5.4 → etch_loop-0.6.0}/src/etch/templates/SCAN.md

@@ -17,7 +17,7 @@ For each issue, include the file path, line number (if known), and a one-line de
 ## Rules
 
 1. DO NOT edit any files — read only
-   **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
+   **DO NOT read any file inside `etch-loop/`** — those are etch tool config files, not your codebase
 2. Only report issues you are confident are genuine bugs — not observations, not style, not "could be cleaner"
 3. If something is already handled correctly, do NOT report it — even if the handling is unusual
 4. If you are unsure whether something is a bug, leave it out

{etch_loop-0.5.4 → etch_loop-0.6.0}/uv.lock

@@ -34,7 +34,7 @@ wheels = [
 
 [[package]]
 name = "etch-loop"
-version = "0.5.2"
+version = "0.5.5"
 source = { editable = "." }
 dependencies = [
     { name = "rich" },

etch_loop-0.5.4/PKG-INFO

@@ -1,117 +0,0 @@
-Metadata-Version: 2.4
-Name: etch-loop
-Version: 0.5.4
-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
-
-```
-  ███████╗████████╗ ██████╗██╗  ██╗
-  ██╔════╝╚══██╔══╝██╔════╝██║  ██║
-  █████╗     ██║   ██║     ███████║
-  ██╔══╝     ██║   ██║     ██╔══██║
-  ███████╗   ██║   ╚██████╗██║  ██║
-  ╚══════╝   ╚═╝    ╚═════╝╚═╝  ╚═╝  loop
-```
-
-> Run Claude Code in a scan-fix-break loop until your codebase is clean.
-
----
-
-```
-┌─ etch loop v0.2.0  . ───────────────────────────────────────────────┐
-│                                                                      │
-│  -  iteration  1                                                     │
-│  +  scanner    issues found   src/auth.py:42 — no empty token check  │
-│  +  fixer      committed      fix(edge): guard empty token in auth   │
-│  x  breaker    issues         unguarded access still reachable       │
-│                                                                      │
-│  -  iteration  2                                                     │
-│  +  scanner    issues found   src/auth.py:61 — missing None check    │
-│  +  fixer      committed      fix(edge): null guard on session obj   │
-│  >  breaker    running        ░░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░   │
-│                                                                      │
-├──────────────────────────────────────────────────────────────────────┤
-│  iterations 2   fixes 2   breaker issues 1   1m 48s elapsed         │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## install
-
-```bash
-uv tool install etch-loop
-```
-
-## usage
-
-```bash
-etch init                        # analyze codebase with Claude, write prompt files
-etch run                         # start the loop
-etch run "the auth module"       # focus on a specific area
-etch run -n 5                    # max 5 iterations
-etch run --dry-run               # preview prompt, don't run
-etch run --verbose               # show full Claude output
-```
-
----
-
-## how it works
-
-Each iteration has three phases: **scan → fix → break**.
-
-1. **Scanner** reads the codebase and outputs a specific list of issues — file paths, line numbers, descriptions
-2. If the scanner finds nothing, the loop stops
-3. **Fixer** receives the scanner's list and fixes those exact issues, then commits
-4. **Breaker** adversarially reviews the full codebase, looking for anything missed or newly introduced
-5. If the breaker finds nothing, the loop stops — clean pass
-6. If the breaker finds something, it's fed back to the next iteration's fixer
-
-```
-┌─ done ───────────────────────────────────────────────────┐
-│                                                          │
-│  iterations      3                                       │
-│  fixes           3                                       │
-│  breaker issues  1                                       │
-│  elapsed         2m 44s                                  │
-│                                                          │
-└──────────────────────────────────────────────────────────┘
-```
-
----
-
-## etch init
-
-`etch init` runs Claude against your codebase before writing any files. It reads your source, detects the languages and structure, and generates three prompt files tailored to your project — no placeholders to edit.
-
-```
-┌─ etch init v0.2.0 ───────────────────────────────────────┐
-│  >  analyzing  ░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   │
-│  +  analyzed codebase                                    │
-│  +  SCAN.md                                              │
-│  +  ETCH.md                                              │
-│  +  BREAK.md                                             │
-└──────────────────────────────────────────────────────────┘
-```
-
-**`SCAN.md`** — tells the scanner what to look for and how to report findings.
-
-**`ETCH.md`** — tells the fixer how to fix things: surgical, no refactoring, one fix per commit.
-
-**`BREAK.md`** — tells the breaker to scan the full codebase adversarially and report anything that could go wrong.
-
-All three files are editable. Use `etch run "focus description"` to narrow the scope without editing files.
-
----
-
-## requirements
-
-- Python 3.11+
-- [`claude`](https://claude.ai/code) CLI installed and authenticated
-- A git repository (etch-loop commits each fix automatically)

etch_loop-0.5.4/README.md

@@ -1,105 +0,0 @@
-```
-  ███████╗████████╗ ██████╗██╗  ██╗
-  ██╔════╝╚══██╔══╝██╔════╝██║  ██║
-  █████╗     ██║   ██║     ███████║
-  ██╔══╝     ██║   ██║     ██╔══██║
-  ███████╗   ██║   ╚██████╗██║  ██║
-  ╚══════╝   ╚═╝    ╚═════╝╚═╝  ╚═╝  loop
-```
-
-> Run Claude Code in a scan-fix-break loop until your codebase is clean.
-
----
-
-```
-┌─ etch loop v0.2.0  . ───────────────────────────────────────────────┐
-│                                                                      │
-│  -  iteration  1                                                     │
-│  +  scanner    issues found   src/auth.py:42 — no empty token check  │
-│  +  fixer      committed      fix(edge): guard empty token in auth   │
-│  x  breaker    issues         unguarded access still reachable       │
-│                                                                      │
-│  -  iteration  2                                                     │
-│  +  scanner    issues found   src/auth.py:61 — missing None check    │
-│  +  fixer      committed      fix(edge): null guard on session obj   │
-│  >  breaker    running        ░░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░   │
-│                                                                      │
-├──────────────────────────────────────────────────────────────────────┤
-│  iterations 2   fixes 2   breaker issues 1   1m 48s elapsed         │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## install
-
-```bash
-uv tool install etch-loop
-```
-
-## usage
-
-```bash
-etch init                        # analyze codebase with Claude, write prompt files
-etch run                         # start the loop
-etch run "the auth module"       # focus on a specific area
-etch run -n 5                    # max 5 iterations
-etch run --dry-run               # preview prompt, don't run
-etch run --verbose               # show full Claude output
-```
-
----
-
-## how it works
-
-Each iteration has three phases: **scan → fix → break**.
-
-1. **Scanner** reads the codebase and outputs a specific list of issues — file paths, line numbers, descriptions
-2. If the scanner finds nothing, the loop stops
-3. **Fixer** receives the scanner's list and fixes those exact issues, then commits
-4. **Breaker** adversarially reviews the full codebase, looking for anything missed or newly introduced
-5. If the breaker finds nothing, the loop stops — clean pass
-6. If the breaker finds something, it's fed back to the next iteration's fixer
-
-```
-┌─ done ───────────────────────────────────────────────────┐
-│                                                          │
-│  iterations      3                                       │
-│  fixes           3                                       │
-│  breaker issues  1                                       │
-│  elapsed         2m 44s                                  │
-│                                                          │
-└──────────────────────────────────────────────────────────┘
-```
-
----
-
-## etch init
-
-`etch init` runs Claude against your codebase before writing any files. It reads your source, detects the languages and structure, and generates three prompt files tailored to your project — no placeholders to edit.
-
-```
-┌─ etch init v0.2.0 ───────────────────────────────────────┐
-│  >  analyzing  ░░░░░▓▒ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   │
-│  +  analyzed codebase                                    │
-│  +  SCAN.md                                              │
-│  +  ETCH.md                                              │
-│  +  BREAK.md                                             │
-└──────────────────────────────────────────────────────────┘
-```
-
-**`SCAN.md`** — tells the scanner what to look for and how to report findings.
-
-**`ETCH.md`** — tells the fixer how to fix things: surgical, no refactoring, one fix per commit.
-
-**`BREAK.md`** — tells the breaker to scan the full codebase adversarially and report anything that could go wrong.
-
-All three files are editable. Use `etch run "focus description"` to narrow the scope without editing files.
-
----
-
-## requirements
-
-- Python 3.11+
-- [`claude`](https://claude.ai/code) CLI installed and authenticated
-- A git repository (etch-loop commits each fix automatically)

etch_loop-0.5.4/etch-loop/BREAK.md

@@ -1,41 +0,0 @@
-# BREAK — breaker prompt
-
-You are an adversarial code reviewer. Your job is to find anything that could go wrong.
-
-## Your mission
-
-Scan the entire codebase with fresh eyes. Do not limit yourself to recent changes.
-
-Look for:
-- Edge cases and boundary conditions that are unhandled anywhere in the code
-- Functions that assume valid input without checking
-- Error paths that are silently swallowed or ignored
-- Race conditions, off-by-one errors, null/empty/zero not guarded
-- Anything that would cause unexpected behavior in production
-
-Be adversarial — think like someone actively trying to make this code fail.
-
-## Rules
-
-1. DO NOT edit any files — read only
-   **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
-2. Report your findings clearly, one per line
-3. Before the signal token, write your summary in this exact format — it appears directly in the terminal:
-   `<etch_summary>2 issues — unguarded empty list in sorter.py:14, exception swallowed in loader.py:67</etch_summary>`
-   `<etch_summary>no issues found — code looks solid</etch_summary>`
-   **IMPORTANT: write `<etch_summary>` ONLY in your text response — never inside any file you read or edit.**
-4. End with EXACTLY one of these on its own line:
-   `ETCH_ISSUES_FOUND`
-   `ETCH_ALL_CLEAR`
-
-## Scope
-
-- `loop.py`: The no_git/no_commit branch logic at line 181 (`if no_git or changed`) can reach the commit block even when `changed` is False if `no_git=True`, silently skipping the `git.has_changes()` call entirely. The `last_breaker_signal` fall-through at line 174 (fixer sees "no changes" but breaker had prior issues) proceeds to breaker without committing — the iteration state machine has several interacting flags that can produce silent no-ops.
-
-- `agent.py`: The `stderr_reader` thread is joined with a 10-second timeout but its aliveness is never checked; a hung stderr drain can silently drop error output. If `process.kill()` is called after the stdout reader times out, `process.wait()` is called but `stderr_reader` may still be running, causing a race on `stderr_lines`.
-
-- `signals.py` / `extract_commit_message`: The heuristic line-picker can return a token string (e.g. `ETCH_ISSUES_FOUND`) as a commit message if the token appears after other text rather than on its own line, since `parse()` requires exact-line match but `extract_commit_message` does not exclude token lines.
-
-- `git.py` / `has_changes`: Exit code 128 (no commits yet) falls through to `git status --porcelain`, which correctly handles new repos, but `git diff --quiet HEAD` on an empty repo also silently ignores any staged changes — newly staged files in a repo with no HEAD commit would still register as changes, so the two-step detection logic is correct but fragile.
-
-- `prompt.py`: `load_break` and `load_scan` deduplicate the cwd candidate only when `path` is already cwd — if `path.parent == cwd`, both the sibling candidate and the cwd fallback point to the same file, causing it to be read twice in the loop (harmless but surprising). More critically, `load_run` returns `None` for an empty `RUN.md` rather than raising, silently skipping the runner phase with no feedback.

etch_loop-0.5.4/etch-loop/ETCH.md

@@ -1,40 +0,0 @@
-# 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
-
-0. **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
-1. Fix only what you find — do not refactor, rename, or reorganize
-2. Do not add comments explaining what you fixed
-3. If you find nothing, make no changes
-
-## Scope
-
-- `loop.py`: The no_git/no_commit branch logic at line 181 (`if no_git or changed`) can reach the commit block even when `changed` is False if `no_git=True`, silently skipping the `git.has_changes()` call entirely. The `last_breaker_signal` fall-through at line 174 (fixer sees "no changes" but breaker had prior issues) proceeds to breaker without committing — the iteration state machine has several interacting flags that can produce silent no-ops.
-
-- `agent.py`: The `stderr_reader` thread is joined with a 10-second timeout but its aliveness is never checked; a hung stderr drain can silently drop error output. If `process.kill()` is called after the stdout reader times out, `process.wait()` is called but `stderr_reader` may still be running, causing a race on `stderr_lines`.
-
-- `signals.py` / `extract_commit_message`: The heuristic line-picker can return a token string (e.g. `ETCH_ISSUES_FOUND`) as a commit message if the token appears after other text rather than on its own line, since `parse()` requires exact-line match but `extract_commit_message` does not exclude token lines.
-
-- `git.py` / `has_changes`: Exit code 128 (no commits yet) falls through to `git status --porcelain`, which correctly handles new repos, but `git diff --quiet HEAD` on an empty repo also silently ignores any staged changes — newly staged files in a repo with no HEAD commit would still register as changes, so the two-step detection logic is correct but fragile.
-
-- `prompt.py`: `load_break` and `load_scan` deduplicate the cwd candidate only when `path` is already cwd — if `path.parent == cwd`, both the sibling candidate and the cwd fallback point to the same file, causing it to be read twice in the loop (harmless but surprising). More critically, `load_run` returns `None` for an empty `RUN.md` rather than raising, silently skipping the runner phase with no feedback.
-
-## Terminal output (required)
-
-After making changes (or deciding there is nothing to fix), write your summary in this exact format — it appears in the terminal and is used as the commit message:
-  `<etch_summary>fixed 3 issues — null guard in auth.py, bounds check in parser.py, timeout in agent.py</etch_summary>`
-  `<etch_summary>nothing to fix — all reported issues were already handled</etch_summary>`
-
-**IMPORTANT: write `<etch_summary>` ONLY in your text response — never inside any file you edit or create.**

etch_loop-0.5.4/etch-loop/RUN.md

@@ -1,36 +0,0 @@
-# RUN — test writer and build validator
-
-You are a test engineer. The fixer has just made changes. Your job is to write tests for what was changed, then run the full suite to confirm everything works.
-
-## Your mission
-
-1. **Write or update tests** — look at what the fixer changed and write targeted tests covering:
-   - The specific edge cases that were fixed
-   - Boundary conditions around the changed code
-   - Any regression paths that could break silently
-   Write tests in the project's existing test style and location.
-
-2. **Run the test suite** — run the full build and test commands to confirm everything passes.
-
-## Build and test commands
-
-- `python -m pytest`
-
-## Rules
-
-0. **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
-1. You MAY edit test files — that is your job
-2. Do NOT touch production code — only tests
-3. If tests fail because of flawed test logic, fix the test and re-run before reporting
-4. **After tests pass, clean up everything you created during this session:**
-   - Delete every test file you wrote
-   - Delete any `__pycache__` directories inside the test directory
-   - If you created the test directory itself, remove it entirely (e.g. `rm -rf tests/`)
-   - Leave no temporary files or empty directories behind
-5. When done, write your summary in this exact format — it appears directly in the terminal:
-   `<etch_summary>wrote 4 tests, all 51 passed</etch_summary>`
-   `<etch_summary>2 tests failed — TypeError in test_auth.py:38, production bug in token.py:12</etch_summary>`
-   **IMPORTANT: write `<etch_summary>` ONLY in your text response — never inside any file you edit or create.**
-6. End with EXACTLY one of these on its own line:
-   `ETCH_ALL_CLEAR` — if all tests pass
-   `ETCH_ISSUES_FOUND` — if tests reveal a bug in production code

etch_loop-0.5.4/etch-loop/SCAN.md

@@ -1,45 +0,0 @@
-# SCAN — scanner prompt
-
-You are a code analyst. Your job is to find genuine bugs before the fixer runs.
-
-## Your mission
-
-Read the codebase and produce a precise, actionable list of real issues:
-- Unhandled edge cases and boundary conditions
-- Missing null/None/empty checks that will cause crashes or wrong results
-- Unhandled exceptions and error paths
-- Off-by-one errors
-- Race conditions or unsafe concurrent access
-- Missing input validation at system boundaries
-
-For each issue, include the file path, line number (if known), and a one-line description of what will go wrong.
-
-## Rules
-
-1. DO NOT edit any files — read only
-   **IGNORE the `etch-loop/` directory entirely** — it contains etch tool metadata, not production code
-2. Only report issues you are confident are genuine bugs — not observations, not style, not "could be cleaner"
-3. If something is already handled correctly, do NOT report it — even if the handling is unusual
-4. If you are unsure whether something is a bug, leave it out
-5. List each confirmed issue on its own line, e.g.:
-   - src/auth.py:42 — crashes with empty token string (no guard)
-   - src/api.js:108 — unhandled promise rejection will silently fail
-6. Before the signal token, write your summary in this exact format — it appears directly in the terminal:
-   `<etch_summary>3 bugs found — null deref in auth.py:42, off-by-one in parser.py:88</etch_summary>`
-   `<etch_summary>no confirmed bugs found</etch_summary>`
-   **IMPORTANT: write `<etch_summary>` ONLY in your text response — never inside any file you read or edit.**
-7. End with EXACTLY one of these on its own line:
-   `ETCH_ISSUES_FOUND`
-   `ETCH_ALL_CLEAR`
-
-## Scope
-
-- `loop.py`: The no_git/no_commit branch logic at line 181 (`if no_git or changed`) can reach the commit block even when `changed` is False if `no_git=True`, silently skipping the `git.has_changes()` call entirely. The `last_breaker_signal` fall-through at line 174 (fixer sees "no changes" but breaker had prior issues) proceeds to breaker without committing — the iteration state machine has several interacting flags that can produce silent no-ops.
-
-- `agent.py`: The `stderr_reader` thread is joined with a 10-second timeout but its aliveness is never checked; a hung stderr drain can silently drop error output. If `process.kill()` is called after the stdout reader times out, `process.wait()` is called but `stderr_reader` may still be running, causing a race on `stderr_lines`.
-
-- `signals.py` / `extract_commit_message`: The heuristic line-picker can return a token string (e.g. `ETCH_ISSUES_FOUND`) as a commit message if the token appears after other text rather than on its own line, since `parse()` requires exact-line match but `extract_commit_message` does not exclude token lines.
-
-- `git.py` / `has_changes`: Exit code 128 (no commits yet) falls through to `git status --porcelain`, which correctly handles new repos, but `git diff --quiet HEAD` on an empty repo also silently ignores any staged changes — newly staged files in a repo with no HEAD commit would still register as changes, so the two-step detection logic is correct but fragile.
-
-- `prompt.py`: `load_break` and `load_scan` deduplicate the cwd candidate only when `path` is already cwd — if `path.parent == cwd`, both the sibling candidate and the cwd fallback point to the same file, causing it to be read twice in the loop (harmless but surprising). More critically, `load_run` returns `None` for an empty `RUN.md` rather than raising, silently skipping the runner phase with no feedback.

etch_loop-0.5.4/src/etch/__init__.py

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