# camilopolo1991-wq/the-forge architecture

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

- Interactive diagram: https://gitdiagram.com/camilopolo1991-wq/the-forge
- Repository: https://github.com/camilopolo1991-wq/the-forge

## Overview

The Forge is a Claude Code agent guard kit: it constrains tool use and scope, checks plans and run state, protects output, and records evidence for later audit. A principal workflow is an operator dispatching a goal; dispatch performs gates and manages the run, while the kit’s commands and hooks enforce checks and maintain logs, tickets, and record-repository changes. The README also documents redaction and post-run journal, plan, and reviewer checks. Relationships below are limited to README statements and visible source references; unsampled modules are included as capability nodes, but their internal call paths are not inferred.

Main entry points: [`bin/loop_dispatch.py`](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_dispatch.py) (Goal dispatcher), [`hooks/_guardlib.py`](https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/_guardlib.py) (Guard helpers), [`bin/loop_steplog.py`](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_steplog.py) (Step-log reader), [`bin/loop_conf.py`](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_conf.py) (Loop configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dispatch["Goal Dispatch"]
  node_dispatcher["Goal dispatcher<br/>[loop_dispatch.py]"]
  node_processes["Leader process count<br/>[loop_procs.py]"]
  node_worktrees["Goal worktrees<br/>[loop_worktree.py]"]
  node_dispatch_gate["Dispatch gate<br/>[dispatch-gate.py]"]
end

subgraph group_guards["Execution Guards"]
  node_pretool["Pre-tool guard<br/>[pretool-guard.py]"]
  node_readonly["Read-only guard<br/>[readonly-guard.py]"]
  node_writer_guards["Writer guards"]
  node_guard_library["Guard helpers<br/>[_guardlib.py]"]
  node_output_redaction["Output redaction<br/>[loop_guard_run.py]"]
  node_redactor["Redaction engine<br/>[loop_redact.py]"]
  node_scan["Secret scanning<br/>[loop_scan.py]"]
end

subgraph group_audit["Audit And Records"]
  node_journal[("Run journal<br/>[loop_journal.py]")]
  node_step_log["Step-log reader<br/>[loop_steplog.py]"]
  node_tickets[("Ticket records<br/>[loop_ticket.py]")]
  node_record_commit["Record commit"]
  node_record_merge["Record merge"]
  node_inventory["Run inventory<br/>[loop_inventory.py]"]
  node_report["Run reports<br/>[loop_report.py]"]
end

subgraph group_checks["Validation Tools"]
  node_card_lint["Card and plan lint<br/>[loop_card_lint.py]"]
  node_preflight["Run preflight<br/>[loop_preflight.py]"]
  node_tripwire["Change tripwire<br/>[loop_tripwire.py]"]
end

subgraph group_config["Shared Configuration"]
  node_config["Loop configuration<br/>[loop_conf.py]"]
end

node_operator(("Operator"))
node_claude(("Claude Code agent"))

node_operator -->|"dispatches goal"| node_dispatcher
node_dispatcher -->|"counts leaders"| node_processes
node_dispatcher -->|"manages worktrees"| node_worktrees
node_dispatcher -.->|"runs under gate"| node_dispatch_gate
node_claude -->|"tool calls"| node_pretool
node_pretool -->|"uses helpers"| node_guard_library
node_readonly -->|"uses helpers"| node_guard_library
node_writer_guards -->|"uses helpers"| node_guard_library
node_operator -->|"runs command"| node_output_redaction
node_output_redaction -.->|"redacts output"| node_redactor
node_operator -->|"checks journal"| node_journal
node_operator -->|"lints plan"| node_card_lint
node_card_lint -->|"reads step log"| node_step_log
node_journal -->|"reads step log"| node_step_log
node_record_commit -->|"reads step log"| node_step_log
node_record_commit -->|"uses worktree operations"| node_worktrees
node_preflight -->|"loads settings"| node_config
node_scan -->|"uses detector"| node_redactor
node_tripwire -->|"loads settings"| node_config
node_tickets -.->|"reads settings"| node_config

click node_dispatcher "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_dispatch.py"
click node_processes "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_procs.py"
click node_worktrees "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_worktree.py"
click node_dispatch_gate "https://github.com/camilopolo1991-wq/the-forge/blob/main/hephaestus/agent-hooks/dispatch-gate.py"
click node_pretool "https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/pretool-guard.py"
click node_readonly "https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/readonly-guard.py"
click node_writer_guards "https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/writer-git-guard.py"
click node_guard_library "https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/_guardlib.py"
click node_output_redaction "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_guard_run.py"
click node_redactor "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_redact.py"
click node_scan "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_scan.py"
click node_journal "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_journal.py"
click node_step_log "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_steplog.py"
click node_tickets "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_ticket.py"
click node_record_commit "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_record_commit.py"
click node_record_merge "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_record_merge.py"
click node_inventory "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_inventory.py"
click node_report "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_report.py"
click node_card_lint "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_card_lint.py"
click node_preflight "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_preflight.py"
click node_tripwire "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_tripwire.py"
click node_config "https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_conf.py"

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_dispatcher,node_processes,node_worktrees,node_dispatch_gate toneBlue
class node_pretool,node_readonly,node_writer_guards,node_guard_library,node_output_redaction,node_redactor,node_scan toneAmber
class node_journal,node_step_log,node_tickets,node_record_commit,node_record_merge,node_inventory,node_report toneMint
class node_card_lint,node_preflight,node_tripwire toneRose
class node_config,node_operator,node_claude toneIndigo
```

## Components

### Goal Dispatch

- [Goal dispatcher](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_dispatch.py): `bin/loop_dispatch.py`
- [Leader process count](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_procs.py): `bin/loop_procs.py`
- [Goal worktrees](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_worktree.py): `bin/loop_worktree.py`
- [Dispatch gate](https://github.com/camilopolo1991-wq/the-forge/blob/main/hephaestus/agent-hooks/dispatch-gate.py): `hephaestus/agent-hooks/dispatch-gate.py`

### Execution Guards

- [Pre-tool guard](https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/pretool-guard.py): `hooks/pretool-guard.py`
- [Read-only guard](https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/readonly-guard.py): `hooks/readonly-guard.py`
- [Writer guards](https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/writer-git-guard.py): `hooks/writer-git-guard.py`
- [Guard helpers](https://github.com/camilopolo1991-wq/the-forge/blob/main/hooks/_guardlib.py): `hooks/_guardlib.py`
- [Output redaction](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_guard_run.py): `bin/loop_guard_run.py`
- [Redaction engine](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_redact.py): `bin/loop_redact.py`
- [Secret scanning](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_scan.py): `bin/loop_scan.py`

### Audit And Records

- [Run journal](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_journal.py): `bin/loop_journal.py`
- [Step-log reader](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_steplog.py): `bin/loop_steplog.py`
- [Ticket records](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_ticket.py): `bin/loop_ticket.py`
- [Record commit](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_record_commit.py): `bin/loop_record_commit.py`
- [Record merge](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_record_merge.py): `bin/loop_record_merge.py`
- [Run inventory](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_inventory.py): `bin/loop_inventory.py`
- [Run reports](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_report.py): `bin/loop_report.py`

### Validation Tools

- [Card and plan lint](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_card_lint.py): `bin/loop_card_lint.py`
- [Run preflight](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_preflight.py): `bin/loop_preflight.py`
- [Change tripwire](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_tripwire.py): `bin/loop_tripwire.py`

### Shared Configuration

- [Loop configuration](https://github.com/camilopolo1991-wq/the-forge/blob/main/bin/loop_conf.py): `bin/loop_conf.py`

### Other components

- **Operator**
- **Claude Code agent**

## Connections

- Operator → Goal dispatcher: dispatches goal (evidence: `README.md`)
- Goal dispatcher → Leader process count: counts leaders (evidence: `bin/loop_dispatch.py`)
- Goal dispatcher → Goal worktrees: manages worktrees (evidence: `bin/loop_dispatch.py`)
- Goal dispatcher → Dispatch gate: runs under gate
- Claude Code agent → Pre-tool guard: tool calls (evidence: `README.md`)
- Pre-tool guard → Guard helpers: uses helpers (evidence: `hooks/pretool-guard.py`)
- Read-only guard → Guard helpers: uses helpers (evidence: `hooks/readonly-guard.py`)
- Writer guards → Guard helpers: uses helpers (evidence: `hooks/writer-git-guard.py`)
- Operator → Output redaction: runs command (evidence: `README.md`)
- Output redaction → Redaction engine: redacts output
- Operator → Run journal: checks journal (evidence: `README.md`)
- Operator → Card and plan lint: lints plan (evidence: `README.md`)
- Card and plan lint → Step-log reader: reads step log (evidence: `bin/loop_card_lint.py`)
- Run journal → Step-log reader: reads step log (evidence: `bin/loop_journal.py`)
- Record commit → Step-log reader: reads step log (evidence: `bin/loop_record_commit.py`)
- Record commit → Goal worktrees: uses worktree operations (evidence: `bin/loop_record_commit.py`)
- Run preflight → Loop configuration: loads settings (evidence: `bin/loop_preflight.py`)
- Secret scanning → Redaction engine: uses detector (evidence: `bin/loop_scan.py`)
- Change tripwire → Loop configuration: loads settings (evidence: `bin/loop_tripwire.py`)
- Ticket records → Loop configuration: reads settings (evidence: `bin/loop_ticket.py`)
