description: Root interfaces and orchestrators
includes:
  - dotscope/cli.py
  - dotscope/mcp_server.py
  - dotscope/composer.py
  - dotscope/resolver.py
  - dotscope/intent.py
  - dotscope/ingest.py
  - dotscope/formatter.py
  - dotscope/discovery.py
  - dotscope/parser.py
  - dotscope/visibility.py
  - dotscope/hooks.py
  - dotscope/budget.py
  - dotscope/models.py
  - dotscope/assertions.py
  - dotscope/health.py
  - dotscope/utility.py
  - dotscope/sessions.py
  - dotscope/virtual.py
  - dotscope/lessons.py
  - dotscope/graph.py
  - dotscope/textio.py
  - dotscope/tokens.py
  - dotscope/matcher.py
  - dotscope/ast_analyzer.py
  - .scopes
excludes:
  - dotscope/__pycache__/
  - dotscope/models/
  - dotscope/passes/
  - dotscope/storage/
context: |
  The root dotscope/ directory holds interfaces and orchestrators.
  Heavy lifting is delegated to passes/. State to storage/. Types to models/.

  ## cli.py — Human Interface
  All CLI commands. Dispatches to functional modules. 20+ commands including
  resolve, check, intent, ingest, test-compiler, bench, debug, health.

  ## mcp_server.py — Agent Interface
  FastMCP server. 16 tools: resolve_scope, dotscope_check, dotscope_debug,
  dotscope_acknowledge, match_scope, session_summary, etc.
  Every resolve_scope call is tracked. Constraints injected prophylactically.

  ## composer.py — Scope Algebra
  Parses expressions like auth+payments-tests&api@context.
  Operators: + (union), - (subtract), & (intersect), @ (modifier).

  ## resolver.py — File Resolution
  Resolves a ScopeConfig to concrete files by expanding glob patterns,
  applying excludes, and computing token estimates.

  ## ingest.py — Codebase Ingestion Orchestrator
  Coordinates the full ingest pipeline: graph → history → docs → synthesis →
  backtest → auto-correct → write. The largest orchestrator.

  ## parser.py — YAML Parser
  Minimal YAML subset parser. Zero dependencies. Handles the specific
  patterns .scope and .scopes files use.

  ## visibility.py — DX Features
  SessionTracker, attribution hints, health nudges, counterfactual
  integration. The glue between observation data and agent-facing output.

  ## Gotchas
  Many root files are backward-compat stubs (graph.py, history.py, etc.)
  that re-export from passes/ or storage/. New code should import from
  the canonical location (passes.graph_builder, not graph).
related:
  - dotscope/models/.scope
  - dotscope/passes/.scope
  - dotscope/storage/.scope
  - dotscope/search/.scope
  - dotscope/generate/.scope
  - dotscope/merge/.scope
  - dotscope/eval/.scope
tags:
  - cli
  - mcp
  - interfaces
tokens_estimate: 18000
