jeffy-loop 1.23.0__py3-none-any.whl

jeffy_loop/__init__.py

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

jeffy_loop/cli.py

@@ -0,0 +1,334 @@
+"""Console entry point for the Jeffy Loop.
+
+The engine is a Claude Code skill plus a Stop hook, both shipped inside this
+package under jeffy_loop/skills. This module is the Python-native equivalent of
+install.sh and install.ps1: it checks the prerequisites, copies the two skill
+folders into the user's Claude Code skills directory, and registers the Stop
+hook in settings.json with the same idempotence and timeout rules.
+"""
+
+import contextlib
+import json
+import os
+import shutil
+import stat
+import sys
+from importlib import metadata, resources
+from pathlib import Path
+
+DISTRIBUTION = "jeffy-loop"
+SKILL_NAMES = ("jeffy", "cancel-jeffy")
+HOOK_FRAGMENT = "skills/jeffy/hooks/stop-hook.sh"
+HOOK_TIMEOUT = 1800
+
+
+def package_version():
+    try:
+        return metadata.version(DISTRIBUTION)
+    except metadata.PackageNotFoundError:
+        from jeffy_loop import __version__
+
+        return __version__
+
+
+def engine_version(skills_root):
+    hook = skills_root / "jeffy" / "hooks" / "stop-hook.sh"
+    if not hook.is_file():
+        raise SystemExit(f"jeffy: packaged Stop hook not found at {hook}")
+    for line in hook.read_text(encoding="utf-8").splitlines():
+        if line.startswith("JEFFY_VERSION="):
+            return line.split("=", 1)[1].strip().strip('"')
+    raise SystemExit(f"jeffy: no JEFFY_VERSION line in {hook}")
+
+
+def claude_home():
+    return Path.home() / ".claude"
+
+
+def which(name):
+    return shutil.which(name) is not None
+
+
+def check_prerequisites():
+    ok = True
+    if which("claude"):
+        print("[OK] Claude Code CLI found")
+    else:
+        print("[MISSING] Claude Code CLI. Install it first: https://claude.com/claude-code")
+        ok = False
+    if which("jq"):
+        print("[OK] jq found")
+    elif os.name == "nt":
+        print(
+            "[MISSING] jq. Install it manually: winget install jqlang.jq "
+            "(or see https://jqlang.github.io/jq/download/)"
+        )
+        ok = False
+    else:
+        print(
+            "[MISSING] jq. Install it with your package manager "
+            "(brew install jq / sudo apt install jq)"
+        )
+        ok = False
+    return ok
+
+
+def relative_files(root):
+    return sorted(
+        p.relative_to(root) for p in root.rglob("*") if p.is_file()
+    )
+
+
+def install_skills(skills_root):
+    for name in SKILL_NAMES:
+        src = skills_root / name
+        if not (src / "SKILL.md").is_file():
+            raise SystemExit(f"jeffy: packaged skills/{name}/SKILL.md not found at {src}")
+        dest = claude_home() / "skills" / name
+        dest.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(src, dest, dirs_exist_ok=True)
+        # A copy over the top never removes. Files the shipped tree no longer
+        # carries are removed, and nothing else.
+        for rel in relative_files(dest):
+            if not (src / rel).exists():
+                (dest / rel).unlink()
+                print(f"[OK] removed {dest / rel} (no longer shipped)")
+        print(f"[OK] /{name} skill installed to {dest}")
+
+
+def make_hook_executable():
+    if os.name == "nt":
+        return
+    hook = claude_home() / "skills" / "jeffy" / "hooks" / "stop-hook.sh"
+    if hook.is_file():
+        mode = hook.stat().st_mode
+        hook.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def hook_command():
+    hook = claude_home() / "skills" / "jeffy" / "hooks" / "stop-hook.sh"
+    path = str(hook)
+    if os.name == "nt":
+        # The command runs under bash (Git Bash on Windows), as install.ps1 writes it.
+        path = path.replace("\\", "/")
+    return f'bash "{path}"'
+
+
+def matching_hooks(settings):
+    hooks = settings.get("hooks")
+    if not isinstance(hooks, dict):
+        return []
+    stop = hooks.get("Stop")
+    if not isinstance(stop, list):
+        return []
+    found = []
+    for entry in stop:
+        if not isinstance(entry, dict):
+            continue
+        inner = entry.get("hooks")
+        if not isinstance(inner, list):
+            continue
+        for hook in inner:
+            if isinstance(hook, dict) and HOOK_FRAGMENT in str(hook.get("command", "")):
+                found.append(hook)
+    return found
+
+
+def write_settings(path, settings):
+    path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+
+
+def register_hook():
+    settings_path = claude_home() / "settings.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    if settings_path.is_file() and settings_path.stat().st_size > 0:
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            print(
+                f"[FAILED] {settings_path} is not valid JSON; fix it, then "
+                "re-run this installer to register the hook."
+            )
+            return False
+        if not isinstance(settings, dict):
+            print(
+                f"[FAILED] {settings_path} is not valid JSON; fix it, then "
+                "re-run this installer to register the hook."
+            )
+            return False
+    else:
+        settings = {}
+
+    found = matching_hooks(settings)
+    if found:
+        # A pre-1.2 registration lacks the timeout field and a 1.2-1.14
+        # registration carries 600s, which the verify bound can exceed (P1-58).
+        # Either shape moves to 1800s exactly once.
+        stale = [h for h in found if "timeout" not in h or h["timeout"] == 600]
+        if not stale:
+            print(f"[OK] Jeffy Stop hook already registered in {settings_path}")
+            return True
+        for hook in stale:
+            hook["timeout"] = HOOK_TIMEOUT
+        write_settings(settings_path, settings)
+        print(
+            f"[OK] Jeffy Stop hook registration upgraded to an 1800s timeout in {settings_path}"
+        )
+        return True
+
+    entry = {
+        "hooks": [
+            {"type": "command", "command": hook_command(), "timeout": HOOK_TIMEOUT}
+        ]
+    }
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        print(
+            f"[FAILED] could not update {settings_path}; add the Stop hook entry "
+            "by hand (see README) and re-run to verify."
+        )
+        return False
+    stop = hooks.setdefault("Stop", [])
+    if not isinstance(stop, list):
+        print(
+            f"[FAILED] could not update {settings_path}; add the Stop hook entry "
+            "by hand (see README) and re-run to verify."
+        )
+        return False
+    stop.append(entry)
+    write_settings(settings_path, settings)
+    print(f"[OK] Jeffy Stop hook registered in {settings_path} (1800s timeout)")
+    return True
+
+
+def cmd_install(skills_root):
+    print("Jeffy installer")
+    print("")
+    ok = check_prerequisites()
+    install_skills(skills_root)
+    make_hook_executable()
+    if not register_hook():
+        ok = False
+    print("")
+    if ok:
+        print("Done. Start a new Claude Code session in any project and run: /jeffy")
+        return 0
+    print("Skills installed, but fix the items above, then re-run this installer to verify.")
+    return 1
+
+
+def cmd_uninstall():
+    for name in SKILL_NAMES:
+        dest = claude_home() / "skills" / name
+        if dest.is_dir():
+            shutil.rmtree(dest)
+            print(f"[OK] removed {dest}")
+        else:
+            print(f"[OK] {dest} was not installed")
+
+    settings_path = claude_home() / "settings.json"
+    if not (settings_path.is_file() and settings_path.stat().st_size > 0):
+        print(f"[OK] no {settings_path} to clean")
+        return 0
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        print(
+            f"[FAILED] {settings_path} is not valid JSON; fix it, then re-run "
+            "to remove the hook."
+        )
+        return 1
+    if not isinstance(settings, dict):
+        print(
+            f"[FAILED] {settings_path} is not valid JSON; fix it, then re-run "
+            "to remove the hook."
+        )
+        return 1
+
+    hooks = settings.get("hooks")
+    stop = hooks.get("Stop") if isinstance(hooks, dict) else None
+    if not isinstance(stop, list):
+        print(f"[OK] no Jeffy Stop hook in {settings_path}")
+        return 0
+
+    removed = 0
+    kept_entries = []
+    for entry in stop:
+        if not isinstance(entry, dict) or not isinstance(entry.get("hooks"), list):
+            kept_entries.append(entry)
+            continue
+        kept_hooks = []
+        for hook in entry["hooks"]:
+            if isinstance(hook, dict) and HOOK_FRAGMENT in str(hook.get("command", "")):
+                removed += 1
+            else:
+                kept_hooks.append(hook)
+        if kept_hooks:
+            entry["hooks"] = kept_hooks
+            kept_entries.append(entry)
+        elif not entry["hooks"]:
+            kept_entries.append(entry)
+    if removed == 0:
+        print(f"[OK] no Jeffy Stop hook in {settings_path}")
+        return 0
+    if kept_entries:
+        hooks["Stop"] = kept_entries
+    else:
+        del hooks["Stop"]
+    write_settings(settings_path, settings)
+    print(f"[OK] removed the Jeffy Stop hook from {settings_path}")
+    return 0
+
+
+def cmd_version(skills_root):
+    pkg = package_version()
+    engine = engine_version(skills_root)
+    print(f"jeffy-loop {pkg} (engine JEFFY_VERSION {engine} from the packaged stop-hook.sh)")
+    if pkg != engine:
+        print(
+            f"jeffy: version mismatch. The package says {pkg} and the packaged "
+            f"stop-hook.sh says {engine}. The package was built without the "
+            "release bump; bump JEFFY_VERSION in skills/jeffy/hooks/stop-hook.sh "
+            "or the version in pyproject.toml so they agree, then rebuild.",
+            file=sys.stderr,
+        )
+        return 2
+    return 0
+
+
+def cmd_help():
+    print("jeffy install    install both skills and register the Stop hook in settings.json")
+    print("jeffy uninstall  remove both skills and the Jeffy Stop hook entry")
+    print("jeffy version    print the package version and the packaged engine version")
+    print("jeffy path       print the packaged skills directory")
+    return 0
+
+
+def main():
+    args = sys.argv[1:]
+    cmd = args[0] if args else "help"
+
+    if cmd in ("help", "--help", "-h"):
+        return cmd_help()
+    if cmd == "uninstall":
+        return cmd_uninstall()
+    if cmd not in ("install", "version", "--version", "path"):
+        print(f"jeffy: unknown command: {cmd}", file=sys.stderr)
+        cmd_help()
+        return 2
+
+    with contextlib.ExitStack() as stack:
+        root = stack.enter_context(resources.as_file(resources.files("jeffy_loop")))
+        skills_root = Path(root) / "skills"
+        if not skills_root.is_dir():
+            raise SystemExit(f"jeffy: packaged skills directory not found at {skills_root}")
+        if cmd == "path":
+            print(skills_root)
+            return 0
+        if cmd in ("version", "--version"):
+            return cmd_version(skills_root)
+        return cmd_install(skills_root)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jeffy_loop/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/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.