jeffy-loop 1.23.0__tar.gz

jeffy_loop-1.23.0/.gitignore

@@ -0,0 +1,53 @@
+.DS_Store
+Thumbs.db
+
+# Python bytecode - evals/records/repro.py generates this when run or compiled,
+# and the loop's git add -A checkpoints would otherwise sweep it in
+__pycache__/
+
+# Jeffy transient loop state - session-scoped, must never be committed
+# (jeffy-loop.local.md is the 2.0 engine's file; ralph-loop.local.md is legacy)
+.claude/jeffy-loop.local.md
+.claude/ralph-loop.local.md
+
+# Jeffy self-hosting state - dev logs from running Jeffy on this repo, not part
+# of the product. Anchored to the repo root so a future nested product doc with
+# one of these names is not silently ignored.
+/PLAN.md
+/BACKLOG.md
+/JOURNAL.md
+/JOURNAL-archive.md
+/STATUS.md
+
+/CHANGELOG.md
+
+# Launch and announcement drafts - not part of the product
+/reddit_post.md
+/reddit_post.MD
+
+# Avatar and profile art working files - the shipped product images live in
+# media/, so these are anchored to the repo root only
+/jeffy-avatar*.png
+/jeffy.jpg
+
+# Session dev logs - class patterns so future logs are covered by default
+# (both casings spelled out: gitignore matching is case-sensitive on Linux)
+/FABLE*.md
+/FABLE*.MD
+/Fable*.md
+/Fable*.MD
+
+# Versioned release-planning docs (plan4.7.md, plan4.8.md, ...) - maintainer
+# working notes, not product. Digit-anchored so a future product doc called
+# plan-something.md is not silently ignored, and both casings spelled out for
+# the same reason as the dev-log patterns above. Without this a self-run's
+# `git add -A` checkpoint sweeps them into the public history.
+/plan[0-9]*.md
+/plan[0-9]*.MD
+/Plan[0-9]*.md
+/PLAN[0-9]*.md
+
+# Python package build output (uv build) - never product
+/dist/
+/build/
+*.egg-info/

jeffy_loop-1.23.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Jeff Lenamon and the Jeffy Loop contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jeffy_loop-1.23.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: jeffy-loop
+Version: 1.23.0
+Summary: The Jeffy Loop: an autonomous audit-and-fix loop for Claude Code, with proof.
+Project-URL: Repository, https://github.com/lenamonj/jeffy-loop
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/lenamonj/jeffy-loop/main/media/banner-dark.png">
+  <img src="https://raw.githubusercontent.com/lenamonj/jeffy-loop/main/media/banner-light.png" alt="Jeffy Loop - point it at a project, give it a budget, come back to a better codebase and a report" width="900">
+</picture>
+
+[![Validate](https://img.shields.io/github/actions/workflow/status/lenamonj/jeffy-loop/validate.yml?style=for-the-badge&label=validate&logo=githubactions&logoColor=white)](https://github.com/lenamonj/jeffy-loop/actions/workflows/validate.yml)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-Skill-D97757?style=for-the-badge&logo=claude&logoColor=white)](https://claude.com/claude-code)
+![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Mac%20%7C%20Linux-0EA5E9?style=for-the-badge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge)](https://github.com/lenamonj/jeffy-loop/blob/main/LICENSE)
+
+**[Quickstart](#quickstart)** &nbsp;·&nbsp; **[Usage](https://github.com/lenamonj/jeffy-loop/blob/main/docs/usage.md)** &nbsp;·&nbsp; **[How it works](https://github.com/lenamonj/jeffy-loop/blob/main/docs/how-it-works.md)** &nbsp;·&nbsp; **[The receipts](https://github.com/lenamonj/jeffy-loop/blob/main/evals/README.md)** &nbsp;·&nbsp; **[Headless](https://github.com/lenamonj/jeffy-loop/blob/main/docs/headless.md)** &nbsp;·&nbsp; **[White paper](https://github.com/lenamonj/jeffy-loop/raw/main/The-Jeffy-Loop.pdf)**
+
+## Autonomous Engineering With Proof
+
+> **Agents that don’t just act.**  
+> They audit · verify · attack · and prove.
+
+</div>
+
+Jeffy Loop is an autonomous engineering system built around a simple principle: **AI agents shouldn’t just produce work. They should produce evidence that the work is correct.** Instead of asking an agent to complete a task and trusting its conclusion, Jeffy creates a continuous **Audit → Attack → Verify → Prove** loop in which specialized agents inspect the work, challenge it, validate the result, and generate an auditable record of what happened. The goal isn’t simply autonomous code generation; it is **autonomous engineering with proof** - where every claimed result is accompanied by reproducible evidence that can be independently examined.
+
+**Jeffy treats “done” as something that must be demonstrated, not declared.** The system is designed to turn autonomous engineering from a conversational interaction into an evidence-producing process: actions leave traces, decisions have provenance, failures are exposed rather than hidden, and successful outcomes produce a durable receipt of what was changed, why it was changed, and how the result was verified.
+
+## The proof
+
+Jeffy was run against <!-- count:tested -->132<!-- /count --> open-source projects with no connection to this repository, each judged by its own test suite, every run published, failures included.
+
+| Projects tested | Converged | Failed | PRs merged | PRs open | Issues filed |
+|:---:|:---:|:---:|:---:|:---:|:---:|
+| **<!-- count:tested -->132<!-- /count -->** | **<!-- count:converged -->103<!-- /count -->** | **<!-- count:failed -->28<!-- /count -->** | **<!-- count:merged -->24<!-- /count -->** | **<!-- count:prs-open -->37<!-- /count -->** | **<!-- count:issues -->4<!-- /count -->** |
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/lenamonj/jeffy-loop/main/media/language-pie-dark.png">
+  <img src="https://raw.githubusercontent.com/lenamonj/jeffy-loop/main/media/language-pie-light.png" alt="Pie chart of the 103 converged public targets by language: Python 20 at 19.4 percent, Rust 14 at 13.6 percent, Go 12 at 11.7 percent, JavaScript 10 at 9.7 percent, C++ 7 at 6.8 percent, Java 6 at 5.8 percent, Ruby 6 at 5.8 percent, Swift 6 at 5.8 percent, C 5 at 4.9 percent, PHP 5 at 4.9 percent, TypeScript 5 at 4.9 percent, Kotlin 4 at 3.9 percent, C# 3 at 2.9 percent." width="900">
+</picture>
+
+<sub><!-- count:converged -->103<!-- /count --> projects run to convergence across <!-- count:languages -->13<!-- /count --> languages with no language-specific analyzer or ruleset. Derived from the scorecard at render time.</sub>
+
+</div>
+
+## Independent Validation
+
+A merged pull request is the one result Jeffy cannot award itself. It takes an independent maintainer, someone with no stake in this project, to review the patch and accept it into their own codebase. Maintainers across <!-- count:merged-projects -->21<!-- /count --> open source projects have done exactly that, including:
+
+- **Google, [snappy](https://github.com/google/snappy/pull/257)** - every release build compressed a 4 GiB input into a stream whose header claimed 0 bytes; merged the morning after filing.
+- **Apple (2)**
+  - [swift-log](https://github.com/apple/swift-log/pull/504) - a documented no-op setter asserted instead; merged after the maintainer asked for the doc-only form.
+  - [swift-protobuf](https://github.com/apple/swift-protobuf/pull/2164) - the project's own CMake build of `protoc-gen-swift` had not compiled since June; approved and merged the day it was filed.
+- **Microsoft, [mimalloc](https://github.com/microsoft/mimalloc/pull/1385)** - the zeroing allocator returned uninitialized memory above the small-size threshold; merged by the author the same day.
+- **Apache (2)**
+  - [commons-text](https://github.com/apache/commons-text/pull/768) - a `StringMatcher` overload forwarded the buffer end as its start; merged the morning after review.
+  - [commons-csv](https://github.com/apache/commons-csv/pull/633) - the record counter's Javadoc said headers were not counted while the constructor's header was; corrected, merged three days after filing.
+- **JetBrains, [kotlinx-datetime](https://github.com/Kotlin/kotlinx-datetime/pull/650)** - deprecation quick-fixes pointed developers at the wrong replacement; merged within two hours.
+- **Node.js, [ada](https://github.com/ada-url/ada/pull/1244)** - the URL parser reported `host_end` one byte short; merged twelve minutes after filing.
+
+**[Every project, every patch, and every failure](https://github.com/lenamonj/jeffy-loop/blob/main/evals/README.md)**
+
+## Quickstart
+
+You need [Claude Code](https://claude.com/claude-code), signed in once, and [git](https://git-scm.com/downloads). The installer handles everything else, including `jq`.
+
+```bash
+git clone https://github.com/lenamonj/jeffy-loop.git
+cd jeffy-loop
+./install.sh        # Windows PowerShell: .\install.ps1
+```
+
+Or, with [uv](https://docs.astral.sh/uv/), no clone needed:
+
+```bash
+uv tool install jeffy-loop
+jeffy install
+```
+
+> [!NOTE]
+> If PowerShell refuses with "running scripts is disabled on this system", run `powershell -ExecutionPolicy Bypass -File .\install.ps1` once.
+
+Open Claude Code in the project you want to improve and type `/jeffy 10`. It is a slash command inside the session, not a shell command. If you only want the Highs found and fixed, type `/jeffy 10 --highs`; it stops at the first audit that finds none, so it is usually the faster run ([High hunt](https://github.com/lenamonj/jeffy-loop/blob/main/docs/usage.md#high-hunt)). When the run ends, start a new session to run it again; [the restart is doing real work](https://github.com/lenamonj/jeffy-loop/blob/main/docs/usage.md#use-several-short-runs-not-one-long-one).
+
+## Five guarantees
+
+Each one is enforced by the iteration prompt, the state files, or the Stop hook. [How.](https://github.com/lenamonj/jeffy-loop/blob/main/docs/how-it-works.md#five-guarantees)
+
+1. **It audits like an engineer, not a linter.** A finding exists only when the loop can point at it and prove it with a runnable check.
+2. **It cannot wreck your repo.** Every iteration is a local commit, a broken verify is reverted, and nothing is ever pushed.
+3. **"Done" is not the agent's opinion.** An adversarial evaluator and a shell gate re-check every declaration.
+4. **It cannot claim what it never looked at.** The whole public surface goes on a checklist before any finding is filed.
+5. **Lessons become machinery.** A rule learned once binds every later iteration, and the engine itself passes <!-- count:checks -->**347 behavioural checks**<!-- /count --> on Linux, Windows and macOS.
+
+## Documentation
+
+| Page | What it covers |
+|:---|:---|
+| [Usage](https://github.com/lenamonj/jeffy-loop/blob/main/docs/usage.md) | Flags, rounds and budgets, scoped mode, cancelling, [upgrading](https://github.com/lenamonj/jeffy-loop/blob/main/docs/usage.md#already-installed-upgrade), uninstalling, and what to know before a first run |
+| [How it works](https://github.com/lenamonj/jeffy-loop/blob/main/docs/how-it-works.md) | The run lifecycle, the five guarantees, the full rule set, what a converged stop looks like, and how the loop improves itself |
+| [Headless runs](https://github.com/lenamonj/jeffy-loop/blob/main/docs/headless.md) | Running budgeted rounds unattended from bash or PowerShell |
+| [The receipts](https://github.com/lenamonj/jeffy-loop/blob/main/evals/README.md) | Every open-source target with its outcome, the merged patches, the greenfield builds |
+| [Contributing](https://github.com/lenamonj/jeffy-loop/blob/main/CONTRIBUTING.md) | The validator and the review bar |
+| [White paper](https://github.com/lenamonj/jeffy-loop/raw/main/The-Jeffy-Loop.pdf) | For readers new to agent loops: how loops got here, every rule from first principles, and what this method still cannot do |
+
+> [!IMPORTANT]
+> **Trust model.** The engine is one shell script, `skills/jeffy/hooks/stop-hook.sh`, plus the small library beside it in `skills/jeffy/hooks/lib/`, registered as a Claude Code Stop hook. In a session with no live Jeffy state file it exits at once and does nothing. The installer writes two skill folders under `~/.claude/skills`, one hook entry in `~/.claude/settings.json`, and, only if you say yes when `jq` is missing, a `jq` install through your package manager.
+
+## License
+
+MIT

jeffy_loop-1.23.0/README.md

@@ -0,0 +1,110 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="media/banner-dark.png">
+  <img src="media/banner-light.png" alt="Jeffy Loop - point it at a project, give it a budget, come back to a better codebase and a report" width="900">
+</picture>
+
+[![Validate](https://img.shields.io/github/actions/workflow/status/lenamonj/jeffy-loop/validate.yml?style=for-the-badge&label=validate&logo=githubactions&logoColor=white)](https://github.com/lenamonj/jeffy-loop/actions/workflows/validate.yml)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-Skill-D97757?style=for-the-badge&logo=claude&logoColor=white)](https://claude.com/claude-code)
+![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Mac%20%7C%20Linux-0EA5E9?style=for-the-badge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge)](LICENSE)
+
+**[Quickstart](#quickstart)** &nbsp;·&nbsp; **[Usage](docs/usage.md)** &nbsp;·&nbsp; **[How it works](docs/how-it-works.md)** &nbsp;·&nbsp; **[The receipts](evals/README.md)** &nbsp;·&nbsp; **[Headless](docs/headless.md)** &nbsp;·&nbsp; **[White paper](https://github.com/lenamonj/jeffy-loop/raw/main/The-Jeffy-Loop.pdf)**
+
+## Autonomous Engineering With Proof
+
+> **Agents that don’t just act.**  
+> They audit · verify · attack · and prove.
+
+</div>
+
+Jeffy Loop is an autonomous engineering system built around a simple principle: **AI agents shouldn’t just produce work. They should produce evidence that the work is correct.** Instead of asking an agent to complete a task and trusting its conclusion, Jeffy creates a continuous **Audit → Attack → Verify → Prove** loop in which specialized agents inspect the work, challenge it, validate the result, and generate an auditable record of what happened. The goal isn’t simply autonomous code generation; it is **autonomous engineering with proof** - where every claimed result is accompanied by reproducible evidence that can be independently examined.
+
+**Jeffy treats “done” as something that must be demonstrated, not declared.** The system is designed to turn autonomous engineering from a conversational interaction into an evidence-producing process: actions leave traces, decisions have provenance, failures are exposed rather than hidden, and successful outcomes produce a durable receipt of what was changed, why it was changed, and how the result was verified.
+
+## The proof
+
+Jeffy was run against <!-- count:tested -->132<!-- /count --> open-source projects with no connection to this repository, each judged by its own test suite, every run published, failures included.
+
+| Projects tested | Converged | Failed | PRs merged | PRs open | Issues filed |
+|:---:|:---:|:---:|:---:|:---:|:---:|
+| **<!-- count:tested -->132<!-- /count -->** | **<!-- count:converged -->103<!-- /count -->** | **<!-- count:failed -->28<!-- /count -->** | **<!-- count:merged -->24<!-- /count -->** | **<!-- count:prs-open -->37<!-- /count -->** | **<!-- count:issues -->4<!-- /count -->** |
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="media/language-pie-dark.png">
+  <img src="media/language-pie-light.png" alt="Pie chart of the 103 converged public targets by language: Python 20 at 19.4 percent, Rust 14 at 13.6 percent, Go 12 at 11.7 percent, JavaScript 10 at 9.7 percent, C++ 7 at 6.8 percent, Java 6 at 5.8 percent, Ruby 6 at 5.8 percent, Swift 6 at 5.8 percent, C 5 at 4.9 percent, PHP 5 at 4.9 percent, TypeScript 5 at 4.9 percent, Kotlin 4 at 3.9 percent, C# 3 at 2.9 percent." width="900">
+</picture>
+
+<sub><!-- count:converged -->103<!-- /count --> projects run to convergence across <!-- count:languages -->13<!-- /count --> languages with no language-specific analyzer or ruleset. Derived from the scorecard at render time.</sub>
+
+</div>
+
+## Independent Validation
+
+A merged pull request is the one result Jeffy cannot award itself. It takes an independent maintainer, someone with no stake in this project, to review the patch and accept it into their own codebase. Maintainers across <!-- count:merged-projects -->21<!-- /count --> open source projects have done exactly that, including:
+
+- **Google, [snappy](https://github.com/google/snappy/pull/257)** - every release build compressed a 4 GiB input into a stream whose header claimed 0 bytes; merged the morning after filing.
+- **Apple (2)**
+  - [swift-log](https://github.com/apple/swift-log/pull/504) - a documented no-op setter asserted instead; merged after the maintainer asked for the doc-only form.
+  - [swift-protobuf](https://github.com/apple/swift-protobuf/pull/2164) - the project's own CMake build of `protoc-gen-swift` had not compiled since June; approved and merged the day it was filed.
+- **Microsoft, [mimalloc](https://github.com/microsoft/mimalloc/pull/1385)** - the zeroing allocator returned uninitialized memory above the small-size threshold; merged by the author the same day.
+- **Apache (2)**
+  - [commons-text](https://github.com/apache/commons-text/pull/768) - a `StringMatcher` overload forwarded the buffer end as its start; merged the morning after review.
+  - [commons-csv](https://github.com/apache/commons-csv/pull/633) - the record counter's Javadoc said headers were not counted while the constructor's header was; corrected, merged three days after filing.
+- **JetBrains, [kotlinx-datetime](https://github.com/Kotlin/kotlinx-datetime/pull/650)** - deprecation quick-fixes pointed developers at the wrong replacement; merged within two hours.
+- **Node.js, [ada](https://github.com/ada-url/ada/pull/1244)** - the URL parser reported `host_end` one byte short; merged twelve minutes after filing.
+
+**[Every project, every patch, and every failure](evals/README.md)**
+
+## Quickstart
+
+You need [Claude Code](https://claude.com/claude-code), signed in once, and [git](https://git-scm.com/downloads). The installer handles everything else, including `jq`.
+
+```bash
+git clone https://github.com/lenamonj/jeffy-loop.git
+cd jeffy-loop
+./install.sh        # Windows PowerShell: .\install.ps1
+```
+
+Or, with [uv](https://docs.astral.sh/uv/), no clone needed:
+
+```bash
+uv tool install jeffy-loop
+jeffy install
+```
+
+> [!NOTE]
+> If PowerShell refuses with "running scripts is disabled on this system", run `powershell -ExecutionPolicy Bypass -File .\install.ps1` once.
+
+Open Claude Code in the project you want to improve and type `/jeffy 10`. It is a slash command inside the session, not a shell command. If you only want the Highs found and fixed, type `/jeffy 10 --highs`; it stops at the first audit that finds none, so it is usually the faster run ([High hunt](docs/usage.md#high-hunt)). When the run ends, start a new session to run it again; [the restart is doing real work](docs/usage.md#use-several-short-runs-not-one-long-one).
+
+## Five guarantees
+
+Each one is enforced by the iteration prompt, the state files, or the Stop hook. [How.](docs/how-it-works.md#five-guarantees)
+
+1. **It audits like an engineer, not a linter.** A finding exists only when the loop can point at it and prove it with a runnable check.
+2. **It cannot wreck your repo.** Every iteration is a local commit, a broken verify is reverted, and nothing is ever pushed.
+3. **"Done" is not the agent's opinion.** An adversarial evaluator and a shell gate re-check every declaration.
+4. **It cannot claim what it never looked at.** The whole public surface goes on a checklist before any finding is filed.
+5. **Lessons become machinery.** A rule learned once binds every later iteration, and the engine itself passes <!-- count:checks -->**347 behavioural checks**<!-- /count --> on Linux, Windows and macOS.
+
+## Documentation
+
+| Page | What it covers |
+|:---|:---|
+| [Usage](docs/usage.md) | Flags, rounds and budgets, scoped mode, cancelling, [upgrading](docs/usage.md#already-installed-upgrade), uninstalling, and what to know before a first run |
+| [How it works](docs/how-it-works.md) | The run lifecycle, the five guarantees, the full rule set, what a converged stop looks like, and how the loop improves itself |
+| [Headless runs](docs/headless.md) | Running budgeted rounds unattended from bash or PowerShell |
+| [The receipts](evals/README.md) | Every open-source target with its outcome, the merged patches, the greenfield builds |
+| [Contributing](CONTRIBUTING.md) | The validator and the review bar |
+| [White paper](https://github.com/lenamonj/jeffy-loop/raw/main/The-Jeffy-Loop.pdf) | For readers new to agent loops: how loops got here, every rule from first principles, and what this method still cannot do |
+
+> [!IMPORTANT]
+> **Trust model.** The engine is one shell script, `skills/jeffy/hooks/stop-hook.sh`, plus the small library beside it in `skills/jeffy/hooks/lib/`, registered as a Claude Code Stop hook. In a session with no live Jeffy state file it exits at once and does nothing. The installer writes two skill folders under `~/.claude/skills`, one hook entry in `~/.claude/settings.json`, and, only if you say yes when `jq` is missing, a `jq` install through your package manager.
+
+## License
+
+MIT

jeffy_loop-1.23.0/hatch_build.py

@@ -0,0 +1,24 @@
+"""Rewrite the README for PyPI at build time.
+
+PyPI renders the project description from README.md but cannot resolve
+relative paths, so images under assets/ and links to files in the repository
+render broken there. This hook turns every relative src, srcset and markdown
+link into an absolute GitHub URL in the built metadata only; the README in the
+repository stays relative, which is what GitHub wants.
+"""
+import os
+import re
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+class ReadmeHook(MetadataHookInterface):
+    def update(self, metadata):
+        repo = self.config["repo"]
+        raw = f"https://raw.githubusercontent.com/{repo}/main/"
+        blob = f"https://github.com/{repo}/blob/main/"
+        with open(os.path.join(self.root, "README.md"), encoding="utf-8") as f:
+            text = f.read()
+        text = re.sub(r'((?:src|srcset)=")(?!https?://)([^"]+)"', lambda m: f'{m.group(1)}{raw}{m.group(2)}"', text)
+        text = re.sub(r'\]\((?!https?://|#|mailto:)([^)\s]+)\)', lambda m: f"]({blob}{m.group(1)})", text)
+        metadata["readme"] = {"content-type": "text/markdown", "text": text}

jeffy_loop-1.23.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jeffy-loop"
+version = "1.23.0"
+description = "The Jeffy Loop: an autonomous audit-and-fix loop for Claude Code, with proof."
+dynamic = ["readme"]
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.scripts]
+jeffy = "jeffy_loop.cli:main"
+
+[project.urls]
+Repository = "https://github.com/lenamonj/jeffy-loop"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jeffy_loop"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/jeffy" = "jeffy_loop/skills/jeffy"
+"skills/cancel-jeffy" = "jeffy_loop/skills/cancel-jeffy"
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "src/jeffy_loop",
+  "hatch_build.py",
+  "skills/jeffy",
+  "skills/cancel-jeffy",
+  "README.md",
+  "LICENSE",
+]
+
+[tool.hatch.metadata.hooks.custom]
+path = "hatch_build.py"
+repo = "lenamonj/jeffy-loop"

jeffy_loop-1.23.0/skills/cancel-jeffy/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: cancel-jeffy
+description: Use when the user runs /cancel-jeffy to stop the active Jeffy improvement loop in the current project
+disable-model-invocation: true
+---
+
+# Cancel Jeffy
+
+Stop the Jeffy loop in this project by removing the loop state file the Stop hook reads.
+
+1. Project root is the directory Claude Code was started in, not wherever the shell currently sits: the Bash tool's cwd persists across calls and may have drifted into a subdirectory that holds its own orphaned state file from another session. Always check state files with absolute paths anchored at the project root, never bare relative ones.
+2. Check `<project-root>/.claude/jeffy-loop.local.md`. If it exists, read its frontmatter and report its session_id, iteration, and started_at, then delete the file and confirm the loop is cancelled. Once the file is gone the Stop hook lets the session end normally.
+3. Also check `<project-root>/.claude/ralph-loop.local.md`: it belongs to the ralph-loop plugin's engine or a pre-2.0 Jeffy. If it exists, report the same frontmatter fields and delete it too, so no legacy loop keeps re-feeding.
+4. If neither file exists, report that no Jeffy loop is active in this project and stop.
+5. Remind the user that PLAN.md, BACKLOG.md, and JOURNAL.md are untouched: the loop picks up where it left off the next time they run /jeffy.

jeffy_loop-1.23.0/skills/jeffy/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: jeffy
+description: Use when the user runs /jeffy to start an autonomous Jeffy improvement loop on the current project
+disable-model-invocation: true
+argument-hint: "[N] [--highs] [focus...]"
+---
+
+# Jeffy
+
+Bootstrap per-project Jeffy state files, write the loop state file, and begin iteration 1. The loop engine is Jeffy's own Stop hook, shipped with this skill at hooks/stop-hook.sh: at every turn end it reads `.claude/jeffy-loop.local.md` at the project root, and while that file names this session and budget remains it re-feeds the iteration prompt; it deletes the file and lets the session end when the budget is spent, the completion promise fires, or one of its own gates ends the run - a stall, an oscillation, a time ceiling, the sweep fail-fast, or an audit or refill inside the closing window. The hook anchors itself to CLAUDE_PROJECT_DIR, which hooks receive fixed at the directory Claude Code was started in, so shell cwd drift mid-iteration cannot kill the loop. The hook is registered machine-wide in `~/.claude/settings.json` by the installer but exits immediately in any session whose project has no state file. This skill only sets up and launches; the hook implements the loop mechanics.
+
+Project root means the directory Claude Code was started in - the session's primary working directory shown in the environment, which is stable regardless of shell drift. Resolve it to an absolute path with forward slashes and use it everywhere below; never trust the shell's current cwd, which persists across Bash calls and may have drifted into a subdirectory.
+
+## Arguments
+
+Parse $ARGUMENTS: if the first token is an integer, it is the iteration budget N, default 10, or 5 on a `--highs` launch. Next parse the mode flag and the ceiling flags wherever they appear in the remainder. `--highs` takes no value and selects High-hunt mode for this run: the loop audits the whole surface, fixes only Highs, audits again once no High is open, and closes the first time an audit finds none - no sweep obligation, no Medium or Low queue, no evaluator gate, no closing extension and no convergence claim; a hunt is not a convergence and its receipt is the pull request its Highs produce. The ceiling flags each take one value: `--max-time <duration>` sets `max_wall_clock_seconds`, `--max-iter-time <duration>` sets `max_iteration_seconds`, and `--max-context <N>` sets `max_context_growth`; a duration is a bare number of seconds or a number suffixed `s`, `m`, or `h` (`45m`, `2h`, `900s`, `900`), and `0` means off, the default for all three. A flag missing its value, an unparseable duration, or an unrecognized `--` token is a refusal naming the token, never silently folded into the focus - a documented ceiling that becomes free text is a ceiling that is silently off. Whatever text remains after the budget and the flags is the focus directive for this run. If the token after the optional budget is exactly `enhance`, refuse the launch and stop: Enhance mode was removed in v1.11.0 - the defect loop is the product - and the last release that carries it is v1.10.0. On a fresh project, iteration 1 is always consumed by the audit that generates the backlog, so N=2 executes exactly one task; if the user picks N below 5, proceed but note that larger budgets make materially more progress.
+
+## Step 1: Pre-flight
+
+If any check fails, stop and report the exact fix needed. Do no other work first.
+
+1. Hook dependency: `which jq`. If missing the Stop hook cannot parse its input and the loop cannot run. Suggest `winget install jqlang.jq` (Windows), `brew install jq` (macOS), or `sudo apt-get install jq` (Debian/Ubuntu) and stop.
+2. Hook install: locate Jeffy's Stop hook script, substituting the absolute home directory and using forward slashes even on Windows (`~` is not expanded by this tool). Glob for `<home>/.claude/skills/jeffy/hooks/stop-hook.sh`. If it is missing, the install is broken or predates the self-owned engine; tell the user to re-run the installer (install.sh or install.ps1) and stop. If it exists, the hook must also be registered: read `<home>/.claude/settings.json` and confirm some Stop hook command contains `skills/jeffy/hooks/stop-hook.sh`. If the registration is missing, tell the user to re-run the installer, which registers it, and stop. When the project root itself carries `skills/jeffy/hooks/stop-hook.sh` - a checkout of Jeffy, the one project where the engine under development is also the engine driving the loop - compare that file with the installed one byte for byte and say so in one line when they differ: the loop is driven by the installed copy, so whatever the tree has fixed since is not in force, and the suite grades a file the run never executes. Compare content, never JEFFY_VERSION, which is equal across a divergence by construction because a development tree carries the next release's fixes under the current version string. This never blocks and never prompts: an unmatched pair is the ordinary state of a tree mid-change, and the remedy - re-running install.sh - belongs to the operator and must not be taken mid-run, since it would swap the engine between iterations.
+3. Session identity: `echo "$CLAUDE_CODE_SESSION_ID"` must print a non-empty id. If empty, the state file would be written without session scoping and the loop would capture every Claude session in this project. Stop.
+4. Existing loop state: if `.claude/jeffy-loop.local.md` exists at the project root, do not assume a loop is active. Read its frontmatter and compare its `session_id` with the current session id:
+   - Equal: this session already has a loop running. Stop.
+   - Different or missing: either another live session owns it or, far more often, it is an orphan from a closed session. The hook deletes the file only when its own session's run ends - at the budget, the promise, or one of its gates - so a crashed or closed session leaks it forever. Report the file's session_id, started_at, and iteration, then ask the user: if no other session is running Jeffy in this project, confirm deletion and continue; otherwise stop. Never delete the file without explicit confirmation.
+   Also check for a legacy `.claude/ralph-loop.local.md` at the project root: it belongs to the ralph-loop plugin's engine (or a pre-2.0 Jeffy). If present, a ralph-loop-driven loop may still be active in another session; report it and ask the user to cancel or delete it before launching, so two engines never interleave in one project.
+5. Checkpoint baseline: if the project is a git repository (`git rev-parse --is-inside-work-tree` succeeds), run `git status --porcelain` and ignore any path under `.jeffy/metrics/`. That file is the engine's own telemetry, written at the end of every turn including the one that ends a run - so the last write of any completed run necessarily lands after that run's final checkpoint and leaves the path modified with no iteration left to commit it. It is never the user's work, the next checkpoint sweeps it up, and treating it as a dirty tree stops every unattended second round dead: the question goes to a headless session that cannot answer it. If what remains prints anything, tell the user: the loop ends every iteration with a local checkpoint commit made with `git add -A`, so these uncommitted changes would be swept into the first checkpoint. Ask them to choose: commit or stash first (then relaunch), proceed anyway (their changes ride along in the first jeffy checkpoint), or abort. Never proceed silently past a dirty tree. When every modified path is a symlink in the index (`git ls-files -s` reports mode `120000` for each), say so explicitly: the likely cause is a cross-filesystem tree - Windows git cannot stat symlinks over `\\wsl.localhost` and reports them all modified - and the fix is running the loop from a git that lives on the same filesystem as the tree, not committing or stashing. If the project is not a git repository, note once that checkpoints, salvage, the ratchet, the verify-gate revert, and the stall check degrade to journal-only discipline, and continue.
+6. Verify command lint: if `PLAN.md` exists at the project root and its `## Verify command` section carries a `Command: ` line whose payload is neither `none` nor an unfilled `<...>` placeholder, sanitize that payload exactly as the hook does - trim the surrounding whitespace, then strip one wrapping pair of backticks when both ends carry one and nothing between them does - and run `bash -n` over the result. If it does not parse, report the exact defect (the first `bash -n` error line) and the exact corrected `Command: ` line to write into PLAN.md, then stop. Apply the same refusal when the payload contains a pipe and its final pipeline stage is a pager or truncator - `head`, `tail`, `less`, `more`, or `cat` - because the pipeline's exit status is then the truncator's, not the suite's, and a failing suite reports green; name the offending stage and tell the user to drop it. The hook executes that line verbatim at the converged stop, so a malformed line costs a rejected declaration at the end of a run instead of one message at its start. A missing PLAN.md, a section carrying no `Command: ` line, a payload of `none`, and a payload still wearing the template's `<first audit fills this in>` placeholder are all fine and stop nothing: the hook skips its own check on the first three, and the placeholder is the line the first audit exists to fill, so linting it would hard-stop every relaunch whose bootstrapped PLAN.md never reached that audit.
+7. Line-ending safety: if the project is a git repository and the platform is not Windows (or the project root is a Linux or WSL filesystem path), run `git config core.autocrlf`. If it prints `true` or `input`, refuse to launch: the loop's verify-gate revert path runs `git checkout`, which would rewrite every text file in the tree to CRLF and break the build while looking like a clean revert. Report the exact fix - run `git config core.autocrlf false` at the project root - and stop.
+8. Repository scope: if the project is a git repository, compare `git rev-parse --show-toplevel` with the project root. When they differ, the project is a subdirectory of a larger repository, so every checkpoint's `git add -A` stages changes across the whole parent tree. State both paths plainly and ask the user whether to proceed, exactly as the dirty-tree check does; working in a subdirectory is legitimate, so never refuse outright.
+9. Nested Jeffy project: glob for `*/.claude/jeffy-loop.local.md` and `*/PLAN.md` below the project root. If a nested directory carries Jeffy state files, surface its path and ask whether the user meant to launch there instead: launching above an existing Jeffy project sweeps that project's state files into this project's checkpoints.
+10. Budget echo: print one line the operator has to see before the state file is written - the resolved N, the project root, the base HEAD - and, when JOURNAL.md exists, two figures derived from its headings: the N of the most recent `## iter i/N` heading, and the count of distinct run ids across JOURNAL-archive.md and JOURNAL.md, so the line reads `Budget: N=<N> at <short HEAD> in <root>; run <k+1> of this project (previous run N=<n>)`. Derive them with `grep -h '^## iter [0-9]' JOURNAL.md | tail -n 1 | sed -n 's|^## iter [0-9]*/\([0-9]*\).*|\1|p'` and `cat JOURNAL-archive.md JOURNAL.md 2>/dev/null | grep '^## iter [0-9]' | cut -d'|' -f2 | tr -d ' ' | sort -u | wc -l`. The second reads the run id as a field rather than through a substitution, because the heading is pipe-delimited and a sed whose own delimiter appears three times inside its pattern is read as a truncated expression: written that way it printed an error and returned 0, so the line reported run 1 of every project forever. Both commands anchor on `[0-9]` so the grammar example in the journal template's preamble is not counted as an entry. Never ask and never stop on it: a headless session cannot answer a question and the campaign driver owns the budget; the line exists so a run launched at the wrong N, or a fifth run on a four-run pre-registration, is seen at launch rather than found afterwards.
+
+## Step 2: Bootstrap state files
+
+Create each file at the project root only if it is missing. The default contents live in this skill's references directory and are copied with cp, never read into context or retyped: the templates are large static payloads and the copy is byte-exact.
+
+First resolve REF, the absolute path of this skill's references directory. Glob for `<home>/.claude/skills/jeffy/references/iteration-prompt.txt`, substituting the absolute home directory with forward slashes as in pre-flight check 2. REF is the directory of the match. If nothing matches, stop and report a broken install: the references directory is missing, so re-run the installer. Substitute the resolved REF below and wherever later steps say REF.
+
+Mode guard: when PLAN.md already exists at the project root, read the first word of its `## Mode` section body. If it reads Enhance, refuse the launch: Enhance mode was removed in v1.11.0, and its ledger ranks work by impact rather than severity, so its state files must not continue under the standard rules. Tell the user to archive those state files first - commit them and delete them, or keep them on a separate branch or checkout - and relaunch standard, or to run v1.10.0, the last release that carries the mode; then stop. The same guard keys on the launch mode both ways: a `--highs` launch over a PLAN.md whose first Mode word is not High-hunt refuses, because a standard ledger carries Mediums a hunt must not work and a standard Converged history a hunt does not extend, and a launch without `--highs` over a PLAN.md whose first Mode word is High-hunt refuses, because a hunt ledger and its Hunted history mean nothing to the standard closing rule; both refusals name the same archive step and stop. Any other mode proceeds and reuses the existing state files exactly as any relaunch does; a PLAN.md with no `## Mode` section is a user-authored plan and is treated as standard.
+
+```bash
+REF="<resolved references dir>"
+PR="<PROJECT_ROOT>"
+PLAN_TPL=plan-default.md
+BACKLOG_TPL=backlog-default.md
+# On a --highs launch the two templates are the hunt ones instead:
+# PLAN_TPL=plan-highs.md
+# BACKLOG_TPL=backlog-highs.md
+[ -f "$PR/PLAN.md" ]    || cp "$REF/$PLAN_TPL"    "$PR/PLAN.md"
+[ -f "$PR/BACKLOG.md" ] || cp "$REF/$BACKLOG_TPL" "$PR/BACKLOG.md"
+[ -f "$PR/JOURNAL.md" ] || cp "$REF/journal-default.md" "$PR/JOURNAL.md"
+```
+
+On a `--highs` launch set PLAN_TPL to plan-highs.md and BACKLOG_TPL to backlog-highs.md as the commented lines show, before the copies run. The standard templates define Improvement mode (PLAN.md with the Goal, Operating envelope, Method, severity rubric, and Definition of done), the BACKLOG.md ledger sections (Now, Next, Later, Proposed, Settled classes, Declined, Converged), and the append-only JOURNAL.md heading grammar. The hunt templates define High-hunt mode (the same envelope, inventory, Verify command and rubric, a Definition of done that is one fresh audit finding no High) and a ledger of Highs only (Now, Proposed, Declined, Hunted); JOURNAL.md is shared, and its grammar carries the `hunted` status a hunt's closing entry takes. Edit the copies in the project to customize one run; edit the templates in references/ only to change every future run.
+
+All work happens directly in the current project folder on the current branch. When the project is a git repository, every iteration ends in a local checkpoint commit made with git add -A and a message prefixed jeffy:. The checkpoint is the loop's revert and recovery unit; nothing is ever pushed and no branches are created - the user reviews with git log and squashes if they want one commit. Because the checkpoint uses git add -A, also do this during bootstrap: if the project is a git repository and `git check-ignore -q .claude/jeffy-loop.local.md` fails, append `.claude/jeffy-loop.local.md` to the project's .gitignore (creating the file if needed) so the transient session-scoped loop state can never be committed.
+
+## Step 3: Launch the loop
+
+Verify bound first: when PLAN.md exists at the project root and carries a `Command: ` line under `## Verify command`, look there for a labeled line reading `Verify duration: <N>s` (a measured figure earlier runs record). The launcher computes no bound of its own: it resolves the same chain the hook resolves when the state file carries no key - `verify_timeout_seconds`, else `Verify duration` x3 floored at 240s, else 240s, capped at 1740s because the installer registers the hook with an 1800s timeout. Found: resolve that chain against the measured seconds and add a `verify_timeout_seconds: <bound>` line to the frontmatter written below, so the Stop hook's converged-stop verify re-run inherits a bound sized to this suite across relaunches. Absent, with a `Command: ` line present: ask the user one question - roughly how long does the verify command run? Resolve the chain against their answer: if it lands on the floor, write no line, because the hook applies that same floor by default; if it lands above the floor, write `verify_timeout_seconds: <that resolved bound>`. This threshold is the chain's rather than a separate one, so it moved when the chain became the single statement of the bound: the replaced text wrote no line for any answer under four minutes, where the chain writes one for any answer above eighty seconds, always wider than the floor it replaces and never narrower. An answer of a minute still writes no line, because three times it lands on the floor. No PLAN.md yet, or no `Command: ` line: write no line and move on; the first run measures, records `Verify duration:` in PLAN.md, and every later launch inherits it from there.
+
+Write the loop state file yourself, at the project root, with an absolute path. If focus text was given, sanitize it first: remove double quotes, backticks, dollar signs, and newlines, which would break the heredoc or the frontmatter, then substitute it below; with no focus, leave the value empty (the line stays, its value blank). Substitute PROJECT_ROOT, REF (resolved in Step 2), and N. `base_head` records the commit the run starts on, or `none` outside a repository; the Stop hook uses it to tell a genuine convergence ratchet, which re-declares a tree an earlier run certified, from a run that did the work itself and typed RATCHET over it. The heredoc terminator EOF must stay at column 0.
+
+```bash
+PR="<PROJECT_ROOT>"
+REF="<resolved references dir>"
+mkdir -p "$PR/.claude"
+cat > "$PR/.claude/jeffy-loop.local.md" <<EOF
+---
+session_id: $CLAUDE_CODE_SESSION_ID
+iteration: 1
+max_iterations: <N>
+prompt_path: $REF/<iteration-prompt-highs.txt on a --highs launch, else iteration-prompt.txt>
+focus: <sanitized focus, or empty>
+completion_promise: <JEFFY HUNT COMPLETE on a --highs launch, else JEFFY CONVERGED>
+<mode: highs on a --highs launch, else omit this line entirely>
+started_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+run_started_at: $(date +%s)
+iteration_started_at: $(date +%s)
+max_wall_clock_seconds: <seconds from --max-time, else 0>
+max_iteration_seconds: <seconds from --max-iter-time, else 0>
+max_context_growth: <multiple from --max-context, else 0>
+sandboxed: <yes|no|unknown from hooks/lib/detect-sandbox.sh>
+base_head: $(git -C "$PR" rev-parse HEAD 2>/dev/null || echo none)
+<verify_timeout_seconds line when derived above, else omit this line entirely>
+---
+Jeffy loop state. Session-scoped and transient: the Stop hook deletes it when
+the run ends. Cancel with /cancel-jeffy, or delete this file to end the loop.
+EOF
+grep -n "session_id\|iteration:" "$PR/.claude/jeffy-loop.local.md"
+```
+
+**Blast radius.** Run `bash <REF>/../hooks/lib/detect-sandbox.sh` at launch
+and record its answer as `sandboxed` in the state file. When it answers `no`,
+the launch banner carries one further line: *"Not sandboxed: this run has
+whatever access this shell has - credentials, SSH keys, tokens - and an
+unattended agent usually runs with permissions relaxed. See SECURITY.md."*
+On any other answer, say nothing. **It never blocks and never prompts.**
+The loop does not widen its own mandate, and it has no business narrowing the
+operator's either; what it owes them is one honest sentence about what is
+reachable, said once, before the run rather than after it.
+
+**Context pressure.** The engine re-feeds one session, so context accumulates
+within a run, and the corpus prices that: later runs of long targets re-filed
+findings earlier runs had already swept and scored clean. The hook measures it
+from the transcript the harness names on its stdin - the thing itself, rather
+than an iteration ordinal standing in for it - as a multiple of this run's own
+first measurement, which calibrates to the project instead of to a constant
+invented here. `--max-context <N>` sets `max_context_growth`; past N times the
+opening size, the re-feed carries a CONTEXT PRESSURE note recommending the run
+finish its current task and close, so the next one reads the state files with a
+clean window. **It is advice and never a stop**: the closing rule governs, and
+a pre-registered budget is never cut short by it. Off unless set, and the
+measured growth is reported in the run state either way.
+
+**Time ceilings.** A turn budget counts turns, and a turn is unbounded in
+time, so the state file carries two optional ceilings the Stop hook enforces
+at every turn end. Both are **0 (off) unless the launch sets them**, and that
+default is deliberate: this engine publishes no figure it has not measured,
+and the right ceiling belongs to the project rather than to the tool. For
+reference when choosing one, rounds of ten iterations in the published corpus
+run roughly 60 to 130 minutes. `--max-time <duration>` sets
+`max_wall_clock_seconds` and ends the run out of time the way exhaustion ends
+it out of turns; `--max-iter-time <duration>` sets `max_iteration_seconds`,
+after which a long iteration draws an ITERATION OVERRUN note and two
+consecutive overruns end the run. Accept `45m`, `2h`, `900s` or a bare
+integer of seconds, and `0` as an explicit opt-out. Neither ceiling can cut a
+turn short - the hook fires after it - and neither preempts the closing
+extension or a converged declaration. Whether a ceiling is set or not, the
+run state line reports elapsed wall time every iteration, so a run can see
+its own clock.
+
+Verify the write: the grep output must show the current session id and `iteration: 1`. If the session id line is empty or wrong, delete the file, report the failure, and stop. The state file carries the mode as three keys the Stop hook reads: `mode: highs` (absent on a standard launch, where every hook path is the one it always was), the promise phrase, and the prompt path. The iteration prompt itself is a single line stored at `$REF/iteration-prompt.txt`, or `$REF/iteration-prompt-highs.txt` for a hunt, which is the standard prompt with the convergence machinery deleted so every shared sentence stays byte-identical; the hook reads it from disk at every turn end and JSON-encodes it with jq, so its content never needs to be injected through the shell. Never edit iteration-prompt.txt casually: the loop's journal grammar, checkpoint discipline, run report, and closing rule all live in it, and it must stay a single line.
+
+Then announce the launch in one line - Jeffy v<version>, N iterations, the mode and its promise phrase (Improvement with JEFFY CONVERGED, or High-hunt with JEFFY HUNT COMPLETE), the focus if one was given, and the absolute path of the verify wrapper, `<REF>/../hooks/lib/quiet-verify.sh`, because the iteration prompt names it by its repository-relative path and a target project has no such path, and the absolute path of the Stop hook, `<REF>/../hooks/stop-hook.sh`, because the iteration prompt runs it in lint mode before every gate invocation - reading the version from the installed hook with `sed -n 's/^JEFFY_VERSION="\(.*\)"/\1/p' <home>/.claude/skills/jeffy/hooks/stop-hook.sh`, so every run's transcript opens by naming the engine version a bug report needs.
+
+## Step 4: Begin iteration 1
+
+Read "<REF>/iteration-prompt.txt" now, or "<REF>/iteration-prompt-highs.txt" on a `--highs` launch (REF as resolved in Step 2), its only in-context load, and immediately start following it yourself. Do not wait for input. Every later turn end triggers the Stop hook, which re-feeds the same prompt until N iterations complete, the promise fires, or the state file is deleted.
+
+## Operational notes
+
+- Cancel: run /cancel-jeffy (or delete `.claude/jeffy-loop.local.md`).
+- Permission prompts pause the loop. Unattended runs need test and file tools allowlisted, or acceptEdits mode. Never allowlist push or force operations for a loop.
+- A user message sent mid-loop gets answered and then the Stop hook re-feeds the iteration prompt, so a side question flows straight into the next iteration. The turn it consumed counts against the iteration budget, because the budget counts turns.
+- Prefer several small runs over one large budget. The hook re-feeds the same session, so context accumulates across iterations within a run; the state files persist between runs and convergence is sticky, so two runs of 5 beat one run of 10. The clean context is the whole point, and it only arrives with a new session: relaunching /jeffy in the session that just finished a run keeps every accumulated token and forfeits the benefit entirely. Close the session and start a new one in the same directory; the state files on disk carry the run forward, nothing is lost.
+- Edit PLAN.md or BACKLOG.md between iterations, not while one is running: a mid-iteration edit can collide with the loop's own in-flight edit. The Proposed section of BACKLOG.md is the designed channel for decisions.
+- Checkpoints: every iteration ends in a local commit prefixed jeffy:. Review a run with git log --oneline, revert a bad iteration by reverting its checkpoint, and squash the run into one commit if you want tidy history. Nothing is ever pushed.
+- One Jeffy loop per project at a time. The state file is transient; a crashed or closed session can leave it behind, which pre-flight check 4 handles. Orphans can also hide in subdirectories if a session was ever started there; they are inert for the hook, which anchors at the project root, but confuse relative-path checks, so always inspect state files with absolute paths.
+- Git hygiene: `.claude/jeffy-loop.local.md` is transient, session-scoped state that must never be committed. Bootstrap appends it to the target project's `.gitignore` automatically, because the checkpoint's git add -A would otherwise sweep it in. The three state files (PLAN.md, BACKLOG.md, JOURNAL.md) are meant to persist between runs and are committed by the checkpoints; that is intentional, they are the loop's memory.
+- If a loop ever dies silently mid-run (turn ends, no re-feed, state file frozen at its last iteration), the likely causes are: the hook was installed or registered after this session started (start a fresh session and relaunch); or the jeffy skills folder was moved or removed, so the state file's prompt_path went stale - the hook then ends the loop with a message to stderr, and re-running /jeffy relaunches with the new path.
+- When a run ends, the loop closes with a run report; JOURNAL.md and the checkpoint commits in git log hold the full record.