Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(self-build): store a brief per project and triage issues for code builds (#759)

Ruben Lütke1b82c779b1ab
diff --git a/dodaios/self_build/code/__init__.py b/dodaios/self_build/code/__init__.py
new file mode 100644
index 0000000000..b34043e16d
--- /dev/null
+++ b/dodaios/self_build/code/__init__.py
@@ -0,0 +1,8 @@
+"""Coding projects for the self-building loop (``Kind.CODE``).
+
+Dodaios knows the person's own repositories well enough to pick a suitable
+issue now and then and ship it through their coding agent as a pull request.
+This part holds what it knows: :mod:`.brief` (the stored project brief),
+:mod:`.commands` (how a project is tested), :mod:`.github` (the GitHub reads
+and writes it may make) and :mod:`.triage` (which issues qualify).
+"""
diff --git a/dodaios/self_build/code/brief.py b/dodaios/self_build/code/brief.py
new file mode 100644
index 0000000000..f3dced84d1
--- /dev/null
+++ b/dodaios/self_build/code/brief.py
@@ -0,0 +1,319 @@
+"""The project brief: what the code builder knows about one of the person's repositories.
+
+A brief is stored per repository checkout (``self_build_code.db``) and made of
+parts. Each part remembers the key it was built for, and a refresh rebuilds
+only the parts whose key changed:
+
+* ``git``: HEAD, branch, default branch, GitHub repository (HEAD moves).
+* ``structure``: stack, top folders, languages, a file map (the tree changes).
+* ``commands``: how to set up and test, what CI runs (the tree changes).
+* ``conventions``: AGENTS.md, CLAUDE.md and the like (one changes on disk).
+* ``activity``: recent commits, what the person worked on (HEAD moves).
+* ``github``: open issues and pull requests (each issue poll, ``intake``).
+* ``outcomes``: merged / changed / closed loop PRs, lessons (``watch``).
+
+Everything here is deterministic: git calls and file reads, no model. Keys
+are read with three cheap git calls and a few ``stat`` calls, so an unchanged
+project costs almost nothing to refresh.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Final
+
+from loguru import logger
+
+from . import commands, gitcmd
+from .store import CodeStore
+
+#: Instruction files whose rules the coding agent must follow.
+INSTRUCTION_FILES: Final[tuple[str, ...]] = (
+ "AGENTS.md",
+ "CLAUDE.md",
+ "GEMINI.md",
+ ".github/copilot-instructions.md",
+ "CONTRIBUTING.md",
+)
+_PER_FILE_CHARS: Final[int] = 2_500
+_CONVENTIONS_CHARS: Final[int] = 6_000
+_MAP_CHARS: Final[int] = 1_800
+_RENDER_CHARS: Final[int] = 9_000
+#: Parts this module builds from the checkout.
+LOCAL_PARTS: Final[tuple[str, ...]] = ("git", "structure", "commands", "conventions", "activity")
+_SKIP_DIRS: Final[frozenset[str]] = frozenset(
+ {"node_modules", ".venv", "venv", "env", "dist", "build", "target", "__pycache__", ".git"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Brief:
+ project_key: str
+ folder: str
+ repo: str
+ parts: dict[str, Any]
+ keys: dict[str, str]
+ updated_ms: int = 0
+
+ @property
+ def test_commands(self) -> list[list[str]]:
+ return [list(c) for c in (self.parts.get("commands") or {}).get("test") or []]
+
+ @property
+ def setup_commands(self) -> list[list[str]]:
+ return [list(c) for c in (self.parts.get("commands") or {}).get("setup") or []]
+
+ @property
+ def default_branch(self) -> str:
+ return str((self.parts.get("git") or {}).get("default_branch") or "")
+
+ def render(self, max_chars: int = _RENDER_CHARS) -> str:
+ """The brief as the text a coding agent reads first."""
+ p = self.parts
+ g = p.get("git") or {}
+ s = p.get("structure") or {}
+ c = p.get("commands") or {}
+ a = p.get("activity") or {}
+ lines = [f"Repository: {self.repo or '(no GitHub remote)'}"]
+ if g.get("default_branch"):
+ lines.append(f"Default branch: {g['default_branch']}")
+ if s.get("stacks"):
+ lines.append("Stack: " + ", ".join(s["stacks"]))
+ if s.get("languages"):
+ lines.append("Languages: " + ", ".join(s["languages"]))
+ if s.get("top_level"):
+ lines.append("Top-level folders: " + ", ".join(s["top_level"]))
+ if c.get("test"):
+ lines.append("Tests: " + " && ".join(commands.shown(cmd) for cmd in c["test"]))
+ if c.get("ci"):
+ lines.append("CI: " + " | ".join(c["ci"]))
+ if a.get("mine"):
+ lines.append("The person's recent commits here:")
+ lines += [f" - {subject}" for subject in a["mine"][:8]]
+ if a.get("hot_paths"):
+ lines.append("Where they have been working: " + ", ".join(a["hot_paths"]))
+ outcomes = p.get("outcomes") or {}
+ if outcomes.get("lessons"):
+ lines.append("Earlier loop attempts here went wrong because:")
+ lines += [f" - {lesson}" for lesson in outcomes["lessons"][-5:]]
+ if outcomes.get("changed"):
+ lines.append("The person changed these loop PRs before merging:")
+ lines += [f" - {item}" for item in outcomes["changed"][-3:]]
+ conventions = p.get("conventions") or {}
+ for name, text in (conventions.get("files") or {}).items():
+ lines += ["", f"--- {name} ---", text]
+ if s.get("map"):
+ lines += ["", "--- File map ---", s["map"]]
+ text = "\n".join(lines)
+ return text if len(text) <= max_chars else text[: max_chars - 1].rstrip() + "…"
+
+
+# ------------------------------------------------------------------ keys
+
+
+def project_key(folder: str | Path) -> str:
+ """One key per repository checkout: every worktree shares its main checkout's."""
+ from dodaios.agentic_ide.github_link import folder_key
+
+ return folder_key(folder)
+
+
+def _stamp(paths: list[Path]) -> str:
+ digest = hashlib.sha256()
+ for path in paths:
+ try:
+ info = path.stat()
+ except OSError: # a file deleted meanwhile simply leaves the stamp
+ continue
+ digest.update(f"{path.name}:{info.st_size}:{info.st_mtime_ns}\n".encode())
+ return digest.hexdigest()[:20]
+
+
+def part_keys(folder: str | Path) -> dict[str, str]:
+ root = Path(folder)
+ head = gitcmd.out(["rev-parse", "HEAD"], root)
+ tree = gitcmd.out(["rev-parse", "HEAD^{tree}"], root)
+ present = [root / name for name in INSTRUCTION_FILES if (root / name).is_file()]
+ return {
+ "git": head,
+ "structure": tree,
+ "commands": tree,
+ "conventions": _stamp(present) if present else "none",
+ "activity": head,
+ }
+
+
+# ------------------------------------------------------------------ parts
+
+
+def default_branch(root: Path) -> str:
+ ref = gitcmd.out(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], root)
+ if ref.startswith("origin/"):
+ return ref.partition("/")[2]
+ for name in ("main", "master", "trunk", "develop"):
+ if gitcmd.git(["show-ref", "--verify", "--quiet", f"refs/heads/{name}"], root).ok:
+ return name
+ return gitcmd.out(["rev-parse", "--abbrev-ref", "HEAD"], root)
+
+
+def _git_part(root: Path, repo: str) -> dict[str, Any]:
+ return {
+ "head": gitcmd.out(["rev-parse", "HEAD"], root),
+ "branch": gitcmd.out(["rev-parse", "--abbrev-ref", "HEAD"], root),
+ "default_branch": default_branch(root),
+ "repo": repo,
+ }
+
+
+def _languages(root: Path) -> list[str]:
+ listing = gitcmd.out(["ls-files"], root)
+ counts: Counter[str] = Counter()
+ for line in listing.splitlines()[:50_000]:
+ suffix = Path(line).suffix.lower()
+ if suffix and len(suffix) <= 6:
+ counts[suffix] += 1
+ return [f"{ext} ({n})" for ext, n in counts.most_common(6)]
+
+
+def _structure_part(root: Path) -> dict[str, Any]:
+ from dodaios.agentic_ide.folders import probe_project
+
+ profile = probe_project(root)
+ file_map = ""
+ try:
+ from dodaios.agentic_ide.file_index import build_index
+
+ file_map = build_index(root).render_map(max_chars=_MAP_CHARS)
+ except Exception as exc: # noqa: BLE001 - the map is optional; the brief still helps
+ logger.debug("self-build code: file map unavailable for {}: {}", root, exc)
+ return {
+ "stacks": list(profile.stacks),
+ "top_level": [d for d in profile.top_level_dirs if d not in _SKIP_DIRS][:20],
+ "languages": _languages(root),
+ "map": file_map,
+ }
+
+
+def _conventions_part(root: Path) -> dict[str, Any]:
+ files: dict[str, str] = {}
+ budget = _CONVENTIONS_CHARS
+ for name in INSTRUCTION_FILES:
+ path = root / name
+ if budget <= 0 or not path.is_file():
+ continue
+ try:
+ text = path.read_text(encoding="utf-8", errors="replace").strip()
+ except OSError: # an unreadable instruction file is left out of the brief
+ continue
+ clip = text[: min(_PER_FILE_CHARS, budget)]
+ files[name] = clip + ("…" if len(text) > len(clip) else "")
+ budget -= len(clip)
+ return {"files": files}
+
+
+def _activity_part(root: Path) -> dict[str, Any]:
+ email = gitcmd.out(["config", "user.email"], root).lower()
+ log = gitcmd.out(["log", "-n", "40", "--format=%ae%x1f%ct%x1f%s"], root)
+ recent: list[str] = []
+ mine: list[str] = []
+ for line in log.splitlines():
+ author, _, rest = line.partition("\x1f")
+ _stamp_, _, subject = rest.partition("\x1f")
+ recent.append(subject)
+ if email and author.lower() == email:
+ mine.append(subject)
+ hot: Counter[str] = Counter()
+ if email:
+ names = gitcmd.out(
+ ["log", f"--author={email}", "--since=30.days", "--name-only", "--format="], root
+ )
+ for name in names.splitlines():
+ parts = Path(name.strip()).parts
+ if parts:
+ hot["/".join(parts[:2]) if len(parts) > 2 else parts[0]] += 1
+ return {
+ "recent": recent[:15],
+ "mine": mine[:15],
+ "hot_paths": [path for path, _n in hot.most_common(8)],
+ "person_active": bool(mine),
+ }
+
+
+def _build_part(part: str, root: Path, repo: str) -> Any:
+ if part == "git":
+ return _git_part(root, repo)
+ if part == "structure":
+ return _structure_part(root)
+ if part == "commands":
+ return commands.detect(root)
+ if part == "conventions":
+ return _conventions_part(root)
+ if part == "activity":
+ return _activity_part(root)
+ raise ValueError(part)
+
+
+# ------------------------------------------------------------------ refresh
+
+
+def load(store: CodeStore, folder: str | Path) -> Brief | None:
+ row = store.brief(project_key(folder))
+ if row is None:
+ return None
+ return Brief(
+ project_key=row["project_key"],
+ folder=row["folder"],
+ repo=row["repo"],
+ parts=row["parts"],
+ keys=row["keys"],
+ updated_ms=row["updated_ms"],
+ )
+
+
+def refresh(store: CodeStore, folder: str | Path, *, repo: str = "") -> tuple[Brief, list[str]]:
+ """The stored brief, with every stale local part rebuilt. Returns the brief
+ and the names of the parts that were rebuilt (empty: nothing changed)."""
+ root = Path(folder)
+ key = project_key(root)
+ old = store.brief(key) or {"parts": {}, "keys": {}, "repo": ""}
+ keys = part_keys(root)
+ parts = dict(old["parts"])
+ stored_keys = dict(old["keys"])
+ rebuilt: list[str] = []
+ repo = repo or str(old.get("repo") or "")
+ for part in LOCAL_PARTS:
+ if part in parts and stored_keys.get(part) == keys[part] and keys[part]:
+ continue
+ try:
+ parts[part] = _build_part(part, root, repo)
+ except Exception as exc: # noqa: BLE001 - one unreadable part must not lose the rest
+ logger.warning("self-build code: brief part {} failed for {}: {}", part, root, exc)
+ continue
+ stored_keys[part] = keys[part]
+ rebuilt.append(part)
+ if rebuilt or repo != old.get("repo"):
+ store.put_brief(key, folder=os.fspath(root), repo=repo, parts=parts, keys=stored_keys)
+ return (
+ Brief(project_key=key, folder=os.fspath(root), repo=repo, parts=parts, keys=stored_keys),
+ rebuilt,
+ )
+
+
+def note_outcomes(store: CodeStore, folder: str | Path, profile: dict[str, Any]) -> None:
+ """Fold the repository's outcome profile into its brief (``outcomes`` part)."""
+ merged = [e for e in profile.get("merged", []) if isinstance(e, dict)]
+ summary = {
+ "merged": len([e for e in merged if not e.get("changed")]),
+ "changed": [f"#{e.get('number')} {e.get('title', '')}" for e in merged if e.get("changed")][
+ -5:
+ ],
+ "closed": len(profile.get("closed", [])),
+ "lessons": [
+ str(e.get("lesson") or "") for e in profile.get("lessons", []) if isinstance(e, dict)
+ ][-8:],
+ }
+ store.set_part(project_key(folder), "outcomes", summary)
diff --git a/dodaios/self_build/code/commands.py b/dodaios/self_build/code/commands.py
new file mode 100644
index 0000000000..f5b12e80e6
--- /dev/null
+++ b/dodaios/self_build/code/commands.py
@@ -0,0 +1,131 @@
+"""How a project is tested, read from its files and nothing else.
+
+The test command is the judge of a loop-made change, so it comes from the
+project as it was BEFORE the coding agent touched it, never from the agent.
+Detection is deterministic and conservative: a project whose tests cannot be
+found is not worked on (triage refuses it), rather than shipped untested.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+#: Where a project keeps its virtual environment, newest convention first.
+_VENVS = (".venv", "venv", "env")
+_WORKFLOW_RUN = re.compile(r"^\s*(?:-\s*)?run:\s*(.+)$")
+_TESTY = re.compile(
+ r"\b(pytest|tox|nox|jest|vitest|mocha|npm (?:run )?test|pnpm (?:run )?test|yarn test|"
+ r"cargo test|go test|make test|gradle test|mvn test)\b"
+)
+
+
+def _read(path: Path, limit: int = 200_000) -> str:
+ try:
+ return path.read_text(encoding="utf-8", errors="replace")[:limit]
+ except OSError: # an unreadable file counts as absent: no command from it
+ return ""
+
+
+def _python(folder: Path) -> str:
+ """The project's own interpreter when it has a virtual environment."""
+ for name in _VENVS:
+ for rel in ("Scripts/python.exe", "bin/python"):
+ candidate = folder / name / rel
+ if candidate.is_file():
+ return str(candidate)
+ return "python"
+
+
+def _python_tests(folder: Path) -> bool:
+ has_tests = any((folder / name).is_dir() for name in ("tests", "test"))
+ if (folder / "pytest.ini").is_file() or (folder / "conftest.py").is_file():
+ return True
+ if "[tool.pytest" in _read(folder / "pyproject.toml"):
+ return True
+ if "[tool:pytest]" in _read(folder / "setup.cfg"):
+ return True
+ markers = ("pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "tox.ini")
+ return has_tests and any((folder / m).is_file() for m in markers)
+
+
+def _node(folder: Path) -> tuple[list[list[str]], list[list[str]]]:
+ raw = _read(folder / "package.json")
+ if not raw:
+ return [], []
+ try:
+ package = json.loads(raw)
+ except ValueError: # a broken package.json gives no test command, so no build
+ return [], []
+ scripts = package.get("scripts") if isinstance(package, dict) else None
+ test = str((scripts or {}).get("test") or "") if isinstance(scripts, dict) else ""
+ if not test or "no test specified" in test:
+ return [], []
+ if (folder / "pnpm-lock.yaml").is_file():
+ return [["pnpm", "install", "--frozen-lockfile"]], [["pnpm", "test"]]
+ if (folder / "yarn.lock").is_file():
+ return [["yarn", "install", "--frozen-lockfile"]], [["yarn", "test"]]
+ setup = [["npm", "ci"]] if (folder / "package-lock.json").is_file() else [["npm", "install"]]
+ return setup, [["npm", "test", "--silent"]]
+
+
+def _makefile_test(folder: Path) -> bool:
+ text = _read(folder / "Makefile")
+ return bool(re.search(r"^test\s*:", text, re.MULTILINE))
+
+
+def ci_lines(folder: Path, limit: int = 8) -> list[str]:
+ """The workflow files and the test lines they run (for the brief only)."""
+ workflows = folder / ".github" / "workflows"
+ if not workflows.is_dir():
+ return []
+ lines: list[str] = []
+ try:
+ files = sorted(p for p in workflows.iterdir() if p.suffix in (".yml", ".yaml"))
+ except OSError: # unreadable workflows only leave the brief without CI lines
+ return []
+ for path in files[:12]:
+ runs = [
+ match.group(1).strip()
+ for match in map(_WORKFLOW_RUN.match, _read(path, 60_000).splitlines())
+ if match and _TESTY.search(match.group(1))
+ ]
+ lines.append(f"{path.name}: " + ("; ".join(runs[:3]) if runs else "(no test step)"))
+ if len(lines) >= limit:
+ break
+ return lines
+
+
+def detect(folder: str | Path) -> dict[str, Any]:
+ """``{"label", "setup", "test", "ci"}``: argv lists, empty when unknown."""
+ root = Path(folder)
+ setup: list[list[str]] = []
+ test: list[list[str]] = []
+ label = ""
+ if _python_tests(root):
+ test.append([_python(root), "-m", "pytest", "-q", "-x", "-p", "no:cacheprovider"])
+ label = "pytest"
+ node_setup, node_test = _node(root)
+ if node_test:
+ setup += node_setup
+ test += node_test
+ label = label or node_test[0][0]
+ if (root / "Cargo.toml").is_file():
+ test.append(["cargo", "test", "--quiet"])
+ label = label or "cargo"
+ if (root / "go.mod").is_file():
+ test.append(["go", "test", "./..."])
+ label = label or "go"
+ if not test and _makefile_test(root):
+ test.append(["make", "test"])
+ label = "make"
+ return {"label": label, "setup": setup, "test": test, "ci": ci_lines(root)}
+
+
+def shown(argv: list[str]) -> str:
+ """A command as the person would type it (the venv path shortened)."""
+ if argv and Path(argv[0]).name.lower().startswith("python") and len(argv[0]) > 12:
+ return " ".join(["python", *argv[1:]])
+ return " ".join(argv)
diff --git a/dodaios/self_build/code/gitcmd.py b/dodaios/self_build/code/gitcmd.py
new file mode 100644
index 0000000000..273f76d64f
--- /dev/null
+++ b/dodaios/self_build/code/gitcmd.py
@@ -0,0 +1,75 @@
+"""The few git and shell calls the code builder makes, bounded and windowless."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS
+
+GIT_TIMEOUT_S = 60.0
+NETWORK_TIMEOUT_S = 180.0
+
+
+@dataclass(frozen=True, slots=True)
+class Result:
+ code: int
+ out: str
+ err: str
+
+ @property
+ def ok(self) -> bool:
+ return self.code == 0
+
+ def tail(self, limit: int = 1500) -> str:
+ text = (self.out + ("\n" + self.err if self.err else "")).strip()
+ return text[-limit:]
+
+
+def run(
+ argv: Sequence[str],
+ cwd: str | Path,
+ *,
+ timeout: float = GIT_TIMEOUT_S,
+ env: Mapping[str, str] | None = None,
+) -> Result:
+ """Run ``argv`` in ``cwd``. Never raises: a missing program or a timeout is a
+ non-zero :class:`Result` whose ``err`` says which."""
+ child = dict(os.environ if env is None else env)
+ # Never wait on a credential or editor prompt nobody can see.
+ child["GIT_TERMINAL_PROMPT"] = "0"
+ child.setdefault("GIT_EDITOR", "true")
+ child["GH_PROMPT_DISABLED"] = "1"
+ try:
+ done = subprocess.run(
+ list(argv),
+ cwd=str(cwd),
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ timeout=timeout,
+ check=False,
+ env=child,
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ except FileNotFoundError: # reported in the Result, which every caller checks
+ return Result(127, "", f"{argv[0]} is not installed")
+ except subprocess.TimeoutExpired: # reported in the Result, which every caller checks
+ return Result(124, "", f"{argv[0]} did not finish within {int(timeout)} s")
+ except OSError as exc: # reported in the Result, which every caller checks
+ return Result(126, "", f"{argv[0]} could not start: {exc}")
+ return Result(done.returncode, done.stdout or "", done.stderr or "")
+
+
+def git(args: Sequence[str], cwd: str | Path, *, timeout: float = GIT_TIMEOUT_S) -> Result:
+ return run(["git", "-c", "core.quotepath=off", *args], cwd, timeout=timeout)
+
+
+def out(args: Sequence[str], cwd: str | Path) -> str:
+ """Trimmed stdout of a git call, ``""`` when it failed."""
+ result = git(args, cwd)
+ return result.out.strip() if result.ok else ""
diff --git a/dodaios/self_build/code/github.py b/dodaios/self_build/code/github.py
new file mode 100644
index 0000000000..1d41867a85
--- /dev/null
+++ b/dodaios/self_build/code/github.py
@@ -0,0 +1,366 @@
+"""The GitHub calls the code builder makes, with the person's existing connection.
+
+Reads: who the person is and which organisations they administer, a
+repository's open issues and pull requests, one pull request's state and CI.
+Writes, only in the person's own repositories: open a pull request, close it
+(undo), merge it (only where the person opted in per repository). Nothing
+else: no issue comments, no labels, no reviews.
+
+The credential is the one the IDE's Git tab uses (``github_link.credential``):
+the app's GitHub connection, else ``gh auth token``. There is no public webhook
+URL on a desktop, so the loop polls.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from dodaios.agentic_ide import github_link
+from dodaios.agentic_ide.github_link import GitHubError
+
+#: Owner permissions that may receive a loop pull request.
+OWN_PERMISSIONS = frozenset({"ADMIN", "MAINTAIN"})
+
+
+@dataclass(frozen=True, slots=True)
+class Viewer:
+ login: str
+ #: Organisations the person administers (lower case).
+ admin_orgs: frozenset[str] = frozenset()
+
+ def owns(self, repo: str) -> bool:
+ owner = repo.partition("/")[0].strip().lower()
+ return bool(owner) and (owner == self.login.lower() or owner in self.admin_orgs)
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+ number: int
+ title: str
+ body: str = ""
+ url: str = ""
+ author: str = ""
+ labels: tuple[str, ...] = ()
+ assignees: int = 0
+ comments: int = 0
+ state: str = "OPEN"
+ updated_at: str = ""
+
+ def to_json(self) -> dict[str, Any]:
+ return {
+ "number": self.number,
+ "title": self.title,
+ "body": self.body,
+ "url": self.url,
+ "author": self.author,
+ "labels": list(self.labels),
+ "assignees": self.assignees,
+ "comments": self.comments,
+ "state": self.state,
+ "updated_at": self.updated_at,
+ }
+
+ @classmethod
+ def from_json(cls, data: dict[str, Any]) -> Issue:
+ return cls(
+ number=int(data.get("number") or 0),
+ title=str(data.get("title") or ""),
+ body=str(data.get("body") or ""),
+ url=str(data.get("url") or ""),
+ author=str(data.get("author") or ""),
+ labels=tuple(str(x) for x in data.get("labels") or ()),
+ assignees=int(data.get("assignees") or 0),
+ comments=int(data.get("comments") or 0),
+ state=str(data.get("state") or "OPEN"),
+ updated_at=str(data.get("updated_at") or ""),
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class PullRef:
+ number: int
+ title: str
+ head: str = ""
+ body: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+ repo: str
+ permission: str = ""
+ archived: bool = False
+ fork: bool = False
+ default_branch: str = ""
+ issues: tuple[Issue, ...] = ()
+ pulls: tuple[PullRef, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class PullState:
+ id: str
+ number: int
+ url: str
+ #: ``OPEN`` | ``CLOSED`` | ``MERGED``.
+ state: str
+ draft: bool = False
+ head_oid: str = ""
+ #: The CI rollup of the head commit: ``SUCCESS`` | ``FAILURE`` | ``ERROR`` |
+ #: ``PENDING`` | ``EXPECTED`` | ``""`` (no checks at all).
+ checks: str = ""
+ commits: int = 0
+ failing: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True, slots=True)
+class CreatedPull:
+ id: str
+ number: int
+ url: str
+
+
+class GitHub(Protocol):
+ """What the loop needs from GitHub; tests pass a fake."""
+
+ def viewer(self) -> Viewer: ...
+ def snapshot(self, repo: str) -> Snapshot: ...
+ def create_pull(
+ self, repo: str, *, head: str, base: str, title: str, body: str, draft: bool
+ ) -> CreatedPull: ...
+ def pull(self, repo: str, number: int) -> PullState: ...
+ def close_pull(self, pull_id: str) -> None: ...
+ def merge_pull(self, pull_id: str, *, head_oid: str) -> None: ...
+
+
+_VIEWER = """
+query {
+ viewer {
+ login
+ organizations(first: 100) { nodes { login viewerCanAdminister } }
+ }
+}
+"""
+
+_SNAPSHOT = """
+query($owner: String!, $name: String!) {
+ repository(owner: $owner, name: $name) {
+ nameWithOwner isArchived isFork viewerPermission
+ defaultBranchRef { name }
+ issues(states: OPEN, first: 30, orderBy: {field: UPDATED_AT, direction: DESC}) {
+ nodes {
+ number title body url updatedAt state
+ author { login }
+ assignees(first: 1) { totalCount }
+ labels(first: 20) { nodes { name } }
+ comments { totalCount }
+ }
+ }
+ pullRequests(states: OPEN, first: 30, orderBy: {field: UPDATED_AT, direction: DESC}) {
+ nodes { number title headRefName body }
+ }
+ }
+}
+"""
+
+_PULL = """
+query($owner: String!, $name: String!, $number: Int!) {
+ repository(owner: $owner, name: $name) {
+ pullRequest(number: $number) {
+ id number url state isDraft headRefOid
+ commits(last: 1) {
+ totalCount
+ nodes { commit { statusCheckRollup {
+ state
+ contexts(first: 30) { nodes {
+ ... on CheckRun { name conclusion }
+ ... on StatusContext { context state }
+ } }
+ } } }
+ }
+ }
+ }
+}
+"""
+
+_REPOSITORY_ID = """
+query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { id } }
+"""
+
+_CREATE = """
+mutation($input: CreatePullRequestInput!) {
+ createPullRequest(input: $input) { pullRequest { id number url } }
+}
+"""
+
+_CLOSE = """
+mutation($id: ID!) { closePullRequest(input: {pullRequestId: $id}) { pullRequest { state } } }
+"""
+
+_MERGE = """
+mutation($id: ID!, $oid: GitObjectID) {
+ mergePullRequest(input: {pullRequestId: $id, mergeMethod: SQUASH, expectedHeadOid: $oid}) {
+ pullRequest { state }
+ }
+}
+"""
+
+_BAD = frozenset(
+ {"FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"}
+)
+
+
+def _split(repo: str) -> tuple[str, str]:
+ owner, _, name = repo.partition("/")
+ if not owner or not name:
+ raise GitHubError("A repository is written as owner/name.", code="needs_repo")
+ return owner, name
+
+
+def _first_error(payload: dict[str, Any]) -> str:
+ for error in payload.get("errors") or []:
+ if isinstance(error, dict) and error.get("message"):
+ return str(error["message"])[:300]
+ return ""
+
+
+class GitHubApi:
+ """:class:`GitHub` over GraphQL with the person's token."""
+
+ def __init__(self, token: str) -> None:
+ self._token = token
+
+ @classmethod
+ def connect(cls) -> GitHubApi | None:
+ cred = github_link.credential()
+ return cls(cred.token) if cred is not None else None
+
+ def _q(self, query: str, variables: dict[str, Any] | None = None) -> dict[str, Any]:
+ return github_link.graphql(self._token, query, variables or {})
+
+ def viewer(self) -> Viewer:
+ data = (self._q(_VIEWER).get("data") or {}).get("viewer") or {}
+ orgs = frozenset(
+ str(node.get("login") or "").lower()
+ for node in (data.get("organizations") or {}).get("nodes") or []
+ if isinstance(node, dict) and node.get("viewerCanAdminister")
+ )
+ return Viewer(login=str(data.get("login") or ""), admin_orgs=orgs - {""})
+
+ def snapshot(self, repo: str) -> Snapshot:
+ owner, name = _split(repo)
+ data = (self._q(_SNAPSHOT, {"owner": owner, "name": name}).get("data") or {}).get(
+ "repository"
+ ) or {}
+ issues = []
+ for node in (data.get("issues") or {}).get("nodes") or []:
+ if not isinstance(node, dict):
+ continue
+ issues.append(
+ Issue(
+ number=int(node.get("number") or 0),
+ title=str(node.get("title") or ""),
+ body=str(node.get("body") or "")[:8_000],
+ url=str(node.get("url") or ""),
+ author=str((node.get("author") or {}).get("login") or ""),
+ labels=tuple(
+ str(label.get("name") or "")
+ for label in (node.get("labels") or {}).get("nodes") or []
+ if isinstance(label, dict)
+ ),
+ assignees=int((node.get("assignees") or {}).get("totalCount") or 0),
+ comments=int((node.get("comments") or {}).get("totalCount") or 0),
+ state=str(node.get("state") or "OPEN"),
+ updated_at=str(node.get("updatedAt") or ""),
+ )
+ )
+ pulls = [
+ PullRef(
+ number=int(node.get("number") or 0),
+ title=str(node.get("title") or ""),
+ head=str(node.get("headRefName") or ""),
+ body=str(node.get("body") or "")[:4_000],
+ )
+ for node in (data.get("pullRequests") or {}).get("nodes") or []
+ if isinstance(node, dict)
+ ]
+ return Snapshot(
+ repo=str(data.get("nameWithOwner") or repo),
+ permission=str(data.get("viewerPermission") or ""),
+ archived=bool(data.get("isArchived")),
+ fork=bool(data.get("isFork")),
+ default_branch=str((data.get("defaultBranchRef") or {}).get("name") or ""),
+ issues=tuple(issues),
+ pulls=tuple(pulls),
+ )
+
+ def create_pull(
+ self, repo: str, *, head: str, base: str, title: str, body: str, draft: bool
+ ) -> CreatedPull:
+ owner, name = _split(repo)
+ found = self._q(_REPOSITORY_ID, {"owner": owner, "name": name})
+ repo_id = ((found.get("data") or {}).get("repository") or {}).get("id")
+ if not repo_id:
+ raise GitHubError("GitHub does not know this repository.", code="repo_missing")
+ payload = self._q(
+ _CREATE,
+ {
+ "input": {
+ "repositoryId": repo_id,
+ "baseRefName": base,
+ "headRefName": head,
+ "title": title,
+ "body": body,
+ "draft": draft,
+ }
+ },
+ )
+ created = ((payload.get("data") or {}).get("createPullRequest") or {}).get("pullRequest")
+ if not isinstance(created, dict) or not created.get("url"):
+ raise GitHubError(
+ _first_error(payload) or "GitHub could not open the pull request.",
+ code="refused",
+ )
+ return CreatedPull(
+ id=str(created.get("id") or ""),
+ number=int(created.get("number") or 0),
+ url=str(created["url"]),
+ )
+
+ def pull(self, repo: str, number: int) -> PullState:
+ owner, name = _split(repo)
+ variables = {"owner": owner, "name": name, "number": int(number)}
+ repository = (self._q(_PULL, variables).get("data") or {}).get("repository") or {}
+ data = repository.get("pullRequest") or {}
+ if not data:
+ raise GitHubError("GitHub does not know this pull request.", code="not_found")
+ commits = data.get("commits") or {}
+ nodes = commits.get("nodes") or []
+ rollup = ((nodes[-1] or {}).get("commit") or {}).get("statusCheckRollup") if nodes else None
+ failing: list[str] = []
+ for ctx in ((rollup or {}).get("contexts") or {}).get("nodes") or []:
+ if not isinstance(ctx, dict):
+ continue
+ verdict = str(ctx.get("conclusion") or ctx.get("state") or "").upper()
+ if verdict in _BAD:
+ failing.append(str(ctx.get("name") or ctx.get("context") or "check"))
+ return PullState(
+ id=str(data.get("id") or ""),
+ number=int(data.get("number") or number),
+ url=str(data.get("url") or ""),
+ state=str(data.get("state") or ""),
+ draft=bool(data.get("isDraft")),
+ head_oid=str(data.get("headRefOid") or ""),
+ checks=str((rollup or {}).get("state") or ""),
+ commits=int(commits.get("totalCount") or 0),
+ failing=tuple(failing[:10]),
+ )
+
+ def close_pull(self, pull_id: str) -> None:
+ payload = self._q(_CLOSE, {"id": pull_id})
+ if not ((payload.get("data") or {}).get("closePullRequest")):
+ raise GitHubError(_first_error(payload) or "GitHub could not close the pull request.")
+
+ def merge_pull(self, pull_id: str, *, head_oid: str) -> None:
+ payload = self._q(_MERGE, {"id": pull_id, "oid": head_oid or None})
+ if not ((payload.get("data") or {}).get("mergePullRequest")):
+ raise GitHubError(_first_error(payload) or "GitHub could not merge the pull request.")
diff --git a/dodaios/self_build/code/store.py b/dodaios/self_build/code/store.py
new file mode 100644
index 0000000000..e2b6890f06
--- /dev/null
+++ b/dodaios/self_build/code/store.py
@@ -0,0 +1,252 @@
+"""``self_build_code.db``: what the code builder knows about the person's projects.
+
+The build ledger (``self_build.db``) holds one row per build. This file holds
+the knowledge the code builder works from, so nothing is recomputed from
+scratch on every pass:
+
+* ``briefs``: one project brief per repository checkout, stored in parts, each
+ part with the key it was built for (a HEAD, a tree, file stamps). A pass
+ rebuilds only the parts whose key changed.
+* ``issues``: the triage verdict per issue and the ``updatedAt`` it was given
+ for, so an unchanged issue is not triaged twice.
+* ``profiles``: per repository, what happened to the loop's pull requests
+ (merged as they were, changed before merge, closed) and the lessons of
+ failed runs. Triage and the next prompt read it.
+* ``polls``: when a repository was last asked for issues.
+
+Plain ``sqlite3`` behind one lock, like the ledger; async callers wrap calls in
+``asyncio.to_thread``.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Any, Final
+
+from ..ledger import now_ms
+from ..records import dumps
+
+DB_NAME: Final[str] = "self_build_code.db"
+
+_SCHEMA: Final[str] = """
+CREATE TABLE IF NOT EXISTS briefs (
+ project_key TEXT PRIMARY KEY,
+ folder TEXT NOT NULL,
+ repo TEXT NOT NULL DEFAULT '',
+ parts_json TEXT NOT NULL DEFAULT '{}',
+ keys_json TEXT NOT NULL DEFAULT '{}',
+ updated_ms INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS issues (
+ repo TEXT NOT NULL,
+ number INTEGER NOT NULL,
+ updated_at TEXT NOT NULL DEFAULT '',
+ verdict TEXT NOT NULL DEFAULT '',
+ reason TEXT NOT NULL DEFAULT '',
+ issue_json TEXT NOT NULL DEFAULT '{}',
+ seen_ms INTEGER NOT NULL,
+ PRIMARY KEY (repo, number)
+);
+CREATE TABLE IF NOT EXISTS profiles (
+ repo TEXT PRIMARY KEY,
+ json TEXT NOT NULL DEFAULT '{}',
+ updated_ms INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS polls (
+ repo TEXT PRIMARY KEY,
+ last_ms INTEGER NOT NULL
+);
+"""
+
+#: How many merged / closed pull requests and lessons a profile remembers.
+PROFILE_KEEP: Final[int] = 30
+
+
+def _loads(raw: Any, default: Any) -> Any:
+ try:
+ value = json.loads(raw or "")
+ except (TypeError, ValueError): # a damaged row reads as empty, the next write repairs it
+ return default
+ return value if isinstance(value, type(default)) else default
+
+
+def repo_key(repo: str) -> str:
+ """GitHub names are case-insensitive: one row per repository."""
+ return repo.strip().lower()
+
+
+class CodeStore:
+ def __init__(self, path: Path) -> None:
+ self._path = Path(path)
+ self._lock = threading.RLock()
+ self._path.parent.mkdir(parents=True, exist_ok=True)
+ self._conn = sqlite3.connect(str(self._path), check_same_thread=False, timeout=5.0)
+ self._conn.execute("PRAGMA journal_mode=WAL")
+ self._conn.execute("PRAGMA busy_timeout=5000")
+ self._conn.executescript(_SCHEMA)
+ self._conn.commit()
+
+ @property
+ def path(self) -> Path:
+ return self._path
+
+ def close(self) -> None:
+ with self._lock:
+ self._conn.close()
+
+ # ------------------------------------------------------------ briefs
+
+ def brief(self, project_key: str) -> dict[str, Any] | None:
+ with self._lock:
+ row = self._conn.execute(
+ "SELECT folder, repo, parts_json, keys_json, updated_ms FROM briefs"
+ " WHERE project_key = ?",
+ (project_key,),
+ ).fetchone()
+ if row is None:
+ return None
+ return {
+ "project_key": project_key,
+ "folder": str(row[0]),
+ "repo": str(row[1]),
+ "parts": _loads(row[2], {}),
+ "keys": _loads(row[3], {}),
+ "updated_ms": int(row[4]),
+ }
+
+ def briefs(self) -> list[dict[str, Any]]:
+ with self._lock:
+ keys = [r[0] for r in self._conn.execute("SELECT project_key FROM briefs").fetchall()]
+ return [b for b in (self.brief(k) for k in keys) if b is not None]
+
+ def put_brief(
+ self,
+ project_key: str,
+ *,
+ folder: str,
+ repo: str,
+ parts: dict[str, Any],
+ keys: dict[str, str],
+ ) -> None:
+ with self._lock:
+ self._conn.execute(
+ "INSERT INTO briefs (project_key, folder, repo, parts_json, keys_json, updated_ms)"
+ " VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(project_key) DO UPDATE SET"
+ " folder = excluded.folder, repo = excluded.repo,"
+ " parts_json = excluded.parts_json, keys_json = excluded.keys_json,"
+ " updated_ms = excluded.updated_ms",
+ (project_key, folder, repo, dumps(parts), dumps(keys), now_ms()),
+ )
+ self._conn.commit()
+
+ def set_part(self, project_key: str, part: str, value: Any, key: str = "") -> None:
+ """Replace one part of a stored brief (the issue poll writes ``github``)."""
+ with self._lock:
+ current = self.brief(project_key)
+ if current is None:
+ return
+ parts = dict(current["parts"])
+ keys = dict(current["keys"])
+ parts[part] = value
+ keys[part] = key or str(now_ms())
+ self.put_brief(
+ project_key, folder=current["folder"], repo=current["repo"], parts=parts, keys=keys
+ )
+
+ # ------------------------------------------------------------ issues
+
+ def issue(self, repo: str, number: int) -> dict[str, Any] | None:
+ with self._lock:
+ row = self._conn.execute(
+ "SELECT updated_at, verdict, reason, issue_json, seen_ms FROM issues"
+ " WHERE repo = ? AND number = ?",
+ (repo_key(repo), int(number)),
+ ).fetchone()
+ if row is None:
+ return None
+ return {
+ "updated_at": str(row[0]),
+ "verdict": str(row[1]),
+ "reason": str(row[2]),
+ "issue": _loads(row[3], {}),
+ "seen_ms": int(row[4]),
+ }
+
+ def put_issue(
+ self,
+ repo: str,
+ number: int,
+ *,
+ updated_at: str,
+ verdict: str,
+ reason: str,
+ issue: dict[str, Any],
+ ) -> None:
+ with self._lock:
+ self._conn.execute(
+ "INSERT INTO issues (repo, number, updated_at, verdict, reason, issue_json,"
+ " seen_ms) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(repo, number) DO UPDATE SET"
+ " updated_at = excluded.updated_at, verdict = excluded.verdict,"
+ " reason = excluded.reason, issue_json = excluded.issue_json,"
+ " seen_ms = excluded.seen_ms",
+ (
+ repo_key(repo),
+ int(number),
+ updated_at,
+ verdict,
+ reason[:300],
+ dumps(issue),
+ now_ms(),
+ ),
+ )
+ self._conn.commit()
+
+ # ------------------------------------------------------------ profiles
+
+ def profile(self, repo: str) -> dict[str, Any]:
+ with self._lock:
+ row = self._conn.execute(
+ "SELECT json FROM profiles WHERE repo = ?", (repo_key(repo),)
+ ).fetchone()
+ profile = _loads(row[0], {}) if row else {}
+ for name in ("merged", "closed", "lessons"):
+ if not isinstance(profile.get(name), list):
+ profile[name] = []
+ return profile
+
+ def add_to_profile(self, repo: str, field: str, entry: dict[str, Any]) -> dict[str, Any]:
+ """Append ``entry`` to one list of the repository's profile (newest kept)."""
+ with self._lock:
+ profile = self.profile(repo)
+ items = [e for e in profile.get(field, []) if isinstance(e, dict)]
+ items.append({**entry, "ms": now_ms()})
+ profile[field] = items[-PROFILE_KEEP:]
+ self._conn.execute(
+ "INSERT INTO profiles (repo, json, updated_ms) VALUES (?, ?, ?)"
+ " ON CONFLICT(repo) DO UPDATE SET json = excluded.json,"
+ " updated_ms = excluded.updated_ms",
+ (repo_key(repo), dumps(profile), now_ms()),
+ )
+ self._conn.commit()
+ return profile
+
+ # ------------------------------------------------------------ polls
+
+ def last_poll(self, repo: str) -> int:
+ with self._lock:
+ row = self._conn.execute(
+ "SELECT last_ms FROM polls WHERE repo = ?", (repo_key(repo),)
+ ).fetchone()
+ return int(row[0]) if row else 0
+
+ def set_poll(self, repo: str, stamp: int | None = None) -> None:
+ with self._lock:
+ self._conn.execute(
+ "INSERT INTO polls (repo, last_ms) VALUES (?, ?)"
+ " ON CONFLICT(repo) DO UPDATE SET last_ms = excluded.last_ms",
+ (repo_key(repo), int(stamp if stamp is not None else now_ms())),
+ )
+ self._conn.commit()
diff --git a/dodaios/self_build/code/triage.py b/dodaios/self_build/code/triage.py
new file mode 100644
index 0000000000..1e5bf966d5
--- /dev/null
+++ b/dodaios/self_build/code/triage.py
@@ -0,0 +1,180 @@
+"""Which issues the loop may pick: deterministic, in Python, before any model.
+
+An issue is a candidate only when all of these hold:
+
+* it is open and nobody is assigned;
+* the person stands behind it: they wrote it, or it carries a label that marks
+ it for agents (labels need triage rights in the repository, so only the
+ person or their collaborators set them). A stranger's issue text alone never
+ starts a build (docs/self-build.md, rule 2);
+* it is fit for an agent: labelled for agents, or like issues whose loop pull
+ requests the person merged before;
+* its scope is clear: a real title and description, not an epic, no long
+ discussion, no pull request already open for it;
+* it does not touch secrets, credentials, deployment, releases or CI config;
+* the repository has a test command, so the result can be judged;
+* the repository's record is not against it: once the person closed loop pull
+ requests there without merging any, the loop stays out.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Final
+
+from .github import Issue, PullRef
+
+#: Labels that mark an issue for an agent (lower case).
+FIT_LABELS: Final[frozenset[str]] = frozenset(
+ {
+ "dodaios",
+ "agent",
+ "agents",
+ "ai",
+ "ai-agent",
+ "agent-ready",
+ "good first issue",
+ "good-first-issue",
+ "easy",
+ "small",
+ "trivial",
+ }
+)
+#: Labels that keep an issue away from the loop.
+BLOCK_LABELS: Final[frozenset[str]] = frozenset(
+ {
+ "wontfix",
+ "won't fix",
+ "question",
+ "discussion",
+ "blocked",
+ "duplicate",
+ "invalid",
+ "epic",
+ "needs design",
+ "needs-design",
+ "needs discussion",
+ "needs-discussion",
+ "security",
+ "do not merge",
+ "manual",
+ "no-agent",
+ "no agent",
+ }
+)
+#: Labels too common to make two issues alike.
+_GENERIC: Final[frozenset[str]] = frozenset(
+ {"bug", "enhancement", "feature", "documentation", "docs", "improvement"}
+)
+#: Words that mean secrets, deployment, releases or CI: never for the loop.
+RISKY: Final[re.Pattern[str]] = re.compile(
+ r"(?i)(?<![\w-])("
+ r"secrets?|tokens?|passwords?|credentials?|api[ _-]?keys?|private[ _-]keys?|\.env|"
+ r"oauth|auth(?:entication)?|deploy(?:s|ment|ments|ing)?|releases?|publish(?:ing)?|"
+ r"production|prod|infra(?:structure)?|terraform|kubernetes|k8s|helm|dockerfile|"
+ r"ci|ci/cd|workflows?|github actions|\.github|pipelines?|billing|payments?|"
+ r"migrations?|dns|ssl|tls|certificates?|signing|licen[cs]e"
+ r")(?![\w-])"
+)
+_CHECKBOX: Final[re.Pattern[str]] = re.compile(r"^\s*[-*]\s*\[[ xX]\]", re.MULTILINE)
+_WORD: Final[re.Pattern[str]] = re.compile(r"[a-z0-9]{3,}")
+_STOP: Final[frozenset[str]] = frozenset(
+ "the and for with that this from when should not are add fix use into have has can "
+ "but all any its was were will make".split()
+)
+MAX_BODY: Final[int] = 6_000
+MIN_BODY: Final[int] = 30
+MAX_COMMENTS: Final[int] = 8
+MAX_CHECKBOXES: Final[int] = 6
+SIMILAR: Final[float] = 0.34
+
+
+@dataclass(frozen=True, slots=True)
+class Verdict:
+ fit: bool
+ reason: str
+ #: Why the issue is fit, in one phrase (``labelled agent``, ``like #12``).
+ signal: str = ""
+
+
+def _no(reason: str) -> Verdict:
+ return Verdict(False, reason)
+
+
+def words(text: str) -> set[str]:
+ return {w for w in _WORD.findall(text.lower()) if w not in _STOP}
+
+
+def _similar(issue: Issue, merged: list[dict[str, Any]]) -> str:
+ """``like #n`` when the issue resembles one whose loop PR was merged unchanged."""
+ mine = words(issue.title)
+ labels = {label.lower() for label in issue.labels} - _GENERIC
+ for entry in reversed(merged):
+ if entry.get("changed"):
+ continue
+ other = words(str(entry.get("title") or ""))
+ union = mine | other
+ if union and len(mine & other) / len(union) >= SIMILAR:
+ return f"like #{entry.get('number')}"
+ if labels & ({str(x).lower() for x in entry.get("labels") or []} - _GENERIC):
+ return f"like #{entry.get('number')}"
+ return ""
+
+
+def has_open_pull(issue: Issue, pulls: tuple[PullRef, ...] | list[PullRef]) -> bool:
+ mention = re.compile(rf"(?<![\w/])#{issue.number}(?!\d)")
+ branch = re.compile(rf"(?<!\d){issue.number}(?!\d)")
+ for pull in pulls:
+ if mention.search(pull.title) or mention.search(pull.body):
+ return True
+ if "issue" in pull.head.lower() and branch.search(pull.head):
+ return True
+ return False
+
+
+def triage(
+ issue: Issue,
+ *,
+ login: str,
+ profile: dict[str, Any],
+ pulls: tuple[PullRef, ...] | list[PullRef] = (),
+ has_tests: bool,
+) -> Verdict:
+ if issue.state.upper() != "OPEN":
+ return _no("closed")
+ if issue.assignees:
+ return _no("assigned")
+ labels = {label.strip().lower() for label in issue.labels}
+ blocked = sorted(labels & BLOCK_LABELS)
+ if blocked:
+ return _no(f"labelled {blocked[0]}")
+ fit_labels = sorted(labels & FIT_LABELS)
+ if not (issue.author and issue.author.lower() == login.lower()) and not fit_labels:
+ return _no("neither written nor labelled by the person")
+ if not has_tests:
+ return _no("no test command in this repository")
+ text = f"{issue.title}\n{issue.body}"
+ risky = RISKY.search(text)
+ if risky:
+ return _no(f"touches {risky.group(1).lower()}")
+ if len(issue.title.strip()) < 8:
+ return _no("title too short to know the scope")
+ if not MIN_BODY <= len(issue.body.strip()) <= MAX_BODY:
+ return _no("description too short or too long to know the scope")
+ if len(_CHECKBOX.findall(issue.body)) > MAX_CHECKBOXES:
+ return _no("a list of tasks, not one task")
+ if issue.comments > MAX_COMMENTS:
+ return _no("long discussion, scope unclear")
+ if has_open_pull(issue, pulls):
+ return _no("a pull request is already open for it")
+ merged = [e for e in profile.get("merged", []) if isinstance(e, dict)]
+ closed = [e for e in profile.get("closed", []) if isinstance(e, dict)]
+ if len(closed) >= 2 and not merged:
+ return _no("the person closed earlier loop pull requests here")
+ if fit_labels:
+ return Verdict(True, "fit", f"labelled {fit_labels[0]}")
+ like = _similar(issue, merged)
+ if like:
+ return Verdict(True, "fit", like)
+ return _no("no sign it suits an agent")
diff --git a/tests/unit/self_build/code_sandbox.py b/tests/unit/self_build/code_sandbox.py
new file mode 100644
index 0000000000..3ca7751a81
--- /dev/null
+++ b/tests/unit/self_build/code_sandbox.py
@@ -0,0 +1,63 @@
+"""Sandbox repositories for the code builder's tests: a bare "GitHub" remote whose
+path holds ``github.com/<owner>/<name>`` (so the origin parser reads it as that
+repository) and a clone the person works in. Nothing reaches the network."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from dodaios.self_build.code.github import Issue
+
+ISSUE_BODY = "Add a mul(a, b) function next to add in calc.py, with a test for it."
+
+
+def git(cwd: Path, *args: str) -> str:
+ done = subprocess.run(
+ ["git", *args], cwd=cwd, capture_output=True, text=True, check=True, encoding="utf-8"
+ )
+ return done.stdout.strip()
+
+
+def sandbox(tmp_path: Path, owner: str = "me", name: str = "proj") -> Path:
+ """A bare "GitHub" remote (its path holds github.com/<owner>/<name>) and a clone."""
+ remote = tmp_path / "github.com" / owner / f"{name}.git"
+ remote.mkdir(parents=True)
+ git(remote, "init", "--bare", "--initial-branch=main")
+ work = tmp_path / "work" / name
+ work.mkdir(parents=True)
+ git(work, "init", "--initial-branch=main")
+ git(work, "config", "user.name", "Test Person")
+ git(work, "config", "user.email", "[email protected]")
+ (work / "calc.py").write_text("def add(a, b):\n return a + b\n", encoding="utf-8")
+ (work / "tests").mkdir()
+ (work / "tests" / "test_calc.py").write_text(
+ "from calc import add\n\n\ndef test_add():\n assert add(1, 2) == 3\n", encoding="utf-8"
+ )
+ (work / "pyproject.toml").write_text(
+ '[project]\nname = "proj"\n\n[tool.pytest.ini_options]\ntestpaths = ["tests"]\n',
+ encoding="utf-8",
+ )
+ (work / "AGENTS.md").write_text("Use type hints in new code.\n", encoding="utf-8")
+ git(work, "add", "-A")
+ git(work, "commit", "-m", "initial")
+ git(work, "remote", "add", "origin", remote.as_posix())
+ git(work, "push", "-u", "origin", "main")
+ git(remote, "symbolic-ref", "HEAD", "refs/heads/main")
+ git(work, "remote", "set-head", "origin", "main")
+ return work
+
+
+def make_issue(number: int = 1, **overrides: Any) -> Issue:
+ values: dict[str, Any] = {
+ "number": number,
+ "title": "Add a mul function",
+ "body": ISSUE_BODY,
+ "url": f"https://github.com/me/proj/issues/{number}",
+ "author": "me",
+ "labels": ("agent",),
+ "updated_at": "2026-10-19T10:00:00Z",
+ }
+ values.update(overrides)
+ return Issue(**values)
diff --git a/tests/unit/self_build/test_self_build_code_brief.py b/tests/unit/self_build/test_self_build_code_brief.py
new file mode 100644
index 0000000000..7ed7a22bcb
--- /dev/null
+++ b/tests/unit/self_build/test_self_build_code_brief.py
@@ -0,0 +1,121 @@
+"""Project briefs, test-command detection, triage and the intake store."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+import pytest
+
+from dodaios.self_build.code import brief as brief_mod
+from dodaios.self_build.code import commands, triage
+from dodaios.self_build.code.github import PullRef, Viewer
+from dodaios.self_build.code.store import CodeStore
+
+from .code_sandbox import make_issue, sandbox
+
+
+def store(tmp_path: Path) -> CodeStore:
+ book = CodeStore(tmp_path / "self_build_code.db")
+ yield book
+ book.close()
+
+
+def work(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.setattr(commands, "_python", lambda folder: sys.executable)
+ return sandbox(tmp_path)
+
+
+def test_brief_rebuilds_only_the_parts_that_changed(store: CodeStore, work: Path) -> None:
+ brief, rebuilt = brief_mod.refresh(store, work, repo="me/proj")
+ assert set(rebuilt) == set(brief_mod.LOCAL_PARTS)
+ assert brief.test_commands[0][1:3] == ["-m", "pytest"]
+ assert brief.default_branch == "main"
+ assert "AGENTS.md" in brief.parts["conventions"]["files"]
+ assert brief.parts["activity"]["mine"] == ["initial"]
+ _, rebuilt = brief_mod.refresh(store, work, repo="me/proj")
+ assert rebuilt == []
+ (work / "AGENTS.md").write_text("Use type hints. Keep it short.\n", encoding="utf-8")
+ _, rebuilt = brief_mod.refresh(store, work, repo="me/proj")
+ assert rebuilt == ["conventions"]
+ text = brief_mod.load(store, work).render()
+ assert "Keep it short." in text and "Tests:" in text
+
+
+def test_triage_rules() -> None:
+ fit = triage.triage(make_issue(), login="me", profile={}, has_tests=True)
+ assert fit.fit and fit.signal == "labelled agent"
+ unlabelled = make_issue(labels=(), title="Add a mul function to calc")
+ assert not triage.triage(unlabelled, login="me", profile={}, has_tests=True).fit
+ merged = {"merged": [{"number": 7, "title": "Add a sub function to calc", "labels": []}]}
+ like = triage.triage(unlabelled, login="me", profile=merged, has_tests=True)
+ assert like.fit and like.signal == "like #7"
+ assert not triage.triage(make_issue(), login="me", profile={}, has_tests=False).fit
+ pulls = [PullRef(number=3, title="Add mul (#1)")]
+ assert not triage.triage(make_issue(), login="me", profile={}, pulls=pulls, has_tests=True).fit
+ closed = {"closed": [{"number": 1}, {"number": 2}]}
+ assert not triage.triage(make_issue(), login="me", profile=closed, has_tests=True).fit
+ assert not triage.triage(
+ replace(make_issue(), state="CLOSED"), login="me", profile={}, has_tests=True
+ ).fit
+
+
+def test_test_commands_come_from_the_project_files(tmp_path: Path) -> None:
+ empty = tmp_path / "empty"
+ empty.mkdir()
+ assert commands.detect(empty)["test"] == []
+ node = tmp_path / "node"
+ node.mkdir()
+ (node / "package.json").write_text('{"scripts": {"test": "vitest run"}}', encoding="utf-8")
+ (node / "package-lock.json").write_text("{}", encoding="utf-8")
+ found = commands.detect(node)
+ assert found["test"] == [["npm", "test", "--silent"]]
+ assert found["setup"] == [["npm", "ci"]]
+ (node / "package.json").write_text(
+ '{"scripts": {"test": "echo \\"Error: no test specified\\" && exit 1"}}', encoding="utf-8"
+ )
+ assert commands.detect(node)["test"] == []
+ rust = tmp_path / "rust"
+ rust.mkdir()
+ (rust / "Cargo.toml").write_text("[package]\n", encoding="utf-8")
+ (rust / ".github" / "workflows").mkdir(parents=True)
+ (rust / ".github" / "workflows" / "ci.yml").write_text(
+ "jobs:\n t:\n steps:\n - run: cargo test --all\n", encoding="utf-8"
+ )
+ found = commands.detect(rust)
+ assert found["test"] == [["cargo", "test", "--quiet"]]
+ assert found["ci"] == ["ci.yml: cargo test --all"]
+
+
+def test_outcomes_fold_into_the_brief(store: CodeStore, work: Path) -> None:
+ brief_mod.refresh(store, work, repo="me/proj")
+ store.add_to_profile("Me/Proj", "merged", {"number": 3, "title": "a", "changed": True})
+ store.add_to_profile("me/proj", "lessons", {"number": 4, "lesson": "tests were slow"})
+ profile = store.profile("me/proj")
+ brief_mod.note_outcomes(store, work, profile)
+ stored = brief_mod.load(store, work)
+ assert stored.parts["outcomes"]["changed"] == ["#3 a"]
+ text = stored.render()
+ assert "tests were slow" in text and "#3 a" in text
+ # A refresh of the local parts keeps what the loop learned.
+ (work / "AGENTS.md").write_text("New rules.\n", encoding="utf-8")
+ again, _ = brief_mod.refresh(store, work, repo="me/proj")
+ assert again.parts["outcomes"]["lessons"] == ["tests were slow"]
+
+
+def test_store_remembers_issues_and_polls(store: CodeStore) -> None:
+ assert store.issue("me/proj", 1) is None
+ store.put_issue("Me/Proj", 1, updated_at="t1", verdict="unfit", reason="assigned", issue={})
+ assert store.issue("me/proj", 1)["verdict"] == "unfit"
+ assert store.last_poll("me/proj") == 0
+ store.set_poll("me/proj", 123)
+ assert store.last_poll("ME/PROJ") == 123
+
+
+def test_only_the_persons_own_accounts_count_as_owners() -> None:
+ who = Viewer(login="Me", admin_orgs=frozenset({"my-org"}))
+ assert who.owns("me/proj") and who.owns("My-Org/site")
+ assert not who.owns("someone/lib") and not who.owns("")