roboco/.roboco/conventions.yml

# Architectural conventions for RoboCo.
#
# 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:
  - python
  - typescript

modules:
  # --- Backend: roboco/ --------------------------------------------------------
  - path: roboco/models
    purpose: SQLAlchemy + Pydantic data models
    forbidden:
      - route
  - path: roboco/api
    purpose: API package wiring — app, deps, middleware, websocket
    forbidden:
      - model
  - path: roboco/api/routes
    purpose: HTTP routes — thin handlers that delegate to services
    forbidden:
      - model
      - helper
  - path: roboco/api/schemas
    purpose: API request / response schemas
    forbidden:
      - route
  - path: roboco/mcp/schemas
    purpose: MCP tool input / output schemas
    forbidden:
      - route
  - path: roboco/services
    purpose: business logic, DB writes, side effects — the only layer that owns them
    forbidden:
      - route
  - path: roboco/utils
    purpose: shared, side-effect-free helpers
    forbidden:
      - route
      - component

  # --- Frontend: panel/ --------------------------------------------------------
  - path: panel/src/components
    purpose: presentational UI components
    forbidden:
      - model
      - route
  - path: panel/src/hooks
    purpose: React hooks — data fetching + state, no JSX
    forbidden:
      - component
      - model
      - route
  - path: panel/src/store
    purpose: client-side state management
    forbidden:
      - component
      - route
  - path: panel/src/lib/api
    purpose: typed API client
    forbidden:
      - model
  - path: panel/src/lib
    purpose: shared frontend helpers / utilities
    forbidden:
      - route
      - component

rules:
  # 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:
    level: warn
  # 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:
    level: warn
  # A few panel components still fetch inline; extract into hooks, then promote.
  thin_components:
    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:
  - path: panel/src/hooks/__tests__/use-tasks-null-guards.test.tsx
    rule: no_components_in_hooks
    reason: >-
      `wrapper` is a QueryClientProvider test fixture local to this test file,
      not a production component — the same pattern already used by the
      pre-existing use-agents.test.tsx / use-observability.test.tsx hook
      tests colocated under hooks/__tests__/.
  - path: roboco/api/routes/prompter_live.py
    rule: no_lint_suppressions
    reason: >-
      preview_live_batch's `session_id` path parameter is unused in the
      function body (the endpoint is a pure precompute) but must stay in the
      signature under that exact name for FastAPI to bind the
      `/live/{session_id}/preview-batch` path — renaming or dropping it
      breaks routing, so the ARG001 suppression is a permanent framework
      constraint, not silenced debt.
  - path: roboco/foundation/policy/lifecycle.py
    rule: no_lint_suppressions
    reason: >-
      The module-load-time `_run_all_lifecycle_validators` import sits below
      other module code deliberately: its validators live in
      `roboco.foundation._validate_lifecycle`, a sibling of
      `foundation/_validate.py`, and `roboco.foundation.__init__` eagerly
      imports `_validate` — importing it at the top of this file would
      create a real import cycle. The E402 suppression documents a genuine
      circular-import constraint, not silenced debt.