description: Root interfaces and orchestrators
includes:
  - dotscope/
excludes:
  - dotscope/__pycache__/
  - "*.pyc"
context: |
  The root dotscope/ directory holds interfaces and orchestrators.
  Heavy lifting is delegated to passes/. State to storage/. Types to models/.
  
  ## cli/ — Human Interface (package: core.py, hooks.py, ingest.py, observability.py)
  All CLI commands. Dispatches to functional modules. 20+ commands including
  resolve, check, intent, ingest, test-compiler, bench, debug, health.
  
  ## mcp/ — Agent Interface (package: core.py, hooks.py, ingest.py, observability.py)
  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.
  
  ## Import convention
  All imports use canonical locations: passes.graph_builder (not graph),
  storage.session_manager (not sessions), models.intent (not check.models).
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
