cleaner-crew 0.1.0__tar.gz

cleaner_crew-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

cleaner_crew-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/

cleaner_crew-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: cleaner-crew
+Version: 0.1.0
+Summary: Autonomous crew of Claude Code agents that picks up small, safe tasks and opens MRs.
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# Cleaner Crew 🧹
+
+A crew of Claude Code agents that picks up small, safe tasks from your tracker
+(Linear, Jira), fixes them in isolation, and opens merge requests on GitHub or GitLab.
+It only ships a change when a deterministic policy gate agrees, it never merges, and it
+earns more autonomy per category only as humans accept its work.
+
+```
+scout ──► proposed tickets (cleaner-crew:proposed)
+             │  a human adds the `cleaner-crew` label to the ones worth doing
+candidate tickets (cleaner-crew)
+             │
+manager ──► claim ──► triage + plan
+             │
+             ├─► inspector   write a failing test that reproduces the bug (bugfix)
+             ├─► janitor     implement the plan (cannot edit tests)
+             ├─► inspector   cover the change with tests (can only edit tests)
+             ├─► tests + lint + diff + mutation testing, run by the orchestrator
+             └─► hooded      read-only security review, can veto
+             │
+policy gate + manager verdict + trust level ──► MR │ draft MR │ shadow │ escalate │ reject
+             │
+target repo CI: cleaner-crew-verify (required check) + human approval ──► merge
+```
+
+## Install into a repository
+
+```sh
+cd path/to/your/cloned/repo
+uvx cleaner-crew init        # or: uv tool install cleaner-crew && cleaner-crew init
+```
+
+`init` walks you through:
+
+1. **Code host.** It detects GitHub/GitLab from `origin`, checks the token (or an existing
+   `gh` login) and verifies that it has push and MR permissions.
+2. **Task manager.** You choose Linear or Jira, paste a token if one is missing, pick the
+   team/project, and map the todo / in progress / in review statuses.
+3. **Tests.** It detects the stack, confirms the test and lint commands, and runs the suite
+   once. If the baseline is red, the crew is installed disabled.
+4. **Files.** It writes `.cleaner-crew/config.yml`, `policy.yml` and `.claude/agents/cleaner-crew-*.md`.
+5. **Runner.** Choose a scheduled CI job (GitHub Actions / GitLab schedule), a local
+   daemon (loop or systemd user timer), or both.
+6. **Protection.** It adds the `cleaner-crew-verify` CI check, checks branch protection on
+   the default branch and tells you exactly what to turn on.
+
+Secrets go to `.cleaner-crew/secrets.env` (gitignored, mode 600) or your CI secrets.
+`config.yml` holds only the variable names.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `cleaner-crew init` | install and connect |
+| `cleaner-crew doctor` | re-check connections, CLI, test baseline, kill switch |
+| `cleaner-crew run --dry-run` | scout and plan only; nothing is claimed, filed or pushed |
+| `cleaner-crew run` | one run: up to `max_tasks_per_run` tickets |
+| `cleaner-crew trust` | each category's earned trust level and acceptance rate |
+| `cleaner-crew verify --base main` | CI check re-applying the base branch's policy to a crew branch |
+| `cleaner-crew daemon` | run in a loop on this machine |
+| `cleaner-crew stop` / `resume` | kill switch (commit `.cleaner-crew/STOP` to stop CI too) |
+
+## How it earns trust
+
+**Humans choose the work.** The scout only *proposes* (`cleaner-crew:proposed`). Adding
+the `cleaner-crew` label takes about ten seconds and is far cheaper than reviewing a
+pointless MR. At most `max_open_proposals` proposals are open at once.
+
+**Autonomy per category is measured, not assumed.** An MR counts as *accepted* if it was
+merged with no human commits pushed to its branch (crew commits carry `Cleaner-Crew-*`
+git trailers). Over the last `trust.window` closed MRs per category:
+
+| record | level | behaviour |
+|---|---|---|
+| fewer than `min_samples` | draft | MRs are opened as drafts |
+| acceptance ≥ `promote_at` (80%) | ready | MRs are opened ready for review |
+| acceptance < `demote_below` (50%) | shadow | the plan is posted on the ticket; nothing changes |
+| otherwise | draft | |
+
+The earned level is capped by each category's `max_level` in `policy.yml`. After fixing
+whatever caused a demotion, set `trust_since` to today's date to start a fresh record.
+History is read from the code host, so CI and local runners agree.
+
+**Tests must actually test the change.** After tests pass, the crew mutates the changed
+lines (`==`→`!=`, `<`→`<=`, `n`→`n+1`, `and`→`or`, ...) and re-runs the tests. If
+fewer than `mutation.min_score` of the mutants are caught, the MR becomes a draft, and
+the surviving mutants are listed in the MR.
+
+## Protecting the target repo
+
+The crew never merges. The repository's own protections are the real safety net:
+
+- **Branch protection** on the default branch: require at least one approving review,
+  dismiss stale approvals, and require `cleaner-crew-verify` plus your test workflow.
+- **`cleaner-crew-verify`** re-checks every `cleaner-crew/*` MR against the policy *from
+  the base branch*. It checks forbidden paths (including the crew's own config), size
+  limits, required tests, category enabled, and crew trailers present. On GitHub it runs
+  as `pull_request_target`, so an MR can't edit the check that judges it, and it never
+  executes the MR's code.
+- **CODEOWNERS** for `/.cleaner-crew/`, `/.claude/` and CI config.
+
+`cleaner-crew doctor` reports whether the default branch is adequately protected.
+
+## Safety model
+
+- **The policy gate is code, not a prompt.** `policy.yml` sets size limits, forbidden
+  paths, required tests and security approval. The manager's verdict can only be made
+  stricter by the policy.
+- **Separate contexts.** Each role is a separate `claude -p` process. The inspector and
+  hooded agent see the plan and diff, never the janitor's reasoning.
+- **Separation of duties.** Janitors cannot edit tests, and inspectors can only edit tests.
+  Scout, manager and hooded agents are read-only.
+- **Three layers of tool restriction:** `--allowedTools` per role, the agent's `tools:`
+  frontmatter, and a PreToolUse guard hook (`cleaner_crew.hooks.guard`). The guard blocks
+  the network, git history commands, secrets files, anything outside the task worktree,
+  and the crew's own config.
+- **Agents hold no credentials.** Tracker and code host tokens are stripped from agent
+  environments. Only the orchestrator claims tickets, commits, pushes and opens MRs.
+- **Ticket text is untrusted.** It is wrapped as data. The hooded agent checks the diff
+  against the plan and flags suspected prompt injection, which blocks the change.
+- **Limits:** max open crew MRs, a per-task cost cap, a green baseline requirement, and a
+  kill switch.
+- **Audit trail:** every agent transcript, the test log and the outcome are kept under
+  `.cleaner-crew/runs/` (uploaded as a CI artifact).
+
+## Extending
+
+Add a tracker or code host by implementing `TaskSource` or `CodeHost` in
+`src/cleaner_crew/adapters/base.py` and registering it in `adapters/__init__.py`.
+Customise agent behaviour by editing `.claude/agents/cleaner-crew-*.md` in the target repo.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+```

cleaner_crew-0.1.0/README.md

@@ -0,0 +1,137 @@
+# Cleaner Crew 🧹
+
+A crew of Claude Code agents that picks up small, safe tasks from your tracker
+(Linear, Jira), fixes them in isolation, and opens merge requests on GitHub or GitLab.
+It only ships a change when a deterministic policy gate agrees, it never merges, and it
+earns more autonomy per category only as humans accept its work.
+
+```
+scout ──► proposed tickets (cleaner-crew:proposed)
+             │  a human adds the `cleaner-crew` label to the ones worth doing
+candidate tickets (cleaner-crew)
+             │
+manager ──► claim ──► triage + plan
+             │
+             ├─► inspector   write a failing test that reproduces the bug (bugfix)
+             ├─► janitor     implement the plan (cannot edit tests)
+             ├─► inspector   cover the change with tests (can only edit tests)
+             ├─► tests + lint + diff + mutation testing, run by the orchestrator
+             └─► hooded      read-only security review, can veto
+             │
+policy gate + manager verdict + trust level ──► MR │ draft MR │ shadow │ escalate │ reject
+             │
+target repo CI: cleaner-crew-verify (required check) + human approval ──► merge
+```
+
+## Install into a repository
+
+```sh
+cd path/to/your/cloned/repo
+uvx cleaner-crew init        # or: uv tool install cleaner-crew && cleaner-crew init
+```
+
+`init` walks you through:
+
+1. **Code host.** It detects GitHub/GitLab from `origin`, checks the token (or an existing
+   `gh` login) and verifies that it has push and MR permissions.
+2. **Task manager.** You choose Linear or Jira, paste a token if one is missing, pick the
+   team/project, and map the todo / in progress / in review statuses.
+3. **Tests.** It detects the stack, confirms the test and lint commands, and runs the suite
+   once. If the baseline is red, the crew is installed disabled.
+4. **Files.** It writes `.cleaner-crew/config.yml`, `policy.yml` and `.claude/agents/cleaner-crew-*.md`.
+5. **Runner.** Choose a scheduled CI job (GitHub Actions / GitLab schedule), a local
+   daemon (loop or systemd user timer), or both.
+6. **Protection.** It adds the `cleaner-crew-verify` CI check, checks branch protection on
+   the default branch and tells you exactly what to turn on.
+
+Secrets go to `.cleaner-crew/secrets.env` (gitignored, mode 600) or your CI secrets.
+`config.yml` holds only the variable names.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `cleaner-crew init` | install and connect |
+| `cleaner-crew doctor` | re-check connections, CLI, test baseline, kill switch |
+| `cleaner-crew run --dry-run` | scout and plan only; nothing is claimed, filed or pushed |
+| `cleaner-crew run` | one run: up to `max_tasks_per_run` tickets |
+| `cleaner-crew trust` | each category's earned trust level and acceptance rate |
+| `cleaner-crew verify --base main` | CI check re-applying the base branch's policy to a crew branch |
+| `cleaner-crew daemon` | run in a loop on this machine |
+| `cleaner-crew stop` / `resume` | kill switch (commit `.cleaner-crew/STOP` to stop CI too) |
+
+## How it earns trust
+
+**Humans choose the work.** The scout only *proposes* (`cleaner-crew:proposed`). Adding
+the `cleaner-crew` label takes about ten seconds and is far cheaper than reviewing a
+pointless MR. At most `max_open_proposals` proposals are open at once.
+
+**Autonomy per category is measured, not assumed.** An MR counts as *accepted* if it was
+merged with no human commits pushed to its branch (crew commits carry `Cleaner-Crew-*`
+git trailers). Over the last `trust.window` closed MRs per category:
+
+| record | level | behaviour |
+|---|---|---|
+| fewer than `min_samples` | draft | MRs are opened as drafts |
+| acceptance ≥ `promote_at` (80%) | ready | MRs are opened ready for review |
+| acceptance < `demote_below` (50%) | shadow | the plan is posted on the ticket; nothing changes |
+| otherwise | draft | |
+
+The earned level is capped by each category's `max_level` in `policy.yml`. After fixing
+whatever caused a demotion, set `trust_since` to today's date to start a fresh record.
+History is read from the code host, so CI and local runners agree.
+
+**Tests must actually test the change.** After tests pass, the crew mutates the changed
+lines (`==`→`!=`, `<`→`<=`, `n`→`n+1`, `and`→`or`, ...) and re-runs the tests. If
+fewer than `mutation.min_score` of the mutants are caught, the MR becomes a draft, and
+the surviving mutants are listed in the MR.
+
+## Protecting the target repo
+
+The crew never merges. The repository's own protections are the real safety net:
+
+- **Branch protection** on the default branch: require at least one approving review,
+  dismiss stale approvals, and require `cleaner-crew-verify` plus your test workflow.
+- **`cleaner-crew-verify`** re-checks every `cleaner-crew/*` MR against the policy *from
+  the base branch*. It checks forbidden paths (including the crew's own config), size
+  limits, required tests, category enabled, and crew trailers present. On GitHub it runs
+  as `pull_request_target`, so an MR can't edit the check that judges it, and it never
+  executes the MR's code.
+- **CODEOWNERS** for `/.cleaner-crew/`, `/.claude/` and CI config.
+
+`cleaner-crew doctor` reports whether the default branch is adequately protected.
+
+## Safety model
+
+- **The policy gate is code, not a prompt.** `policy.yml` sets size limits, forbidden
+  paths, required tests and security approval. The manager's verdict can only be made
+  stricter by the policy.
+- **Separate contexts.** Each role is a separate `claude -p` process. The inspector and
+  hooded agent see the plan and diff, never the janitor's reasoning.
+- **Separation of duties.** Janitors cannot edit tests, and inspectors can only edit tests.
+  Scout, manager and hooded agents are read-only.
+- **Three layers of tool restriction:** `--allowedTools` per role, the agent's `tools:`
+  frontmatter, and a PreToolUse guard hook (`cleaner_crew.hooks.guard`). The guard blocks
+  the network, git history commands, secrets files, anything outside the task worktree,
+  and the crew's own config.
+- **Agents hold no credentials.** Tracker and code host tokens are stripped from agent
+  environments. Only the orchestrator claims tickets, commits, pushes and opens MRs.
+- **Ticket text is untrusted.** It is wrapped as data. The hooded agent checks the diff
+  against the plan and flags suspected prompt injection, which blocks the change.
+- **Limits:** max open crew MRs, a per-task cost cap, a green baseline requirement, and a
+  kill switch.
+- **Audit trail:** every agent transcript, the test log and the outcome are kept under
+  `.cleaner-crew/runs/` (uploaded as a CI artifact).
+
+## Extending
+
+Add a tracker or code host by implementing `TaskSource` or `CodeHost` in
+`src/cleaner_crew/adapters/base.py` and registering it in `adapters/__init__.py`.
+Customise agent behaviour by editing `.claude/agents/cleaner-crew-*.md` in the target repo.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+```

cleaner_crew-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "cleaner-crew"
+version = "0.1.0"
+description = "Autonomous crew of Claude Code agents that picks up small, safe tasks and opens MRs."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "pyyaml>=6",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+cleaner-crew = "cleaner_crew.cli:app"
+
+[dependency-groups]
+dev = ["pytest>=8", "respx>=0.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cleaner_crew"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cleaner_crew-0.1.0/src/cleaner_crew/__init__.py

@@ -0,0 +1,4 @@
+__version__ = "0.1.0"
+
+CREW_DIR = ".cleaner-crew"
+BRANCH_PREFIX = "cleaner-crew/"

cleaner_crew-0.1.0/src/cleaner_crew/__main__.py

@@ -0,0 +1,3 @@
+from .cli import app
+
+app()

cleaner_crew-0.1.0/src/cleaner_crew/adapters/__init__.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from ..config import Config, env
+from .base import CodeHost, TaskSource
+
+
+def make_tracker(cfg: Config) -> TaskSource:
+    t = cfg.tracker
+    if t.kind == "linear":
+        from .linear import Linear
+        return Linear(t, env(t.token_env))
+    if t.kind == "jira":
+        from .jira import Jira
+        return Jira(t, env(t.email_env), env(t.token_env))
+    raise ValueError(f"unknown tracker kind: {t.kind}")
+
+
+def make_code_host(cfg: Config) -> CodeHost:
+    c = cfg.code_host
+    if c.kind == "github":
+        from .github import GitHub, github_token
+        tok = github_token(c.token_env)
+        if not tok:
+            raise RuntimeError(f"no GitHub token: set {c.token_env} or run `gh auth login`")
+        return GitHub(c.repo, tok, c.api_url)
+    if c.kind == "gitlab":
+        from .gitlab import GitLab
+        return GitLab(c.repo, env(c.token_env), c.api_url)
+    raise ValueError(f"unknown code host kind: {c.kind}")
+
+
+__all__ = ["CodeHost", "TaskSource", "make_code_host", "make_tracker"]

cleaner_crew-0.1.0/src/cleaner_crew/adapters/base.py

@@ -0,0 +1,109 @@
+"""Adapter interfaces. Add a new tracker or code host by implementing one of these."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..config import TrackerConfig
+from ..models import ConnectionReport, Finding, MrRecord, Task
+
+
+class TaskSource(ABC):
+    """Jira, Linear, ... The tracker is the source of truth for what the crew works on."""
+
+    cfg: TrackerConfig
+
+    @abstractmethod
+    def check(self) -> ConnectionReport:
+        """Verify credentials and that the configured project exists."""
+
+    @abstractmethod
+    def list_projects(self) -> list[tuple[str, str]]:
+        """(key, name) pairs, for the installer."""
+
+    @abstractmethod
+    def list_statuses(self) -> list[str]:
+        """Workflow status names of the configured project, for the installer."""
+
+    @abstractmethod
+    def fetch_candidates(self, limit: int = 20) -> list[Task]:
+        """Open tickets a human labelled as candidates, not yet claimed or settled by the crew."""
+
+    @abstractmethod
+    def find_issues(self, labels: list[str], open_only: bool, limit: int = 100) -> list[Task]:
+        """Tickets carrying any of `labels`."""
+
+    @abstractmethod
+    def create_finding(self, finding: Finding) -> Task:
+        """File a scout finding as a *proposed* ticket. Only a human makes it a candidate."""
+
+    @abstractmethod
+    def claim(self, task: Task) -> None:
+        """Mark in progress so no other run (CI or daemon) picks it up."""
+
+    @abstractmethod
+    def comment(self, task: Task, body: str) -> None: ...
+
+    @abstractmethod
+    def mark_in_review(self, task: Task, mr_url: str) -> None: ...
+
+    @abstractmethod
+    def release(self, task: Task, label: str, comment: str) -> None:
+        """Drop the claim, return the ticket to todo, add `label` and comment."""
+
+    def reject(self, task: Task, reason: str) -> None:
+        self.release(task, self.cfg.rejected_label, f"Cleaner crew: not shipping this.\n\n{reason}")
+
+    def escalate(self, task: Task, reason: str) -> None:
+        self.release(task, self.cfg.escalated_label,
+                     f"Cleaner crew: this needs a human.\n\n{reason}")
+
+    def shadow(self, task: Task, plan: str) -> None:
+        self.release(task, self.cfg.shadow_label,
+                     "Cleaner crew (shadow mode): this is what I would have done. "
+                     f"Nothing was changed.\n\n{plan}")
+
+    def blocked_labels(self) -> set[str]:
+        c = self.cfg
+        return {c.in_progress_label, c.rejected_label, c.escalated_label, c.shadow_label}
+
+    def all_crew_labels(self) -> list[str]:
+        c = self.cfg
+        return [c.candidate_label, c.proposed_label, *sorted(self.blocked_labels())]
+
+    def find_by_fingerprint(self, fp: str) -> Task | None:
+        """Any ticket the crew ever filed or touched, open or closed, so nothing is re-filed."""
+        issues = self.find_issues(self.all_crew_labels(), open_only=False, limit=250)
+        return next((t for t in issues if t.fingerprint == fp), None)
+
+    def count_open_proposals(self) -> int:
+        issues = self.find_issues([self.cfg.proposed_label], open_only=True)
+        return sum(1 for t in issues if self.cfg.candidate_label not in t.labels)
+
+
+class CodeHost(ABC):
+    """GitHub, GitLab, ..."""
+
+    @abstractmethod
+    def check(self) -> ConnectionReport:
+        """Verify credentials and push/MR permissions on the repository."""
+
+    @abstractmethod
+    def count_open_mrs(self, branch_prefix: str) -> int: ...
+
+    @abstractmethod
+    def open_mr(self, branch: str, base: str, title: str, body: str, draft: bool,
+                labels: list[str]) -> str:
+        """Open a merge/pull request and return its URL."""
+
+    @abstractmethod
+    def crew_mr_history(self, branch_prefix: str, limit: int = 100) -> list[MrRecord]:
+        """Recently closed crew MRs with their category, merge state and human changes."""
+
+    @abstractmethod
+    def branch_protection(self, branch: str) -> tuple[bool | None, str]:
+        """(adequately protected?, detail). None when it can't be determined.
+
+        Adequate means humans must approve before merge and, where the host exposes it,
+        the cleaner-crew-verify check is required.
+        """

cleaner_crew-0.1.0/src/cleaner_crew/adapters/github.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+import subprocess
+
+import httpx
+
+from ..models import ConnectionReport, MrRecord, category_from_labels, is_crew_commit
+from .base import CodeHost
+
+
+def github_token(token_env: str) -> str:
+    tok = os.environ.get(token_env, "")
+    if tok:
+        return tok
+    # Fall back to an existing gh CLI login for local use.
+    try:
+        return subprocess.run(["gh", "auth", "token"], capture_output=True, text=True,
+                              timeout=10).stdout.strip()
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ""
+
+
+class GitHub(CodeHost):
+    def __init__(self, repo: str, token: str, api_url: str = "https://api.github.com"):
+        self.repo = repo
+        self.http = httpx.Client(
+            base_url=api_url,
+            headers={"Authorization": f"Bearer {token}",
+                     "Accept": "application/vnd.github+json",
+                     "X-GitHub-Api-Version": "2022-11-28"},
+            timeout=30,
+        )
+
+    def check(self) -> ConnectionReport:
+        r = self.http.get("/user")
+        if r.status_code != 200:
+            return ConnectionReport(False, "github", detail=f"auth failed ({r.status_code})")
+        login = r.json()["login"]
+        r = self.http.get(f"/repos/{self.repo}")
+        if r.status_code != 200:
+            return ConnectionReport(False, "github", login,
+                                    f"repo {self.repo} not accessible ({r.status_code})")
+        perms = r.json().get("permissions", {})
+        missing = [] if perms.get("push") else ["push access (contents: write, pull_requests: write)"]
+        return ConnectionReport(not missing, "github", login, f"repo {self.repo}", missing)
+
+    def count_open_mrs(self, branch_prefix: str) -> int:
+        r = self.http.get(f"/repos/{self.repo}/pulls", params={"state": "open", "per_page": 100})
+        r.raise_for_status()
+        return sum(1 for pr in r.json() if pr["head"]["ref"].startswith(branch_prefix))
+
+    def open_mr(self, branch: str, base: str, title: str, body: str, draft: bool,
+                labels: list[str]) -> str:
+        r = self.http.post(f"/repos/{self.repo}/pulls", json={
+            "title": title, "head": branch, "base": base, "body": body, "draft": draft})
+        r.raise_for_status()
+        pr = r.json()
+        self.http.post(f"/repos/{self.repo}/issues/{pr['number']}/labels",
+                       json={"labels": labels}).raise_for_status()
+        return pr["html_url"]
+
+    def crew_mr_history(self, branch_prefix: str, limit: int = 100) -> list[MrRecord]:
+        r = self.http.get(f"/repos/{self.repo}/pulls", params={
+            "state": "closed", "sort": "updated", "direction": "desc", "per_page": 100})
+        r.raise_for_status()
+        out = []
+        for pr in r.json():
+            if not pr["head"]["ref"].startswith(branch_prefix) or len(out) >= limit:
+                continue
+            cat = category_from_labels([l["name"] for l in pr.get("labels", [])])
+            if cat is None:
+                continue
+            commits = self.http.get(f"/repos/{self.repo}/pulls/{pr['number']}/commits",
+                                    params={"per_page": 100})
+            commits.raise_for_status()
+            human = any(not is_crew_commit(c["commit"]["message"]) for c in commits.json())
+            out.append(MrRecord(cat, merged=pr.get("merged_at") is not None,
+                                changed_by_human=human, closed_at=pr["closed_at"]))
+        return out
+
+    def branch_protection(self, branch: str) -> tuple[bool | None, str]:
+        r = self.http.get(f"/repos/{self.repo}/branches/{branch}")
+        if r.status_code != 200:
+            return None, f"cannot read branch {branch} ({r.status_code})"
+        if not r.json().get("protected"):
+            return False, f"{branch} is not protected"
+        r = self.http.get(f"/repos/{self.repo}/branches/{branch}/protection")
+        if r.status_code != 200:
+            return True, f"{branch} is protected (details need admin rights)"
+        p = r.json()
+        checks = (p.get("required_status_checks") or {}).get("contexts", [])
+        reviews = (p.get("required_pull_request_reviews") or {}).get(
+            "required_approving_review_count", 0)
+        detail = f"{reviews} required review(s); required checks: {', '.join(checks) or 'none'}"
+        return bool(reviews) and any("cleaner-crew" in c for c in checks), detail
+