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.

.roboco/conventions.yml

@@ -1,14 +1,16 @@
 # Architectural conventions for RoboCo.
-# Repo-canonical: this file overlays the auto-derived scan, and every consumer
-# (the validator, the per-task constraints, the ambient prompt block) reads the
-# merged effective map. Edit freely; the panel's Conventions tab round-trips it.
 #
-# Convention vs. claude-agent-runway: RoboCo keeps `no_inline_comments` at WARN,
-# not block. The codebase deliberately documents intent in-line and in module /
-# function docstrings, so comments are welcome and never strand a task; the gate
-# only nudges. The runway "no lint suppressions" rule is honoured but currently
-# WARN (see the rule note below) until the ~18 existing pydantic-required
-# suppressions migrate to pyproject config, at which point it returns to block.
+# This file overlays the auto-derived scan: every consumer (the validator, the
+# per-task constraints, the spawn-time ambient block) reads the merged effective
+# map, so only project-specific divergences need to live here. The scan already
+# excludes tests/ and docs/, maps the backend (roboco/) + frontend (panel/)
+# layers, and defaults misplaced-helper to warn — so this file is mostly a small
+# set of module declarations plus the rule-level policy below.
+#
+# Posture: BLOCK every boundary the codebase already honors (a model or helper
+# in a route, a route in a service, a model/route in a panel component, a hook
+# returning JSX — all refused), WARN the boundaries that still carry debt so a
+# task is never stranded on pre-existing code.
 
 version: 1
 languages:
@@ -22,11 +24,11 @@ modules:
     forbidden:
       - route
   - path: roboco/api
-    purpose: API package wiring — app, deps, middleware, websocket (helpers welcome)
+    purpose: API package wiring — app, deps, middleware, websocket
     forbidden:
       - model
   - path: roboco/api/routes
-    purpose: HTTP routes only — thin handlers that delegate to services
+    purpose: HTTP routes — thin handlers that delegate to services
     forbidden:
       - model
       - helper
@@ -34,11 +36,6 @@ modules:
     purpose: API request / response schemas
     forbidden:
       - route
-  - path: roboco/api/utils
-    purpose: API-layer helpers / utilities
-    forbidden:
-      - route
-      - component
   - path: roboco/mcp/schemas
     purpose: MCP tool input / output schemas
     forbidden:
@@ -70,11 +67,6 @@ modules:
     forbidden:
       - component
       - route
-  - path: panel/src/lib/stores
-    purpose: client-side state management
-    forbidden:
-      - component
-      - route
   - path: panel/src/lib/api
     purpose: typed API client
     forbidden:
@@ -84,80 +76,27 @@ modules:
     forbidden:
       - route
       - component
-  - path: panel/lib
-    purpose: shared frontend helpers / utilities
-    forbidden:
-      - route
-      - component
-
-  # --- Neutralized: tests + docs own no placement rules ------------------------
-  # The auto-scan treats any dir named api/models/services/utils/schemas/routes
-  # as an enforceable code module. Under tests/ and docs/ that is wrong: test
-  # modules legitimately define fixtures, fakes, and helper functions, and docs/
-  # is the MkDocs site (markdown, never classified). These overrides switch off
-  # placement there so a test or docs task is never stranded. Longest-prefix wins,
-  # so each derived sub-path is neutralized explicitly.
-  - path: tests/unit/api
-    purpose: tests — any kind may be defined
-    forbidden: []
-  - path: tests/unit/api/routes
-    purpose: tests — any kind may be defined
-    forbidden: []
-  - path: tests/unit/api/schemas
-    purpose: tests — any kind may be defined
-    forbidden: []
-  - path: tests/unit/models
-    purpose: tests — any kind may be defined
-    forbidden: []
-  - path: tests/unit/services
-    purpose: tests — any kind may be defined
-    forbidden: []
-  - path: tests/unit/utils
-    purpose: tests — any kind may be defined
-    forbidden: []
-  - path: docs/api
-    purpose: documentation site — not code
-    forbidden: []
-  - path: docs/models
-    purpose: documentation site — not code
-    forbidden: []
 
 rules:
-  # Posture: BLOCK every boundary this codebase already honors (real teeth, zero
-  # false-strands), WARN the boundaries that still carry debt so a task is never
-  # stranded on pre-existing code. Every placement rule not named here inherits
-  # the derived BLOCK level — e.g. a route in roboco/services, a model in a panel
-  # component, or a hook returning JSX is refused outright.
-  #
-  # Hygiene
-  no_lint_suppressions:
-    # ~18 live in roboco/ today, most pydantic-required (computed_field
-    # prop-decorator, TC003 runtime types). WARN until they migrate to pyproject
-    # per-file-ignores / mypy overrides, then this returns to block.
-    level: warn
+  # Comments are welcome in RoboCo — intent is documented in-code and in
+  # docstrings. The rule only nudges (full-line comments are never flagged).
   no_inline_comments:
-    # RoboCo documents intent in-code; comments are welcome and never block.
     level: warn
-  # Placement debt — clean these up, then promote back to block
-  no_models_in_routes:
-    # Inline request/response models in *_live.py belong in roboco/api/schemas.
-    level: warn
-  no_helpers_in_routes:
-    # Local _-prefixed route helpers; tighten once they move to services/utils.
-    level: warn
-  # Modularity
-  modular_cohesion:
-    # Same root as no_models_in_routes (a file with both a model and a route).
+  # A handful of unavoidable framework suppressions are auto-allowed
+  # (TC001-003, pydantic prop-decorator); the few remaining inline E402 / E501 /
+  # arg-type suppressions stay warn until they migrate to pyproject config.
+  no_lint_suppressions:
     level: warn
+  # RoboCo routes deliberately call db.commit() (get_db auto-commit is unreliable
+  # under BaseHTTPMiddleware); explicit commits no longer count as data access,
+  # so this stays advisory for the few routes that still read/write directly.
   thin_routes:
-    # RoboCo routes deliberately call db.commit() (get_db auto-commit is
-    # unreliable under BaseHTTPMiddleware) and the check counts commit as data
-    # access — so this stays advisory rather than blocking the commit convention.
     level: warn
+  # A few panel components still fetch inline; extract into hooks, then promote.
   thin_components:
     level: warn
-  god_class:
-    level: warn
+  # Everything else inherits the derived BLOCK level — no models/helpers in
+  # routes, no routes in services, no models/routes in panel components, etc.
 
 custom: []
 waivers: []