feat(conventions): generalize defaults, backfill old projects, adopt the standard in-repo

Harden the architectural-conventions standard so it works out-of-the-box on
any project and resolves for projects that predate it, and make RoboCo pass
its own gate.

General defaults (apply to every project, not just one with a tuned file):
- The auto-scan excludes test and documentation trees (tests/, docs/) — those
  legitimately define fixtures and aren't enforced code.
- Helper placement seeds at warn, not block: `helper` matches any top-level
  function, too blunt a signal to hard-block a route file's small private glue.
  Misplaced model/route/component stay block; the body-level thin_routes check
  remains the real fat-handler guard.
- thin_routes no longer counts transaction-lifecycle calls (commit/flush/
  refresh) as data access — an explicit `db.commit()` after delegating to a
  service is a valid pattern.
- no_lint_suppressions exempts a small allowlist of structurally-unavoidable
  framework codes (ruff TC001-TC003, pydantic prop-decorator); bare or other
  suppressions still flag.
- CLAUDE.md rule-lifting skips bare common-word tokens that would match
  everywhere (e.g. "commit"), keeping only specific identifiers.
- The ambient prompt block lists only constrained modules and truncates at a
  line boundary with a "+N more" pointer instead of cutting mid-line.

Backfill: the standard previously read the committed file + repo scan from
project.workspace_path, a field only a manual API call set — so an older
project (or one whose workspace was cleared) showed an empty "missing" map no
matter what was pushed. The service now ensures a dedicated, default-branch
read clone on demand (WorkspaceService.ensure_read_clone) and resolves from
it, persisting the resolved path + real HEAD. The panel tab, the spawn-time
ambient block, and the per-task constraints all resolve the committed standard
with no manual setup.

Adopt in-repo: relocate the inline request/response models from the system and
*_live route modules into roboco/api/schemas/ so the codebase passes its own
placement gate, and ship a canonical .roboco/conventions.yml. no_models_in_routes
and modular_cohesion are now clean and enforced at block.

Docs updated across the user guide, the agent-facing RAG standard, the
developer and pr_reviewer role prompts, CLAUDE.md, and the changelog. New unit
tests cover the scan exclusions, helper-warn, the suppression allowlist, the
commit exemption, and the resolve/backfill path; the conventions + project
integration suites pass against Postgres.

tests/unit/api/test_secretary_live_routes.py

@@ -8,7 +8,7 @@ from unittest.mock import AsyncMock, MagicMock
 import pytest
 from fastapi import HTTPException
 from roboco.api.routes import secretary_live as sl
-from roboco.api.routes.secretary_live import (
+from roboco.api.schemas.secretary_live import (
     AgentEvent,
     LiveMessageRequest,
     StartSecretaryRequest,

tests/unit/conventions/test_hygiene.py

@@ -59,6 +59,41 @@ def test_python_marker_not_applied_to_typescript() -> None:
     assert _rules(findings, "no_lint_suppressions") == []
 
 
+def _src(line: str) -> bytes:
+    # Build via a variable so a literal suppression marker never sits on this
+    # test file's own source line (ruff would parse it as a real directive).
+    return (line + "\n").encode()
+
+
+def test_runtime_typing_noqa_is_allowed() -> None:
+    # A runtime-needed typing import (pydantic / SQLAlchemy) — the sanctioned
+    # escape, not error-silencing.
+    findings = check_hygiene(
+        "a.py", _src("from uuid import UUID  # noqa: TC003"), "python", _STD
+    )
+    assert _rules(findings, "no_lint_suppressions") == []
+
+
+def test_pydantic_prop_decorator_ignore_is_allowed() -> None:
+    findings = check_hygiene(
+        "a.py", _src("y = f()  # type: ignore[prop-decorator]"), "python", _STD
+    )
+    assert _rules(findings, "no_lint_suppressions") == []
+
+
+def test_other_ignore_code_is_still_flagged() -> None:
+    findings = check_hygiene(
+        "a.py", _src("x = bad()  # type: ignore[arg-type]"), "python", _STD
+    )
+    assert _rules(findings, "no_lint_suppressions")
+
+
+def test_mixed_allowed_and_disallowed_codes_is_flagged() -> None:
+    # One allowed code does not launder a disallowed one alongside it.
+    findings = check_hygiene("a.py", _src("x = 1  # noqa: TC003, E501"), "python", _STD)
+    assert _rules(findings, "no_lint_suppressions")
+
+
 def test_rule_level_override_from_standard() -> None:
     std = ConventionsStandard(
         rules={"no_inline_comments": Rule(name="no_inline_comments", level="block")}

tests/unit/conventions/test_modularity.py

@@ -77,6 +77,21 @@ def test_thin_routes_clean_when_delegating_to_a_service() -> None:
     assert "thin_routes" not in rules
 
 
+def test_thin_routes_allows_explicit_commit_in_route() -> None:
+    # Committing the unit of work after delegating is a common, valid pattern —
+    # a bare `db.commit()` must not count as the route doing data access.
+    rules = _py(
+        "from fastapi import APIRouter\n"
+        "router = APIRouter()\n"
+        "@router.post('/users')\n"
+        "async def create_user(svc, db):\n"
+        "    user = await svc.create()\n"
+        "    await db.commit()\n"
+        "    return user\n"
+    )
+    assert "thin_routes" not in rules
+
+
 # --- Thin components: data fetching belongs in a hook ----------------------- #
 
 

tests/unit/conventions/test_scan.py

@@ -48,11 +48,35 @@ def test_scan_ignores_vendored_directories(tmp_path: Path) -> None:
 
 def test_scan_lifts_claude_md_imperative_into_custom_rule(tmp_path: Path) -> None:
     _sample_repo(tmp_path)
-    (tmp_path / "CLAUDE.md").write_text("- Never use `print()`; use the logger.\n")
+    (tmp_path / "CLAUDE.md").write_text("- Never call `os.system()`; use subprocess.\n")
     custom = derive_from_scan(tmp_path).custom
     assert custom
     assert custom[0].level == "warn"
-    assert "print" in custom[0].pattern
+    assert custom[0].id == "os-system"
+
+
+def test_scan_skips_bare_common_word_in_claude_md(tmp_path: Path) -> None:
+    # A bare word like `commit` would match everywhere; it must not be lifted.
+    _sample_repo(tmp_path)
+    (tmp_path / "CLAUDE.md").write_text("- Never `commit` straight to master.\n")
+    assert derive_from_scan(tmp_path).custom == []
+
+
+def test_scan_excludes_test_and_docs_trees(tmp_path: Path) -> None:
+    (tmp_path / "tests" / "unit" / "services").mkdir(parents=True)
+    (tmp_path / "docs" / "api").mkdir(parents=True)
+    (tmp_path / "app" / "services").mkdir(parents=True)
+    paths = {m.path for m in derive_from_scan(tmp_path).modules}
+    assert "app/services" in paths
+    assert not any(p.startswith(("tests/", "docs/")) for p in paths)
+
+
+def test_scan_seeds_helper_placement_as_warn(tmp_path: Path) -> None:
+    _sample_repo(tmp_path)
+    std = derive_from_scan(tmp_path)
+    # A misplaced model is a hard error; a misplaced helper only warns.
+    assert std.rules["no_models_in_routers"].level == "block"
+    assert std.rules["no_helpers_in_routers"].level == "warn"
 
 
 def test_render_yaml_round_trips_through_parse(tmp_path: Path) -> None:

tests/unit/services/test_conventions_resolve.py

@@ -0,0 +1,66 @@
+"""ConventionsService root/HEAD resolution + backfill persistence (no DB)."""
+
+from __future__ import annotations
+
+import subprocess
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+from roboco.services.conventions import ConventionsService
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _git_repo(root: Path) -> str:
+    (root / "roboco" / "services").mkdir(parents=True)
+    (root / "roboco" / "services" / "x.py").write_text("def f():\n    return 1\n")
+    for cmd in (
+        ["git", "init", "-q"],
+        ["git", "add", "-A"],
+        ["git", "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "i"],
+    ):
+        subprocess.run(cmd, cwd=root, check=True, capture_output=True)
+    return subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+    ).stdout.strip()
+
+
+def _svc() -> ConventionsService:
+    return ConventionsService(session=None)  # type: ignore[arg-type]
+
+
+def test_resolve_reads_clone_head_and_backfills(tmp_path: Path) -> None:
+    sha = _git_repo(tmp_path)
+    project = SimpleNamespace(workspace_path=None, head_commit=None, slug="p")
+    root, head = _svc()._resolve(project, tmp_path)
+    assert root == tmp_path
+    assert head == sha
+    # The backfill: the resolved path + real HEAD are persisted on the project.
+    assert project.workspace_path == str(tmp_path)
+    assert project.head_commit == sha
+
+
+def test_resolve_non_git_path_keeps_persisted_head(tmp_path: Path) -> None:
+    project = SimpleNamespace(
+        workspace_path=str(tmp_path), head_commit="deadbeef", slug="p"
+    )
+    _root, head = _svc()._resolve(project, None)
+    # A non-git legacy path must not clobber the persisted head_commit.
+    assert head == "deadbeef"
+    assert project.head_commit == "deadbeef"
+
+
+def test_resolve_no_workspace_returns_none_root() -> None:
+    project = SimpleNamespace(workspace_path=None, head_commit=None, slug="p")
+    root, head = _svc()._resolve(project, None)
+    assert root is None
+    assert head == "HEAD"
+
+
+def test_head_sha_at_non_git_returns_none(tmp_path: Path) -> None:
+    assert ConventionsService._head_sha_at(tmp_path) is None