loopgate 0.1.0__py3-none-any.whl

harness/gate.py

@@ -0,0 +1,297 @@
+"""1) Preflight pre-commit checks basic quality plus agent containment. `def run_preflight`
+
+2) Full gate on staged files.
+`def run_gate` mirrors what will run on Github (CI runs this same `harness gate`).
+
+All containment lists and check commands come from [tool.harness] in pyproject.toml, read once at
+import into the constants below. A check is a (name, argv) pair; its `preflight`/`blocking` flags sort
+it into the maps and sets this module runs on.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from functools import cache
+from pathlib import Path
+
+import tomlkit as tomllib
+import typer
+from rich.console import Console
+
+from mutation.check_mutmut import MINIMUM_MUTATION_SCORE, analyze_mutmut_report_passed
+
+try:
+    from preferences.preferences import preferences_violations as prefs
+except ImportError:  # humans can delete preferences.py
+    prefs = None
+
+console = Console(force_terminal=True, color_system=None if os.environ.get("RALPH_LOOP") else "auto")
+
+
+class Gate:
+    """Contains Gate configuration values and methods."""
+
+    EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"  # universal empty tree hash
+
+    def __init__(self, root: Path) -> None:
+        self.repo_root = root
+        pyproject = self.repo_root / "pyproject.toml"
+        toml = tomllib.loads(pyproject.read_text(encoding="utf-8")).unwrap() if pyproject.is_file() else {}
+        harness = toml.get("tool", {}).get("harness")
+        if not harness:
+            defaults = tomllib.loads(Path(__file__).with_name("temp.pyproject.toml").read_text(encoding="utf-8"))
+            harness = defaults["tool"]["harness"]
+        self.settings = harness.get("settings", {"behavior": "fail", "error_diff_lines": 500, "languages": ["py"]})
+        self.forbidden: dict[str, list[str]] = harness.get("FORBIDDEN", {})
+        self.agents: dict[str, list[str]] = harness.get("agents", {})
+        self.commit_checks: dict[str, list[str]] = harness.get("preflight", {})
+        self.gate_checks: dict[str, list[str]] = harness.get("gate", {}) | self.commit_checks
+        self.forbidden_files: tuple[str, ...] = tuple(self.forbidden.get("FILES", []))
+        self.forbidden_dirs: tuple[str, ...] = tuple(self.forbidden.get("DIRS", []))
+        self.forbidden_patterns: tuple[str, ...] = tuple(self.forbidden.get("PATTERNS", []))
+
+    def run_checks(self, checks: dict[str, list[str]]) -> dict[str, list[str]]:
+        """Run each named command, streaming its output live under a phase header.
+        Reports what each command did and leaves the verdict to the caller.
+
+        Args:
+            checks: Mapping of check name to the argv that runs it.
+
+        Returns:
+            { "pass": [...], "warn": [...], "fail": [ problems ] } bucketing each check name by exit code.
+            If anything is in "fail", a commit is not allowed.
+        """
+        clean_env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
+        if not os.environ.get("RALPH_LOOP"):
+            clean_env.update({"FORCE_COLOR": "1", "CLICOLOR_FORCE": "1", "SEMGREP_FORCE_COLOR": "1"})
+        results: dict[str, list[str]] = {"pass": [], "fail": [], "warn": []}
+        for name, command in checks.items():
+            colorize(name, " ".join(command))
+            sys.stdout.flush()
+            with subprocess.Popen(command, cwd=self.repo_root, env=clean_env) as process:
+                exit_code = process.wait()
+            if exit_code == 0:
+                results["pass"].append(name)
+            elif "format" in name:
+                results["warn"].append(name)
+            else:
+                results[self.settings["behavior"]].append(name)
+        key = "fail" if os.environ.get("RALPH_LOOP") else "warn"
+        colorize("AGENT CHECKs", "running non-human agent checks")
+        self._run_non_human_checks(results, key)
+        mutmut_key = "pass" if analyze_mutmut_report_passed() >= MINIMUM_MUTATION_SCORE else key
+        results[mutmut_key].append("mutmut")
+        return results
+
+    def _run_non_human_checks(self, results: dict[str, list[str]], key: str):
+        """Runs checks on non-humans only. Checks things that linters or other chekcs to do not check.
+        Unstages files that should never be touched.
+
+        Arguments:
+            results: The original bucketing of each check name into "pass"/"fail"/"warn" lists
+            key: `results` dictionary will use "fail"/"warn" if an agent is being checked
+        """
+        ref = "HEAD" if run_git(["rev-parse", "--verify", "HEAD"], check=False).strip() else self.EMPTY_TREE
+        staged = run_git([
+            "diff",
+            "--cached",
+            "--name-only",
+            "--no-renames",
+            "--diff-filter=ACMRD",
+        ]).splitlines()
+        if not staged:
+            colorize("EMPTY COMMIT", "nothing staged: do real work, do not commit empty")
+            return
+        forbidden_paths: list[str] = [
+            path
+            for path in staged
+            if path.casefold() in self.forbidden_files or path.casefold().startswith(self.forbidden_dirs)
+        ]
+        if forbidden_paths:
+            out = "\n".join(forbidden_paths)
+            colorize("EJECTED", f"Would keep forbidden paths out of agent commit:[dim green]\n{out}[/]")
+            if key == "fail":
+                run_git(["reset", "-q", ref, "--", *forbidden_paths])
+        if forbidden_patterns := self._check_for_bad_patterns():
+            results[key].append("FORBIDDEN FOR AGENT:\n" + "\n".join(forbidden_patterns))
+        if ignored_preferences := self._check_for_preferences():
+            results[key].append(f"PREFERENCES IGNORED:\n{ignored_preferences}")
+        self._check_diff_size(ref, results, key)
+
+    def _check_for_bad_patterns(self) -> list[str]:
+        """Check staged files for banned patterns (agent-in-loop containment).
+        Does not unstage anything. Later, if any problem lands in { "fail": ... } the commit is blocked.
+
+        Banned patterns are flagged only on ADDED diff lines (a '+' line, never a '+++' header).
+
+        Returns:
+            The banned-pattern hits plus any preference violations found in the staged files.
+        """
+        staged_lines = run_git([
+            "diff",
+            "--cached",
+            "--unified=0",
+            "--output-indicator-new=a",
+            ":(exclude,icase,glob)**/*.toml",
+            ":(exclude,icase,glob)**/*.md",
+        ])
+        problems: set[str] = set()
+        current_file = ""
+        for line in staged_lines.splitlines():
+            if line.startswith("+++ b/"):
+                current_file = line.removeprefix("+++ b/")
+            elif line.startswith("a"):
+                problems.update(
+                    f"{current_file}: '{pattern}'"
+                    for pattern in self.forbidden_patterns
+                    if pattern.casefold() in line.casefold()
+                )
+        colorize("BANNED PATTERNS FOR AGENT", f"check for banned patterns in staged files\nIssues:\n{problems}")
+        return list(problems)
+
+    def _check_diff_size(self, ref: str, results: dict[str, list[str]], key: str):
+        """Report size of staged diff and block a bloated commit if past Lines Of Code (LOC) cap.
+
+        LOC = added + deleted. Count diff lines, staged and unstaged. An edit is
+        one deletion plus one addition. Lockfiles and binaries are excluded.
+
+        Arguments:
+            ref: Git SHA to run git diff on
+            results: The full-checks result bucketing each check name into "pass"/"fail"/"warn" lists.
+            key: Whether to "fail" this check because an agent is being checked (not a human)
+        """
+        stats = run_git(["diff", ref, "--numstat", "--cached", "--find-renames"]).splitlines()
+        total = 0
+        for line in stats:
+            inserted, deleted, path = line.split("\t", 2)
+            if not (inserted == "-" or path.lower().endswith(".lock")):  # binary or lockfile
+                total += int(inserted) + int(deleted)
+        warn_at_75: int = round(self.settings["error_diff_lines"] * 0.75)
+        msg = (
+            f"{total} lines of code modified (insertions + deletions in staged files). Agents get WARN at "
+            f"75% {warn_at_75}, ERROR at {self.settings['error_diff_lines']}."
+        )
+        do_better = (
+            "\nRefactor bloat, reduce mis-direction, re-use fixtures, cut duplication, slim down "
+            "code. More code does not mean good code."
+        )
+        if total > self.settings["error_diff_lines"]:
+            results[key].append(msg + do_better)
+        elif total > warn_at_75:
+            results["warn"].append(msg + do_better)
+        colorize("DIFF SIZE", msg)
+
+    def _check_for_preferences(self) -> str:
+        """Checks user preferences honored. Currently only a preferences.py file exists. New languages should
+        add their own branch.
+
+        Returns:
+            The preferences violations and filepath found in staged files.
+        """
+        problems: list[str] = []
+        if "py" in self.settings["languages"]:
+            staged = run_git([
+                "diff",
+                "--cached",
+                "--name-only",
+                "--diff-filter=d",
+                "--",
+                "*.py",
+            ]).splitlines()
+            if prefs:
+                for path in staged:
+                    messages: str = prefs(path, run_git(["show", f":{path}"]))
+                    if messages:
+                        problems.append(messages)
+        colorize("REPO PREFERENCES", f"checking repo preferences are respected by agents\nIssues:\n{problems}")
+        return "\n".join(problems)
+
+    def run_preflight(self) -> dict[str, list[str]]:
+        """Pre-commit: checks plus an informational format report. For agents in the loop also
+        unstages forbidden filepaths and flags banned patterns and any human-preferences not honored.
+
+        Returns:
+            The commit-checks result with any containment problems in a "fail" list.
+        """
+        return self.run_checks(self.commit_checks)
+
+    def run_gate(self) -> dict[str, list[str]]:
+        """Pre-push / CI: lint, types, pylint, security, pytest/hypothesis (blocking), complexipy, plus an
+        informational format report.
+
+        Returns:
+            results: The full-checks result bucketing each check name into "pass"/"fail"/"warn" lists.
+        """
+        return self.run_checks(self.gate_checks)
+
+    def prepare_commit_msg(self, argv: list[str]) -> int:
+        """Logic for the git prepare-commit-msg hook applicable to agents in the loop.
+
+        Args:
+            argv: arguments used to invoke `git commit`
+
+        Returns:
+            Status code integer 0 or 1 (git blocks commit on code 1)
+        """
+        if not os.environ.get("RALPH_LOOP"):
+            return 0
+        commit_msg_file: str = argv[1] if len(argv) > 1 else ""
+        command = argv[2] if len(argv) > 2 else ""
+        msg = ""
+        if command in {"merge", "squash", "rebase", "reset", "clean", "filter-branch"}:
+            msg = f"You cannot use that git command `{command}`.\n"
+        ref = "HEAD" if run_git(["rev-parse", "--verify", "HEAD"], check=False).strip() else self.EMPTY_TREE
+        if not run_git(["diff-index", "--cached", "--name-only", ref]):
+            msg += "Empty commit detected. Stage real work, Don't use --allow-empty. Say if you're blocked\n"
+        if Path(commit_msg_file).exists():
+            content = Path(commit_msg_file).read_text(encoding="utf-8")
+            actual_text = "\n".join([line for line in content.splitlines() if not line.startswith("#")]).strip()
+            if not actual_text:
+                msg += "Commit message is blank. Provide an informative message with your agent ID.\n"
+        if msg:
+            colorize("prepare-commit-message", msg)
+            return 1  # Intercepts git
+        return 0
+
+
+def run_git(args: list[str], repo: Path | None = None, check: bool = True) -> str:
+    """Run a git command in the repo and return its stdout.
+
+    Arguments:
+        args: Git subcommand and its arguments
+        repo: the repository directory to run the git command from. Defaults to REPO_ROOT.
+        check: If check is True and the exit code was non-zero, it raises a CalledProcessError.
+
+    Returns:
+        The command's raw stdout string (callers will .splitlines() as needed)
+    """
+    target = gates().repo_root if repo is None else repo
+    command = ["git", "-C", str(target), *args]
+    git_env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
+    result = subprocess.run(command, capture_output=True, text=True, check=check, env=git_env)
+    return result.stdout
+
+
+def colorize(name: str, command: str) -> None:
+    """Rich consosle printing to signpost checks.
+
+    Args:
+        name: Phase name shown in the rule header.
+        command: The command string printed beneath the header.
+    """
+    if os.environ.get("RALPH_LOOP"):  # loop agents get plain text (no ANSI)
+        typer.echo(f"PHASE: {name.upper()}\n{command}")
+    else:
+        console.rule(f"[bold cyan] PHASE: {name.upper()}[/]", style="blink cyan on grey15")
+        console.print(f"[dim italic]{command}[/dim italic]\n", justify="center")
+
+
+@cache
+def gates() -> Gate:
+    """Returns the singleton object containing gate checks and configs."""
+    root = run_git(["rev-parse", "--show-toplevel"], repo=Path.cwd(), check=False).strip()
+    if not root:
+        typer.echo("Run this inside a git repository")
+    return Gate(Path(root).resolve())

harness/js-scaffold/PROMPT.md

@@ -0,0 +1,8 @@
+# JS Quiz Scaffold
+
+A minimal vanilla JS quiz that checks answers and colors buttons.
+
+## Rules
+- Do not change the correct answer without updating specs/quiz.md
+- Tests must pass after every change: `npm test`
+- Do not add frameworks or large dependencies

harness/js-scaffold/README.md

@@ -0,0 +1,12 @@
+# JS Scaffold Example
+
+Shows how Ralph works with a frontend JS project.
+
+## Structure
+- `PROMPT.md` — rules Ralph must follow
+- `specs/` — behavior specs Ralph must not break
+- `npm test` — fails if behavior is broken
+
+## Usage
+npm install
+npm test

harness/js-scaffold/index.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Quiz</title>
+    <script src="./quiz.js" type="module" defer></script>
+    <style>
+        body {
+    display: flex;
+    flex-direction: column;
+    justify-content: center; 
+    align-items: center;          
+    margin: 0;
+}
+h1{
+    font-size: 3.4rem;
+}
+p{
+    font-size: 1.5rem;
+   text-align: center
+}
+button{
+    padding-inline: 1.5rem;
+    width: 100%;
+    font-size: 1rem;
+    padding-block: 0.5rem;
+    display: block;
+    margin-bottom: 1rem;
+}
+    </style>
+</head>
+<body>
+    <main>
+        <header>
+            <h1> Quiz Test </h1>
+        </header>
+        <section>
+            <p>NaN === NaN</p>
+            <button id="btn-true" type="button">True</button>
+            <button id="btn-false" type="button">False</button>
+        </section>
+    </main>
+</body>
+
+</html>

harness/js-scaffold/package-lock.json

@@ -0,0 +1,176 @@
+{
+	"name": "js-scaffold",
+	"lockfileVersion": 3,
+	"requires": true,
+	"packages": {
+		"": {
+			"name": "js-scaffold",
+			"devDependencies": {
+				"@biomejs/biome": "latest"
+			}
+		},
+		"node_modules/@biomejs/biome": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.5.4.tgz",
+			"integrity": "sha512-xy5FNE5kQJKyK5MR1gJy6ztXYx4WBAbYGlK04lMEgmyPRWKybY9NFwiG9yo0XdzOU8Xvhj41u034J1ywfoWfMw==",
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"bin": {
+				"biome": "bin/biome"
+			},
+			"engines": {
+				"node": ">=14.21.3"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/biome"
+			},
+			"optionalDependencies": {
+				"@biomejs/cli-darwin-arm64": "2.5.4",
+				"@biomejs/cli-darwin-x64": "2.5.4",
+				"@biomejs/cli-linux-arm64": "2.5.4",
+				"@biomejs/cli-linux-arm64-musl": "2.5.4",
+				"@biomejs/cli-linux-x64": "2.5.4",
+				"@biomejs/cli-linux-x64-musl": "2.5.4",
+				"@biomejs/cli-win32-arm64": "2.5.4",
+				"@biomejs/cli-win32-x64": "2.5.4"
+			}
+		},
+		"node_modules/@biomejs/cli-darwin-arm64": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.5.4.tgz",
+			"integrity": "sha512-4o3NFRobXHynkgcFVrlZsoDAFtF2ldlEGN8sORSws5ZQqyY4PXnPUIylu4ksfyHuwkfvDREuWh3JK+niRwGq3w==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		},
+		"node_modules/@biomejs/cli-darwin-x64": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.5.4.tgz",
+			"integrity": "sha512-D32P5HkU2Y6PySuC/WsVDTOgsDwVFmujzhhhOQjajtATpVWFDXuVd3oRbsWNSEA+aaFzyzZm22szsyydBYlSyQ==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		},
+		"node_modules/@biomejs/cli-linux-arm64": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.5.4.tgz",
+			"integrity": "sha512-pSEfW7B8kTsXUjUxC1xVVK+y85Ht3C5XxZ9gclmC7/3Ku9Vqz8jmI7k0p/BNIjQ6t4sFERI2sFeH73ybiZl6YQ==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		},
+		"node_modules/@biomejs/cli-linux-arm64-musl": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.5.4.tgz",
+			"integrity": "sha512-Rpm5/AT1m+DlJmUoYvS4/vXc+0tXJPJ2NQz25TGPyHVF5JrWy75PE0GH6kVxsKtQDuCH4OgzquZq0R4kj/wCVg==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		},
+		"node_modules/@biomejs/cli-linux-x64": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.5.4.tgz",
+			"integrity": "sha512-FNxojWJkL7EajAuzBgoLe0T2G0y112M4lBrDIFl/DomFTx8yqenYOIdsRLNXvOvBBofE8hJi85LjzLmBDpY7/Q==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		},
+		"node_modules/@biomejs/cli-linux-x64-musl": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.5.4.tgz",
+			"integrity": "sha512-aby/PohmmgbShcHqFsZVzG8H6D98+P+A6xRWRrQcLW1pCjabcov5UUlke4UqNQBYTkDQav+jB4zyyDDeKB2GaA==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		},
+		"node_modules/@biomejs/cli-win32-arm64": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.5.4.tgz",
+			"integrity": "sha512-emoXexPZIPAZkz2RKmA95WJUqK3I5MJNYtwEbL5ESciRzhmFMMyekDhNG8hpeOaK+ZGRDxAU4wvGuA5IHQ0h0w==",
+			"cpu": [
+				"arm64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"win32"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		},
+		"node_modules/@biomejs/cli-win32-x64": {
+			"version": "2.5.4",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.5.4.tgz",
+			"integrity": "sha512-U1jaluLw1qQc2Tx7/CeSoL9N5XcqIH+GWjpUAy1ouB5nVjSCMNO+NNHdY3RAs8zxNurLWAdj6pehQdCA2zyU+Q==",
+			"cpu": [
+				"x64"
+			],
+			"dev": true,
+			"license": "MIT OR Apache-2.0",
+			"optional": true,
+			"os": [
+				"win32"
+			],
+			"engines": {
+				"node": ">=14.21.3"
+			}
+		}
+	}
+}

harness/js-scaffold/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "js-scaffold",
+	"type": "module",
+	"scripts": {
+		"test": "node --test",
+		"lint": "npx @biomejs/biome check .",
+		"format": "npx @biomejs/biome check --write .",
+		"security": "semgrep scan --error --config auto --config p/secrets --exclude-rule yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag ../..",
+		"coverage": "node --test --experimental-test-coverage",
+		"preflight": "npm run lint && npm run format",
+		"gate": "npm run coverage && npm run security"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "latest"
+	}
+}

harness/js-scaffold/quiz.js

@@ -0,0 +1,21 @@
+export function checkAnswer(answer) {
+	const correctAnswer = false;
+	return answer === correctAnswer;
+}
+function testQuiz() {
+	const trueBtn = document.getElementById("btn-true");
+	const falseBtn = document.getElementById("btn-false");
+	trueBtn.addEventListener("click", () => {
+		const isCorrect = checkAnswer(true);
+		trueBtn.style.background = isCorrect ? "#d4edda" : "#f8d7da";
+		falseBtn.style.background = "";
+	});
+	falseBtn.addEventListener("click", () => {
+		const isCorrect = checkAnswer(false);
+		falseBtn.style.background = isCorrect ? "#d4edda" : "#f8d7da";
+		trueBtn.style.background = "";
+	});
+}
+if (typeof document !== "undefined") {
+	testQuiz();
+}

harness/js-scaffold/specs/quiz.md

@@ -0,0 +1,6 @@
+# Quiz Specs
+
+## checkAnswer(answer)
+- returns true when answer matches the correct answer
+- returns false otherwise
+- correct answer for "NaN === NaN" is false

harness/js-scaffold/test.js

@@ -0,0 +1,8 @@
+import assert from "node:assert";
+import test from "node:test";
+import { checkAnswer } from "./quiz.js";
+
+test(" Quiz - checkAnswer function", () => {
+	assert.strictEqual(checkAnswer(false), true);
+	assert.strictEqual(checkAnswer(true), false);
+});

harness/ralph.ps1

@@ -0,0 +1,84 @@
+# Ralph (Windows twin of ralph.sh). Hand docs/PROMPT.md to a fresh-context agent and loop.
+# Keep Ralph Dumb: start the worker, give it the prompt, print a line, repeat. Nothing else.
+# Windows has no POSIX `timeout`, so this uses Process.WaitForExit + taskkill /T.
+#
+# Usage:
+#   powershell.exe -File ralph.ps1 <max_iterations> <max_minutes_per_iteration> <agent command...>
+
+$ErrorActionPreference = "Stop"
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+# Mark loop commits so the gate (run by the git hooks) applies containment to the worker.
+$env:RALPH_LOOP = "1"
+
+function ConvertTo-WindowsArgument([string]$argument) {
+    $escaped = [regex]::Replace($argument, '(\\*)"', '$1$1\"')
+    return '"' + $escaped + [regex]::Match($argument, '(\\*)$').Groups[1].Value + '"'
+}
+
+function Write-RalphEvent([System.Collections.IDictionary]$payload) {
+    [Console]::Out.WriteLine(($payload | ConvertTo-Json -Compress))
+    [Console]::Out.Flush()
+}
+
+if ($args.Count -lt 3) {
+    [Console]::Error.WriteLine(
+        "Usage: ralph.ps1 <max_iterations> <max_minutes_per_iteration> <agent command...>"
+    )
+    exit 2
+}
+
+$maxIterations = [int]$args[0]
+$maxMinutes = [double]$args[1]
+$worker = @($args | Select-Object -Skip 2)
+$timeoutMilliseconds = [int][Math]::Ceiling($maxMinutes * 60 * 1000)
+
+$iteration = 1
+while ($iteration -le $maxIterations) {
+    Write-RalphEvent ([ordered]@{
+        type = "ralph"
+        iteration = $iteration
+        max_iterations = $maxIterations
+        max_minutes = $maxMinutes
+        timestamp = (Get-Date).ToString("yyyy-MM-ddTHH:mm")
+    })
+
+    $startInfo = [System.Diagnostics.ProcessStartInfo]::new()
+    $startInfo.FileName = $worker[0]
+    if ($worker.Count -gt 1) {
+        $startInfo.Arguments = (($worker[1..($worker.Count - 1)] | ForEach-Object {
+            ConvertTo-WindowsArgument $_
+        }) -join ' ')
+    }
+    $startInfo.RedirectStandardInput = $true
+    $startInfo.UseShellExecute = $false
+
+    $process = [System.Diagnostics.Process]::Start($startInfo)
+    $prompt = "$($env:RALPH_PROMPT)`n`nRALPH_ITERATION=$iteration/$maxIterations`n"
+    $process.StandardInput.Write($prompt)
+    $process.StandardInput.Close()
+
+    if (-not $process.WaitForExit($timeoutMilliseconds)) {
+        taskkill.exe /F /T /PID $process.Id | Out-Null
+        $process.WaitForExit()
+        $process.Dispose()
+        exit 124
+    }
+
+    $process.WaitForExit()
+    $exitCode = $process.ExitCode
+    $process.Dispose()
+    if ($exitCode -ne 0) {
+        exit $exitCode
+    }
+
+    $iteration += 1
+}
+
+Write-RalphEvent ([ordered]@{
+    type = "ralph"
+    completed = $iteration - 1
+    max_minutes = $maxMinutes
+    timestamp = (Get-Date).ToString("yyyy-MM-ddTHH:mm")
+})