# thilak15/deontic architecture

> Architecture diagram of the GitHub repository thilak15/deontic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thilak15/deontic
- Repository: https://github.com/thilak15/deontic

## Overview

Deontic statically analyzes AI-agent harness files and MCP configurations, profiles context costs, and offers splitting, synchronization, and session-trace analysis. The main workflow is CLI command dispatch into workspace discovery and analysis, followed by diagnostics or reports; separate commands expose cost, split, sync, trace, and live MCP probing. The README documents these capabilities, while sampled source confirms key orchestration and parsing links. Several command internals and analyzer passes are unsampled, so their detailed connections are omitted.

Main entry points: [`packages/core/src/analyzer/index.ts`](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/index.ts) (Analysis Orchestrator), [`packages/cli/src/index.ts`](https://github.com/thilak15/deontic/blob/main/packages/cli/src/index.ts) (CLI Dispatcher), [`packages/core/src/discovery/index.ts`](https://github.com/thilak15/deontic/blob/main/packages/core/src/discovery/index.ts) (File Discovery), [`packages/core/src/autofix/path-splitter.ts`](https://github.com/thilak15/deontic/blob/main/packages/core/src/autofix/path-splitter.ts) (Path Splitter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Reporting"]
  node_cli["CLI Dispatcher<br/>[index.ts]"]
  node_check["Check Command<br/>[check.ts]"]
  node_cost["Cost Command<br/>[cost.ts]"]
  node_split["Split Command<br/>[split.ts]"]
  node_sync["Sync Command<br/>[sync.ts]"]
  node_trace["Trace Command<br/>[trace.ts]"]
  node_probe["MCP Probe Command<br/>[mcp-probe.ts]"]
  node_reporters["Diagnostic Reporters"]
end

subgraph group_workspace["Workspace Preparation"]
  node_config["Workspace Config<br/>[index.ts]"]
  node_discovery["File Discovery<br/>[index.ts]"]
  node_parser["Harness Parser<br/>[index.ts]"]
  node_scope["Profile and Scope<br/>[index.ts]"]
end

subgraph group_analysis["Static Analysis"]
  node_engine["Analysis Orchestrator<br/>[index.ts]"]
  node_imports["Import Checks<br/>[00-imports.ts]"]
  node_contradictions["Contradiction Solver"]
  node_groundtruth["Reference Checks<br/>[02-ground-truth.ts]"]
  node_budget["Context Budget<br/>[03-bloat-cliff.ts]"]
  node_mcp["MCP Schema Analysis<br/>[04-mcp-schema.ts]"]
  node_redundancy["Redundancy Checks<br/>[05-redundancy.ts]"]
  node_roi["Trace ROI<br/>[06-trace-roi.ts]"]
  node_ontology["Directive Ontology<br/>[ontology.ts]"]
end

subgraph group_operations["Refactoring and Insights"]
  node_splitter["Path Splitter<br/>[path-splitter.ts]"]
  node_crosssync["Cross-Tool Sync<br/>[cross-sync.ts]"]
end

node_user(("Engineer"))

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches check"| node_check
node_cli -->|"dispatches cost"| node_cost
node_cli -->|"dispatches split"| node_split
node_cli -->|"dispatches sync"| node_sync
node_cli -->|"dispatches trace"| node_trace
node_cli -->|"dispatches probe"| node_probe
node_check -->|"formats results"| node_reporters
node_engine -->|"loads config"| node_config
node_engine -->|"discovers files"| node_discovery
node_discovery -->|"classifies files"| node_scope
node_discovery -->|"parses harnesses"| node_parser
node_parser -->|"resolves scope"| node_scope
node_engine -->|"runs pass"| node_imports
node_engine -->|"runs pass"| node_contradictions
node_engine -->|"runs pass"| node_groundtruth
node_engine -->|"runs pass"| node_budget
node_engine -->|"runs pass"| node_mcp
node_engine -->|"runs pass"| node_redundancy
node_engine -->|"runs pass"| node_roi
node_contradictions -->|"uses ontology"| node_ontology
node_splitter -->|"loads config"| node_config
node_splitter -->|"discovers files"| node_discovery
node_crosssync -.-> node_config
node_crosssync -.-> node_discovery
node_cli -.->|"checks workspace"| node_engine
node_cost -.->|"profiles cost"| node_budget
node_split -.->|"requests split"| node_splitter
node_sync -.->|"requests sync"| node_crosssync
node_trace -.->|"analyzes sessions"| node_roi
node_probe -.->|"probes servers"| node_mcp

click node_cli "https://github.com/thilak15/deontic/blob/main/packages/cli/src/index.ts"
click node_check "https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/check.ts"
click node_cost "https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/cost.ts"
click node_split "https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/split.ts"
click node_sync "https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/sync.ts"
click node_trace "https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/trace.ts"
click node_probe "https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/mcp-probe.ts"
click node_reporters "https://github.com/thilak15/deontic/tree/main/packages/cli/src/reporters"
click node_config "https://github.com/thilak15/deontic/blob/main/packages/core/src/config/index.ts"
click node_discovery "https://github.com/thilak15/deontic/blob/main/packages/core/src/discovery/index.ts"
click node_parser "https://github.com/thilak15/deontic/blob/main/packages/core/src/parser/index.ts"
click node_scope "https://github.com/thilak15/deontic/blob/main/packages/core/src/scope/index.ts"
click node_engine "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/index.ts"
click node_imports "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/00-imports.ts"
click node_contradictions "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/01-contradiction.ts"
click node_groundtruth "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/02-ground-truth.ts"
click node_budget "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/03-bloat-cliff.ts"
click node_mcp "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/04-mcp-schema.ts"
click node_redundancy "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/05-redundancy.ts"
click node_roi "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/06-trace-roi.ts"
click node_ontology "https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/ontology.ts"
click node_splitter "https://github.com/thilak15/deontic/blob/main/packages/core/src/autofix/path-splitter.ts"
click node_crosssync "https://github.com/thilak15/deontic/blob/main/packages/core/src/autofix/cross-sync.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_check,node_cost,node_split,node_sync,node_trace,node_probe,node_reporters toneBlue
class node_config,node_discovery,node_parser,node_scope toneAmber
class node_engine,node_imports,node_contradictions,node_groundtruth,node_budget,node_mcp,node_redundancy,node_roi,node_ontology toneMint
class node_splitter,node_crosssync toneRose
class node_user toneIndigo
```

## Components

### CLI and Reporting

- [CLI Dispatcher](https://github.com/thilak15/deontic/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`
- [Check Command](https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/check.ts): `packages/cli/src/commands/check.ts`
- [Cost Command](https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/cost.ts): `packages/cli/src/commands/cost.ts`
- [Split Command](https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/split.ts): `packages/cli/src/commands/split.ts`
- [Sync Command](https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/sync.ts): `packages/cli/src/commands/sync.ts`
- [Trace Command](https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/trace.ts): `packages/cli/src/commands/trace.ts`
- [MCP Probe Command](https://github.com/thilak15/deontic/blob/main/packages/cli/src/commands/mcp-probe.ts): `packages/cli/src/commands/mcp-probe.ts`
- [Diagnostic Reporters](https://github.com/thilak15/deontic/tree/main/packages/cli/src/reporters): `packages/cli/src/reporters`

### Workspace Preparation

- [Workspace Config](https://github.com/thilak15/deontic/blob/main/packages/core/src/config/index.ts): `packages/core/src/config/index.ts`
- [File Discovery](https://github.com/thilak15/deontic/blob/main/packages/core/src/discovery/index.ts): `packages/core/src/discovery/index.ts`
- [Harness Parser](https://github.com/thilak15/deontic/blob/main/packages/core/src/parser/index.ts): `packages/core/src/parser/index.ts`
- [Profile and Scope](https://github.com/thilak15/deontic/blob/main/packages/core/src/scope/index.ts): `packages/core/src/scope/index.ts`

### Static Analysis

- [Analysis Orchestrator](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/index.ts): `packages/core/src/analyzer/index.ts`
- [Import Checks](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/00-imports.ts): `packages/core/src/analyzer/00-imports.ts`
- [Contradiction Solver](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/01-contradiction.ts): `packages/core/src/analyzer/01-contradiction.ts`
- [Reference Checks](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/02-ground-truth.ts): `packages/core/src/analyzer/02-ground-truth.ts`
- [Context Budget](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/03-bloat-cliff.ts): `packages/core/src/analyzer/03-bloat-cliff.ts`
- [MCP Schema Analysis](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/04-mcp-schema.ts): `packages/core/src/analyzer/04-mcp-schema.ts`
- [Redundancy Checks](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/05-redundancy.ts): `packages/core/src/analyzer/05-redundancy.ts`
- [Trace ROI](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/06-trace-roi.ts): `packages/core/src/analyzer/06-trace-roi.ts`
- [Directive Ontology](https://github.com/thilak15/deontic/blob/main/packages/core/src/analyzer/ontology.ts): `packages/core/src/analyzer/ontology.ts`

### Refactoring and Insights

- [Path Splitter](https://github.com/thilak15/deontic/blob/main/packages/core/src/autofix/path-splitter.ts): `packages/core/src/autofix/path-splitter.ts`
- [Cross-Tool Sync](https://github.com/thilak15/deontic/blob/main/packages/core/src/autofix/cross-sync.ts): `packages/core/src/autofix/cross-sync.ts`

### Other components

- **Engineer**

## Connections

- Engineer → CLI Dispatcher: runs command (evidence: `packages/cli/src/index.ts`)
- CLI Dispatcher → Check Command: dispatches check (evidence: `packages/cli/src/index.ts`)
- CLI Dispatcher → Cost Command: dispatches cost (evidence: `packages/cli/src/index.ts`)
- CLI Dispatcher → Split Command: dispatches split (evidence: `packages/cli/src/index.ts`)
- CLI Dispatcher → Sync Command: dispatches sync (evidence: `packages/cli/src/index.ts`)
- CLI Dispatcher → Trace Command: dispatches trace (evidence: `packages/cli/src/index.ts`)
- CLI Dispatcher → MCP Probe Command: dispatches probe (evidence: `packages/cli/src/index.ts`)
- Check Command → Diagnostic Reporters: formats results (evidence: `packages/cli/src/commands/check.ts`)
- Analysis Orchestrator → Workspace Config: loads config (evidence: `packages/core/src/analyzer/index.ts`)
- Analysis Orchestrator → File Discovery: discovers files (evidence: `packages/core/src/analyzer/index.ts`)
- File Discovery → Profile and Scope: classifies files (evidence: `packages/core/src/discovery/index.ts`)
- File Discovery → Harness Parser: parses harnesses (evidence: `packages/core/src/discovery/index.ts`)
- Harness Parser → Profile and Scope: resolves scope (evidence: `packages/core/src/parser/index.ts`)
- Analysis Orchestrator → Import Checks: runs pass (evidence: `packages/core/src/analyzer/index.ts`)
- Analysis Orchestrator → Contradiction Solver: runs pass (evidence: `packages/core/src/analyzer/index.ts`)
- Analysis Orchestrator → Reference Checks: runs pass (evidence: `packages/core/src/analyzer/index.ts`)
- Analysis Orchestrator → Context Budget: runs pass (evidence: `packages/core/src/analyzer/index.ts`)
- Analysis Orchestrator → MCP Schema Analysis: runs pass (evidence: `packages/core/src/analyzer/index.ts`)
- Analysis Orchestrator → Redundancy Checks: runs pass (evidence: `packages/core/src/analyzer/index.ts`)
- Analysis Orchestrator → Trace ROI: runs pass (evidence: `packages/core/src/analyzer/index.ts`)
- Contradiction Solver → Directive Ontology: uses ontology (evidence: `packages/core/src/analyzer/01-contradiction.ts`)
- Path Splitter → Workspace Config: loads config (evidence: `packages/core/src/autofix/path-splitter.ts`)
- Path Splitter → File Discovery: discovers files (evidence: `packages/core/src/autofix/path-splitter.ts`)
- Cross-Tool Sync → Workspace Config (evidence: `packages/core/src/autofix/cross-sync.ts`)
- Cross-Tool Sync → File Discovery (evidence: `packages/core/src/autofix/cross-sync.ts`)
- CLI Dispatcher → Analysis Orchestrator: checks workspace
- Cost Command → Context Budget: profiles cost
- Split Command → Path Splitter: requests split
- Sync Command → Cross-Tool Sync: requests sync
- Trace Command → Trace ROI: analyzes sessions
- MCP Probe Command → MCP Schema Analysis: probes servers
