loopgate 0.1.0__py3-none-any.whl

harness/config.py

@@ -0,0 +1,203 @@
+"""Only hardcoded values go in here and only with explicit permission. This is a no-bloat zone."""
+
+from __future__ import annotations
+
+from importlib.metadata import distribution, packages_distributions
+from pathlib import Path
+from typing import Any
+
+from harness.gate import gates
+
+distribution_name = packages_distributions()["harness"][0]
+site_packages = Path(str(distribution(distribution_name).locate_file("")))
+package_root = site_packages / "harness"
+repo_root = gates().repo_root
+
+CATEGORIES: dict[str, str] = {
+    "audit": "audit",
+    "complexity": "complexity",
+    "format": "ruff_format",
+    "lint": "ruff_lint",
+    "security": "security",
+    "test": "test",
+    "types": "types",
+}
+
+PHASES = (
+    ("agents", gates().agents),
+    ("preflight", gates().commit_checks),
+    ("gate", gates().gate_checks),
+    ("forbidden", gates().forbidden),
+)
+
+CODEX_RULES = """\
+prefix_rule(
+    pattern = ["git", ["push", "commit"], ["--no-verify", "-n"]],
+    decision = "forbidden",
+    justification = "Run git commands without hook-bypass flags.",
+)
+prefix_rule(
+    pattern = [["unset", "unsetenv"], "RALPH_LOOP"],
+    decision = "forbidden",
+    justification = "Keep RALPH_LOOP=1 so harness containment remains active.",
+)
+prefix_rule(
+    pattern = ["env", "-u", "RALPH_LOOP"],
+    decision = "forbidden",
+    justification = "Keep RALPH_LOOP=1 so harness containment remains active.",
+)
+prefix_rule(
+    pattern = [
+        ["bash", "/bin/bash", "zsh", "/bin/zsh", "sh", "/bin/sh"],
+        ["-c", "-lc"],
+        ["RALPH_LOOP=0", "export RALPH_LOOP=0"],
+    ],
+    decision = "forbidden",
+    justification = "Keep RALPH_LOOP=1 so harness containment remains active.",
+)
+"""
+
+TOOLS: dict[str, dict[str, Any]] = {
+    "audit": {"category": "audit", "args": gates().gate_checks["audit"]},
+    "bandit": {
+        "category": "security",
+        "filenames": [".bandit"],
+        "pyproject": ["bandit"],
+        "args": ["bandit", "-r", ".", "-x", "build,tox,docs,tests,.venv,scratchpad,mutants,tests"],
+    },
+    "ruff_format": {
+        "category": "format",
+        "filenames": [".ruff.toml", "ruff.toml"],
+        "pyproject": ["ruff", "format"],
+        "args": gates().commit_checks["ruff_format"],
+    },
+    "ruff_lint": {
+        "category": "lint",
+        "filenames": [".ruff.toml", "ruff.toml"],
+        "pyproject": ["ruff", "lint"],
+        "args": gates().commit_checks["ruff_lint"],
+    },
+    "black": {"category": "format", "pyproject": ["black"], "args": ["black", "--check", "."]},
+    "coverage": {
+        "category": "test",
+        "filenames": [".coveragerc", ".coveragerc.toml"],
+        "pyproject": ["coverage"],
+    },
+    "flake8": {"category": "lint", "filenames": [".flake8"], "args": ["flake8", "."]},
+    "hypothesis": {"category": "test", "pyproject": ["hypothesis"]},
+    "lint": {"category": "lint", "pyproject": ["lint"]},
+    "pytest": {
+        "category": "test",
+        "filenames": ["pytest.toml", ".pytest.toml", "pytest.ini", ".pytest.ini"],
+        "pyproject": ["pytest", "ini_options"],
+        "args": gates().gate_checks["test"],
+    },
+    "pyright": {
+        "category": "types",
+        "filenames": ["pyrightconfig.json"],
+        "pyproject": ["pyright"],
+        "args": gates().gate_checks["types"],
+    },
+    "pylint": {
+        "category": "lint",
+        "filenames": ["pylintrc", "pylintrc.toml", ".pylintrc", ".pylintrc.toml"],
+        "pyproject": ["pylint"],
+        "args": gates().commit_checks["pylint"],
+    },
+    "mypy": {
+        "category": "types",
+        "filenames": ["mypy.ini", ".mypy.ini"],
+        "pyproject": ["mypy"],
+        "args": ["mypy", "."],
+    },
+    "mutmut": {"category": "test", "pyproject": ["mutmut"]},
+    "radon": {
+        "category": "complexity",
+        "filenames": ["radon.cfg"],
+        "pyproject": ["radon"],
+        "args": [
+            "radon",
+            "cc",
+            "-s",
+            "-a",
+            "-i",
+            "build,tox,docs,tests,.venv,scratchpad,mutants,tests",
+            "-e",
+            "**/__init__.py.",
+        ],
+    },
+    "safety": {"category": "audit", "args": ["safety", "scan"]},
+    "sonarqube": {
+        "category": "security",
+        "filenames": ["sonar-project.properties"],
+        "args": ["sonar-scanner", "-Dsonar.qualitygate.wait=true"],
+    },
+    "snyk": {"category": "security", "filenames": [".snyk"], "args": ["snyk", "test"]},
+    "ty": {
+        "category": "types",
+        "filenames": [
+            "ty.toml",
+            "~/.config/ty/ty.toml",
+            "$XDG_CONFIG_HOME/ty/ty.toml",  # Linux/macOS
+            "%APPDATA%\\ty\\ty.toml",  # Windows
+        ],
+        "pyproject": ["ty"],
+        "args": ["ty", "check"],
+    },
+    "complexipy": {
+        "category": "complexity",
+        "filenames": ["complexipy.toml", ".complexipy.toml"],
+        "pyproject": ["complexipy"],
+        "args": gates().commit_checks["complexity"],
+    },
+    "semgrep": {
+        "category": "security",
+        "filenames": [
+            ".semgrep.yml",
+            ".semgrep.yaml",
+            "semgrep.yml",
+            "semgrep.yaml",
+            "semgrep.config.yml",
+            "semgrep.config.yaml",
+        ],
+        "args": gates().gate_checks["security"],
+    },
+    "pyrefly": {
+        "category": "types",
+        "filenames": ["pyrefly.toml", ".pyrefly.toml"],
+        "pyproject": ["pyrefly"],
+        "args": ["pyrefly", "check"],
+    },
+    "xenon": {
+        "category": "complexity",
+        "filenames": [".xenon.yml"],
+        "args": ["xenon", "--max-absolute", "B", "--max-modules", "A", "--max-average", "A", "."],
+    },
+    "zuban": {
+        "category": "types",
+        "filenames": [".zuban.toml"],
+        "pyproject": ["zuban"],
+        "args": ["zuban", "check"],
+    },
+}
+
+CLAUDE_RULES: set[str] = {
+    "Bash(*git push*--no-verify*)",
+    "Bash(*git commit*--no-verify*)",
+    "Bash(*git push* -n*)",
+    "Bash(*git commit* -n*)",
+    "Bash(*unset RALPH_LOOP*)",
+    "Bash(*env -u RALPH_LOOP*)",
+    "Bash(*unsetenv RALPH_LOOP*)",
+    "Bash(*RALPH_LOOP=0*)",
+    "Bash(*export RALPH_LOOP=0*)",
+}
+
+ASSETS: dict[str, tuple[Path, Path]] = {
+    "docs": (package_root / "docs", repo_root / "docs"),
+    "githooks": (package_root / ".githooks", repo_root / ".githooks"),
+    "preferences": (site_packages / "preferences", repo_root / "preferences"),
+    "mutation": (site_packages / "mutation", repo_root / "mutation"),
+    "pref_tests": (package_root / "tests/preferences", repo_root / "tests/preferences"),
+    "mutation_tests": (package_root / "tests/mutation", repo_root / "tests/mutation"),
+}

harness/docs/PROJECT_STATUS.md

@@ -0,0 +1,38 @@
+# Project Status
+
+> Current truth of the repo. Keep it short and current < 100 lines. Human-agent interface document.
+
+## Current Focus
+
+- Active spec + milestone: <e.g. docs/specs/base.md → Milestone 2>
+
+## Current State
+
+- <current repo state>
+- <current state of each feature described in plan.md>
+- <current state of functionalities described in plan.md>
+- <current remaining gap of repo and what is described in plan.md>
+
+## Checks
+
+- `harness preflight` <status>
+- `harness gate` <status>
+- <another-check-to-use>
+- <another-check-to-use>
+
+## Next
+
+1. <next concrete action>
+2. <next concrete action>
+3. <next concrete action>
+
+## Changelog
+
+- <what a previous iteration tried, and enduring changes or failures (with the error/check) example>
+-  <what THIS iteration tried, and whether it worked or failures (with the error/check) example>
+
+## Blockers
+
+- <known blocker, or None known>
+- <known blocker, or None known>
+- <known blocker, or None known>

harness/docs/PROMPT.md

@@ -0,0 +1,39 @@
+You are a fresh-context iteration in a loop. The repo `src/` and `docs/` are your memory. Specs say what to build.
+You decide what is the next most useful change.
+
+1. Read `docs/specs/*.md` and `docs/plan.md` and identify the most important unfinished items.
+2. If a spec is wrong or missing, add or update the spec using `plan.md` as a guide instead of guessing.
+3. Inspect the relevant code and tests before editing.
+4. Implement the scoped change that advances the specs.
+5. If you are blocked, report it in `docs/PROJECT_STATUS.md` and exit: do not waste your turn and tokens pretending to work.
+6. Verify existing 'blockers' before trusting them. Try to remove blockers.
+7. Add or update tests that prove behavior and challenge the source; use durable, behavior-focused names and docstrings.
+8. A milestone is not DONE until a test executes the entry point end-to-end and asserts observable output and exit code. Unit-testing an internal function is not sufficient. Prefer `hypothesis` property tests when possible.
+9. Periodically run `mutmut run` and kill mutants.
+10. Run `harness gate`. If `harness` is not on PATH, run `.venv/bin/harness gate`.
+11. Update the relevant spec and `docs/PROJECT_STATUS.md` to match what changed. Keep `docs/PROJECT_STATUS.md` uncluttered: persist only actionable items.
+12. Commit on the current branch.
+
+Rules:
+
+- Do not batch unrelated work.
+- Keep history linear on the current branch: no branches or worktrees unless the human explicitly asked for them. Commit only relevant current-branch work.
+- If forbidden paths block a commit, run `git restore --staged <path>` and leave those working-tree edits for human review.
+- Never delete tests or assertions to make checks pass.
+- Fix failures without weakening tests, coverage, typing, security checks, or the gate.
+- Do not edit forbidden paths: `AGENTS.md`, `harness/`, `.githooks/`, `.github/`, `pyproject.toml`, `PROMPT.md`.
+- Use tests for code output and contracts. Do not test for `.md` contents.
+  Commit message:
+
+```
+One sentence summary
+
+- concrete detail
+- concrete detail
+...
+
+<prefix><your-agent-id>-<spec-you-worked>-<RALPH_ITERATION> # e.g. `codex-0006-frontend_ui-6/7`
+```
+
+Use the agent id the harness gave you (e.g. `0002-codex`); append the spec you worked and the
+`RALPH_ITERATION` value. This makes commits traceable to their run log (`scratchpad/runs/<id>.jsonl`).

harness/docs/plan.md

@@ -0,0 +1,68 @@
+# The human vision
+
+Agents read this for direction; `docs/specs/` turns it into concrete, prioritized work. Humans start owning this file. Delete or comment out the `docs/plan.md` entry in `[tool.harness.gate] forbidden_files` at [pyproject.toml](../pyproject.toml) if you want agents to take over managing the vision.
+
+Code will go in `src/`
+
+## Objective
+
+Prose to describe the intended outcome, e.g. a one page web app that does X for Y users. e.g. email will always be clear of junk mail. Use affirmative phrasing in non-contradictory detail.
+
+## Features and functionality
+
+Detail the objective outcome.
+
+EXAMPLE:
+
+- User experience is like {this}
+- Data Storage {stores X like Y}
+- Cost is kept to {#}
+- Page X does Y, Page A does B
+- Links to wireframes or mockups
+- Schema contract
+- Tests to include to enforce functionality
+- Project will be deployed at {place}
+- API integrations include {A}, {B}, {C}
+- Local tasks are {X}, {Y}, {Z}
+
+## Approach
+
+Describe the high-level steps for completing the project. Prefer concrete direction over vague quality words. For example, describe user experience deliverables, data flows, or things the project must avoid, in the ontext of timing.
+
+EXAMPLE:
+
+- User description
+- Major technical choices
+- Workflows
+- Libraries and architecture
+- Storage choices
+- APIs
+- Services
+- Data sources
+- Performanec targets
+- UX expectations
+- Compatibility requirements
+
+EXAMPLE:
+
+1. Dependencies installed: FastAPI, Numpy, Requests, Supabase
+2. FastAPI Backend working with health endponit.
+3. User can see blank homepage.
+4. API `/data` endpoint reurns user info. React/Vite homepage shows raw html.
+   ...
+   {FINAL}. The one page web app is styled like mockup and ... (This item should be a mirror of the Objective at the top)
+
+## Milestones
+
+Similar to 'Approach', with concrete deliverables in a timeline
+
+1. First major milestone and its concrete description
+2. Second major milestone and its concrete description
+3. Third major milestone and its concrete description
+4. {fill in additional milestones}
+5. Release or handoff milestone
+
+## Out of Scope
+
+1. {item the project will NOT do}
+2. {item the project will NOT do}

harness/docs/specs/another_spec.md

@@ -0,0 +1,56 @@
+# Base Spec
+
+> **PRIORITY <1|2|3>.** Replace with 1–2 sentence context outlining the core problem this spec solves.
+
+## Scope
+
+Clear definitions of what the agent should focus on. Detail APIs, frameworks, data schemas, or libraries the agent must use.
+
+## Priorities
+
+1. Milestone <name>
+  - Description
+  - Link to which [docs/plan.md] **Milestone** this addresses
+  - Sub-tasks
+    - <sub-task-1>
+    - <sub-task-2>
+    - <additional sub-tasks>
+  - Files created or updated
+  - Definition of done: <command/test that exits 0 when met, e.g. `pytest tests/test_x.py::test_y`>
+
+<fill in additional milestones>
+
+## Guardrails
+
+Examples:
+- Structure
+- Style
+- Behavioral tests
+- Dependencies to use
+- Compatibilities to support
+
+## Acceptance Criteria
+
+Measurable criteria for success. Instead of vague quality terms like "should be fast," use verifiable metrics (e.g., "P95 latency < 100ms", or "npx prisma generate succeeds").
+
+- <measurable criterion>
+- <measurable criterion>
+- <fill in additional criterion as needed>
+
+## Out of Scope
+(Features/scope the agent must not start.)
+
+- <explicit non-goal>
+- <explicit non-goal>
+- <fill in additional non-goals as needed>
+
+## Blockers
+
+- <List specific item preventing completion of this spec>
+- <List specific item preventing completion of this spec>
+- <fill in additional blockers as needed>
+
+## Changelog
+
+_Keep brief and to the latest items to keep spec < 100 lines_
+- Each agent adds their name + iteration info, what the current agent tried, and what worked or did not work

harness/docs/specs/base.md

@@ -0,0 +1,56 @@
+# Base Spec
+
+> **PRIORITY <1|2|3>.** Replace with 1–2 sentence context outlining the core problem this spec solves.
+
+## Scope
+
+Clear definitions of what the agent should focus on. Detail APIs, frameworks, data schemas, or libraries the agent must use.
+
+## Priorities
+
+1. Milestone <name>
+  - Description
+  - Link to which [docs/plan.md] **Milestone** this addresses
+  - Sub-tasks
+    - <sub-task-1>
+    - <sub-task-2>
+    - <additional sub-tasks>
+  - Files created or updated
+  - Definition of done: <command/test that exits 0 when met, e.g. `pytest tests/test_x.py::test_y`>
+
+<fill in additional milestones>
+
+## Guardrails
+
+Examples:
+- Structure
+- Style
+- Behavioral tests
+- Dependencies to use
+- Compatibilities to support
+
+## Acceptance Criteria
+
+Measurable criteria for success. Instead of vague quality terms like "should be fast," use verifiable metrics (e.g., "P95 latency < 100ms", or "npx prisma generate succeeds").
+
+- <measurable criterion>
+- <measurable criterion>
+- <fill in additional criterion as needed>
+
+## Out of Scope
+(Features/scope the agent must not start.)
+
+- <explicit non-goal>
+- <explicit non-goal>
+- <fill in additional non-goals as needed>
+
+## Blockers
+
+- <List specific item preventing completion of this spec>
+- <List specific item preventing completion of this spec>
+- <fill in additional blockers as needed>
+
+## Changelog
+
+_Keep brief and to the latest items to keep spec < 100 lines_
+- Each agent adds their name + iteration info, what the current agent tried, and what worked or did not work