The Forge

Uma entrada. Vários especialistas. Apenas o contexto necessário. Resultado verificável.

The Forge é um control plane local-first. Ele descobre Forges especialistas (Spark Forge AWS, Spark Forge Azure, API Forge, Platform Forge, os Doctors, …), escolhe o provider certo por capability de forma determinística e explicável e registra cada execução com evidência e receipt verificáveis. The Forger é o orquestrador interno.

Instalação (desenvolvimento)

git clone <repo> the-forger && cd the-forger
python3.11 -m venv .venv                      # qualquer Python >= 3.11
.venv/bin/python -m pip install -e ".[dev]"   # Windows: .venv\Scripts\python

O runtime só usa a stdlib. O comando canônico é theforge, usado em todos os exemplos; forge é um alias de conveniência (ADR 0008). Use theforge se forge colidir com Foundry ou Laravel Forge no seu PATH. Para rodar a suíte de testes, instale também os adapters (ver Desenvolvimento).

Instalação portátil (uso, não desenvolvimento)

setup.sh (POSIX) / setup.ps1 (Windows) fazem o bootstrap: resolvem um Python compatível, criam um venv isolado em ~/.forge/installs/the-forge, instalam o wheel (não o checkout), gravam o launcher em ~/.local/bin e registram o manifesto em ~/.forge/installations/the-forge.json. Depois o checkout pode ser apagado.

./setup.sh            # ou: pwsh setup.ps1
theforge --version    # smoke test embutido no bootstrap

Com o CLI no PATH, a própria forge instala seus host assets em qualquer repo e orquestra a família inteira:

cd seu-projeto
theforge install apply --yes              # skills + markers gerenciados (.claude/.devin/.agents/.github)
theforge install apply --dry-run          # plano determinístico, sem escrever
theforge install auto --yes               # delega a cada forge registrada em ~/.forge/installations
theforge install status|doctor|repair|uninstall
theforge installations list               # registry do bootstrap (read-only)

theforge portal [--no-browser]            # UI local opcional — command center da federação

Cada escrita passa por ledger sha256 com posse: uninstall remove só o que é gerenciado, arquivos do usuário e edições manuais sobrevivem. Escopos project (padrão), workspace e user; profiles minimal/recommended/full; hosts claude, devin, codex, copilot ou all. Contrato e matriz: docs/portable-installation/ (ADR 0058).

Primeiros passos

Os comandos abaixo assumem o venv ativado (source .venv/bin/activate; no Windows, .venv\Scripts\activate). Sem ativar, chame .venv/bin/theforge (Windows: .venv\Scripts\theforge).

theforge doctor
theforge init
theforge capabilities list
theforge ask "eco olá" --capability demo.echo
theforge explain <run_id>   # o run_id é impresso por `ask`
theforge plan "<tarefa>" --profile max            # só planeja (desfecho planned)
theforge plan "<tarefa>" --profile max --execute  # executa os nós em sequência

Registrar um provider

O providers.toml do usuário é o único que concede trust. Ele fica em %APPDATA%\theforge\providers.toml no Windows e em $XDG_CONFIG_HOME/theforge/providers.toml no POSIX (fallback ~/.config/theforge/providers.toml); $THEFORGE_CONFIG_DIR sobrescreve o diretório em qualquer plataforma.

[[providers]]
id = "my-forge"
argv = ["my-forge-cli", "protocol"]   # "{python}" vira o interpretador atual
trust = "local"                        # trusted | local | unverified | blocked (padrão: unverified)

O providers.toml de projeto (.forge/config/providers.toml) pode declarar providers, mas eles entram sempre como unverified e não são executados (nem describe) sem --allow-unverified. Para confiar num provider de projeto, copie a entrada para o arquivo do usuário. Ids builtin (echo-forge) são reservados: usá-los em qualquer providers.toml é erro de uso (exit 2). Uma entrada de projeto cujo id já esteja definido no arquivo do usuário é ignorada, com aviso.

Depois rode theforge registry refresh. Para começar um provider do zero, theforge provider init <dir> --id <id> escreve o scaffold (manifest, esqueleto stdlib, teste de conformidade) e theforge provider check -- <argv> roda a bateria de conformidade sem registrar nada (provider-authoring).

O version do manifest precisa ser SemVer 2.0.0 (senão o provider fica invalid, FORGE-MANIFEST-VERSION), e cada capability segue a taxonomia (fora dela, a capability é excluída com aviso FORGE-MANIFEST-TAXONOMY). Para quem já tem um provider: nota de migração.

Forges reais

Os Forges reais entram por seis adapters em adapters/, instalados no interpretador de cada especialista (o API Forge exige Python 3.12; os Doctors exigem Python ≥ 3.11) e registrados como qualquer provider (ADR 0014): Spark Forge AWS (spark-forge-aws), Spark Forge Azure (spark-forge-azure), API Forge (api-forge), Platform Forge (platform-forge), Forge Doctor Data (forge-doctor-data) e Forge Doctor API (forge-doctor-api). Só capabilities read-only e offline são expostas; o resto aparece em limitations do manifest com o motivo (catálogo, ADR 0017). O estado nativo de cada execute fica em .forge/runs/<id>/work/ e é reduzido aos artifacts declarados; esse diretório não passa por redaction (segurança). Instalação, registro, testes de integração e troubleshooting: docs/real-providers.md.

Mapa do ecossistema

• The Forge é a plataforma (este repositório); The Forger é o orquestrador interno que coordena — routing, budget, planos, receipts.
• Forges especialistas engenheiram: Spark Forge AWS (pipelines de dados AWS/PySpark), Spark Forge Azure (pipelines Azure/Fabric — sem equivalência falsa AWS↔Azure), API Forge (construção/evolução de APIs) e Platform Forge (inteligência de plataforma: IaC, k8s, secrets, CI/CD, gitops).
• Doctors observam: Forge Doctor Data e Forge Doctor API escaneiam e diagnosticam, produzem evidência e verificam o trabalho dos engenheiros — nunca executam mudanças.
• Routing pertence só à Forge (determinístico, de sinais declarados); verificação pertence a um provider diferente do produtor (can_verify declarado).
• Troca: evidência tipada com proveniência via Handoff — nunca prompts repetidos nem estado interno sincronizado.
• Adicionar um Forge: theforge provider init + provider-authoring.
• Visão das relações declaradas: theforge graph --mesh.
• Camada agentic: forge-knowledge/ (bootstrap metadata — nunca verdade de runtime, doc), skills forge-* canônicas renderizadas por host (doc) e oito agentes especializados com autoridade fechada (doc). theforge knowledge list/show/check e theforge agents list/show expõem os dois registries — check confronta o freshness recordado com o registry ao vivo.

Exit codes

Código	Significado
0	sucesso: ok / partial em ask e plan, planned em plan sem --execute, explain/replay sem divergência
1	doctor / providers health / provider check com falha
2	uso inválido (inclusive arquivo de plano ilegível, FORGE-PLAN-FILE, e run id malformado ou desconhecido) ou workspace não inicializado
3	no_route / ambiguous
4	provider_failure / refused (inclusive recusa de policy, plano rejeitado e replay --mode execute recusado)
5	falha ao gravar ou ler o run (theforge: persistence error:)
6	divergência de integridade: explain, replay --mode verify e replay --mode render
70	erro interno inesperado (sem traceback)
130	interrompido (Ctrl+C)

Igual à tabela de docs/cli.md, que detalha o exit de cada subcomando.

Documentação

Mapa completo por preocupação em docs/README.md e o índice canônico gerado em docs/INDEX.md. Principais:

• Arquitetura
• Forge Protocol v1
• Escrevendo um provider
• Providers reais: Spark Forge AWS e API Forge
• Capabilities: taxonomia e catálogo
• Versionamento e compatibilidade
• Segurança
• CLI
• Control plane (lifecycle dos especialistas, detecção/ativação de hosts, delegação real)
• Códigos de erro (lista canônica dos códigos FORGE-*)
• Semântica de falha (modos de falha → código, superfície, recuperação)
• Ontologia compartilhada (vocabulário epistêmico e proveniência entre providers)
• Performance: benchmark, baseline e budgets
• Capability negotiation v2 (requirement × offer, gates × signals)
• Registry sources (local autoritativo; fontes configuradas = metadata não-confiável)
• Remote discovery (candidatos por requirement; discovery ≠ instalação)
• Provider distribution (InstallationPlan/v2: plano gated, pinned, rollback)
• Economy observations (ExecutionObservation/v1, GlobalEconomyReceipt, maturidade por surface)
• Adaptive strategy (shadow champion/challenger — advisory, nunca promove sozinho)
• Global Stop (autoridade cross-provider e decisão receipted)
• Information Gain (ganho qualitativo, sem probabilidades inventadas)
• Trace federation (trace global + refs nativos opacos)
• Context ROI (utilização medida; recomendação advisory, não causal)
• Adaptive experiments (champion/challenger governado, sem auto-promoção)
• A2A bridge (experimental: cards/tasks/artifacts ⇄ contratos Forge; agente remoto nunca é provider local)

DX (Standard v1): handbook do ecossistema · command reference · skills · agents · tutorial · economy · troubleshooting · EN quickstart

• MCP interoperability (MCP = tools ≠ provider; awareness opcional via registry oficial, detecção sem instalação)
• Contract stability (scorecard forge-contracts: evidência para não extrair)
• Engineering memory (conhecimento verificável, isolamento cross-project)
• Execution targets (alvos declarados, classificação de dados, remote trust)
• Forge Knowledge (bootstrap metadata por especialista; runtime reality vence)
• Ecosystem skills (forge-* canônicas → mirrors por host; freshness auditado)
• Specialized agents (oito AgentSpec, autoridade fechada, sem auto-escalonamento)
• Installation orchestration (knowledge → plano → aprovação → verificação)
• Cross-forge orchestration (produces→consumes, produtor≠verificador)
• Agentic ecosystem (mapa da camada agentic: knowledge + skills + agents + auditoria)
• Loop Factory (fila operacional de specs: factory/ onde a pasta é o estado; grill gate humano, archive só com aceite)
• Reality manifests (estado real dos especialistas: SHAs, surfaces, drift)
• Feature freeze (Cycle 5.1: arquitetura congelada, dogfooding a seguir)
• Dogfooding (uso em projetos reais + taxonomia de observações)
• Desenvolvimento com agentes
• Índice de ADRs e índice de relatórios
• Relatório do Cycle 5.1 (reality sync, benchmarks B01–B15, Memory ROI, freeze)
• Relatório do Cycle 5 (Federated Engineering Intelligence: memory, targets, remote trust, strategy governance)
• Relatório do Cycle 4.1 (closure, Global Stop, trace federation e adaptive learning) — Cycle 4.1: CLOSED_LOCALLY / REMOTE_VALIDATION_BLOCKED on 0.5.0
• Changelog e release checklist (versionamento e fechamento evidence-based)
• Validation state policy (distingue REMOTE_BLOCKED de REMOTE_FAILED sem inventar green/red)
• Relatório do Cycle 4 (Capability Mesh: negociação, discovery, economia adaptativa, A2A/MCP, hardening; provas de realidade)
• Relatório do Cycle 3.1 (fechamento; waves documentadas uma a uma)
• Relatório do Cycle 3
• Relatório final do Cycle 2
• Spec do ciclo 1

Desenvolvimento

A suíte offline roda os adapters reais em modo replay, então o setup de desenvolvimento os instala editáveis junto com o core:

.venv/bin/python -m pip install -e ".[dev]" -e ./adapters/sparkforge_aws -e ./adapters/sparkforge_azure -e ./adapters/apiforge -e ./adapters/platformforge -e ./adapters/doctordata -e ./adapters/doctorapi
.venv/bin/python -m pytest            # suite offline
.venv/bin/python -m pytest -m slow    # gates de zero deps e instalação limpa (baixa hatchling)
.venv/bin/python -m pytest -m security   # categoria: unit, contract, integration, e2e, slow, security
.venv/bin/python -m pytest -m real_provider   # Forges reais; ver docs/real-providers.md
.venv/bin/ruff check .
.venv/bin/mypy
.venv/bin/python -m theforge.contracts.schema schemas   # regenerar schemas
.venv/bin/python scripts/agentic/audit_assets.py        # auditoria dos assets agentic; ver docs/agentic.md