git-bug-broker 0.1.0__tar.gz

git_bug_broker-0.1.0/LICENSE

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

git_bug_broker-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: git-bug-broker
+Version: 0.1.0
+Summary: MCP server that lets several agents share one git-bug store while the web UI is open
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JovianIce/git-bug-broker
+Project-URL: Source, https://github.com/JovianIce/git-bug-broker
+Project-URL: Issues, https://github.com/JovianIce/git-bug-broker/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# git-bug-broker
+
+An MCP server that lets several agents file, label and close issues in one [git-bug](https://github.com/git-bug/git-bug) store (a distributed issue tracker that keeps issues in git refs) while its web UI stays open.
+
+![An issue filed, reproduced, fixed and closed by an agent and its subagents, seen in git-bug's web UI](https://raw.githubusercontent.com/JovianIce/git-bug-broker/main/docs/agent-bug-sample.png)
+
+git-bug keeps issues inside the repository as git objects, so agents can track work
+next to the code with no hosted tracker, API token or network. Through this server an
+agent can open an issue for a bug it finds, comment on it as it investigates, label it,
+read what other agents have written, and close it with a note naming the commit that
+fixed it. Issues are versioned like commits and sync through any git remote with
+`git bug push` and `git bug pull`, so the record carries over between sessions and
+between agents.
+
+`git-bug webui` holds the search index for as long as it runs, and every CLI command waits on it without saying so. The broker talks to the web UI's GraphQL endpoint instead, takes a file lock for each write, and refuses any write that breaks the project's conventions: claim-style titles, one `area/` and one `kind/` label, required body sections. A rejected write lists every problem at once. Unlike a wrapper around the CLI, it keeps working while `git-bug webui` is open, and concurrent writes don't collide. The client is also a small Python library, so a script can write to the store while the UI is open too.
+
+Works with git-bug 0.11. Tested on Windows; the Linux and macOS paths are written but
+untested.
+
+## Install
+
+```sh
+pip install git-bug-broker
+```
+
+or from a checkout of [the repository](https://github.com/JovianIce/git-bug-broker), `pip install -e .`. Needs Python 3.10+ and `git-bug` on `PATH`.
+
+## Run
+
+```sh
+git-bug-broker-start <repo>            # start the web UI (reuses one already running)
+git-bug-broker-start <repo> --status
+git-bug-broker-start <repo> --stop
+```
+
+It prints the web UI's URL. An issue is at `<url>/_/issues/<id>`, where `<id>` is the
+short id the tools return. The issue list starts filtered to `status:open`; clear the
+search box to see closed issues too. `--stop` only stops the process it started.
+
+## Use from Python
+
+```python
+from git_bug_broker.client import Client
+
+c = Client(repo="/path/to/repo")
+c.file_entry(
+    "The retry loop never backs off after a 429",
+    "**What** retry() sleeps a fixed 1 s.
+**Done when** the delay doubles per attempt.",
+    ["area/api", "kind/defect"],
+)
+```
+
+## Connect an MCP client
+
+`.mcp.json` for Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "git-bug": {
+      "command": "git-bug-broker",
+      "env": {
+        "GITBUG_BROKER_REPO": "/path/to/repo",
+        "GITBUG_BROKER_RULES": "/path/to/repo/.git-bug-rules.json"
+      }
+    }
+  }
+}
+```
+
+Any stdio MCP client takes the same command and env.
+
+`GITBUG_BROKER_RULES` is optional. Without it the defaults in
+`src/git_bug_broker/rules/default.json` apply and any area name is accepted.
+`examples/rules.example.json` shows a project file with a fixed area list.
+
+`GITBUG_BROKER_URL` points the client at a web UI the broker did not start, for example one on another port.
+
+Tools: `file_entry`, `comment`, `edit_body`, `edit_comment`, `relabel`, `set_status`,
+`set_title`, `get`, `query`. A rejected write lists every problem at once.
+
+## Rules
+
+What gets checked is in [CONVENTIONS.md](https://github.com/JovianIce/git-bug-broker/blob/main/CONVENTIONS.md). Briefly:
+
+- a title is a claim about the code, at most 80 characters, with no leading number
+- exactly one `area/` and one `kind/` label, with a slash, never a colon
+- defects and chores have `What` and `Done when` sections
+
+## Why the lock
+
+git-bug 0.11 applies an operation and commits it in two unguarded steps. When two
+writes hit the same issue at once both land, but one caller is told
+`can't commit an entity with no pending operation`, and a retry duplicates the write.
+The broker holds `<repo>/.git/git-bug-broker/write.lock` for each write. Reads don't
+lock.
+
+Measured on git-bug 0.11 on Windows: with the lock, 24 parallel writes from 4 server processes, 12 of them to one shared
+issue, finished in 3.7 s with no errors. Without it, 28 of 30 concurrent writes to one
+issue reported failure although all 30 had landed.
+
+## Limitations
+
+- The web UI has to be running. If it isn't, every tool says so and nothing is queued.
+- Filing an issue is two mutations, create then label. A crash in between leaves an
+  unlabelled issue; the error gives its id.
+- The web UI binds to 127.0.0.1 with no authentication.
+- Edits made in the web UI aren't checked against the rules.
+- Free-text search returns at most 10 results. `title:`, `label:` and `status:`
+  filters return everything.
+
+## Development
+
+```sh
+pip install -e .[dev]
+pytest
+```
+
+`tools/view.py` renders the store as a static HTML page and a JSON Lines snapshot. It reads through the CLI, so run it while the web UI is stopped; anything reading its output needs neither.
+
+## License
+
+MIT

git_bug_broker-0.1.0/README.md

@@ -0,0 +1,124 @@
+# git-bug-broker
+
+An MCP server that lets several agents file, label and close issues in one [git-bug](https://github.com/git-bug/git-bug) store (a distributed issue tracker that keeps issues in git refs) while its web UI stays open.
+
+![An issue filed, reproduced, fixed and closed by an agent and its subagents, seen in git-bug's web UI](https://raw.githubusercontent.com/JovianIce/git-bug-broker/main/docs/agent-bug-sample.png)
+
+git-bug keeps issues inside the repository as git objects, so agents can track work
+next to the code with no hosted tracker, API token or network. Through this server an
+agent can open an issue for a bug it finds, comment on it as it investigates, label it,
+read what other agents have written, and close it with a note naming the commit that
+fixed it. Issues are versioned like commits and sync through any git remote with
+`git bug push` and `git bug pull`, so the record carries over between sessions and
+between agents.
+
+`git-bug webui` holds the search index for as long as it runs, and every CLI command waits on it without saying so. The broker talks to the web UI's GraphQL endpoint instead, takes a file lock for each write, and refuses any write that breaks the project's conventions: claim-style titles, one `area/` and one `kind/` label, required body sections. A rejected write lists every problem at once. Unlike a wrapper around the CLI, it keeps working while `git-bug webui` is open, and concurrent writes don't collide. The client is also a small Python library, so a script can write to the store while the UI is open too.
+
+Works with git-bug 0.11. Tested on Windows; the Linux and macOS paths are written but
+untested.
+
+## Install
+
+```sh
+pip install git-bug-broker
+```
+
+or from a checkout of [the repository](https://github.com/JovianIce/git-bug-broker), `pip install -e .`. Needs Python 3.10+ and `git-bug` on `PATH`.
+
+## Run
+
+```sh
+git-bug-broker-start <repo>            # start the web UI (reuses one already running)
+git-bug-broker-start <repo> --status
+git-bug-broker-start <repo> --stop
+```
+
+It prints the web UI's URL. An issue is at `<url>/_/issues/<id>`, where `<id>` is the
+short id the tools return. The issue list starts filtered to `status:open`; clear the
+search box to see closed issues too. `--stop` only stops the process it started.
+
+## Use from Python
+
+```python
+from git_bug_broker.client import Client
+
+c = Client(repo="/path/to/repo")
+c.file_entry(
+    "The retry loop never backs off after a 429",
+    "**What** retry() sleeps a fixed 1 s.
+**Done when** the delay doubles per attempt.",
+    ["area/api", "kind/defect"],
+)
+```
+
+## Connect an MCP client
+
+`.mcp.json` for Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "git-bug": {
+      "command": "git-bug-broker",
+      "env": {
+        "GITBUG_BROKER_REPO": "/path/to/repo",
+        "GITBUG_BROKER_RULES": "/path/to/repo/.git-bug-rules.json"
+      }
+    }
+  }
+}
+```
+
+Any stdio MCP client takes the same command and env.
+
+`GITBUG_BROKER_RULES` is optional. Without it the defaults in
+`src/git_bug_broker/rules/default.json` apply and any area name is accepted.
+`examples/rules.example.json` shows a project file with a fixed area list.
+
+`GITBUG_BROKER_URL` points the client at a web UI the broker did not start, for example one on another port.
+
+Tools: `file_entry`, `comment`, `edit_body`, `edit_comment`, `relabel`, `set_status`,
+`set_title`, `get`, `query`. A rejected write lists every problem at once.
+
+## Rules
+
+What gets checked is in [CONVENTIONS.md](https://github.com/JovianIce/git-bug-broker/blob/main/CONVENTIONS.md). Briefly:
+
+- a title is a claim about the code, at most 80 characters, with no leading number
+- exactly one `area/` and one `kind/` label, with a slash, never a colon
+- defects and chores have `What` and `Done when` sections
+
+## Why the lock
+
+git-bug 0.11 applies an operation and commits it in two unguarded steps. When two
+writes hit the same issue at once both land, but one caller is told
+`can't commit an entity with no pending operation`, and a retry duplicates the write.
+The broker holds `<repo>/.git/git-bug-broker/write.lock` for each write. Reads don't
+lock.
+
+Measured on git-bug 0.11 on Windows: with the lock, 24 parallel writes from 4 server processes, 12 of them to one shared
+issue, finished in 3.7 s with no errors. Without it, 28 of 30 concurrent writes to one
+issue reported failure although all 30 had landed.
+
+## Limitations
+
+- The web UI has to be running. If it isn't, every tool says so and nothing is queued.
+- Filing an issue is two mutations, create then label. A crash in between leaves an
+  unlabelled issue; the error gives its id.
+- The web UI binds to 127.0.0.1 with no authentication.
+- Edits made in the web UI aren't checked against the rules.
+- Free-text search returns at most 10 results. `title:`, `label:` and `status:`
+  filters return everything.
+
+## Development
+
+```sh
+pip install -e .[dev]
+pytest
+```
+
+`tools/view.py` renders the store as a static HTML page and a JSON Lines snapshot. It reads through the CLI, so run it while the web UI is stopped; anything reading its output needs neither.
+
+## License
+
+MIT

git_bug_broker-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "git-bug-broker"
+version = "0.1.0"
+description = "MCP server that lets several agents share one git-bug store while the web UI is open"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["mcp>=2.2,<3"]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/JovianIce/git-bug-broker"
+Source = "https://github.com/JovianIce/git-bug-broker"
+Issues = "https://github.com/JovianIce/git-bug-broker/issues"
+
+[project.scripts]
+git-bug-broker = "git_bug_broker.server:main"
+git-bug-broker-start = "git_bug_broker.start:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+git_bug_broker = ["rules/*.json"]

git_bug_broker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

git_bug_broker-0.1.0/src/git_bug_broker/__init__.py

@@ -0,0 +1,2 @@
+"""git-bug broker: a serialising MCP front end for git-bug webui."""
+__version__ = "0.1.0"

git_bug_broker-0.1.0/src/git_bug_broker/client.py

@@ -0,0 +1,263 @@
+"""Client over the git-bug web UI's GraphQL endpoint.
+
+One `git-bug webui` process owns the store and its BoltDB index lock, and every
+read and write goes to it over HTTP, so nothing here runs the git-bug CLI.
+
+Writes also take a file lock (`<repo>/.git/git-bug-broker/write.lock`) for the
+length of one logical write. git-bug v0.11's resolvers apply an operation and
+commit it in two steps without holding the entity in between, so when two writes
+hit the same entry both land but one caller gets "can't commit an entity with no
+pending operation". That false failure invites a retry that duplicates the write.
+
+Standard library only; the MCP server is the only part with a dependency.
+"""
+import contextlib
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+
+from . import rules as R
+
+STATE_DIRNAME = "git-bug-broker"
+LOCK_TIMEOUT_S = 30.0
+HTTP_TIMEOUT_S = 30.0
+
+
+class BrokerDown(RuntimeError):
+    pass
+
+
+class GraphQLError(RuntimeError):
+    pass
+
+
+def state_dir(repo):
+    return os.path.join(os.path.abspath(repo), ".git", STATE_DIRNAME)
+
+
+def read_endpoint(repo):
+    path = os.path.join(state_dir(repo), "endpoint.json")
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return None
+
+
+@contextlib.contextmanager
+def _file_lock(path, timeout=LOCK_TIMEOUT_S):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    f = open(path, "a+b")
+    deadline = time.monotonic() + timeout
+    try:
+        if os.name == "nt":
+            import msvcrt
+            while True:
+                try:
+                    f.seek(0)
+                    msvcrt.locking(f.fileno(), msvcrt.LK_NBLCK, 1)
+                    break
+                except OSError:
+                    if time.monotonic() > deadline:
+                        raise TimeoutError(f"write lock {path} held for more than {timeout}s")
+                    time.sleep(0.005)
+            try:
+                yield
+            finally:
+                f.seek(0)
+                msvcrt.locking(f.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+            while True:
+                try:
+                    fcntl.flock(f.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except OSError:
+                    if time.monotonic() > deadline:
+                        raise TimeoutError(f"write lock {path} held for more than {timeout}s")
+                    time.sleep(0.005)
+            try:
+                yield
+            finally:
+                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+    finally:
+        f.close()
+
+
+BUG_FIELDS = """id humanId status title createdAt lastEdit
+  labels { name }
+  author { displayName }
+  comments(first: 500) { nodes { id message author { displayName } } }"""
+
+LIST_FIELDS = "id humanId status title lastEdit labels { name }"
+
+
+class Client:
+    def __init__(self, repo=None, url=None, rules_path=None):
+        self.repo = repo or os.environ.get("GITBUG_BROKER_REPO")
+        url = url or os.environ.get("GITBUG_BROKER_URL")
+        if not url and self.repo:
+            ep = read_endpoint(self.repo)
+            url = ep and ep.get("url")
+        if not url:
+            raise BrokerDown("no broker endpoint: set GITBUG_BROKER_REPO to a repository whose "
+                             "web UI was started with git-bug-broker-start, or GITBUG_BROKER_URL")
+        self.url = url.rstrip("/") + "/graphql" if not url.endswith("/graphql") else url
+        self.rules = R.load_rules(rules_path)
+        lock_home = state_dir(self.repo) if self.repo else os.path.join(
+            os.environ.get("TEMP", "/tmp"), STATE_DIRNAME)
+        self.lock_path = os.path.join(lock_home, "write.lock")
+
+    # transport -----------------------------------------------------------
+
+    def _gql(self, query, variables=None):
+        data = json.dumps({"query": query, "variables": variables or {}}).encode()
+        req = urllib.request.Request(self.url, data, {"Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=HTTP_TIMEOUT_S) as r:
+                out = json.load(r)
+        except urllib.error.URLError as e:
+            raise BrokerDown(f"git-bug web UI at {self.url} is not answering ({e.reason}); "
+                             "start it with git-bug-broker-start.") from e
+        if out.get("errors"):
+            raise GraphQLError("; ".join(e.get("message", str(e)) for e in out["errors"]))
+        return out["data"]
+
+    def _write(self, query, variables, verify=None, bug_id=None):
+        """Run one mutation under the write lock.
+
+        If git-bug still reports "no pending operation" (possible when another
+        writer, such as the web UI itself, skips the lock), `verify(bug)` checks
+        whether the change landed anyway."""
+        with _file_lock(self.lock_path):
+            try:
+                return self._gql(query, variables)
+            except GraphQLError as e:
+                if "no pending operation" in str(e) and verify is not None:
+                    bug = self.get(bug_id or variables["i"]["prefix"], _raw=True)
+                    if verify(bug):
+                        return {"verified_after_race": True}
+                raise
+
+    # reads ---------------------------------------------------------------
+
+    def get(self, id_prefix, _raw=False):
+        d = self._gql("query($p:String!){repository{bug(prefix:$p){%s}}}" % BUG_FIELDS,
+                      {"p": id_prefix})
+        bug = d["repository"]["bug"]
+        if bug is None:
+            raise KeyError(f"no entry with id prefix '{id_prefix}'")
+        return bug if _raw else _flatten(bug)
+
+    def query(self, query="status:open", first=100):
+        """List entries matching a git-bug query (status:, label:, title:, author:, sort:).
+
+        Free-text terms go through bleve, which returns at most 10 hits."""
+        d = self._gql("query($q:String,$n:Int){repository{allBugs(query:$q,first:$n)"
+                      "{totalCount nodes{%s}}}}" % LIST_FIELDS, {"q": query, "n": first})
+        conn = d["repository"]["allBugs"]
+        return {"total": conn["totalCount"],
+                "entries": [{"id": n["humanId"], "full_id": n["id"], "status": n["status"].lower(),
+                             "title": n["title"], "labels": sorted(l["name"] for l in n["labels"]),
+                             "last_edit": n["lastEdit"]} for n in conn["nodes"]]}
+
+    # writes --------------------------------------------------------------
+
+    def file_entry(self, title, body, labels):
+        labels = sorted(set(labels))
+        R.check_entry(self.rules, title, body, labels)
+        with _file_lock(self.lock_path):
+            d = self._gql("mutation($i:BugCreateInput!){bugCreate(input:$i){bug{id humanId}}}",
+                          {"i": {"title": title.strip(), "message": body}})
+            bid = d["bugCreate"]["bug"]["id"]
+            try:
+                self._gql("mutation($i:BugChangeLabelInput){bugChangeLabels(input:$i){results{status}}}",
+                          {"i": {"prefix": bid, "added": labels}})
+            except Exception as e:
+                raise GraphQLError(f"entry {bid[:7]} created but labelling failed: {e}") from e
+        return {"id": bid[:7], "full_id": bid}
+
+    def comment(self, id_prefix, message):
+        if not message.strip():
+            raise R.RuleViolation(["comment is empty"])
+        bug = self.get(id_prefix, _raw=True)
+        self._write("mutation($i:BugAddCommentInput!){bugAddComment(input:$i){bug{id}}}",
+                    {"i": {"prefix": bug["id"], "message": message}},
+                    verify=lambda b: any(c["message"] == message for c in b["comments"]["nodes"]))
+        return {"id": bug["humanId"], "comments": len(bug["comments"]["nodes"]) + 1}
+
+    def edit_body(self, id_prefix, body):
+        bug = self.get(id_prefix, _raw=True)
+        kind = R.kind_of([l["name"] for l in bug["labels"]])
+        problems = R.check_body(self.rules, body, kind)
+        if problems:
+            raise R.RuleViolation(problems)
+        target = bug["comments"]["nodes"][0]["id"]
+        self._write("mutation($i:BugEditCommentInput!){bugEditComment(input:$i){bug{id}}}",
+                    {"i": {"targetPrefix": target, "message": body}},
+                    verify=lambda b: b["comments"]["nodes"][0]["message"] == body, bug_id=bug["id"])
+        return {"id": bug["humanId"], "edited": "body"}
+
+    def edit_comment(self, comment_id, message):
+        self._write("mutation($i:BugEditCommentInput!){bugEditComment(input:$i){bug{id}}}",
+                    {"i": {"targetPrefix": comment_id, "message": message}})
+        return {"comment": comment_id[:12], "edited": True}
+
+    def relabel(self, id_prefix, add=(), remove=()):
+        add, remove = sorted(set(add)), sorted(set(remove))
+        with _file_lock(self.lock_path):
+            bug = self.get(id_prefix, _raw=True)
+            current = {l["name"] for l in bug["labels"]}
+            result = (current | set(add)) - set(remove)
+            problems = R.check_labels(self.rules, sorted(result))
+            if problems:
+                raise R.RuleViolation(problems)
+            inp = {"prefix": bug["id"]}
+            if add:
+                inp["added"] = add
+            if remove:
+                inp["Removed"] = remove  # capital R is the v0.11 schema's spelling
+            self._gql("mutation($i:BugChangeLabelInput){bugChangeLabels(input:$i)"
+                      "{results{label{name} status}}}", {"i": inp})
+        return {"id": bug["humanId"], "labels": sorted(result)}
+
+    def set_status(self, id_prefix, status, comment=None):
+        status = status.lower()
+        if status not in ("open", "closed"):
+            raise R.RuleViolation([f"status must be 'open' or 'closed', not '{status}'"])
+        bug = self.get(id_prefix, _raw=True)
+        want = status.upper()
+        verify = lambda b: b["status"] == want  # noqa: E731
+        if comment:
+            m = "bugAddCommentAndClose" if status == "closed" else "bugAddCommentAndReopen"
+            t = "BugAddCommentAndCloseInput" if status == "closed" else "BugAddCommentAndReopenInput"
+            self._write("mutation($i:%s!){%s(input:$i){bug{status}}}" % (t, m),
+                        {"i": {"prefix": bug["id"], "message": comment}}, verify=verify)
+        elif bug["status"] != want:
+            m = "bugStatusClose" if status == "closed" else "bugStatusOpen"
+            t = "BugStatusCloseInput" if status == "closed" else "BugStatusOpenInput"
+            self._write("mutation($i:%s!){%s(input:$i){bug{status}}}" % (t, m),
+                        {"i": {"prefix": bug["id"]}}, verify=verify)
+        return {"id": bug["humanId"], "status": status}
+
+    def set_title(self, id_prefix, title):
+        bug = self.get(id_prefix, _raw=True)
+        problems = R.check_title(self.rules, title, R.kind_of([l["name"] for l in bug["labels"]]))
+        if problems:
+            raise R.RuleViolation(problems)
+        self._write("mutation($i:BugSetTitleInput!){bugSetTitle(input:$i){bug{title}}}",
+                    {"i": {"prefix": bug["id"], "title": title.strip()}},
+                    verify=lambda b: b["title"] == title.strip())
+        return {"id": bug["humanId"], "title": title.strip()}
+
+
+def _flatten(bug):
+    cs = bug["comments"]["nodes"]
+    return {"id": bug["humanId"], "full_id": bug["id"], "status": bug["status"].lower(),
+            "title": bug["title"], "labels": sorted(l["name"] for l in bug["labels"]),
+            "author": bug["author"]["displayName"], "created": bug["createdAt"],
+            "last_edit": bug["lastEdit"], "body": cs[0]["message"] if cs else "",
+            "comments": [{"id": c["id"], "author": c["author"]["displayName"],
+                          "message": c["message"]} for c in cs[1:]]}

git_bug_broker-0.1.0/src/git_bug_broker/rules/default.json

@@ -0,0 +1,23 @@
+{
+  "_doc": "Default issue conventions; a file named by GITBUG_BROKER_RULES overrides any of these keys.",
+  "areas": [],
+  "areas_open": true,
+  "kinds": ["defect", "chore", "decision", "investigation", "idea"],
+  "flags": ["blocks", "needs-provenance"],
+  "free_prefixes": ["source/", "filed-by/"],
+  "exactly_one": ["area/", "kind/"],
+  "label_pattern": "^[a-z0-9][a-z0-9./-]*$",
+  "title": {
+    "max_chars": 80,
+    "leading_number_pattern": "^\\s*(#?\\d+[\\s.):-]|item\\s+\\d+|\\[\\d+\\])",
+    "min_words": 4,
+    "claim_markers": ["is", "are", "was", "were", "has", "have", "does", "do", "can", "cannot", "can't", "never", "only", "no", "not", "nothing", "lacks", "misses", "fails", "returns", "skips", "ignores", "leaks", "loses"],
+    "fix_prefixes": ["add", "fix", "remove", "make", "implement", "refactor", "use", "return", "change", "update", "rename", "move", "support"],
+    "fix_prefix_rejected_for": ["defect", "investigation"]
+  },
+  "body_sections": {
+    "defect": ["What", "Done when"],
+    "chore": ["What", "Done when"]
+  },
+  "section_pattern": "(?im)^[ \\t>*_#-]*{name}\\b"
+}

git_bug_broker-0.1.0/src/git_bug_broker/rules.py

@@ -0,0 +1,119 @@
+"""Issue conventions, checked before any write reaches git-bug.
+
+The rules are data (rules/*.json). A project supplies its own file through
+GITBUG_BROKER_RULES; it is layered over rules/default.json key by key, so a
+project file only has to name what differs (usually `areas` and `flags`).
+"""
+import json
+import os
+import re
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+class RuleViolation(ValueError):
+    """Raised with every violation found, one per line, so a caller fixes all at once."""
+
+    def __init__(self, problems):
+        self.problems = list(problems)
+        super().__init__("write refused by the conventions check:\n- " + "\n- ".join(self.problems))
+
+
+def load_rules(path=None):
+    with open(os.path.join(HERE, "rules", "default.json"), encoding="utf-8") as f:
+        rules = json.load(f)
+    path = path or os.environ.get("GITBUG_BROKER_RULES")
+    if path:
+        with open(path, encoding="utf-8") as f:
+            override = json.load(f)
+        for k, v in override.items():
+            if isinstance(v, dict) and isinstance(rules.get(k), dict):
+                rules[k] = {**rules[k], **v}
+            else:
+                rules[k] = v
+    return rules
+
+
+def check_title(rules, title, kind=None):
+    t = rules["title"]
+    out = []
+    s = (title or "").strip()
+    if not s:
+        return ["title is empty"]
+    if "\n" in s:
+        out.append("title must be one line")
+    if len(s) > t["max_chars"]:
+        out.append(f"title is {len(s)} characters, limit {t['max_chars']}")
+    if re.match(t["leading_number_pattern"], s, re.I):
+        out.append("title starts with a number; refer to entries by their git-bug id")
+    words = re.findall(r"[\w'`]+", s.lower())
+    stripped = [w.strip("`") for w in words]
+    if len(words) < t["min_words"] and not set(stripped) & set(t["claim_markers"]):
+        out.append(f"title '{s}' reads as a topic; write a present-tense claim about what the "
+                   "code does (for example 'retry() returns nil when every attempt fails')")
+    if kind in t["fix_prefix_rejected_for"] and stripped and stripped[0] in t["fix_prefixes"]:
+        out.append(f"a {kind} title states what is wrong, not the fix; '{words[0]} ...' "
+                   "names the fix")
+    return out
+
+
+def check_labels(rules, labels):
+    """Validate a complete label set (what the entry will carry after the write)."""
+    out = []
+    pat = re.compile(rules["label_pattern"])
+    areas, kinds = rules["areas"], rules["kinds"]
+    counts = {p: 0 for p in rules["exactly_one"]}
+    for lab in labels:
+        if ":" in lab:
+            out.append(f"label '{lab}' uses a colon; use a slash ('{lab.replace(':', '/')}'), "
+                       "because git-bug's query language reads a colon as a second qualifier")
+            continue
+        if not pat.match(lab):
+            out.append(f"label '{lab}' does not match {rules['label_pattern']}")
+            continue
+        for p in counts:
+            if lab.startswith(p):
+                counts[p] += 1
+        if lab.startswith("area/"):
+            name = lab[5:]
+            if not rules.get("areas_open") and name not in areas:
+                out.append(f"unknown area '{name}'; known: {', '.join(areas)}")
+        elif lab.startswith("kind/"):
+            if lab[5:] not in kinds:
+                out.append(f"unknown kind '{lab[5:]}'; known: {', '.join(kinds)}")
+        elif lab in rules["flags"]:
+            pass
+        elif any(lab.startswith(p) and len(lab) > len(p) for p in rules["free_prefixes"]):
+            pass
+        else:
+            out.append(f"label '{lab}' is not a known flag ({', '.join(rules['flags'])}) or "
+                       f"namespace ({', '.join(rules['exactly_one'] + rules['free_prefixes'])})")
+    for p, n in counts.items():
+        if n != 1:
+            out.append(f"entry must carry exactly one {p} label, has {n}")
+    return out
+
+
+def kind_of(labels):
+    for lab in labels:
+        if lab.startswith("kind/"):
+            return lab[5:]
+    return None
+
+
+def check_body(rules, body, kind):
+    out = []
+    if not (body or "").strip():
+        return ["body is empty"]
+    for name in rules["body_sections"].get(kind or "", []):
+        rx = rules["section_pattern"].replace("{name}", re.escape(name))
+        if not re.search(rx, body):
+            out.append(f"a {kind} body needs a '{name}' section (for example '**{name}.** ...')")
+    return out
+
+
+def check_entry(rules, title, body, labels):
+    kind = kind_of(labels)
+    problems = check_labels(rules, labels) + check_title(rules, title, kind) + check_body(rules, body, kind)
+    if problems:
+        raise RuleViolation(problems)

git_bug_broker-0.1.0/src/git_bug_broker/server.py

@@ -0,0 +1,115 @@
+"""stdio MCP server exposing a git-bug store as tools.
+
+Configuration comes from the environment:
+  GITBUG_BROKER_REPO   repository whose web UI git-bug-broker-start launched (required)
+  GITBUG_BROKER_RULES  project rules file layered over rules/default.json (optional)
+
+Every MCP client runs its own copy of this server. They share one web UI, and
+the write lock in client.py serializes their writes.
+"""
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+from . import client as C
+from . import rules as R
+
+mcp = MCPServer(
+    "git-bug",
+    instructions=(
+        "An issue store kept in git-bug. Use these tools instead of the git-bug "
+        "CLI. Titles are present-tense claims about what the code does, with no leading number. "
+        "Each entry carries exactly one area/<name> and one kind/<name> label; namespaces use a "
+        "slash, never a colon. defect and chore bodies need 'What' and 'Done when' sections. "
+        "A refused write returns every violation; fix them and retry. Free-text query terms "
+        "return at most 10 hits, so filter with label:, status: or title: when completeness "
+        "matters."),
+)
+
+_client = None
+
+
+def cl():
+    global _client
+    if _client is None:
+        _client = C.Client()
+    return _client
+
+
+def _run(name, *a, **kw):
+    # Only a ToolError's text reaches the caller; the SDK reports any other
+    # exception as a bare "Error executing tool". The client is built inside the
+    # try so a missing endpoint or rules file is reported like any other failure.
+    try:
+        return getattr(cl(), name)(*a, **kw)
+    except R.RuleViolation as e:
+        raise ToolError(str(e)) from None
+    except C.BrokerDown as e:
+        raise ToolError(f"git-bug web UI unavailable: {e}") from None
+    except (C.GraphQLError, KeyError, TimeoutError, FileNotFoundError) as e:
+        raise ToolError(f"{type(e).__name__}: {e}") from None
+
+
+@mcp.tool()
+def file_entry(title: str, body: str, labels: list[str]) -> dict:
+    """File a new entry. labels must include exactly one area/<name> and one kind/<name>
+    (defect, chore, decision, investigation, idea); add filed-by/<agent> when an agent files it."""
+    return _run("file_entry", title, body, labels)
+
+
+@mcp.tool()
+def comment(id: str, message: str) -> dict:
+    """Add a comment to an entry, by id or unique id prefix."""
+    return _run("comment", id, message)
+
+
+@mcp.tool()
+def edit_body(id: str, body: str) -> dict:
+    """Replace an entry's body (its first comment). Checked against the entry's kind."""
+    return _run("edit_body", id, body)
+
+
+@mcp.tool()
+def edit_comment(comment_id: str, message: str) -> dict:
+    """Replace the text of one comment, by the comment id that get() returns."""
+    return _run("edit_comment", comment_id, message)
+
+
+@mcp.tool()
+def relabel(id: str, add: list[str] | None = None, remove: list[str] | None = None) -> dict:
+    """Add and remove labels in one operation. The resulting set must satisfy the standard,
+    so swap an area with add=['area/new'], remove=['area/old'] in one call."""
+    return _run("relabel", id, add or [], remove or [])
+
+
+@mcp.tool()
+def set_status(id: str, status: str, comment: str | None = None) -> dict:
+    """Open or close an entry ('open' or 'closed'), optionally with a comment in the same
+    operation. A closing comment should name the commit and the test that pins the fix."""
+    return _run("set_status", id, status, comment)
+
+
+@mcp.tool()
+def set_title(id: str, title: str) -> dict:
+    """Retitle an entry. The new title is checked against the standard."""
+    return _run("set_title", id, title)
+
+
+@mcp.tool()
+def get(id: str) -> dict:
+    """Read one entry: title, status, labels, body and comments with their ids."""
+    return _run("get", id)
+
+
+@mcp.tool()
+def query(query: str = "status:open", first: int = 100) -> dict:
+    """List entries matching a git-bug query, for example 'status:open label:area/api'
+    or 'label:kind/defect sort:edit'. Returns ids, titles, status and labels, not bodies."""
+    return _run("query", query, first)
+
+
+def main():
+    mcp.run("stdio")
+
+
+if __name__ == "__main__":
+    main()

git_bug_broker-0.1.0/src/git_bug_broker/start.py

@@ -0,0 +1,131 @@
+"""Start, stop or inspect the git-bug web UI that owns one repository's store.
+
+    git-bug-broker-start <repo> [--port 38420]      start (idempotent: reuses a live one)
+    git-bug-broker-start <repo> --status            print the endpoint, exit 1 if down
+    git-bug-broker-start <repo> --stop              stop it gracefully (Ctrl+Break to its console)
+
+Writes <repo>/.git/git-bug-broker/endpoint.json ({url, port, pid, repo, started})
+and logs to webui.log beside it. Never passes --read-only, and never --open unless
+--open is given. Only stops a web UI it recorded itself.
+"""
+import argparse
+import datetime
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.request
+
+from . import client as C
+
+
+def alive(url):
+    try:
+        req = urllib.request.Request(url.rstrip("/") + "/graphql",
+                                     json.dumps({"query": "{repository{name}}"}).encode(),
+                                     {"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=3) as r:
+            return "data" in json.load(r)
+    except Exception:
+        return False
+
+
+def start(repo, port, open_browser):
+    sd = C.state_dir(repo)
+    os.makedirs(sd, exist_ok=True)
+    ep = C.read_endpoint(repo)
+    if ep and alive(ep["url"]):
+        print(json.dumps({**ep, "reused": True}))
+        return 0
+    args = ["git-bug", "webui", "--port", str(port), "--open" if open_browser else "--no-open",
+            "--log-errors"]
+    log = open(os.path.join(sd, "webui.log"), "ab")
+    kw = {}
+    if os.name == "nt":
+        # A hidden console of its own, so --stop can send it Ctrl+Break.
+        si = subprocess.STARTUPINFO()
+        si.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        si.wShowWindow = 0
+        kw = {"creationflags": subprocess.CREATE_NEW_CONSOLE, "startupinfo": si}
+    else:
+        kw = {"start_new_session": True}
+    p = subprocess.Popen(args, cwd=repo, stdout=log, stderr=log, stdin=subprocess.DEVNULL, **kw)
+    url = f"http://127.0.0.1:{port}"
+    for _ in range(100):
+        if alive(url):
+            break
+        if p.poll() is not None:
+            print(f"git-bug webui exited with {p.returncode}; see {sd}/webui.log", file=sys.stderr)
+            return 1
+        time.sleep(0.1)
+    else:
+        print("web UI did not answer within 10s", file=sys.stderr)
+        return 1
+    ep = {"url": url, "port": port, "pid": p.pid, "repo": os.path.abspath(repo),
+          "started": datetime.datetime.now().isoformat(timespec="seconds")}
+    with open(os.path.join(sd, "endpoint.json"), "w", encoding="utf-8") as f:
+        json.dump(ep, f, indent=1)
+    print(json.dumps(ep))
+    return 0
+
+
+def _ctrl_c_windows(pid):
+    # Go delivers Ctrl+Break as os.Interrupt, so git-bug shuts down and closes
+    # its index. Ctrl+C would be ignored by a process started on a new console.
+    # The helper attaches to that console and dies of the same event, so its exit
+    # code means nothing; the caller checks the endpoint instead.
+    code = ("import ctypes;k=ctypes.windll.kernel32;k.FreeConsole();"
+            f"k.AttachConsole({pid}) and k.GenerateConsoleCtrlEvent(1,0)")
+    subprocess.run([sys.executable, "-c", code], creationflags=subprocess.CREATE_NO_WINDOW)
+    return True
+
+
+def stop(repo):
+    ep = C.read_endpoint(repo)
+    if not ep:
+        print("no recorded web UI for this repository")
+        return 0
+    pid = ep["pid"]
+    if os.name == "nt":
+        sent = _ctrl_c_windows(pid)
+    else:
+        import signal
+        try:
+            os.kill(pid, signal.SIGINT)
+            sent = True
+        except ProcessLookupError:
+            sent = False
+    for _ in range(100):
+        if not alive(ep["url"]):
+            break
+        time.sleep(0.1)
+    if alive(ep["url"]):
+        print(f"web UI pid {pid} still answering after Ctrl+Break (sent={sent}); not killing it",
+              file=sys.stderr)
+        return 1
+    os.remove(os.path.join(C.state_dir(repo), "endpoint.json"))
+    print(json.dumps({"stopped": pid, "graceful": sent}))
+    return 0
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("repo")
+    ap.add_argument("--port", type=int, default=38420)
+    ap.add_argument("--open", action="store_true")
+    ap.add_argument("--stop", action="store_true")
+    ap.add_argument("--status", action="store_true")
+    a = ap.parse_args()
+    if a.stop:
+        return stop(a.repo)
+    if a.status:
+        ep = C.read_endpoint(a.repo)
+        up = bool(ep and alive(ep["url"]))
+        print(json.dumps({**(ep or {}), "alive": up}))
+        return 0 if up else 1
+    return start(a.repo, a.port, a.open)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

git_bug_broker-0.1.0/src/git_bug_broker.egg-info/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: git-bug-broker
+Version: 0.1.0
+Summary: MCP server that lets several agents share one git-bug store while the web UI is open
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JovianIce/git-bug-broker
+Project-URL: Source, https://github.com/JovianIce/git-bug-broker
+Project-URL: Issues, https://github.com/JovianIce/git-bug-broker/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# git-bug-broker
+
+An MCP server that lets several agents file, label and close issues in one [git-bug](https://github.com/git-bug/git-bug) store (a distributed issue tracker that keeps issues in git refs) while its web UI stays open.
+
+![An issue filed, reproduced, fixed and closed by an agent and its subagents, seen in git-bug's web UI](https://raw.githubusercontent.com/JovianIce/git-bug-broker/main/docs/agent-bug-sample.png)
+
+git-bug keeps issues inside the repository as git objects, so agents can track work
+next to the code with no hosted tracker, API token or network. Through this server an
+agent can open an issue for a bug it finds, comment on it as it investigates, label it,
+read what other agents have written, and close it with a note naming the commit that
+fixed it. Issues are versioned like commits and sync through any git remote with
+`git bug push` and `git bug pull`, so the record carries over between sessions and
+between agents.
+
+`git-bug webui` holds the search index for as long as it runs, and every CLI command waits on it without saying so. The broker talks to the web UI's GraphQL endpoint instead, takes a file lock for each write, and refuses any write that breaks the project's conventions: claim-style titles, one `area/` and one `kind/` label, required body sections. A rejected write lists every problem at once. Unlike a wrapper around the CLI, it keeps working while `git-bug webui` is open, and concurrent writes don't collide. The client is also a small Python library, so a script can write to the store while the UI is open too.
+
+Works with git-bug 0.11. Tested on Windows; the Linux and macOS paths are written but
+untested.
+
+## Install
+
+```sh
+pip install git-bug-broker
+```
+
+or from a checkout of [the repository](https://github.com/JovianIce/git-bug-broker), `pip install -e .`. Needs Python 3.10+ and `git-bug` on `PATH`.
+
+## Run
+
+```sh
+git-bug-broker-start <repo>            # start the web UI (reuses one already running)
+git-bug-broker-start <repo> --status
+git-bug-broker-start <repo> --stop
+```
+
+It prints the web UI's URL. An issue is at `<url>/_/issues/<id>`, where `<id>` is the
+short id the tools return. The issue list starts filtered to `status:open`; clear the
+search box to see closed issues too. `--stop` only stops the process it started.
+
+## Use from Python
+
+```python
+from git_bug_broker.client import Client
+
+c = Client(repo="/path/to/repo")
+c.file_entry(
+    "The retry loop never backs off after a 429",
+    "**What** retry() sleeps a fixed 1 s.
+**Done when** the delay doubles per attempt.",
+    ["area/api", "kind/defect"],
+)
+```
+
+## Connect an MCP client
+
+`.mcp.json` for Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "git-bug": {
+      "command": "git-bug-broker",
+      "env": {
+        "GITBUG_BROKER_REPO": "/path/to/repo",
+        "GITBUG_BROKER_RULES": "/path/to/repo/.git-bug-rules.json"
+      }
+    }
+  }
+}
+```
+
+Any stdio MCP client takes the same command and env.
+
+`GITBUG_BROKER_RULES` is optional. Without it the defaults in
+`src/git_bug_broker/rules/default.json` apply and any area name is accepted.
+`examples/rules.example.json` shows a project file with a fixed area list.
+
+`GITBUG_BROKER_URL` points the client at a web UI the broker did not start, for example one on another port.
+
+Tools: `file_entry`, `comment`, `edit_body`, `edit_comment`, `relabel`, `set_status`,
+`set_title`, `get`, `query`. A rejected write lists every problem at once.
+
+## Rules
+
+What gets checked is in [CONVENTIONS.md](https://github.com/JovianIce/git-bug-broker/blob/main/CONVENTIONS.md). Briefly:
+
+- a title is a claim about the code, at most 80 characters, with no leading number
+- exactly one `area/` and one `kind/` label, with a slash, never a colon
+- defects and chores have `What` and `Done when` sections
+
+## Why the lock
+
+git-bug 0.11 applies an operation and commits it in two unguarded steps. When two
+writes hit the same issue at once both land, but one caller is told
+`can't commit an entity with no pending operation`, and a retry duplicates the write.
+The broker holds `<repo>/.git/git-bug-broker/write.lock` for each write. Reads don't
+lock.
+
+Measured on git-bug 0.11 on Windows: with the lock, 24 parallel writes from 4 server processes, 12 of them to one shared
+issue, finished in 3.7 s with no errors. Without it, 28 of 30 concurrent writes to one
+issue reported failure although all 30 had landed.
+
+## Limitations
+
+- The web UI has to be running. If it isn't, every tool says so and nothing is queued.
+- Filing an issue is two mutations, create then label. A crash in between leaves an
+  unlabelled issue; the error gives its id.
+- The web UI binds to 127.0.0.1 with no authentication.
+- Edits made in the web UI aren't checked against the rules.
+- Free-text search returns at most 10 results. `title:`, `label:` and `status:`
+  filters return everything.
+
+## Development
+
+```sh
+pip install -e .[dev]
+pytest
+```
+
+`tools/view.py` renders the store as a static HTML page and a JSON Lines snapshot. It reads through the CLI, so run it while the web UI is stopped; anything reading its output needs neither.
+
+## License
+
+MIT

git_bug_broker-0.1.0/src/git_bug_broker.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/git_bug_broker/__init__.py
+src/git_bug_broker/client.py
+src/git_bug_broker/rules.py
+src/git_bug_broker/server.py
+src/git_bug_broker/start.py
+src/git_bug_broker.egg-info/PKG-INFO
+src/git_bug_broker.egg-info/SOURCES.txt
+src/git_bug_broker.egg-info/dependency_links.txt
+src/git_bug_broker.egg-info/entry_points.txt
+src/git_bug_broker.egg-info/requires.txt
+src/git_bug_broker.egg-info/top_level.txt
+src/git_bug_broker/rules/default.json
+tests/test_rules.py

git_bug_broker-0.1.0/src/git_bug_broker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

git_bug_broker-0.1.0/src/git_bug_broker.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+git-bug-broker = git_bug_broker.server:main
+git-bug-broker-start = git_bug_broker.start:main

git_bug_broker-0.1.0/src/git_bug_broker.egg-info/requires.txt

@@ -0,0 +1,4 @@
+mcp<3,>=2.2
+
+[dev]
+pytest

git_bug_broker-0.1.0/src/git_bug_broker.egg-info/top_level.txt

@@ -0,0 +1 @@
+git_bug_broker

git_bug_broker-0.1.0/tests/test_rules.py

@@ -0,0 +1,82 @@
+from git_bug_broker import rules as R
+
+BODY = "**What** parseConfig drops the field.\n**Done when** the timeout is honoured."
+
+
+def problems(title, labels, body=BODY, rules=None):
+    try:
+        R.check_entry(rules or R.load_rules(), title, body, labels)
+        return ""
+    except R.RuleViolation as e:
+        return str(e)
+
+
+def test_claim_title_passes():
+    assert problems("The retry loop never backs off after a 429", ["area/api", "kind/defect"]) == ""
+
+
+def test_topic_title_rejected():
+    assert "topic" in problems("Retry handling", ["area/api", "kind/defect"])
+
+
+def test_fix_title_rejected_for_defect():
+    assert "fix" in problems("Add backoff to the retry loop", ["area/api", "kind/defect"])
+
+
+def test_leading_number_rejected():
+    assert problems("12. The retry loop never backs off", ["area/api", "kind/defect"]) != ""
+
+
+def test_colon_label_rejected():
+    assert "colon" in problems("The retry loop never backs off after a 429", ["area:api", "kind/defect"])
+
+
+def test_exactly_one_area_and_kind():
+    assert problems("The retry loop never backs off after a 429", ["area/api", "area/ui", "kind/defect"]) != ""
+    assert problems("The retry loop never backs off after a 429", ["area/api"]) != ""
+
+
+def test_defect_body_needs_sections():
+    assert "Done when" in problems("The retry loop never backs off after a 429", ["area/api", "kind/defect"], body="It is broken.")
+
+
+def test_project_file_closes_areas(tmp_path):
+    f = tmp_path / "rules.json"
+    f.write_text('{"areas": ["api"], "areas_open": false}', encoding="utf-8")
+    rules = R.load_rules(str(f))
+    assert problems("The retry loop never backs off after a 429", ["area/api", "kind/defect"], rules=rules) == ""
+    assert "unknown area" in problems("The retry loop never backs off after a 429", ["area/ui", "kind/defect"], rules=rules)
+
+
+CLAIM = "The retry loop never backs off after a 429"
+
+
+def test_long_title_rejected():
+    assert "limit 80" in problems("The retry loop " + "never " * 20 + "backs off", ["area/api", "kind/defect"])
+
+
+def test_multiline_title_rejected():
+    assert "one line" in problems("The retry loop never backs off\nafter a 429", ["area/api", "kind/defect"])
+
+
+def test_unknown_kind_rejected():
+    assert "unknown kind" in problems(CLAIM, ["area/api", "kind/bug"])
+
+
+def test_unknown_flag_or_namespace_rejected():
+    assert "not a known flag" in problems(CLAIM, ["area/api", "kind/defect", "urgent"])
+    assert "not a known flag" in problems(CLAIM, ["area/api", "kind/defect", "team/web"])
+    assert "not a known flag" in problems(CLAIM, ["area/api", "kind/defect", "source/"])
+
+
+def test_uppercase_label_rejected():
+    assert "does not match" in problems(CLAIM, ["area/API", "kind/defect"])
+
+
+def test_chore_body_needs_sections():
+    out = problems("Rename the config loader to settings", ["area/api", "kind/chore"], body="Tidy up.")
+    assert "What" in out and "Done when" in out
+
+
+def test_fix_verb_accepted_for_chore():
+    assert problems("Rename the config loader to settings", ["area/api", "kind/chore"]) == ""