# julian-b-smith/autonomous architecture

> Architecture diagram of the GitHub repository julian-b-smith/autonomous, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/julian-b-smith/autonomous
- Repository: https://github.com/julian-b-smith/autonomous

## Overview

autonomous is a standards body, toolkit, and control room for developing and governing a fleet of AI-built software projects. The principal loop is human-directed work by an implementer, independent verification and criticism, deterministic gates, then fleet-wide oversight and follow-up. The graph also preserves the documented session, kit-distribution, coordination, and memory-loop capabilities. Several subsystems are documented but not sampled in source; those links use README evidence, and the coordination layer is described as designed rather than built.

Main entry points: [`governor/monitor.py`](https://github.com/julian-b-smith/autonomous/blob/main/governor/monitor.py) (Fleet monitor), [`kit/sweep/sweep.py`](https://github.com/julian-b-smith/autonomous/blob/main/kit/sweep/sweep.py) (Fleet sweep), [`harness`](https://github.com/julian-b-smith/autonomous/tree/main/harness) (Agent harness), [`governor/retrofit_verify.py`](https://github.com/julian-b-smith/autonomous/blob/main/governor/retrofit_verify.py) (Retrofit verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_doctrine["Doctrine and harness"]
  node_doctrine["Standing doctrine<br/>[DOCTRINE.md]"]
  node_harness["Agent harness"]
  node_kit["Harness kit"]
  node_verify["Verify oracle<br/>[verify.project]"]
end

subgraph group_sessions["Session operations"]
  node_session_state["Session state<br/>[state.py]"]
  node_session_facts["Session facts<br/>[session_facts.py]"]
  node_session_registry[("Session registry<br/>[registry.py]")]
  node_session_board["Session board<br/>[render_registry.py]"]
  node_batch_close["Fleet session close<br/>[batch_close.py]"]
end

subgraph group_fleet["Fleet coordination"]
  node_thread_board["Threads board<br/>[render_threads.py]"]
  node_sweep["Fleet sweep<br/>[sweep.py]"]
  node_kit_sync["Kit synchronization<br/>[kit_sync.py]"]
  node_currency["Kit currency audit<br/>[currency.py]"]
  node_checklist["Fleet checklist"]
end

subgraph group_governance["Deterministic governance"]
  node_ball_scan["Mailbox obligations<br/>[ball_scan.py]"]
  node_monitor["Fleet monitor<br/>[monitor.py]"]
  node_leak_scan["Leak scan<br/>[leak_scan.py]"]
  node_s4_scan["S4 scan<br/>[s4_scan.py]"]
  node_retrofit_verify["Retrofit verification<br/>[retrofit_verify.py]"]
  node_session_brief["Session brief hook<br/>[session-brief.py]"]
end

subgraph group_memory["Memory loops"]
  node_knowledge_loop["Knowledge loop"]
  node_audit_loop["Audit loop"]
end

node_human(("Human operator"))
node_agents(("Coding agents"))
node_project[("Project repositories")]

node_human -->|"directs work"| node_agents
node_agents -->|"work within"| node_harness
node_harness -->|"implements changes"| node_project
node_harness -->|"runs oracle"| node_verify
node_verify -->|"checks tree"| node_project
node_doctrine -->|"sets rules"| node_harness
node_kit -->|"vendors mechanism"| node_project
node_project -->|"provides git facts"| node_session_facts
node_session_facts -.->|"records session"| node_session_registry
node_session_state -->|"reads repo state"| node_project
node_session_board -->|"renders open sessions"| node_session_registry
node_session_brief -->|"scans obligations"| node_ball_scan
node_session_brief -->|"verifies notices"| node_retrofit_verify
node_thread_board -->|"resolves projects"| node_sweep
node_thread_board -->|"scans threads"| node_ball_scan
node_sweep -->|"enumerates fleet"| node_project
node_kit_sync -->|"syncs kit files"| node_project
node_checklist -->|"checks vendoring"| node_kit_sync
node_checklist -.->|"reads fleet status"| node_sweep
node_retrofit_verify -->|"reads currency"| node_currency
node_retrofit_verify -->|"rechecks claims"| node_project
node_monitor -->|"runs scan"| node_leak_scan
node_monitor -->|"runs scan"| node_ball_scan
node_monitor -->|"runs scan"| node_s4_scan
node_monitor -->|"reads fleet"| node_sweep
node_batch_close -->|"reads state"| node_session_state
node_batch_close -->|"closes fleet sessions"| node_sweep
node_human -->|"reviews findings"| node_monitor
node_knowledge_loop -->|"promotes lessons"| node_project
node_audit_loop -->|"down-propagates lessons"| node_project
node_human -->|"ratifies learning"| node_knowledge_loop

click node_doctrine "https://github.com/julian-b-smith/autonomous/blob/main/doctrine/DOCTRINE.md"
click node_harness "https://github.com/julian-b-smith/autonomous/tree/main/harness"
click node_kit "https://github.com/julian-b-smith/autonomous/tree/main/kit"
click node_verify "https://github.com/julian-b-smith/autonomous/blob/main/kit/templates/verify.project"
click node_session_state "https://github.com/julian-b-smith/autonomous/blob/main/kit/session/state.py"
click node_session_facts "https://github.com/julian-b-smith/autonomous/blob/main/kit/hooks/session_facts.py"
click node_session_registry "https://github.com/julian-b-smith/autonomous/blob/main/kit/session/registry.py"
click node_session_board "https://github.com/julian-b-smith/autonomous/blob/main/kit/session/render_registry.py"
click node_thread_board "https://github.com/julian-b-smith/autonomous/blob/main/kit/session/render_threads.py"
click node_sweep "https://github.com/julian-b-smith/autonomous/blob/main/kit/sweep/sweep.py"
click node_kit_sync "https://github.com/julian-b-smith/autonomous/blob/main/kit/kit_sync.py"
click node_currency "https://github.com/julian-b-smith/autonomous/blob/main/kit/currency.py"
click node_checklist "https://github.com/julian-b-smith/autonomous/blob/main/kit/render_checklist.py"
click node_ball_scan "https://github.com/julian-b-smith/autonomous/blob/main/governor/ball_scan.py"
click node_monitor "https://github.com/julian-b-smith/autonomous/blob/main/governor/monitor.py"
click node_leak_scan "https://github.com/julian-b-smith/autonomous/blob/main/governor/leak_scan.py"
click node_s4_scan "https://github.com/julian-b-smith/autonomous/blob/main/governor/s4_scan.py"
click node_retrofit_verify "https://github.com/julian-b-smith/autonomous/blob/main/governor/retrofit_verify.py"
click node_session_brief "https://github.com/julian-b-smith/autonomous/blob/main/kit/hooks/session-brief.py"
click node_batch_close "https://github.com/julian-b-smith/autonomous/blob/main/kit/session/batch_close.py"
click node_knowledge_loop "https://github.com/julian-b-smith/autonomous/tree/main/loops/knowledge-loop"
click node_audit_loop "https://github.com/julian-b-smith/autonomous/tree/main/loops/audit-loop"

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_doctrine,node_harness,node_kit,node_verify toneBlue
class node_session_state,node_session_facts,node_session_registry,node_session_board,node_batch_close,node_project toneAmber
class node_thread_board,node_sweep,node_kit_sync,node_currency,node_checklist toneMint
class node_ball_scan,node_monitor,node_leak_scan,node_s4_scan,node_retrofit_verify,node_session_brief toneRose
class node_knowledge_loop,node_audit_loop,node_human,node_agents toneIndigo
```

## Components

### Doctrine and harness

- [Standing doctrine](https://github.com/julian-b-smith/autonomous/blob/main/doctrine/DOCTRINE.md): `doctrine/DOCTRINE.md`
- [Agent harness](https://github.com/julian-b-smith/autonomous/tree/main/harness): `harness`
- [Harness kit](https://github.com/julian-b-smith/autonomous/tree/main/kit): `kit`
- [Verify oracle](https://github.com/julian-b-smith/autonomous/blob/main/kit/templates/verify.project): `kit/templates/verify.project`

### Session operations

- [Session state](https://github.com/julian-b-smith/autonomous/blob/main/kit/session/state.py): `kit/session/state.py`
- [Session facts](https://github.com/julian-b-smith/autonomous/blob/main/kit/hooks/session_facts.py): `kit/hooks/session_facts.py`
- [Session registry](https://github.com/julian-b-smith/autonomous/blob/main/kit/session/registry.py): `kit/session/registry.py`
- [Session board](https://github.com/julian-b-smith/autonomous/blob/main/kit/session/render_registry.py): `kit/session/render_registry.py`
- [Fleet session close](https://github.com/julian-b-smith/autonomous/blob/main/kit/session/batch_close.py): `kit/session/batch_close.py`

### Fleet coordination

- [Threads board](https://github.com/julian-b-smith/autonomous/blob/main/kit/session/render_threads.py): `kit/session/render_threads.py`
- [Fleet sweep](https://github.com/julian-b-smith/autonomous/blob/main/kit/sweep/sweep.py): `kit/sweep/sweep.py`
- [Kit synchronization](https://github.com/julian-b-smith/autonomous/blob/main/kit/kit_sync.py): `kit/kit_sync.py`
- [Kit currency audit](https://github.com/julian-b-smith/autonomous/blob/main/kit/currency.py): `kit/currency.py`
- [Fleet checklist](https://github.com/julian-b-smith/autonomous/blob/main/kit/render_checklist.py): `kit/render_checklist.py`

### Deterministic governance

- [Mailbox obligations](https://github.com/julian-b-smith/autonomous/blob/main/governor/ball_scan.py): `governor/ball_scan.py`
- [Fleet monitor](https://github.com/julian-b-smith/autonomous/blob/main/governor/monitor.py): `governor/monitor.py`
- [Leak scan](https://github.com/julian-b-smith/autonomous/blob/main/governor/leak_scan.py): `governor/leak_scan.py`
- [S4 scan](https://github.com/julian-b-smith/autonomous/blob/main/governor/s4_scan.py): `governor/s4_scan.py`
- [Retrofit verification](https://github.com/julian-b-smith/autonomous/blob/main/governor/retrofit_verify.py): `governor/retrofit_verify.py`
- [Session brief hook](https://github.com/julian-b-smith/autonomous/blob/main/kit/hooks/session-brief.py): `kit/hooks/session-brief.py`

### Memory loops

- [Knowledge loop](https://github.com/julian-b-smith/autonomous/tree/main/loops/knowledge-loop): `loops/knowledge-loop`
- [Audit loop](https://github.com/julian-b-smith/autonomous/tree/main/loops/audit-loop): `loops/audit-loop`

### Other components

- **Human operator**
- **Coding agents**
- **Project repositories**

## Connections

- Human operator → Coding agents: directs work (evidence: `README.md`)
- Coding agents → Agent harness: work within (evidence: `README.md`)
- Agent harness → Project repositories: implements changes (evidence: `README.md`)
- Agent harness → Verify oracle: runs oracle (evidence: `README.md`)
- Verify oracle → Project repositories: checks tree (evidence: `README.md`)
- Standing doctrine → Agent harness: sets rules (evidence: `README.md`)
- Harness kit → Project repositories: vendors mechanism (evidence: `README.md`)
- Project repositories → Session facts: provides git facts (evidence: `kit/hooks/session_facts.py`)
- Session facts → Session registry: records session
- Session state → Project repositories: reads repo state (evidence: `kit/session/state.py`)
- Session board → Session registry: renders open sessions (evidence: `kit/session/render_registry.py`)
- Session brief hook → Mailbox obligations: scans obligations (evidence: `kit/hooks/session-brief.py`)
- Session brief hook → Retrofit verification: verifies notices (evidence: `kit/hooks/session-brief.py`)
- Threads board → Fleet sweep: resolves projects (evidence: `kit/session/render_threads.py`)
- Threads board → Mailbox obligations: scans threads (evidence: `kit/session/render_threads.py`)
- Fleet sweep → Project repositories: enumerates fleet (evidence: `kit/sweep/sweep.py`)
- Kit synchronization → Project repositories: syncs kit files (evidence: `kit/kit_sync.py`)
- Fleet checklist → Kit synchronization: checks vendoring (evidence: `kit/render_checklist.py`)
- Fleet checklist → Fleet sweep: reads fleet status
- Retrofit verification → Kit currency audit: reads currency (evidence: `governor/retrofit_verify.py`)
- Retrofit verification → Project repositories: rechecks claims (evidence: `governor/retrofit_verify.py`)
- Fleet monitor → Leak scan: runs scan (evidence: `governor/monitor.py`)
- Fleet monitor → Mailbox obligations: runs scan (evidence: `governor/monitor.py`)
- Fleet monitor → S4 scan: runs scan (evidence: `governor/monitor.py`)
- Fleet monitor → Fleet sweep: reads fleet (evidence: `governor/monitor.py`)
- Fleet session close → Session state: reads state (evidence: `kit/session/batch_close.py`)
- Fleet session close → Fleet sweep: closes fleet sessions (evidence: `kit/session/batch_close.py`)
- Human operator → Fleet monitor: reviews findings (evidence: `README.md`)
- Knowledge loop → Project repositories: promotes lessons (evidence: `README.md`)
- Audit loop → Project repositories: down-propagates lessons (evidence: `README.md`)
- Human operator → Knowledge loop: ratifies learning (evidence: `README.md`)
